Skip to content

Creating a custom NEXUS workstation

Note

Please note that this page shows you how to create the same workstation as the API Workstation page, except that it will use NEXUS file exchange instead of API calls.

To implement Atinary SDLabs on your own robots or processes, you can create your custom workstation objects. A workstation executes tasks provided by the optimizer.

Pre-requisites

Real Robot Example

Let us assume that our physical workstation is a robot that runs the following catalyzed chemical reaction: A+B -> C+D

Robot parameters

  • Fraction of A [0.0 - 1.0]
  • Fraction of B [0.0 - 1.0]
  • Catalyst type which can be (\(\alpha\), \(\beta\) or \(\gamma\))
  • Catalyst amount (1 to 10 catalyst units)

Robot measurements

  • Reaction yield (i.e. how much of desired product C is produced)
  • Reaction selectivity (i.e. how much of desired product C is produced relative to undesired by-product D)

Here, A and B are reactants and C is the desired product. D is a by-product. These should be modified to match your experimental setup.

Workstation in SDLabs

We will now create our robot according to the provided information. To define a workstation, we need to define metadata, parameters (instructions) and measurements.

Metadata

wst_name = 'My Chemistry Robot'
wst_description = 'Robot runs reaction A+B->C+D. It measures the reaction yield and selectivity.'
wst_bandwidth = 1  # Optional limit, stating that the Robot can only run 1 reaction at a time

Connection

If you want to use files to exchange parameters and measurements between the robot and the platform, please also read the Nexus documentation page and create a "Connection" object as follows: 

# Defining the Nexus connection to the workstation
wst_connection = sct.ConnectConfigNexusObj(
    format=sct.FileFormat.YML,
    nexus_project_name=wst_name,  # easier to keep the same name as the workstation
    user_api_key=API_KEY  # an API key that is valid in your group, so that the workstation may be authenticated onto the Nexus module
)

Parameters

We can have numerical (continuous or discrete) and categorical parameters. Let's create your workstation's parameters:

Continuous Parameters

Define the amounts of reactants A and B as fractions ranging from 0.0 to 1.0.

prm_a = sct.ParameterObj(
    name='fraction_a',
    description='Fraction of reactant A',
    type='continuous',
    high_value=1.0,
    low_value=0.0
)

prm_b = sct.ParameterObj(
    name='fraction_b',
    description='Fraction of reactant B',
    type='continuous',
    high_value=1.0,
    low_value=0.0
)

Categorical Parameter

Define the catalyst type categorical parameter. We can also record category properties such as the catalyst particle size, which is different for each category.

prm_cat_type = sct.ParameterObj(
    name='catalyst_type',
    description='Catalyst type',
    type='categorical',
    descriptors = [
        {
            'category': 'alpha',
            'properties': [{'key': 'particle size', 'value': 0.4}]
        },
        {
            'category': 'beta',
            'properties': [{'key': 'particle size', 'value': 0.76}]
        },
        {
            'category': 'gamma',
            'properties': [{'key': 'particle size', 'value': 1.23}]
        }
    ]
)

Warning

The properties attribute is an array of key-value pairs. The value field of each pair should always be numerical (as seen in the example). Properties are optional, but if they are defined for one category, they must be set for all the categories of that parameter.

Discrete Parameter

Define the amount of catalyst as a discrete parameter ranging from 0 to 10 in strides of 1 unit.

prm_cat_amt = sct.ParameterObj(
    name='catalyst_amount',
    description='Catalyst amount',
    type='discrete',
    high_value=10.0,
    low_value=0.0,
    stride=1.0
)

Create Parameters in SDLabs

Now that we have created the base parameters objects, we can save them using the ParameterApi.parameter_create() method, which will return the parameters with their id.

wst_params = [
    prm_api.parameter_create(parameter_obj=prm).object
    for prm in [prm_a, prm_b, prm_cat_type, prm_cat_amt]
]

Measurements

Measurements are modelled as an array of strings: 

wst_measurements = ['yield', 'selectivity']

Create Workstation in SDLabs

my_wst = wst_api.workstation_create(
    workstation_obj=sct.WorkstationObj(
        name=wst_name,
        description=wst_description,
        conn_type=sct.ConnectionType.NEXUS,
        connection=wst_connection,
        bandwidth=wst_bandwidth,
        measurements=wst_measurements,
        parameters=[p.id for p in wst_params]
    )
).object

You can now check on your Nexus Dashboard that there is a new project associated to your workstation.

Next Steps

  • You can now create a new template that uses this workstation in SDLabs.
  • Once you have created a template and run a campaign associated to this workstation, follow the Nexus tutorial to find out more about how to read parameters and send measurements back to SDLabs via the NEXUS file exchange module.