Execute and Simulate

execute ¶

opentrons.execute: functions and entrypoint for running protocols

This module has functions that can be imported to provide protocol contexts for running protocols during interactive sessions like Jupyter or just regular python shells. It also provides a console entrypoint for running a protocol from the command line.

execute ¶

execute(protocol_file, protocol_name, propagate_logs=False, log_level='warning', emit_runlog=None, custom_labware_paths=None, custom_data_paths=None)

Run the protocol itself.

This is a one-stop function to run a protocol, whether python or json, no matter the api version, from external (i.e. not bound up in other internal server infrastructure) sources.

To run an opentrons protocol from other places, pass in a file like object as protocol_file; this function either returns (if the run has no problems) or raises an exception.

To call from the command line use either the autogenerated entrypoint opentrons_execute or python -m opentrons.execute.

Parameters:

protocol_file (Union[BinaryIO, TextIO]) –

The protocol file to execute.
protocol_name (str) –

The name of the protocol file. This is required internally, but it may not be a thing we can get from the protocol_file argument.
propagate_logs (bool, default: False ) –

Whether this function should allow logs from the Opentrons stack to propagate up to the root handler. This can be useful if you're integrating this function in a larger application, but most logs that occur during protocol simulation are best associated with the actions in the protocol that cause them. Default: False.
log_level (str, default: 'warning' ) –

The level of logs to emit on the command line: "debug", "info", "warning", or "error". Defaults to "warning".
emit_runlog (Optional[_EmitRunlogCallable], default: None ) –
A callback for printing the run log. If specified, this will be called whenever a command adds an entry to the run log, which can be used for display and progress estimation. If specified, the callback should take a single argument (the name doesn't matter) which will be a dictionary:
```
{
    'name': command_name,
    'payload': {
        'text': string_command_text,
        # The rest of this struct is
        # command-dependent; see `commands`.
    }
}
```
Note

In older software versions, payload["text"] was a format string. To get human-readable text, you had to do payload["text"].format(**payload). Don't do that anymore. If payload["text"] happens to contain any { or } characters, it can confuse .format() and cause it to raise a KeyError.
custom_labware_paths (Optional[List[str]], default: None ) –

A list of directories to search for custom labware. Loads valid labware from these paths and makes them available to the protocol context. If this is None (the default), and this function is called on a robot, it will look in the labware subdirectory of the Jupyter data directory.
custom_data_paths (Optional[List[str]], default: None ) –

A list of directories or files to load custom data files from. Ignored if the apiv2 feature flag is not set. Entries may be either files or directories. Specified files and the non-recursive contents of specified directories are presented by the protocol context in ProtocolContext.bundled_data.

get_arguments ¶

get_arguments(parser)

Get the argument parser for this module.

Useful if you want to use this module as a component of another CLI program and want to add its arguments.

Parameters:

parser (ArgumentParser) –

A parser to add arguments to.

Returns:

ArgumentParser –

argparse.ArgumentParser: The parser with arguments added.

get_protocol_api ¶

get_protocol_api(version, bundled_labware=None, bundled_data=None, extra_labware=None)

Build and return a protocol_api.ProtocolContext connected to the robot.

This can be used to run protocols from interactive Python sessions such as Jupyter or an interpreter on the command line:

from opentrons.execute import get_protocol_api
protocol = get_protocol_api('2.0')
instr = protocol.load_instrument('p300_single', 'right')
instr.home()

When this function is called, modules and instruments will be recached.

Parameters:

version (Union[str, APIVersion]) –

The API version to use. This must be lower than opentrons.protocol_api.MAX_SUPPORTED_VERSION. It may be specified either as a string ('2.0') or as a APIVersion (APIVersion(2, 0)).
bundled_labware (Optional[Dict[str, LabwareDefinition]], default: None ) –

If specified, a mapping from labware names to labware definitions for labware to consider in the protocol. Note that if you specify this, only labware in this argument will be allowed in the protocol. This is preparation for a beta feature and is best not used.
bundled_data (Optional[Dict[str, bytes]], default: None ) –

If specified, a mapping from filenames to contents for data to be available in the protocol from bundled_data.
extra_labware (Optional[Dict[str, LabwareDefinition]], default: None ) –

A mapping from labware load names to custom labware definitions. If this is None (the default), and this function is called on a robot, it will look for labware in the labware subdirectory of the Jupyter data directory.

Returns:

ProtocolContext –

The protocol context.

main ¶

main()

Handler for command line invocation to run a protocol.

The arguments the program was invoked with are usually sys.argv but if you want to override that you can.

Returns:

int ( int ) –

A success or failure value suitable for use as a shell return code passed to sys.exit (0 means success, anything else is a kind of failure).

simulate ¶

opentrons.simulate: functions and entrypoints for simulating protocols

This module has functions that provide a console entrypoint for simulating a protocol from the command line.

allow_bundle ¶

allow_bundle()

Check if bundling is allowed with a special not-exposed-to-the-app flag.

Returns True if the environment variable OT_API_FF_allowBundleCreation is "1"

bundle_from_sim ¶

bundle_from_sim(protocol, context)

From a protocol, and the context that has finished simulating that protocol, determine what needs to go in a bundle for the protocol.

format_runlog ¶

format_runlog(runlog)

Format a run log (return value of simulate()) into a human-readable string.

Parameters:

runlog (List[Mapping[str, Any]]) –

The output of a call to simulate().

get_arguments ¶

get_arguments(parser)

Get the argument parser for this module.

Useful if you want to use this module as a component of another CLI program and want to add its arguments.

Parameters:

parser (ArgumentParser) –

A parser to add arguments to. If not specified, one will be created.

Returns:

ArgumentParser –

argparse.ArgumentParser: The parser with arguments added.

get_protocol_api ¶

get_protocol_api(version, bundled_labware=None, bundled_data=None, extra_labware=None, hardware_simulator=None, *, robot_type=None, use_virtual_hardware=True)

Build and return a protocol_api.ProtocolContext that simulates robot control.

This can be used to simulate protocols from interactive Python sessions such as Jupyter or an interpreter on the command line:

from opentrons.simulate import get_protocol_api
protocol = get_protocol_api('2.0')
instr = protocol.load_instrument('p300_single', 'right')
instr.home()

Parameters:

version (Union[str, APIVersion]) –

The API version to use. This must be lower than opentrons.protocol_api.MAX_SUPPORTED_VERSION. It may be specified either as a string ('2.0') or as a APIVersion (APIVersion(2, 0)).
bundled_labware (Optional[Dict[str, LabwareDefinition]], default: None ) –

If specified, a mapping from labware names to labware definitions for labware to consider in the protocol. Note that if you specify this, only labware in this argument will be allowed in the protocol. This is preparation for a beta feature and is best not used.
bundled_data (Optional[Dict[str, bytes]], default: None ) –

If specified, a mapping from filenames to contents for data to be available in the protocol from bundled_data.
extra_labware (Optional[Dict[str, LabwareDefinition]], default: None ) –

A mapping from labware load names to custom labware definitions. If this is None (the default), and this function is called on a robot, it will look for labware in the labware subdirectory of the Jupyter data directory.
hardware_simulator (Optional[ThreadManagedHardware], default: None ) –

This is only for internal use by Opentrons. If specified, it's a hardware simulator instance to reuse instead of creating a fresh one.
robot_type (Optional[_UserSpecifiedRobotType], default: None ) –

The type of robot to simulate: either "Flex" or "OT-2". If you're running this function on a robot, the default is the type of that robot. Otherwise, the default is "OT-2", for backwards compatibility.
use_virtual_hardware (bool, default: True ) –

This is only for internal use by Opentrons. If True, use the Protocol Engine's virtual hardware. If False, use the lower level hardware simulator.

Returns:

ProtocolContext –

The protocol context.

main ¶

main()

Run the simulation

simulate ¶

simulate(protocol_file, file_name=None, custom_labware_paths=None, custom_data_paths=None, propagate_logs=False, hardware_simulator_file_path=None, duration_estimator=None, log_level='warning')

Simulate the protocol itself.

This is a one-stop function to simulate a protocol, whether Python or JSON, no matter the API version, from external (i.e. not bound up in other internal server infrastructure) sources.

To simulate an opentrons protocol from other places, pass in a file-like object as protocol_file; this function either returns (if the simulation has no problems) or raises an exception.

To call from the command line, use either the autogenerated entrypoint opentrons_simulate (opentrons_simulate.exe, on Windows) or python -m opentrons.simulate.

The return value is the run log, a list of dicts that represent the commands executed by the robot; and either the contents of the protocol that would be required to bundle, or None.

Each dict element in the run log has the following keys:

level: The depth at which this command is nested. If this is an aspirate inside a mix inside a transfer, for instance, it would be 3.
payload: The command. The human-readable run log text is available at payload["text"]. The other keys of payload are command-dependent; see opentrons.legacy_commands.

Note

In older software versions, payload["text"] was a format string. To get human-readable text, you had to do payload["text"].format(**payload). Don't do that anymore. If payload["text"] happens to contain any { or } characters, it can confuse .format() and cause it to raise a KeyError.
logs: Any log messages that occurred during execution of this command, as a standard Python LogRecord.

Parameters:

protocol_file (Union[BinaryIO, TextIO]) –

The protocol file to simulate.
file_name (Optional[str], default: None ) –

The name of the file.
custom_labware_paths (Optional[List[str]], default: None ) –

A list of directories to search for custom labware. Loads valid labware from these paths and makes them available to the protocol context. If this is None (the default), and this function is called on a robot, it will look in the labware subdirectory of the Jupyter data directory.
custom_data_paths (Optional[List[str]], default: None ) –

A list of directories or files to load custom data files from. Ignored if the apiv2 feature flag is not set. Entries may be either files or directories. Specified files and the non-recursive contents of specified directories are presented by the protocol context in bundled_data.
hardware_simulator_file_path (Optional[str], default: None ) –

A path to a JSON file defining the simulated hardware. This is mainly for internal use by Opentrons, and is not necessary to simulate protocols.
duration_estimator (Optional[DurationEstimator], default: None ) –

For internal use only. Optional duration estimator object.
propagate_logs (bool, default: False ) –

Whether this function should allow logs from the Opentrons stack to propagate up to the root handler. This can be useful if you're integrating this function in a larger application, but most logs that occur during protocol simulation are best associated with the actions in the protocol that cause them. Default: False.
log_level (str, default: 'warning' ) –

The level of logs to capture in the run log: "debug", "info", "warning", or "error". Defaults to "warning".

Returns:

_SimulateResult –

A tuple of a run log for user output, and possibly the required data to write to a bundle to bundle this protocol. The bundle is only emitted if bundling is allowed and this is an unbundled Protocol API v2 Python protocol. In other cases it is None.