Pipette

Description

Represents a single-channel pipette tool attached to the Jubilee system, similar in behavior to an Opentrons OT-2 pipette.

Provides methods for liquid handling operations including aspiration, dispensing, transferring, mixing, air gaps, tip pickup/return, and stirring.

Extends the base Tool class.

Constructor

Pipette(
    index,
    name,
    brand,
    model,
    max_volume,
    min_volume,
    zero_position,
    blowout_position,
    drop_tip_position,
    mm_to_ul
)

Parameter	Type	Description
index	int	Machine tool index for the pipette.
name	str	User-friendly name of the pipette.
brand	str	Brand name of the pipette (e.g., 'Opentrons').
model	str	Model of the pipette (e.g., 'P300 Single').
max_volume	float	Maximum liquid volume in µL.
min_volume	float	Minimum liquid volume in µL.
zero_position	float	Motor position for 'ready' plunger state.
blowout_position	float	Motor position for 'blowout' plunger state.
drop_tip_position	float	Motor position for dropping tips.
mm_to_ul	float	Conversion factor between plunger mm movement and µL dispensed.

Key Properties

Property	Type	Description
has_tip	bool	Whether a pipette tip is attached.
current_well	Well	The current well the pipette is operating on.
trash	Well	Location for tip disposal.
TipTracker	TipTracker	Object tracking tip usage.
is_primed	bool	Whether the pipette plunger has been primed.

Important Methods

Method	Returns	Description
aspirate(vol, location)	None	Move to location and aspirate volume.
dispense(vol, location)	None	Move to location and dispense volume.
transfer(vol, source, destination, ...)	None	High-level transfer function combining aspirate and dispense.
pickup_tip(tip)	None	Pick up a new pipette tip from specified location.
drop_tip(location)	None	Drop a pipette tip into a specified or default trash location.
mix(n, vol)	None	Perform a mix operation in a well.
stir(n_times, height)	None	Stir liquid in a well with circular motion.
air_gap(vol)	None	Create an air gap inside the pipette tip.
blowout()	None	Forcefully expel any remaining liquid.
add_tiprack(tiprack)	None	Attach a tiprack (or multiple) for automated tip management.
update_z_offset(tip)	None	Update z-offset depending on tip attachment.

Method Details

Aspirate

aspirate(vol: float, location: Union[Well, Tuple, Location])

Move to a specified location and aspirate the given volume.

Requires a tip.

Dispense

dispense(vol: float, location: Union[Well, Tuple, Location])

Move to a specified location and dispense the given volume.

Requires a tip.

Transfer

transfer(
    vol: Union[float, List[float]],
    source_well: Union[Well, Tuple, Location],
    destination_well: Union[Well, Tuple, Location],
    ...
)

High-level command combining aspiration and dispensing in one step.

Supports complex behaviors:

• air_gap
• mix_before, mix_after
• Tip strategies (new_tip='always' | 'never' | 'once')

Pickup Tip

pickup_tip(tip: Union[Well, Tuple] = None)

Pick up a pipette tip from a tiprack or a specified location.

Automatically updates tool offset and registers tip use.

Drop Tip

drop_tip(location: Union[Well, Tuple] = None)

Drop the pipette tip into a trash well or specified location.

Resets tool offset accordingly.

Mix

mix(n: int, vol: float)

Repeatedly aspirate and dispense inside a well to mix the contents.

Stir

stir(n_times: int = 1, height: float = None)

Move in a circular motion inside a well to stir liquids.

Blowout

blowout(s: int = 6000)

Forcefully expel any remaining liquid in the tip.

Air Gap

air_gap(vol: float)

Aspirate a small volume of air between aspirated liquid and pipette plunger.

Add Tiprack

add_tiprack(tiprack: Union[Labware, List[Labware]])

Register a tiprack (or multiple) to track tip usage automatically.

Internal Helpers

Helper	Description
_aspirate, _dispense, _pickup_tip, _drop_tip	Low-level primitives for direct motion control.
_create_volume_list, _extend_source_target_lists, _expand_for_volume_constraints	Helpers for batch transfer logic and volume management.

Usage Flow Example

from science_jubilee.tools import Pipette

# Load pipette from config
pipette = Pipette.from_config(index=2, name="P300_Single", config_file="p300_config.json")

# Attach to machine
m.load_tool(pipette)
m.pickup_tool(pipette)

# Associate tiprack
pipette.add_tiprack(tiprack)

# Aspirate and dispense
pipette.aspirate(100, source_well)
pipette.dispense(100, destination_well)

# Perform transfer
pipette.transfer(100, source_well, destination_well)

Important Notes

• Pipette must be primed before aspirate/dispense actions.
• Pipette requires a tip before any liquid handling.
• Volumes are internally converted to axis movements.
• Custom motion safety checks (safe Z movement) are built-in.
• Tip management (pickup/return/drop) is integrated into usage flow.
• Stirring assumes the well is large enough for circular tip motion.

Related Concepts

• Tool
• Labware
• Location
• TipTracker