Well (inherits from dataclass)

Description

Represents a single well within a labware item. Each well has spatial coordinates, dimensions, liquid capacity, and optional offsets for precise positioning during laboratory automation operations.

Constructor

Well(
    name: str,
    depth: float,
    totalLiquidVolume: float,
    shape: str,
    diameter: float = None,
    xDimension: float = None,
    yDimension: float = None,
    x: float,
    y: float,
    z: float,
    offset: Tuple[float] = None,
    slot: int = None,
    has_tip: bool = False,
    clean_tip: bool = False,
    labware_name: str = None,
)

Initializes a Well with its geometry, coordinates, optional offset, and tip presence attributes.

Properties

Property	Type	Description
name	str	Name of the well (e.g., "A1", "B5").
depth	float	Depth of the well in mm.
totalLiquidVolume	float	Maximum liquid capacity of the well.
shape	str	Shape of the well (e.g., cylindrical, rectangular).
diameter	float	Diameter of the well (optional for cylindrical wells).
xDimension	float	X dimension (width) for rectangular wells.
yDimension	float	Y dimension (depth) for rectangular wells.
x, y, z	float	Coordinates of the well relative to its deck slot.
offset	Tuple[float]	Manual offset applied to coordinates (optional).
slot	int	Slot number where the well is located (optional).
has_tip	bool	Whether the well currently has a tip loaded (for tip racks).
clean_tip	bool	Whether the tip is clean (for tip reuse logic).
labware_name	str	Name of the associated labware.

Methods

Method	Returns	Description
apply_offset(offset: Tuple[float])	None	Applies a manual (x, y, [z]) offset to the well coordinates.
top_ (property)	float	Returns the absolute z-coordinate of the well top.
bottom_ (property)	float	Returns the absolute z-coordinate of the well bottom.
top(z: float)	Location	Returns a Location object offset z mm relative to the well top.
bottom(z: float, check: bool = False)	Location	Returns a Location object offset z mm relative to the well bottom; enforces positive z if check is False.
set_has_tip(value: bool)	None	Sets the has_tip attribute for the well.
set_clean_tip(value: bool)	None	Sets the clean_tip attribute for the well.
__repr__()	str	String representation showing well name, slot, and coordinates.

Short Example

# Example usage of a Well
well_a1 = Well(
    name="A1",
    depth=10.0,
    totalLiquidVolume=360.0,
    shape="circular",
    x=0.0,
    y=0.0,
    z=0.0
)

# Apply an offset
well_a1.apply_offset((10.0, 5.0))

# Get a location 2mm above the bottom
location = well_a1.bottom(2.0)
print(location)

Important Notes

• Coordinate setters (x, y, z) allow dynamic updating of positions.
• apply_offset shifts the well’s entire coordinate space, typically used after loading onto a deck slot.
• Always verify that bottom z-offsets are positive unless explicitly bypassed using check=True.
• The Location class is returned by movement-related methods (top, bottom) to represent 3D points plus context.