Flex Stacker

FlexStackerContext

An object representing a connected Flex Stacker module.

It should not be instantiated directly; instead, it should be created through ProtocolContext.load_module().

New in version 2.25

empty v2.25

empty(message=None)

Pause the protocol to remove all labware stored in the Flex Stacker.

This method sets the location of all labware currently in the stacker to OFF_DECK.

Parameters:

• message (str | None, default: None ) –

  A message to display to note what should be removed from the Flex Stacker.

fill v2.25

fill(count=None, message=None)

Pause the protocol to add labware to the Flex Stacker.

The labware must be the same type the Stacker is configured to store using set_stored_labware(). If no labware type has been set, the API will raise an error.

Parameters:

• count (int | None, default: None ) –

  The amount of labware the Flex Stacker should hold after this command is executed. If not specified, the Flex Stacker should be full after this command is executed.

• message (str | None, default: None ) –

  A message to display noting what kind of labware to fill the Stacker with.

fill_items v2.25

fill_items(labware, message=None)

Pause the protocol to add a specific list of labware to the Flex Stacker.

Parameters:

• labware (list[Labware]) –

  The list of labware to add. The list must:

  • Contain at least one labware.
  • Have labware of the same kind previously passed to set_stored_labware_items() or loaded by set_stored_labware().
  • All labware should be loaded OFF_DECK.
• message (str | None, default: None ) –

  A message to display noting the labware to fill the Stacker with.

get_current_storable_labware v2.25

get_current_storable_labware()

Get the number of labware that the Flex Stacker currently has space for.

Use this function to return the total number of labware that the Flex Stacker can store. A Stacker has a limited amount of internal space and calculates the number of labware that can be stored based on the z height of the labware and the amount they overlap when stacked.

The number is calculated based on the labware definition for the type of labware the Stacker is currently configured to store using set_stored_labware(). This function returns a number based on the current storage conditions of the Stacker, and will change as labware is added or removed. To get the overall maximum number of labware the Flex Stacker can store, use get_max_storable_labware().

get_current_storable_labware_from_list v2.25

get_current_storable_labware_from_list(labware)

Limit a list of labware instances to the number that the Flex Stacker currently has space for, based on the labware that is already stored in the Flex Stacker. Items will be taken from the head of the list.

A Flex Stacker has a limited amount of internal space and computes the number of labware that it can store based on the z height of the labware and the amount they overlap when stacked.

Note

The number of elements in the returned list will change as labware is added or removed from the Flex Stacker. To get a list limited to the overall maximum number of labware the Flex Stacker can store, use get_max_storable_labware_from_list().

Parameters:

• labware (list[Labware]) –

  A list of labware to limit. The returned list takes from the front of the provided list, and it is guaranteed to be suitable for passing to fill_items().

get_max_storable_labware v2.25

get_max_storable_labware()

Get the maximum number of labware that the Flex Stacker can store.

Use this function to return the total number of labware that the Flex Stacker can store. A Stacker has a limited amount of internal space and calculates the total number of labware that can be stored based on the z height of the labware and the amount they overlap when stacked.

The total number is calculated based on the labware definition for the type of labware the Stacker is currently configured to store using set_stored_labware(). This number is the overall maximum and will not change as labware is added or removed. To get the number of labware that can be stored in the Flex Stacker based on its current conditions, use get_current_storable_labware().

get_max_storable_labware_from_list v2.25

get_max_storable_labware_from_list(labware, stacking_offset_z=None)

Limit a list of labware instances to the number that can be stored in a Flex Stacker. Items will be taken from the head of the list.

A Flex Stacker has a limited amount of internal space and computes the number of labware (or labware with lids or adapters) that it can store based on the z heights of the labware and the amount they overlap when stacked. To calculate how many of a given labware the Stacker can store, the labware type must be specified.

Provide a list of labware to this function to return the maximum number of labware of the given type that the Stacker can store. The returned list is guaranteed to be suitable for passing to set_stored_labware_items().

This function limits the list of labware based on the overall maximum number the Stacker can hold and will not change as labware is added or removed. To limit a list of labware to the amount that will currently fit in the Flex Stacker, use get_current_storable_labware_from_list().

Note

If a z stacking offset is provided, be sure to specify the same value when configuring the Flex Stacker with set_stored_labware_items().

See set_stored_labware_items() for more details on stacking offset.

get_stored_labware v2.25

get_stored_labware()

Get the list of labware currently stored inside the Stacker.

This function returns a list of all labware stored in the Stacker based on the labware initially stored using set_stored_labware() and any labware added or removed during the protocol.

The first element of the list occupies the bottom-most position in the labware stack and would be the labware retrieved by a call to retrieve().

labware property v2.0

labware

The labware (if any) present on this module.

load_adapter v2.15

load_adapter(name, namespace=None, version=None)

Load an adapter onto the module using its load parameters.

The parameters of this function behave like those of load_adapter() (which loads adapters directly onto the deck). Note that the parameter name here corresponds to load_name on the ProtocolContext function.

Returns:

• Labware –

  The initialized and loaded adapter object.

load_adapter_from_definition v2.15

load_adapter_from_definition(definition)

Load an adapter onto the module using an inline definition.

Parameters:

• definition (LabwareDefinition) –

  The labware definition.

Returns:

• Labware –

  The initialized and loaded labware object.

load_labware

load_labware(name, label=None, namespace=None, version=None, adapter=None, lid=None, *, adapter_namespace=None, adapter_version=None, lid_namespace=None, lid_version=None)

Load a labware onto the module using its load parameters.

The parameters of this function behave like those of load_labware() (which loads labware directly onto the deck). Note that the parameter name here corresponds to load_name on the ProtocolContext function.

Returns:

• Labware –

  The initialized and loaded labware object.

New in version 2.1: The label, namespace, and version parameters.

New in version 2.26: The adapter_namespace, adapter_version, lid_namespace, and lid_version parameters.

load_labware_by_name v2.1

load_labware_by_name(name, label=None, namespace=None, version=None)

Deprecated in version 2.0: Use load_labware instead.

load_labware_from_definition v2.0

load_labware_from_definition(definition, label=None)

Load a labware onto the module using an inline definition.

Parameters:

• definition (LabwareDefinition) –

  The labware definition.

• label (str, default: None ) –

  An optional special name to give the labware. If specified, this is the name the labware will appear as in the run log and the calibration view in the Opentrons app.

Returns:

• Labware –

  The initialized and loaded labware object.

model property v2.14

model

Get the module's model identifier.

parent property v2.14

parent

The name of the slot the module is on.

On a Flex, this will be like "D1". On an OT-2, this will be like "1". See Deck Slots.

retrieve v2.25

retrieve()

Retrieve a labware from the Flex Stacker and move it onto the shuttle.

The Stacker will retrieve the bottom-most labware in the stack.

Returns:

• Labware –

  The retrieved Labware object. This will always be the main labware, even if the Flex Stacker contains labware on an adapter. To get the adapter object, call Labware.parent on the returned labware.

serial_number property v2.25

serial_number

Get the module's unique hardware serial number.

set_stored_labware v2.25

set_stored_labware(load_name, namespace=None, version=None, adapter=None, lid=None, count=None, stacking_offset_z=None, *, adapter_namespace=None, adapter_version=None, lid_namespace=None, lid_version=None)

Configure the type and starting quantity of labware the Flex Stacker will store during a protocol. This is the only type of labware you'll be able to store in the Stacker until it's reconfigured.

You must use this method to load a labware stack stored inside the Stacker before you're able to retrieve() or store() additional labware.

Parameters:

• load_name (str) –

  A string to use for looking up a labware definition. You can find the load_name for any Opentrons-verified labware on the Labware Library.

• namespace (str, default: None ) –

  The namespace that the labware definition belongs to. If unspecified, the API will automatically search two namespaces:

  • "opentrons", to load standard Opentrons labware definitions.
  • "custom_beta", to load custom labware definitions created with the Custom Labware Creator.

  You might need to specify an explicit namespace if you have a custom definition whose load_name is the same as an Opentrons-verified definition, and you want to explicitly choose one or the other.

• version (int, default: None ) –

  The version of the labware definition. You should normally leave this unspecified to let the method choose a version automatically.

• adapter (str, default: None ) –

  An adapter to load the labware on top of. Accepts the same values as the load_name parameter of load_adapter().

• adapter_namespace (str, default: None ) –

  Applies to adapter the same way that namespace applies to load_name.

  Changed in version 2.26: adapter_namespace may now be specified explicitly. When you've specified namespace for load_name but not adapter_namespace, adapter_namespace now independently follows the same search rules described in namespace. Formerly, it took the exact namespace value.

• adapter_version (int, default: None ) –

  Applies to adapter the same way that version applies to load_name.

  Changed in version 2.26: adapter_version may now be specified explicitly. When unspecified, improved search rules prevent selecting a version that does not exist.

• lid (str, default: None ) –

  A lid to load on top of the main labware. Accepts the same values as the load_name parameter of load_lid_stack(). The lid will use the same namespace as the labware, and the API will choose the lid's version automatically.

  New in version 2.23

• lid_namespace (str, default: None ) –

  The namespace of the lid being loaded. Applies to lid the same way that namespace applies to load_name.

  Changed in version 2.26: lid_namespace may now be specified explicitly. When you've specified namespace for load_name but not lid_namespace, lid_namespace now independently follows the same search rules described in namespace. Formerly, it took the exact namespace value.

• lid_version (int, default: None ) –

  Applies to lid the same way that version applies to load_name.

  Changed in version 2.26: lid_version may now be specified explicitly. When unspecified, improved search rules prevent selecting a version that does not exist.

• count (int, default: None ) –

  The number of labware that the Flex Stacker should store. If not specified, this will be the maximum amount of this kind of labware that the Flex Stacker is capable of storing.

• stacking_offset_z (float, default: None ) –

  Stacking z offset in mm of stored labware. If specified, this overrides the calculated value in the labware definition.

  Note

  The stacking offset is the amount of vertical overlap (in mm) between the bottom side of a labware unit and the top side of the unit below. This offset is used to determine how many units can fit in the Stacker and calculates the z position of the shuttle when retrieving or storing labware.

  There are four possible stacking configurations, each with a different method of calculating the stacking offset:

  • Bare labware: labware (bottom side) overlaps with the top side of the labware below.
  • Labware on adapter: the adapter (bottom side) of the upper labware unit overlaps with the top side of the labware below.
  • Labware with lid: the labware (bottom side) of the upper unit overlaps with the lid (top side) of the unit below.
  • Labware with lid and adapter: the adapter (bottom side) of the upper unit overlaps with the lid (top side) of the unit below.

set_stored_labware_items v2.25

set_stored_labware_items(labware, stacking_offset_z=None)

Configure the labware the Flex Stacker will store during a protocol by providing an initial list of stored labware objects. The start of the list represents the bottom of the Stacker, and the end of the list represents the top of the Stacker.

The kind of labware stored by the Flex Stacker will be calculated from the list of labware specified here. You can use this to store labware objects that you have already created so that, for instance, you can set their liquid state or nicknames.

Parameters:

• labware (list[Labware]) –

  A list of labware to load into the Stacker.

  • The list must have at least one element.
  • All labware must be loaded OFF_DECK.
  • All labware must be of the same kind. If any of them have lids, they must all have lids, and the lids must be the same. If any of them are on adapters, they all must be on adapters, and the adapters must be the same. All lids and adapters must be compatible with the Stacker.
  • The number of labware objects must fit in the Stacker physically. To make sure the labware will fit, use the return value of get_max_storable_labware_from_list().
• stacking_offset_z (float | None, default: None ) –

  Stacking z offset in mm of stored labware. If specified, this overrides the calculated value from labware definitions.

Note

The stacking offset is the amount of vertical overlap (in mm) between the bottom side of a labware unit and the top side of the unit below. This offset is used to determine how many units can fit in the stacker and calculates the z position of the shuttle when retrieving or storing labware.

There are four possible stacking configurations, each with a different method of calculating the stacking offset:

• Bare labware: labware (bottom side) overlaps with the top side of the labware below.
• Labware on adapter: the adapter (bottom side) of the upper labware unit overlaps with the top side of the labware below.
• Labware with lid: the labware (bottom side) of the upper unit overlaps with the lid (top side) of the unit below.
• Labware with lid and adapter: the adapter (bottom side) of the upper unit overlaps with the lid (top side) of the unit below.

store v2.25

store()

Move a labware currently on the Flex Stacker shuttle into the Flex Stacker.

The labware must be the same type the Stacker is configured to store using set_stored_labware(). If labware is currently stacked inside the module, this method moves the new labware to the bottom-most position of the stack.

type property v2.14

type

Get the module's general type identifier.