Skip to content

Wells and Liquids

Well

The Well class represents a single well in a Labware. It provides parameters and functions for three major uses:

bottom v2.0 

bottom(z=0.0)

Parameters:

  • z (float, default: 0.0 ) –

    An offset on the z-axis, in mm. Positive offsets are higher and negative offsets are lower.

Returns:

  • Location –

    A Location corresponding to the absolute position of the bottom-center of the well, plus the z offset (if specified).

center v2.0 

center()

Returns:

  • Location –

    A Location corresponding to the absolute position of the center of the well (in all three dimensions).

current_liquid_height v2.21 

current_liquid_height()

Get the current liquid height in a well.

current_liquid_volume v2.21 

current_liquid_volume()

Get the current liquid volume in a well.

depth property v2.9 

depth

The depth, in mm, of a well along the z-axis, from the very top of the well to the very bottom.

diameter property v2.0 

diameter

The diameter, in mm, of a circular well. Returns None if the well is not circular.

display_name property 

display_name

A human-readable name for the well, including labware and deck location.

For example, "A1 of Corning 96 Well Plate 360 µL Flat on slot D1". Run log entries use this format for identifying wells. See commands().

estimate_liquid_height_after_pipetting v2.21 

estimate_liquid_height_after_pipetting(mount, operation_volume)

Check the height of the liquid within a well.

Returns:

  • LiquidTrackingType –

    The height, in mm, of the liquid from the deck.

Note

This is intended for Opentrons internal use only and is not a guaranteed API.

from_center_cartesian v2.8 

from_center_cartesian(x, y, z)

Specifies a Point based on fractions of the distance from the center of the well to the edge along each axis.

For example, from_center_cartesian(0, 0, 0.5) specifies a point at the well's center on the x- and y-axis, and half of the distance from the center of the well to its top along the z-axis. To move the pipette to that location, construct a Location relative to the same well:

    location = types.Location(
        plate["A1"].from_center_cartesian(0, 0, 0.5), plate["A1"]
    )
    pipette.move_to(location)

See Points and Locations for more information.

Parameters:

  • x (float) –

    The fraction of the distance from the well's center to its edge along the x-axis. Negative values are to the left, and positive values are to the right.

  • y (float) –

    The fraction of the distance from the well's center to its edge along the y-axis. Negative values are to the front, and positive values are to the back.

  • z (float) –

    The fraction of the distance from the well's center to its edge along the x-axis. Negative values are down, and positive values are up.

Returns:

  • Point –

    A Point representing the specified position in absolute deck coordinates.

Note

Even if the absolute values of x, y, and z are all less than 1, a location constructed from the well and the result of from_center_cartesian may be outside of the physical well. For example, from_center_cartesian(0.9, 0.9, 0) would be outside of a cylindrical well, but inside a square well.

New in version 2.8

has_tip property v2.0 writable 

has_tip

Whether this well contains an unused tip.

From API v2.2 on:

  • Returns False if:

  • the well has no tip present, or

  • the well has a tip that's been used by the protocol previously

  • Returns True if the well has an unused tip.

Before API v2.2:

  • Returns True as long as the well has a tip, even if it is used.

Always False if the parent labware isn't a tip rack.

New in version 2.2

has_tracked_liquid v2.27 

has_tracked_liquid()

Get the current liquid volume in a well.

height_from_volume v2.24 

height_from_volume(volume)

Return the height in a well corresponding to a given volume.

length property v2.9 

length

The length, in mm, of a rectangular well along the x-axis (left to right). Returns None if the well is not rectangular.

load_liquid v2.14 

load_liquid(liquid, volume)

Load a liquid into a well.

Parameters:

  • liquid (Liquid) –

    The liquid to load into the well.

  • volume (float) –

    The volume of liquid to load, in µL.

Deprecated in version 2.22: Use Labware.load_liquid(), Labware.load_liquid_by_well(), or Labware.load_empty() instead.

max_volume property 

max_volume

The maximum volume, in µL, that the well can hold.

This amount is set by the JSON labware definition, specifically the totalLiquidVolume property of the particular well.

meniscus v2.21 

meniscus(z=0.0, target='end')

Parameters:

  • z (float, default: 0.0 ) –

    An offset on the z-axis, in mm. Positive offsets are higher and negative offsets are lower.

  • target (str, default: 'end' ) –

    The relative position of the liquid meniscus inside the well to target when performing a liquid handling operation.

Returns:

  • Location ( Location ) –

    A Location corresponding to the liquid meniscus, plus a target position and z offset as specified.

parent property v2.0 

parent

The Labware object that the well is a part of.

top v2.0 

top(z=0.0)

Parameters:

  • z (float, default: 0.0 ) –

    An offset on the z-axis, in mm. Positive offsets are higher and negative offsets are lower.

Returns:

  • Location –

    A Location corresponding to the absolute position of the top-center of the well, plus the z offset (if specified).

volume_from_height v2.24 

volume_from_height(height)

Return the volume contained in a well at any height.

well_name property v2.7 

well_name

A string representing the well's coordinates.

For example, "A1" or "H12".

The format of strings that this property returns is the same format as the key for accessing wells in a dictionary.

width property v2.9 

width

The width, in mm, of a rectangular well along the y-axis (front to back). Returns None if the well is not rectangular.

Liquid dataclass

A liquid to load into a well.

Attributes:

  • name (str) –

    A human-readable name for the liquid.

  • description (Optional[str]) –

    An optional description.

  • display_color (Optional[str]) –

    An optional display color for the liquid.

New in version 2.14

LiquidClass dataclass

A data class that contains properties of a specific class of liquids.

get_for 

get_for(pipette, tip_rack)

Get liquid class transfer properties for the specified pipette and tip.

update_for 

update_for(pipette, tip_rack, transfer_properties)

Update the transfer properties for the given pipette and tip combo.

If an entry does not exist, it will be created.