How-To: Experiments

In order to use your WEI-powered automated workcell to run experiments, you will need to write an Experiment Application. This application will be responsible for submitting Workflows to the WEI server to run, logging Events, and retrieving data and results from the system. This guide will walk you through the process of writing an Experiment Application, and show you how to interact with the WEI system to run your experiments.

The ExperimentClient Class

The core of a WEI Experiment Application is the wei.experiment_client.ExperimentClient class. This class provides a convenient interface to the WEI server’s REST API, allowing you to easily create and manage Experiments, submit Workflows, log Events, and retrieve data and results. The ExperimentClient is designed to be easy to use, and provides a number of helper methods to simplify common tasks.

You can either create the client as a normal object, or use it as a context manager.

from wei import ExperimentClient
from wei.types.experiment_types import ExperimentDesign

experiment_design = ExperimentDesign(
    name="ExampleExperiment",
    description="An example experiment"
)

# Create the client as a normal object
experiment_client = ExperimentClient(experiment=experiment_design)

# Use the client as a context manager
with ExperimentClient(experiment=experiment_design) as experiment_client:
    # Do something with the client
    pass

The ExperimentClient class takes a number of different arguments, which allow you to customize its behavior.

  • server_host, which is the hostname or IP address of the WEI server you want to connect to. (Default: “localhost”)

  • server_port, which is the port number of the WEI server you want to connect to. (Default: 8000)

  • experiment, which can be a wei.types.experiment_types.ExperimentDesign object that describes the experiment you want to create, a wei.types.experiment_types.Experiment object to continue an existing experiment, or a string that is the id of an existing experiment you want to attach to.

  • campaign, which can be a wei.types.campaign_types.CampaignDesign object that describes the campaign you want to create, a wei.types.campaign_types.Campaign object to continue an existing campaign, or a string that is the id of an existing campaign you want to attach to.

  • working_dir, which is the directory the client will use for any relative paths to files defined in Workflow definitions (Default: None).

  • email_addresses, which is a list of email addresses to notify for events like step failures. (Default: []).

  • log_experiment_end_on_exit, which is a boolean flag indicating whether to log the end of the experiment when the client’s deconstructor is called. (Default: True). Set to False if you want to manually log the end of the experiment, such as when you know you’ll want to resume the same experiment later.

Using Workflows

You can easily submit workflows with the ExperimentClient by calling the wei.experiment_client.ExperimentClient.start_run() method. This method takes a Workflow definition as a string, and returns a Workflow Run object, which you can use to monitor the progress of the Workflow run and retrieve data points and results.

from pathlib import Path
from wei import ExperimentClient
from wei.types.experiment_types import ExperimentDesign

experiment_design = ExperimentDesign(
    name="ExampleExperiment",
    description="An example experiment"
)

with ExperimentClient(experiment=experiment_design) as experiment_client:

    wf_path = Path("example_workflow.yaml")

    # Submit the Workflow to the Experiment
    wf_run = experiment_client.start_run(
        workflow=wf_path,
        parameters={"param1": 42, "param2": "hello"},
        simulate=False,
        blocking=True,
        raise_on_failed=True,
        raise_on_cancelled=True,
    )


# Retrieve the data generated by the Workflow
datapoint_id = wf_run.get_datapoint_id_by_label("experiment_result")
value = experiment_client.get_datapoint_value(datapoint_id)

print(value)