Quick start guide

First time set-up

Note

This section assumes that tomato has been successfully installed.

To prepare tomato for its first execution, you need to supply additional information configuring the package. The easiest way to do this is to execute tomato in verbose mode:

 PS C:\Users\krpe> tomato -vv
 DEBUG:tomato.main:loglevel set to 'DEBUG'
 DEBUG:tomato.setlib.functions:local config folder is 'C:\Users\krpe\AppData\Local\dgbowl\tomato\0.2a1'
 DEBUG:tomato.setlib.functions:local data folder is 'C:\Users\krpe\AppData\Local\dgbowl\tomato\0.2a1'
 DEBUG:tomato.setlib.functions:local log folder is 'C:\Users\krpe\AppData\Local\dgbowl\tomato\0.2a1\Logs'
 WARNING:tomato.setlib.functions:config file not present. Writing defaults to 'C:\Users\krpe\AppData\Local\dgbowl\tomato\0.2a1\settings.toml'
 ...

As you see on line 3 in this verbose output, tomato is configured to store its local configuration data in a user-accessible folder:

$env:localappdata\dgbowl\tomato\<version> on Windows,

$HOME/.config/<version> on Linux.

Within this local config folder, tomato expects to find at least the Settings file (settings.toml).

As you can also see from the log, on Windows the local data folder is by default also set to the same path, therefore all of tomato’s information (device settings, state and queue tables, job data) will be located in this versioned folder.

Settings file

The settings file named settings.toml has to be located in the local config folder. The default file generated by the first run of tomato -vv above looks similar to the below file:

 [state]
 type = 'sqlite3'
 path = 'C:\Users\krpe\AppData\Local\dgbowl\tomato\0.1rc11\database.db'

 [queue]
 type = 'sqlite3'
 path = 'C:\Users\krpe\AppData\Local\dgbowl\tomato\0.1rc11\database.db'
 storage = 'C:\Users\krpe\AppData\Local\dgbowl\tomato\0.1rc11\Jobs'

 [devices]
 path = 'C:\Users\krpe\AppData\Local\dgbowl\tomato\0.1rc11\devices.yml'

 [drivers]
 [drivers.biologic]
 dllpath = 'C:\EC-Lab Development Package\EC-Lab Development Package'

The sections [state] and [queue] contain the path of the database containing the state and queue tables, as well as the database type. For queue, the storage entry points to the folder where the raw data generated by jobs will be stored.

Note

As of tomato-0.2a1, only sqlite3 is supported as a database type.

The [devices] section within the settings.toml file points to a yaml-formatted Devices file, defining the hardware configuration of the devices managed by tomato.

Additional, driver-specific settings (such as the dllpath required by the biologic driver) may be provided in the [drivers] section.

Devices file

This yaml-formatted file contains information about each device, corresponding to an individual piece of hardware managed by tomato, as well as information about the organisation of such devices into addressable chunks, called pipelines. The pipelines can be thought of as digital twins of experimental set-ups, and should contain all devices required to carry out a payload (see Payload file).

devices section

 devices:
   - name: MPG2-8
     address: "192.109.209.8"
     channels: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16]
     driver: "biologic"
     pollrate: 60
     capabilities:
       - open_circuit_voltage
       - constant_current
       - constant_voltage
       - sweep_current
       - sweep_voltage
       - loop

In the example devices section above, we define a single BioLogic MPG2 potentiostat. Each entry in this section has to define the name of the instrument, the address and channels available and used for connecting to the instrument, the driver with which tomato will manage this device, the pollrate specifying the polling frequency with which the tomato daemon queries the worker job for data, and finally a list of the capabilities this device supports.

Note

The pollrate here is an internal setting for tomato and defaults to 10 s. It is the frequency with which the job daemon supervising the device asks the driver for new data, not the frequency with which the driver asks the hardware for data!

pipelines section

 pipelines:
   - name: MPG2-7-10
     devices:
       - tag: MPG2
         name: MPG2-7
         channel: 10
   - name: MPG2-8-*
     devices:
       - tag: MPG2
         name: MPG2-8
         channel: each

In the example pipelines section above, we show two ways of defining pipelines in tomato. In the first entry on lines 2-6, we define a pipeline by its name, and assign a list of devices into it, identified within the pipeline by their tag, and matched against the devices section using the name and channel.

Alternatively, for multi-channel devices, such as the MPG2-8 defined in the example above, a shorthand for defining a pipeline for each channel is shown in the second entry. The pipeline name will be generated by replacing the * with each channel.

Multiple devices can be combined into a single pipeline using the above syntax.

Payload file

The payload file contains all information required to enter a job into the queue. The overall schema of the payload is defined in the dgbowl_schemas.tomato module, and is parsed using dgbowl_schemas.tomato.to_payload():

pydantic model dgbowl_schemas.tomato.payload_0_2.Payload

Show JSON schema

{
   "title": "Payload",
   "type": "object",
   "properties": {
      "version": {
         "title": "Version",
         "enum": [
            "0.2"
         ],
         "type": "string"
      },
      "tomato": {
         "$ref": "#/definitions/Tomato"
      },
      "sample": {
         "$ref": "#/definitions/Sample"
      },
      "method": {
         "title": "Method",
         "type": "array",
         "items": {
            "$ref": "#/definitions/Method"
         }
      }
   },
   "required": [
      "version",
      "sample",
      "method"
   ],
   "additionalProperties": false,
   "definitions": {
      "Output": {
         "title": "Output",
         "description": "Provide the ``path`` and ``prefix`` for the final FAIR-data archive of the *job*.",
         "type": "object",
         "properties": {
            "path": {
               "title": "Path",
               "type": "string"
            },
            "prefix": {
               "title": "Prefix",
               "type": "string"
            }
         },
         "additionalProperties": false
      },
      "Snapshot": {
         "title": "Snapshot",
         "description": "Provide the ``frequency``, ``path`` and ``prefix`` to configure the snapshotting\nfunctionality of tomato.",
         "type": "object",
         "properties": {
            "path": {
               "title": "Path",
               "type": "string"
            },
            "prefix": {
               "title": "Prefix",
               "type": "string"
            },
            "frequency": {
               "title": "Frequency",
               "default": 3600,
               "type": "integer"
            }
         },
         "additionalProperties": false
      },
      "Tomato": {
         "title": "Tomato",
         "description": "Specification of *job* configuration for tomato.",
         "type": "object",
         "properties": {
            "unlock_when_done": {
               "title": "Unlock When Done",
               "default": false,
               "type": "boolean"
            },
            "verbosity": {
               "title": "Verbosity",
               "default": "WARNING",
               "enum": [
                  "DEBUG",
                  "INFO",
                  "WARNING",
                  "ERROR",
                  "CRITICAL"
               ],
               "type": "string"
            },
            "output": {
               "$ref": "#/definitions/Output"
            },
            "snapshot": {
               "$ref": "#/definitions/Snapshot"
            }
         },
         "additionalProperties": false
      },
      "Sample": {
         "title": "Sample",
         "description": "Additional attributes for each :class:`Sample` may be required, depending on the\n:class:`Method` type.",
         "type": "object",
         "properties": {
            "name": {
               "title": "Name",
               "type": "string"
            }
         },
         "required": [
            "name"
         ]
      },
      "Method": {
         "title": "Method",
         "description": "The :class:`Method` schema is completely *device*- and ``technique``- dependent,\nwith extra arguments required by each ``technique`` defined by each device driver.",
         "type": "object",
         "properties": {
            "device": {
               "title": "Device",
               "type": "string"
            },
            "technique": {
               "title": "Technique",
               "type": "string"
            }
         },
         "required": [
            "device",
            "technique"
         ]
      }
   }
}