doc/source/include/Quickstart.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "729e0589-1610-404f-a4e9-7abf276c4af9",
   "metadata": {},
   "source": [
    "# Quickstart\n",
    "\n",
    "This is the quickstart guide for creating a simulation workflow package based on `libpyvinyl`. Please\n",
    "first install `libpyvinyl` following the instruction in the [Installation](INSTALL.md) section.\n",
    "\n",
    "## Introduction\n",
    "This section is intended to help a developer understand how a new simulation package can use libpyvinyl as a foundation. It is important to understand that libpyvinyl provides base classes from which a developer inherits more specialised classes from, and the final class then both contains the new functionality and the basic capabilities. To make a new package, a developer would have to inherit from these baseclasses:\n",
    "\n",
    "- BaseCalculator\n",
    "- BaseData\n",
    "- BaseDataFormat\n",
    "\n",
    "**Calculator**\n",
    "\n",
    "The specialised calculator that inherits from BaseCalculator is capable of performing a calculation of some sort. The calculation can depend on some data and input values for parameters specified when the calculator is built. The calculator can also return output data. The scope of a calculator is somewhat arbitrary, but the power of libpyvinyl comes from the ability to break a big calculation down into smaller parts of individual calculators. When using a calculator, it is easy for the user to understand a small number of parameters as there are less risks of ambiguity. A rich Parameter class is provided by libpyvinyl to create the necessary parameters in each calculator. When creating a parameter it is possible to set allowed intervals to avoid undefined behaviour. \n",
    "\n",
    "**Data**\n",
    "\n",
    "To create a description of some data that can be either given to or returned from a calculator one starts with the BaseData class. This data could be for example a number of particle states.\n",
    "\n",
    "**DataFormat**\n",
    "\n",
    "Each Data class will have a number of supported DataFormat which are necessary in order to save the data to disk. Our particle data from before could be saved as a json, yaml or some compressed format, and each would need a DataFormat class that contains methods to read and write such data, and make it available to a corresponding Data class.\n",
    "\n",
    "### First steps as a developer\n",
    "To build a simulation package in this framework, think about what calculation need to be performed and what parameters are needed to describe it. Then divide this big calculation into calculators with a limited number of parameters and clear input and output data. For example a particle source, it would need parameters describing the properties of emitted particles and then return a Data object with a large number of particle states. Then a calculator describing a piece of optics might have parameters describing its geometry, and it could have particle states as both input and output. With these kinds of considerations it becomes clear what Calculators and Data classes should be written.\n",
    "\n",
    "### Benefit of libpyvinyl\n",
    "When a package uses libpyvinyl as a foundation, libpyvinyl can be used to write a simulation from a series of these calculators using the Instrument class. Here is an example of a series of calculators that form a simple instrument.\n",
    "\n",
    "\n",
    "| Calculator    | Description       | Parameters                     | Input Data      | Output Data     |\n",
    "|:--------------|:------------------|:------------------------------:|:---------------:|:---------------:|\n",
    "| Source        | Emits particles   | size, divergence, energy       | None            | particle states |\n",
    "| Monochromator | Crystal           | position, d_spacing, mosaicity | particle states | particle states |\n",
    "| Monochromator | Crystal           | position, d_spacing, mosaicity | particle states | particle states |\n",
    "| Sample        | Crystal sample    | position, d_spacing, mosaicity | particle states | particle states |\n",
    "| Detector      | Particle detector | position, size, sensitivity    | particle states | counts in bins  |\n",
    "\n",
    "This setup uses two monochromators, each with their own parameters. The user can set up a master parameter that control both, for example to ensure they have the same d_spacing. Running the instrument then corresponds to running each calculator in turn and providing the output of one to the next.\n",
    "\n",
    "## Design a minimal instrument\n",
    "As a minimal start, we will create an instrument with a calculator that can get the sum of two numbers.\n",
    "\n",
    "There are 3 specialized classes needed to be defined for the package:\n",
    "\n",
    "- `CalculatorClass`: a class based on `BaseCalculator` to perform the calculation.\n",
    "- `DataClass`: to represent the input and output data of the `CalculatorClass`.\n",
    "- `FormatClass`: the interface to exchange data between the memory and the file on the disk in a specific format.\n",
    "\n",
    "### Define a simple python object mapping DataClass\n",
    "Let's firstly define a `NumberData` class mapping the python objects in the memory. This is done by creating a mapping\n",
    "dictionary to connect the data (e.g. an array or a single value) in the python object to the reference variable."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "b6f9eb6e-4bc9-480d-ad6a-63d11aa0d3d8",
   "metadata": {},
   "outputs": [],
   "source": [
    "from libpyvinyl.BaseData import BaseData\n",
    "\n",
    "class NumberData(BaseData):\n",
    "    def __init__(self,key,data_dict=None,filename=None,\n",
    "                 file_format_class=None,file_format_kwargs=None):\n",
    "\n",
    "        expected_data = {}\n",
    "\n",
    "        ### DataClass developer's job start\n",
    "        expected_data[\"number\"] = None\n",
    "        ### DataClass developer's job end\n",
    "\n",
    "        super().__init__(key,expected_data,data_dict,\n",
    "                         filename,file_format_class,file_format_kwargs)\n",
    "\n",
    "    @classmethod\n",
    "    def supported_formats(self):\n",
    "        ### DataClass developer's job start\n",
    "        format_dict = {}\n",
    "        ### DataClass developer's job end\n",
    "        return format_dict\n",
    "\n",
    "# Test if the definition works\n",
    "data = NumberData(key=\"test\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "75909323-a9d0-41fd-814f-621700669476",
   "metadata": {},
   "source": [
    "The above example shows a minimal definition of a DataClass. There are only two sections need to consider by the simulation package developers:\n",
    "\n",
    "- `expected_data`: A dictionary whose keys are the expected keys of the dictionary returned by `get_data()`, we just simply would like to get a \"number\" from a `NumberData`.\n",
    "- `format_dict`: A dictionary of supported format for hard disk files. Now we only need a python object mapper, so we just assign an empty dict to it for the moment.\n",
    "\n",
    "\n",
    "### Define a DataClass also supporting file mapping\n",
    "For a software writing the data to a file instead of a python object, it's necessary to have a interface between the file and the DataClass. We create a FormatClass\n",
    "as the interface:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "5c915a81-5f01-4fba-9f27-a6d7d5f7d4f9",
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "from libpyvinyl.BaseFormat import BaseFormat\n",
    "\n",
    "class TXTFormat(BaseFormat):\n",
    "    def __init__(self) -> None:\n",
    "        super().__init__()\n",
    "\n",
    "    @classmethod\n",
    "    def format_register(self):\n",
    "        key = \"TXT\"\n",
    "        desciption = \"TXT format for NumberData\"\n",
    "        file_extension = \".txt\"\n",
    "        read_kwargs = [\"\"]\n",
    "        write_kwargs = [\"\"]\n",
    "        return self._create_format_register(\n",
    "            key, desciption, file_extension, read_kwargs, write_kwargs\n",
    "        )\n",
    "\n",
    "    @staticmethod\n",
    "    def direct_convert_formats():\n",
    "        return []\n",
    "    \n",
    "    @classmethod\n",
    "    def convert(\n",
    "        cls, obj: BaseData, output: str, output_format_class: str, key, **kwargs):\n",
    "        raise NotImplementedError\n",
    "\n",
    "\n",
    "    @classmethod\n",
    "    def read(cls, filename: str) -> dict:\n",
    "        \"\"\"Read the data from the file with the `filename` to\n",
    "        a dictionary. The dictionary will be used by its corresponding data class.\"\"\"\n",
    "        number = float(np.loadtxt(filename))\n",
    "        data_dict = {\"number\": number}\n",
    "        return data_dict\n",
    "\n",
    "    @classmethod\n",
    "    def write(cls, object, filename: str, key: str = None):\n",
    "        \"\"\"Save the data with the `filename`.\"\"\"\n",
    "        data_dict = object.get_data()\n",
    "        arr = np.array([data_dict[\"number\"]])\n",
    "        np.savetxt(filename, arr, fmt=\"%.3f\")\n",
    "        if key is None:\n",
    "            original_key = object.key\n",
    "            key = original_key + \"_to_TXTFormat\"\n",
    "        return object.from_file(filename, cls, key)\n",
    "\n",
    "# Test if the definition works\n",
    "data = TXTFormat()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5bc6eae3-c0fc-4330-bafe-b38b4ba734ea",
   "metadata": {},
   "source": [
    "In the above example, we create a `TXTFormat` class based on the `BaseFormat` abstract class. We need to provide:\n",
    "\n",
    "- The information of the `format_register` method to get registered in the `NumberData.supported_formats()` method. This will be explained later.\n",
    "- the `read` function to read the data from the file into the `data_dict`, which will be accessed by the `NumberData` class by `NumberData.get_data()`. The dictionary keys match those in the `expected_data` of `NumberData`.\n",
    "- The `write` function to write the `NumberData` object into a file in `TXTFormat`.\n",
    "\n",
    "For the other methods above, we just need to copy but don't have to touch them at this moment.\n",
    "\n",
    "Then, we just need add the `TXTFormat` to the `NumberData` created in the last section."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "1c8ab1d7-e88a-4d64-895a-133e7d31d883",
   "metadata": {},
   "outputs": [],
   "source": [
    "class NumberData(BaseData):\n",
    "    def __init__(self,key,data_dict=None,filename=None,\n",
    "                 file_format_class=None,file_format_kwargs=None):\n",
    "\n",
    "        expected_data = {}\n",
    "\n",
    "        ### DataClass developer's job start\n",
    "        expected_data[\"number\"] = None\n",
    "        ### DataClass developer's job end\n",
    "\n",
    "        super().__init__(key,expected_data,data_dict,\n",
    "                         filename,file_format_class,file_format_kwargs)\n",
    "\n",
    "    @classmethod\n",
    "    def supported_formats(self):\n",
    "        ### DataClass developer's job start\n",
    "        format_dict = {}\n",
    "        self._add_ioformat(format_dict, TXTFormat)\n",
    "        ### DataClass developer's job end\n",
    "        return format_dict"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8ba80c0f-704f-474a-a2fc-f291e35aa787",
   "metadata": {},
   "source": [
    "You can list the formats it supports with:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "bc96109b-7b4a-4cf4-9f28-23250c6d5649",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Format class: <class '__main__.TXTFormat'>\n",
      "Key: TXT\n",
      "Description: TXT format for NumberData\n",
      "File extension: .txt\n",
      "\n",
      "\n"
     ]
    }
   ],
   "source": [
    "NumberData.list_formats()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2accdd52-94da-4f9a-a420-c3703cbf34c4",
   "metadata": {},
   "source": [
    "### Define a Calculator with native python object output\n",
    "Assuming we have a simulation code whose output is a native python object (e.g. a list or dict), we can create a CalculatorClass for the simulation code:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "b8bc5c15-181b-4db0-9e6b-1155ff670b36",
   "metadata": {},
   "outputs": [],
   "source": [
    "from typing import Union\n",
    "from pathlib import Path\n",
    "from libpyvinyl.BaseData import DataCollection\n",
    "from libpyvinyl.BaseCalculator import BaseCalculator, CalculatorParameters\n",
    "\n",
    "class PlusCalculator(BaseCalculator):\n",
    "    def __init__(self, name: str, input: Union[DataCollection, list, NumberData], \n",
    "                 output_keys: Union[list, str] = [\"plus_result\"],\n",
    "                 output_data_types=[NumberData], output_filenames: Union[list, str] = [], \n",
    "                 instrument_base_dir=\"./\", calculator_base_dir=\"PlusCalculator\",\n",
    "        parameters=None):\n",
    "        \"\"\"A python object calculator example\"\"\"\n",
    "        super().__init__(name, input, output_keys, output_data_types=output_data_types,\n",
    "            output_filenames=output_filenames, instrument_base_dir=instrument_base_dir,\n",
    "            calculator_base_dir=calculator_base_dir, parameters=parameters)\n",
    "\n",
    "    def init_parameters(self):\n",
    "        parameters = CalculatorParameters()\n",
    "        times = parameters.new_parameter(\n",
    "            \"plus_times\", comment=\"How many times to do the plus\"\n",
    "        )\n",
    "        times.value = 1\n",
    "        self.parameters = parameters\n",
    "\n",
    "    def backengine(self):\n",
    "        Path(self.base_dir).mkdir(parents=True, exist_ok=True)\n",
    "        input_num0 = self.input.to_list()[0].get_data()[\"number\"]\n",
    "        input_num1 = self.input.to_list()[1].get_data()[\"number\"]\n",
    "        output_num = float(input_num0) + float(input_num1)\n",
    "        if self.parameters[\"plus_times\"].value > 1:\n",
    "            for i in range(self.parameters[\"plus_times\"].value - 1):\n",
    "                output_num += input_num1\n",
    "        data_dict = {\"number\": output_num}\n",
    "        key = self.output_keys[0]\n",
    "        output_data = self.output[key]\n",
    "        output_data.set_dict(data_dict)\n",
    "        return self.output"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "cddca02c-9a4e-41b2-bb43-9d428207f441",
   "metadata": {},
   "source": [
    "In the above example, we define a `PlusCalculator` based on the `BaseCalculator`. The following needs to be provided:\n",
    "\n",
    "- Some default output-related values to initialize empty output Data containers (see [here](https://github.com/JunCEEE/libpyvinyl/blob/5d14bdc107a1536ec08a467e5b446fbddaa1b7b1/libpyvinyl/BaseCalculator.py#L344)):\n",
    "    - output_keys: the key of each Data object in the output `DataCollection`\n",
    "    - output_data_types: the Data type of each Data object.\n",
    "    - output_filenames: the filenames of the output files (if any)\n",
    "- `init_parameters` to define the default values of the parameters need by the calculator. Range restrictions and units of values can be also set here. Details can be found in the `parameter` use guide.\n",
    "- `backengine` to define how to conduct the calculation. It should return a reference of the output DataCollection.\n",
    "\n",
    "The `PlusCalculator.backengine` adds two numbers enclosed in a input `DataCollection` for `PlusCalculator.parameters[\"plus_times\"].value` times. The reference dictionary\n",
    "of python objects `data_dict` is passed to the corresponding `NumberData` in the auto-initialized `self.output: DataCollection` by\n",
    "\n",
    "```py\n",
    "output_data.set_dict(data_dict)\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "58bc131d-cdc5-4a11-9ffc-5198660fc93d",
   "metadata": {
    "tags": []
   },
   "source": [
    "Let's create an instance from the class:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "1b49d8e6-e6dd-4410-b9ee-f8a01b46e0c3",
   "metadata": {},
   "outputs": [],
   "source": [
    "input1 = NumberData.from_dict({\"number\": 1}, \"input1\")\n",
    "input2 = NumberData.from_dict({\"number\": 1}, \"input2\")\n",
    "calculator_plus = PlusCalculator(name=\"test\",input=[input1,input2])"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "48a802d8-a0f0-40b4-b488-af470d050e6d",
   "metadata": {
    "jp-MarkdownHeadingCollapsed": true,
    "tags": []
   },
   "source": [
    "Check available parameters of it:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "id": "89b5a666-8bce-4af8-a2cb-7e4a98f62887",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      " - Parameters object -\n",
      "plus_times                          1                               How many times to do the plus   \n",
      "\n"
     ]
    }
   ],
   "source": [
    "print(calculator_plus.parameters)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ebe6a766-7956-4ffd-b55a-c4cd201eb1a8",
   "metadata": {},
   "source": [
    "Run the calculator with default parameters"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "id": "8efbe1b4-026f-41b6-8ea2-661e4529a8c8",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{'number': 2.0}\n"
     ]
    }
   ],
   "source": [
    "result = calculator_plus.backengine()\n",
    "print(result.get_data())"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "32bb6c82-19ba-4f6a-b987-0fb2e54ad6e3",
   "metadata": {},
   "source": [
    "Modify the parameter and see the difference:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "id": "33117ed3-701e-4bc2-93e3-fa827dc31cd5",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{'number': 6.0}\n"
     ]
    }
   ],
   "source": [
    "calculator_plus.parameters[\"plus_times\"] = 5\n",
    "print(calculator_plus.backengine().get_data())"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5f0f6daa-1fef-4e2d-a65d-bf30aed1ff3b",
   "metadata": {},
   "source": [
    "### Define a Calculator with native file output"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "id": "abecee9d-b450-469d-86c0-8e2f1e4a7049",
   "metadata": {},
   "outputs": [],
   "source": [
    "from typing import Union\n",
    "from pathlib import Path\n",
    "import numpy as np\n",
    "from libpyvinyl.BaseData import DataCollection\n",
    "from libpyvinyl.BaseCalculator import BaseCalculator, CalculatorParameters\n",
    "\n",
    "\n",
    "class MinusCalculator(BaseCalculator):\n",
    "    def __init__(\n",
    "        self,\n",
    "        name: str,\n",
    "        input: Union[DataCollection, list, NumberData],\n",
    "        output_keys: Union[list, str] = [\"minus_result\"],\n",
    "        output_data_types=[NumberData],\n",
    "        output_filenames: Union[list, str] = [\"minus_result.txt\"],\n",
    "        instrument_base_dir=\"./\",\n",
    "        calculator_base_dir=\"MinusCalculator\",\n",
    "        parameters=None,\n",
    "    ):\n",
    "        \"\"\"A python object calculator example\"\"\"\n",
    "        super().__init__(\n",
    "            name,\n",
    "            input,\n",
    "            output_keys,\n",
    "            output_data_types=output_data_types,\n",
    "            output_filenames=output_filenames,\n",
    "            instrument_base_dir=instrument_base_dir,\n",
    "            calculator_base_dir=calculator_base_dir,\n",
    "            parameters=parameters,\n",
    "        )\n",
    "\n",
    "    def init_parameters(self):\n",
    "        parameters = CalculatorParameters()\n",
    "        times = parameters.new_parameter(\n",
    "            \"minus_times\", comment=\"How many times to do the minus\"\n",
    "        )\n",
    "        times.value = 1\n",
    "        self.parameters = parameters\n",
    "\n",
    "    def backengine(self):\n",
    "        Path(self.base_dir).mkdir(parents=True, exist_ok=True)\n",
    "        input_num0 = self.input.to_list()[0].get_data()[\"number\"]\n",
    "        input_num1 = self.input.to_list()[1].get_data()[\"number\"]\n",
    "        output_num = float(input_num0) - float(input_num1)\n",
    "        if self.parameters[\"minus_times\"].value > 1:\n",
    "            for i in range(self.parameters[\"minus_times\"].value - 1):\n",
    "                output_num -= input_num1\n",
    "        arr = np.array([output_num])\n",
    "        file_path = self.output_file_paths[0]\n",
    "        np.savetxt(file_path, arr, fmt=\"%.3f\")\n",
    "        key = self.output_keys[0]\n",
    "        output_data = self.output[key]\n",
    "        output_data.set_file(file_path, TXTFormat)\n",
    "        return self.output"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "95eb1531-e76d-460e-bbbd-22aa5fe9a873",
   "metadata": {},
   "source": [
    "`MinusCalculator` is the similar to `PlusCalculator` except its output_data is a `NumberData` mapping to `TXTFormat` instead of python object.\n",
    "\n",
    "The simulation results can be obtained in the same way as that of `PlusCalculator`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "id": "287058e2-bc00-48cc-9cce-e1a2824794b1",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{'number': 4.0}\n"
     ]
    }
   ],
   "source": [
    "input1 = NumberData.from_dict({\"number\": 5}, \"input1\")\n",
    "input2 = NumberData.from_dict({\"number\": 1}, \"input2\")\n",
    "calculator_minus = MinusCalculator(name=\"test\",input=[input1,input2])\n",
    "output = calculator_minus.backengine()\n",
    "print(output.get_data())"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3a04e182-0d90-4515-af4b-df7556a63f5f",
   "metadata": {},
   "source": [
    "We can see that `output` is now mapping to a file : "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "id": "68bce03f-7e44-4776-b5d0-b266127edb85",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Data collection:\n",
      "key - mapping\n",
      "\n",
      "minus_result - <class '__main__.TXTFormat'>: MinusCalculator/minus_result.txt\n",
      "\n"
     ]
    }
   ],
   "source": [
    "print(output)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b9a921ad-70bc-4ee3-b972-5eb1120bcae4",
   "metadata": {},
   "source": [
    "If we read the file, we should get the same result."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "id": "87ba42cf-45d0-43b4-8357-ab93263da7d7",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "MinusCalculator/minus_result.txt\n",
      "4.000\n",
      "\n"
     ]
    }
   ],
   "source": [
    "print(output[\"minus_result\"].filename)\n",
    "with open(output[\"minus_result\"].filename,'r') as fh:\n",
    "    print(fh.read())"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d66b1772-75d0-47b1-8c8b-21d1fa259e3d",
   "metadata": {},
   "source": [
    "### Define an instrument\n",
    "We can assmeble a single `PlusMinus` instrument from the two Calculators to sum `input1` and `input2` and then subtract the result with `input2`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "id": "1dbaf841-3e0e-466c-b126-7e8e1e9bc388",
   "metadata": {},
   "outputs": [],
   "source": [
    "from libpyvinyl import Instrument\n",
    "\n",
    "# Create an Instrument with the name PlusMinus\n",
    "calculation_instrument = Instrument(\"PlusMinus\")\n",
    "\n",
    "# Create python object data as input\n",
    "input1 = NumberData.from_dict({\"number\": 1}, \"input1\")\n",
    "input2 = NumberData.from_dict({\"number\": 2}, \"input2\")\n",
    "calculator_plus = PlusCalculator(name=\"Plus\",input=[input1,input2])\n",
    "# The the output of calculator_plus as the input of calculator_minus\n",
    "calculator_minus = MinusCalculator(name=\"Minus\",input=[calculator_plus.output[\"plus_result\"],input2])\n",
    "\n",
    "# Assemble the instrument\n",
    "calculation_instrument.add_calculator(calculator_plus)\n",
    "calculation_instrument.add_calculator(calculator_minus)\n",
    "\n",
    "# Set the base output path of the instrument\n",
    "instrument_path = \"PlusMinus\"\n",
    "calculation_instrument.set_instrument_base_dir(str(instrument_path))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a9c43325-b30d-4bd3-a8f5-23fc4656957d",
   "metadata": {},
   "source": [
    "### Run the instrument"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "id": "e9270701-b200-4192-97e8-063975f96c50",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'number': 1.0}"
      ]
     },
     "execution_count": 17,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# 1+2-2 = 1\n",
    "calculation_instrument.run()\n",
    "calculation_instrument.calculators['Minus'].output.get_data()"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "simex-lite-dev",
   "language": "python",
   "name": "simex-lite-dev"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.8.12"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}