API Reference

If you are reading this, you are probably looking for an in-depth explanation of API classes and methods to fully master your protocol development skills.

Robot

All protocols are set up, simulated and executed using a Robot class.

class robot.Robot(config=None, broker=None)

This class is the main interface to the robot.

It should never be instantiated directly; instead, the global instance may be accessed at opentrons.robot.

Through this class you can can:

Each Opentrons protocol is a Python script. When evaluated the script creates an execution plan which is stored as a list of commands in Robot’s command queue.

Here are the typical steps of writing the protocol:

  • Using a Python script and the Opentrons API load your containers and define instruments (see Pipette).

  • Call reset() to reset the robot’s state and clear commands.

  • Write your instructions which will get converted into an execution plan.

  • Review the list of commands generated by a protocol commands().

  • connect() to the robot and call run() it on a real robot.

See Pipette for the list of supported instructions.

add_instrument(self, mount, instrument)

Adds instrument to a robot.

Parameters:

  • mount (str) – Specifies which axis the instruments is attached to. Valid options are “left” or “right”.

  • instrument (Instrument) – An instance of a Pipette to attached to the axis.

Notes

A canonical way to add to add a Pipette to a robot is:

from opentrons import instruments
m300 = instruments.P300_Multi(mount='left')

This will create a pipette and call add_instrument() to attach the instrument.

connect(self, port=None, options=None)

Connects the robot to a serial port.

Parameters:

  • port (str) – OS-specific port name or 'Virtual Smoothie'

  • options (dict) – if port is set to 'Virtual Smoothie', provide the list of options to be passed to get_virtual_device()

Return type:

True for success, False for failure.

Notes

If you wish to connect to the robot without using the OT App, you will need to use this function.

Examples

>>> from opentrons import robot 
>>> robot.connect()
disconnect(self)

Disconnects from the robot.

get_warnings(self)

Get current runtime warnings.

Returns:

  • Runtime warnings accumulated since the last run()

  • or simulate().

head_speed(self, combined_speed=None, x=None, y=None, z=None, a=None, b=None, c=None)

Set the speeds (mm/sec) of the robot

Parameters:

  • combined_speed (number specifying a combined-axes speed) –

  • <axis> (key/value pair, specifying the maximum speed of that axis) –

Examples

>>> from opentrons import robot 
>>> robot.reset() 
>>> robot.head_speed(combined_speed=400) 
#  sets the head speed to 400 mm/sec or the axis max per axis
>>> robot.head_speed(x=400, y=200) 
# sets max speeds of X and Y
home(self, \*args, \*\*kwargs)

Home robot’s head and plunger motors.

move_to(self, location, instrument, strategy='arc', \*\*kwargs)

Move an instrument to a coordinate, container or a coordinate within a container.

Parameters:

  • location (one of the following:) – 1. Placeable (i.e. Container, Deck, Slot, Well) — will move to the origin of a container. 2. Vector move to the given coordinate in Deck coordinate system. 3. (Placeable, Vector) move to a given coordinate within object’s coordinate system.

  • instrument – Instrument to move relative to. If None, move relative to the center of a gantry.

  • strategy ({'arc', 'direct'}) –

    arc : move to the point using arc trajectory avoiding obstacles.

    direct : move to the point in a straight line.

pause(self, msg=None)

Pauses execution of the protocol. Use resume() to resume

reset(self)
Resets the state of the robot and clears:

  • Deck

  • Instruments

  • Command queue

  • Runtime warnings

Examples

>>> from opentrons import robot 
>>> robot.reset()
resume(self)

Resume execution of the protocol after pause()

stop(self)

Stops execution of the protocol. (alias for halt)

Pipette

class pipette.Pipette(robot, model_offset=(0, 0, 0), mount=None, axis=None, mount_obj=None, model=None, name=None, ul_per_mm=None, channels=1, min_volume=0, max_volume=None, trash_container='', tip_racks=[], aspirate_speed=5, dispense_speed=10, blow_out_speed=60, aspirate_flow_rate=None, dispense_flow_rate=None, plunger_current=0.5, drop_tip_current=0.5, return_tip_height=None, drop_tip_speed=5, plunger_positions={'blow_out': 0, 'bottom': 2, 'drop_tip': - 3.5, 'top': 18.5}, pick_up_current=0.1, pick_up_distance=10, pick_up_increment=1, pick_up_presses=3, pick_up_speed=30, quirks=[], fallback_tip_length=51.7, blow_out_flow_rate=None, requested_as=None, pipette_id=None)

DIRECT USE OF THIS CLASS IS DEPRECATED – this class should not be used directly. Its parameters, defaults, methods, and behaviors are subject to change without a major version release. Use the model-specific constructors available through from opentrons import instruments.

All model-specific instrument constructors are inheritors of this class. With any of those instances you can can:

Here are the typical steps of using the Pipette:

  • Instantiate a pipette with a maximum volume (uL) and a mount (left or right)

  • Design your protocol through the pipette’s liquid-handling commands

Methods in this class include assertions where needed to ensure that any action that requires a tip must be preceeded by pick_up_tip. For example: mix, transfer, aspirate, blow_out, and drop_tip.

Parameters:

  • mount (str) – The mount of the pipette’s actuator on the Opentrons robot (‘left’ or ‘right’)

  • trash_container (Container) – Sets the default location drop_tip() will put tips (Default: fixed-trash)

  • tip_racks (list) – A list of Containers for this Pipette to track tips when calling pick_up_tip() (Default: [])

  • aspirate_flow_rate (int) – The speed (in ul/sec) the plunger will move while aspirating (Default: See Model Type)

  • dispense_flow_rate (int) – The speed (in ul/sec) the plunger will move while dispensing (Default: See Model Type)

Return type:

A new instance of Pipette.

Examples

>>> from opentrons import instruments, labware, robot 
>>> robot.reset() 
>>> tip_rack_300ul = labware.load(
...     'GEB-tiprack-300ul', '1') 
>>> p300 = instruments.P300_Single(mount='left',
...     tip_racks=[tip_rack_300ul])
aspirate(self, volume=None, location=None, rate=1.0)

Aspirate a volume of liquid (in microliters/uL) using this pipette from the specified location

Notes

If only a volume is passed, the pipette will aspirate from it’s current position. If only a location is passed, aspirate will default to it’s max_volume.

The location may be a Well, or a specific position in relation to a Well, such as Well.top(). If a Well is specified without calling a a position method (such as .top or .bottom), this method will default to the bottom of the well.

Parameters:

  • volume (int or float) – The number of microliters to aspirate (Default: self.max_volume)

  • location (Placeable or tuple(Placeable, Vector)) – The Placeable (Well) to perform the aspirate. Can also be a tuple with first item Placeable, second item relative Vector

  • rate (float) – Set plunger speed for this aspirate, where speed = rate * aspirate_speed (see set_speed())

Return type:

This instance of Pipette.

Examples

>>> from opentrons import instruments, labware, robot 
>>> robot.reset() 
>>> plate = labware.load('96-flat', '2') 
>>> p300 = instruments.P300_Single(mount='right') 
>>> p300.pick_up_tip() 
# aspirate 50uL from a Well
>>> p300.aspirate(50, plate[0]) 
# aspirate 50uL from the center of a well
>>> p300.aspirate(50, plate[1].bottom()) 
>>> # aspirate 20uL in place, twice as fast
>>> p300.aspirate(20, rate=2.0) 
>>> # aspirate the pipette's remaining volume (80uL) from a Well
>>> p300.aspirate(plate[2])
blow_out(self, location=None)

Force any remaining liquid to dispense, by moving this pipette’s plunger to the calibrated blow_out position

Notes

If no location is passed, the pipette will blow_out from it’s current position.

Parameters:

location (Placeable or tuple(Placeable, Vector)) – The Placeable (Well) to perform the blow_out. Can also be a tuple with first item Placeable, second item relative Vector

Return type:

This instance of Pipette.

Examples

>>> from opentrons import instruments, robot 
>>> robot.reset() 
>>> p300 = instruments.P300_Single(mount='left') 
>>> p300.aspirate(50).dispense().blow_out()
consolidate(self, volume, source, dest, \*args, \*\*kwargs)

Consolidate will move a volume of liquid from a list of sources to a single target location. See Transfer for details and a full list of optional arguments.

Return type:

This instance of Pipette.

Examples

>>> from opentrons import instruments, labware, robot 
>>> robot.reset() 
>>> plate = labware.load('96-flat', 'A3') 
>>> p300 = instruments.P300_Single(mount='left') 
>>> p300.consolidate(50, plate.cols[0], plate[1])
delay(self, seconds=0, minutes=0)
Parameters:

seconds (float) – The number of seconds to freeze in place.

dispense(self, volume=None, location=None, rate=1.0)

Dispense a volume of liquid (in microliters/uL) using this pipette

Notes

If only a volume is passed, the pipette will dispense from it’s current position. If only a location is passed, dispense will default to it’s current_volume

The location may be a Well, or a specific position in relation to a Well, such as Well.top(). If a Well is specified without calling a a position method (such as .top or .bottom), this method will default to the bottom of the well.

Parameters:

  • volume (int or float) – The number of microliters to dispense (Default: self.current_volume)

  • location (Placeable or tuple(Placeable, Vector)) – The Placeable (Well) to perform the dispense. Can also be a tuple with first item Placeable, second item relative Vector

  • rate (float) – Set plunger speed for this dispense, where speed = rate * dispense_speed (see set_speed())

Return type:

This instance of Pipette.

Examples

>>> from opentrons import instruments, labware, robot 
>>> robot.reset() 
>>> plate = labware.load('96-flat', '3') 
>>> p300 = instruments.P300_Single(mount='left') 
# fill the pipette with liquid (200uL)
>>> p300.aspirate(plate[0]) 
# dispense 50uL to a Well
>>> p300.dispense(50, plate[0]) 
# dispense 50uL to the center of a well
>>> relative_vector = plate[1].center() 
>>> p300.dispense(50, (plate[1], relative_vector)) 
# dispense 20uL in place, at half the speed
>>> p300.dispense(20, rate=0.5) 
# dispense the pipette's remaining volume (80uL) to a Well
>>> p300.dispense(plate[2])
distribute(self, volume, source, dest, \*args, \*\*kwargs)

Distribute will move a volume of liquid from a single of source to a list of target locations. See Transfer for details and a full list of optional arguments.

Return type:

This instance of Pipette.

Examples

>>> from opentrons import instruments, labware, robot 
>>> robot.reset() 
>>> plate = labware.load('96-flat', '3') 
>>> p300 = instruments.P300_Single(mount='left') 
>>> p300.distribute(50, plate[1], plate.cols[0])
drop_tip(self, location=None, home_after=True)

Drop the pipette’s current tip

Notes

If no location is passed, the pipette defaults to its trash_container (see Pipette)

Parameters:

location (Placeable or tuple(Placeable, Vector)) – The Placeable (Well) to perform the drop_tip. Can also be a tuple with first item Placeable, second item relative Vector

Return type:

This instance of Pipette.

Examples

>>> from opentrons import instruments, labware, robot 
>>> robot.reset() 
>>> tiprack = labware.load('opentrons_96_tiprack_300ul', 'C2') 
>>> trash = labware.load('point', 'A3') 
>>> p300 = instruments.P300_Single(mount='left') 
>>> p300.pick_up_tip(tiprack[0]) 
# drops the tip in the fixed trash
>>> p300.drop_tip() 
>>> p300.pick_up_tip(tiprack[1]) 
# drops the tip back at its tip rack
>>> p300.drop_tip(tiprack[1])
home(self)

Home the pipette’s plunger axis during a protocol run

Notes

Pipette.home() homes the Robot

Return type:

This instance of Pipette.

Examples

>>> from opentrons import instruments, robot 
>>> robot.reset() 
>>> p300 = instruments.P300_Single(mount='right') 
>>> p300.home()
mix(self, repetitions=1, volume=None, location=None, rate=1.0)

Mix a volume of liquid (in microliters/uL) using this pipette

Notes

If no location is passed, the pipette will mix from it’s current position. If no volume is passed, mix will default to it’s max_volume

Parameters:

  • repetitions (int) – How many times the pipette should mix (Default: 1)

  • volume (int or float) – The number of microliters to mix (Default: self.max_volume)

  • location (Placeable or tuple(Placeable, Vector)) – The Placeable (Well) to perform the mix. Can also be a tuple with first item Placeable, second item relative Vector

  • rate (float) – Set plunger speed for this mix, where speed = rate * (aspirate_speed or dispense_speed) (see set_speed())

Return type:

This instance of Pipette.

Examples

>>> from opentrons import instruments, labware, robot 
>>> robot.reset() 
>>> plate = labware.load('96-flat', '4') 
>>> p300 = instruments.P300_Single(mount='left') 
# mix 50uL in a Well, three times
>>> p300.mix(3, 50, plate[0]) 
# mix 3x with the pipette's max volume, from current position
>>> p300.mix(3)
move_to(self, location, strategy=None)

Move this Pipette to a Placeable on the Deck

Notes

Until obstacle-avoidance algorithms are in place, Robot and Pipette move_to() use either an “arc” or “direct”

Parameters:

  • location (Placeable or tuple(Placeable, Vector)) – The destination to arrive at

  • strategy ("arc" or "direct") – “arc” strategies (default) will pick the head up on Z axis, then over to the XY destination, then finally down to the Z destination. “direct” strategies will simply move in a straight line from the current position

Return type:

This instance of Pipette.

pick_up_tip(self, location=None, presses=None, increment=None)

Pick up a tip for the Pipette to run liquid-handling commands with

Notes

A tip can be manually set by passing a location. If no location is passed, the Pipette will pick up the next available tip in it’s tip_racks list (see Pipette)

Parameters:

  • location (Placeable or tuple(Placeable, Vector)) – The Placeable (Well) to perform the pick_up_tip. Can also be a tuple with first item Placeable, second item relative Vector

  • presses (:any:int) – The number of times to lower and then raise the pipette when picking up a tip, to ensure a good seal (0 [zero] will result in the pipette hovering over the tip but not picking it up–generally not desireable, but could be used for dry-run). Default: 3 presses

  • increment (:int) – The additional distance to travel on each successive press (e.g.: if presses=3 and increment=1, then the first press will travel down into the tip by 3.5mm, the second by 4.5mm, and the third by 5.5mm. Default: 1mm

Return type:

This instance of Pipette.

Examples

>>> from opentrons import instruments, labware, robot 
>>> robot.reset() 
>>> tiprack = labware.load('GEB-tiprack-300', '2') 
>>> p300 = instruments.P300_Single(mount='left',
...     tip_racks=[tiprack]) 
>>> p300.pick_up_tip(tiprack[0]) 
>>> p300.return_tip() 
# `pick_up_tip` will automatically go to tiprack[1]
>>> p300.pick_up_tip() 
>>> p300.return_tip()
return_tip(self, home_after=True)

Drop the pipette’s current tip to it’s originating tip rack

Notes

This method requires one or more tip-rack Container to be in this Pipette’s tip_racks list (see Pipette)

Return type:

This instance of Pipette.

Examples

>>> from opentrons import instruments, labware, robot 
>>> robot.reset() 
>>> tiprack = labware.load('GEB-tiprack-300', '2') 
>>> p300 = instruments.P300_Single(mount='left',
...     tip_racks=[tiprack, tiprack2]) 
>>> p300.pick_up_tip() 
>>> p300.aspirate(50, plate[0]) 
>>> p300.dispense(plate[1]) 
>>> p300.return_tip()
set_flow_rate(self, aspirate=None, dispense=None, blow_out=None)

Set the speed (uL/second) the Pipette plunger will move during aspirate() and dispense(). The speed is set using nominal max volumes for any given pipette model.

Parameters:

  • aspirate (int) – The speed in microliters-per-second, at which the plunger will move while performing an aspirate

  • dispense (int) – The speed in microliters-per-second, at which the plunger will move while performing an dispense

touch_tip(self, location=None, radius=1.0, v_offset=- 1.0, speed=60.0)

Touch the Pipette tip to the sides of a well, with the intent of removing left-over droplets

Notes

If no location is passed, the pipette will touch_tip from it’s current position.

Parameters:

  • location (Placeable) – The Placeable (Well) to perform the touch_tip.

  • radius (float) – Radius is a floating point describing the percentage of a well’s radius. When radius=1.0, touch_tip() will move to 100% of the wells radius. When radius=0.5, touch_tip() will move to 50% of the wells radius. Default: 1.0 (100%)

  • speed (float) – The speed for touch tip motion, in mm/s. Default: 60.0 mm/s, Max: 80.0 mm/s, Min: 20.0 mm/s

  • v_offset (float) – The offset in mm from the top of the well to touch tip. Default: -1.0 mm

Return type:

This instance of Pipette.

Examples

>>> from opentrons import instruments, labware, robot 
>>> robot.reset() 
>>> plate = labware.load('96-flat', '8') 
>>> p300 = instruments.P300_Single(mount='left') 
>>> p300.aspirate(50, plate[0]) 
>>> p300.dispense(plate[1]).touch_tip()
transfer(self, volume, source, dest, \*\*kwargs)

Transfer will move a volume of liquid from a source location(s) to a dest location(s). It is a higher-level command, incorporating other Pipette commands, like aspirate and dispense, designed to make protocol writing easier at the cost of specificity.

Parameters:

  • volumes (number, list, or tuple) – The amount of volume to remove from each sources Placeable and add to each targets Placeable. If volumes is a list, each volume will be used for the sources/targets at the matching index. If volumes is a tuple with two elements, like (20, 100), then a list of volumes will be generated with a linear gradient between the two volumes in the tuple.

  • source (Placeable or list) – Single Placeable or list of Placeables, from where liquid will be aspirated from.

  • dest (Placeable or list) – Single Placeable or list of Placeables, where liquid will be dispenseed to.

  • new_tip (str) – The number of clean tips this transfer command will use. If ‘never’, no tips will be picked up nor dropped. If ‘once’, a single tip will be used for all cmds. If ‘always’, a new tip will be used for each transfer. Default is ‘once’.

  • trash (boolean) – If True (default behavior) and trash container has been attached to this Pipette, then the tip will be sent to the trash container. If False, then tips will be returned to their associated tiprack.

  • touch_tip (boolean) – If True, a touch_tip will occur following each aspirate and dispense. If set to False (default), no touch_tip will occur.

  • blow_out (boolean) – If True, a blow_out will occur following each dispense, but only if the pipette has no liquid left in it. If set to False (default), no blow_out will occur.

  • mix_before (tuple) – Specify the number of repetitions volume to mix, and a mix will proceed each aspirate during the transfer and dispense. The tuple’s values is interpreted as (repetitions, volume).

  • mix_after (tuple) – Specify the number of repetitions volume to mix, and a mix will following each dispense during the transfer or consolidate. The tuple’s values is interpreted as (repetitions, volume).

  • carryover (boolean) – If True (default), any volumes that exceed the maximum volume of this Pipette will be split into multiple smaller volumes.

  • repeat (boolean) – (Only applicable to distribute and consolidate)If True (default), sequential aspirate volumes will be combined into one tip for the purpose of saving time. If False, all volumes will be transferred seperately.

  • gradient (lambda) – Function for calculated the curve used for gradient volumes. When volumes is a tuple of length 2, it’s values are used to create a list of gradient volumes. The default curve for this gradient is linear (lambda x: x), however a method can be passed with the gradient keyword argument to create a custom curve.

Return type:

This instance of Pipette.

Examples

>>> from opentrons import instruments, labware, robot 
>>> robot.reset() 
>>> plate = labware.load('96-flat', '5') 
>>> p300 = instruments.P300_Single(mount='right') 
>>> p300.transfer(50, plate[0], plate[1])

Placeable

class placeable.Placeable(parent=None, properties=None)

This class represents every item on the deck.

It maintains the hierarchy and provides means to: * traverse * retrieve items by name * calculate coordinates in different reference systems

It should never be directly created; it is created by the system during labware load and when accessing wells.

bottom(self, z=0, radius=0, degrees=0, reference=None)

Returns (Placeable, Vector) tuple where the vector points to the bottom of the placeable. This can be passed into any Robot or Pipette method location argument.

If reference (a Placeable) is provided, the return value will be in that placeable’s coordinate system.

The radius and degrees arguments are interpreted as in from_center() (except that degrees is in degrees, not radians). They can be used to specify a further distance from the bottom center of the well; for instance, calling bottom(radius=0.5, degrees=180) will move half the radius in the 180 degree direction from the center of the well.

The z argument is a distance in mm to move in z from the bottom, and can be used to hover above the bottom. For instance, calling bottom(z=1) will move 1mm above the bottom.

Parameters:

  • z – Absolute distance in mm to move in z from the bottom. Note that unlike the other arguments, this is a distance, not a ratio.

  • degrees – Direction in which to move radius from the bottom center.

  • radius – Ratio of the placeable’s radius to move in the direction specified by degrees from the bottom center.

  • reference – An optional placeable for the vector to be relative to.

Returns:

A tuple of the placeable and the offset. This can be passed into any Robot or Pipette method location argument.

center(self, reference=None)

Returns (Placeable, Vector) tuple where the vector points to the center of the placeable, in x, y, and z. This can be passed into any Robot or Pipette method location argument.

If reference (a Placeable) is provided, the return value will be in that placeable’s coordinate system.

Parameters:

reference – An optional placeable for the vector to be relative to.

Returns:

A tuple of the placeable and the offset. This can be passed into any Robot or Pipette method location argument.

from_center(self, x=None, y=None, z=None, r=None, theta=None, h=None, reference=None)

Accepts a set of ratios for Cartesian or ratios/angle for Polar and returns Vector using reference as origin.

Though both polar and cartesian arguments are accepted, only one set should be used at the same time, and the set selected should be entirely used. In addition, all variables in the set should be used.

For instance, if you want to use cartesian coordinates, you must specify all of x, y, and z as numbers; if you want to use polar coordinates, you must specify all of theta, r and h as numbers.

While theta is an absolute angle in radians, the other values are actually ratios which are multiplied by the relevant dimensions of the placeable on which from_center is called. For instance, calling from_center(x=0.5, y=0.5, z=0.5) does not mean “500 micromenters from the center in each dimension”, but “half the x size, half the y size, and half the z size from the center”. Similarly, from_center(r=0.5, theta=3.14, h=0.5) means “half the radius dimension at 180 degrees, and half the height upwards”.

Parameters:

  • x – Ratio of the x dimension of the placeable to move from the center.

  • y – Ratio of the y dimension of the placeable to move from the center.

  • z – Ratio of the z dimension of the placeable to move from the center.

  • r – Ratio of the radius to move from the center.

  • theta – Angle in radians at which to move the percentage of the radius specified by r from the center.

  • h – Percentage of the height to move up in z from the center.

  • reference – If specified, an origin to add to the offset vector specified by the other arguments.

Returns:

A vector from either the origin or the specified reference. This can be passed into any Robot or Pipette method location argument.

top(self, z=0, radius=0, degrees=0, reference=None)

Returns (Placeable, Vector) tuple where the vector points to the top of the placeable. This can be passed into any Robot or Pipette method location argument.

If reference (a Placeable) is provided, the return value will be in that placeable’s coordinate system.

The radius and degrees arguments are interpreted as in from_center() (except that degrees is in degrees, not radians). They can be used to specify a further distance from the top center of the well; for instance, calling top(radius=0.5, degrees=180) will move half the radius in the 180 degree direction from the center of the well.

The z argument is a distance in mm to move in z from the top, and can be used to hover above or below the top. For instance, calling top(z=-1) will move 1mm below the top.

Parameters:

  • z – Absolute distance in mm to move in z from the top. Note that unlike the other arguments, this is a distance, not a ratio.

  • degrees – Direction in which to move radius from the top center.

  • radius – Ratio of the placeable’s radius to move in the direction specified by degrees from the top center.

Returns:

A tuple of the placeable and the offset. This can be passed into any Robot or Pipette method location argument.

Simulation

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.

opentrons.simulate.allow_bundle() → bool

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"

opentrons.simulate.format_runlog(runlog: List[Mapping[str, Any]]) → str

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

Parameters:

runlog – The output of a call to simulate

opentrons.simulate.get_arguments(parser: argparse.ArgumentParser) → argparse.ArgumentParser

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 – A parser to add arguments to. If not specified, one will be created.

Returns argparse.ArgumentParser:

The parser with arguments added.

opentrons.simulate.simulate(protocol_file: Union[BinaryIO, TextIO], file_name: Optional[str] = None, custom_labware_paths: Optional[List[str]] = None, custom_data_paths: Optional[List[str]] = None, propagate_logs: bool = False, hardware_simulator_file_path: Optional[str] = None, duration_estimator: Optional[opentrons.protocols.duration.estimator.DurationEstimator] = None, log_level: str = 'warning') → Tuple[List[Mapping[str, Any]], Optional[opentrons.protocols.types.BundleContents]]

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 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 – The protocol file to simulate.

  • file_name – The name of the file

  • custom_labware_paths – 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 – A list of directories or files to load custom data files from. Ignored if the apiv2 feature flag if 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 protocol_api.ProtocolContext.bundled_data.

  • hardware_simulator_file_path – 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 – For internal use only. Optional duration estimator object.

  • propagate_logs – 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 – The level of logs to capture in the run log: "debug", "info", "warning", or "error". Defaults to "warning".

Returns:

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.