Skip to content

Operate Nexus

Manually Operated Workstations

If you've chosen a Manually Operated workstation, you can skip this Nexus section.

In this section, we will show you how you can read parameters and return measurements to SDLabs. You can do so manually through the Nexus GUI, using the Nexus Bridge, or using the SDK.

  • The Nexus Bridge is a service to automatically map a local directory to a single Nexus project. You will be able to receive parameter files directly in this local directory instead of having to fetch them from the Nexus platform.
  • The Nexus SDK allows you to fetch and submit files using API calls.

Tip

As you go through this section, you can review the File Formats page on the side.

Nexus Bridge

Nexus Bridge

In order to connect to a Nexus project from your computer, install Nexus On-Premise Bridge: Bridge Installation

  1. Download the installer
  2. Run the downloaded file, if a blue warning pop-up appears, click on "More info" and "Run anyway"
  3. Install and open the application.
  1. Download the installer (ARM64)
  2. Install and open the application.
  1. Download the installer
  2. Move the downloaded file to your application's folder (or use AppImageLauncher)
  3. Right-click on it, Properties -> Permissions -> Allow executing file as program
  4. Open the application.

Tutorial: Use a custom workstation through the Nexus Bridge

  1. Create a folder where you will store all your workstations, for example: /home/my_user/nexus_workstations

  2. For each new project, create its corresponding directory in the previously created folder, e.g. /home/my_user/nexus_workstations/My First Project. Inside of it, create two folders: parameters and measurements, and a file named workstation.py.

  3. Inside the Nexus On-Premise Bridge, edit your project and make it point to the directories you just created, and enable it.

This tool will download the parameters provided by the optimizer to the desired location, e.g. /home/my_user/nexus_workstations/My First Project/parameters, you then need to fill the file with the experiment's measurements and push this file into the other folder, e.g. /home/my_user/nexus_workstations/My First Project/measurements, and the Nexus Bridge will automatically forward it to the Nexus platform. Please review the File type and format for more info on how to add the measurements.

Here is a sample of what workstation.py would look like for our experiment:

Modify this script

  • Edit the parts noted as EDIT HERE;

Mocking reactions

To keep this example simple, our reactions are defined as the following:

  • yield = (Reagent A) * 2
  • selectivity = (Reagent B) / 2
# Import libraries
from time import sleep
from glob import glob
import os
import yaml # pip install pyyaml

# EDIT HERE; These have to be the same as defined in the Nexus Bridge project settings
PARAMETERS_PATH = "/home/user/nexus_workstations/.../parameters"
MEASUREMENTS_PATH = "/home/user/nexus_workstations/.../measurements"

SLEEP_TIME = 2 # in seconds

while True:
    # Start by waiting the SLEEP_TIME
    sleep(SLEEP_TIME)

    # Retreive new parameter files
    PARAM_FILES = glob(f"{PARAMETERS_PATH}/*")

    # No parameter file is present, skip
    if len(PARAM_FILES) < 1:
        continue

    # Parameter file is present
    FILE_PATH = PARAM_FILES[0]
    with open(FILE_PATH) as f: 
        # Parse parameter file
        data = yaml.safe_load(f.read())
        data["properties"] = {}

    # EDIT HERE, Process parameters and return measurements
    data["properties"]["yield"] = data["processes"]["Reagent A"] * 2
    data["properties"]["selectivity"] = data["processes"]["Reagent B"] / 2

    # Write the results in measurement path
    with open(f"{MEASUREMENTS_PATH}/{os.path.basename(FILE_PATH)}", "w+") as f:
        f.write(yaml.safe_dump(data))

    # Remove parameter file so we don't process it again
    os.remove(FILE_PATH)

Run the script from a CLI, or run it as a service: 

python3 /home/user/nexus_workstations/.../workstation.py

Nexus SDK

SDK

You need to install the Nexus SDK in the programming language of your choice. Here we will do an overview with a Python implementation.

Installation

Warning

Please ensure you have a virtual environment already activated!

Install the sdk directly from the public github repository. (Info regarding the installation and API calls is also in the README.md file of the repository)

pip install git+https://github.com/Atinary-technologies/nexus_sdk.git

Use custom workstation through Nexus SDK

This tutorial notebook uses Atinary Nexus SDK (downloadable at https://github.com/Atinary-technologies/nexus_sdk ) to simulate a laboratory workstation. This example does the link between a Nexus workstation in SDLabs and your actual laboratory workstation.

For our example, the workstation only does a sum of the two parameters x0 and x1 which is returned inside y measurement in yaml format.

Important

  • You should have already a general grasp of the Nexus service (see Nexus Overview).
  • You should have already started a campaign that uses a custom workstation manually or through the SDK (see the SDLabs SDK and the Nexus custom workstations tutorials).

Configure API and authorization

Users must add their Atinary API key in the indicated location. Please add your API key and then run the following cell. 

# import dependencies
import time
import pathlib
from pprint import pprint
import yaml # pyyaml package
import tempfile

# Nexus SDK (downloadable at https://github.com/Atinary-technologies/nexus_sdk)
import nexus_sdk

API_KEY = # TODO: add your API-KEY here

configuration = nexus_sdk.Configuration(
    host = "https://enterprise.atinary.com/nexus/latest/",
    api_key = {
        'api_key': API_KEY,
    }
)
configuration.access_token = None  # temporary fix when using the SDK

api_client = nexus_sdk.ApiClient(configuration)
projects_api = nexus_sdk.ProjectsApi(api_client)

Get Nexus project created from SDLabs

When you create a workstation inside SDLabs that will communicate through Nexus (see the Nexus custom workstation tutorial), SDLabs may generate a Nexus project named after your workstation, if no nexus_project_name was given in the workstation connection attributes. 

# Wait that SDLabs creates a nexus project.

NEXUS_PROJECT_NAME = # TODO: add the nexus project name previously entered when creating the workstation.
projects = {}

SLEEP_TIME = 10

while NEXUS_PROJECT_NAME not in projects:
    print('Waiting for project creation at Nexus level...')
    projects = {
        obj.name: obj.id
        for obj in projects_api.list_projects().objects
    }
    # Sleep for SLEEP_TIME seconds before retrying.
    # This avoids to overload Atinary Nexus product with queries.
    time.sleep(SLEEP_TIME)

# Retrieve project id
project_id = projects[NEXUS_PROJECT_NAME]
print(f'Atinary Nexus project found with id: {project_id}')

Process parameter files and produce measurement files

When you launch a campaign on SDLabs that uses a custom workstation, a new parameters file will appear in the Nexus project associated to the workstation. Each time there is at least one new parameters file in the project corresponding to your on-going campaign, please do the following:

Steps

  1. Download parameters file
  2. Execute workstation step (i.e. perform the experiment) to build a response file (properties file, containing the measurements).
  3. Upload the properties file on the same Nexus project with the same name as the parameters file.
  4. Delete the parameters file, since it has already been processed.
  5. Wait for the next parameters file (containing new parameters suggestions) to be generated by the platform.
  6. Go back to step 1.
SLEEP_TIME = 10

try:
    # Create API file client
    files_api = nexus_sdk.FilesApi(api_client)

    while True:
        time.sleep(SLEEP_TIME)
        print(f'Checking for new files in Atinary Nexus project {NEXUS_PROJECT_NAME}...')

        # Create
        for param_file in files_api.list_files(
            group_type='parameters', project_id=project_id
        ).objects:

            print(f'Parameter file found {param_file.id}:{param_file.name}')

            file_path = pathlib.Path(
                files_api.download_file(file_id=param_file.id)
            )

            # reading the file
            with open(file_path, 'r') as content:
                data = yaml.safe_load(content)

                # Example data file format received:
                # {
                #     'campaign_id': 'campaign_id',
                #     'id': 'request_id',
                #     'workstation_id': 'workstation_id',
                #     'processes': {'x0': x0_value, 'x1': x1_value}
                # }

            print(f'Parameter downloaded {param_file.id}:{param_file.name} with data: {data}')

            # Process parameters x0 and x1 to fill y measurement.
            data["properties"] = {"y": sum(data['processes'].values())}

            # If your executed parameters are different from those proposed, 
            # you can update "properties" with the new values.

            # Creation of response file
            response_file = pathlib.Path(f'{tempfile.gettempdir()}/{param_file.name}')
            with open(response_file, 'w') as content:
                yaml.dump(data, content)

            # Uploading the file
            files_api.upload_file(
                project_id,
                'properties',
                str(response_file.resolve())
            )
            print(f'Properties uploaded {param_file.id}:{param_file.name}')

            # Remove the temporary file and the parameter file processed in Nexus.
            response_file.unlink()
            files_api.delete_file(param_file.id)
            print(f'Parameter file deleted {param_file.id}:{param_file.name}')

except nexus_sdk.ApiException as exc:
    pprint(exc)
    raise exc

Next steps

Now that you have successfully connected your workstation and used it to read parameters and send measurements, you can go to the Analytics Module to visualize the data from your campaign.