PumpDispenser

Description

Represents a dispenser head tool for coordinated control of multiple peristaltic pumps.

Used to deliver specific volumes of liquid either uniformly or selectively through multiple dispense tips. Supports priming, dispensing, and emptying operations for peristaltic pump-driven systems.

Constructor

PumpDispenser(index, name, pump_group, dispense_tip_offsets, line_volume, waste=None)

Parameter	Type	Description
index	int	Tool index for the dispenser head on the machine.
name	str	Tool name.
pump_group	PeristalticPumps	Associated PeristalticPumps object controlling the pumps.
dispense_tip_offsets	list	List of (x, y) offsets from the dispenser reference point for each dispense tip.
line_volume	int or float	Volume (in mL) corresponding to one full tube line between the pump and dispense head.
waste	Well, optional	Location for dumping waste liquid, if applicable.

Assertion: Number of pumps must match number of dispense tips.

Key Properties

Property	Type	Description
n_dispense_heads	int	Number of dispense heads.
waste	Well or Location	Waste container location.
line_volume	int or float	Configured prime volume for one tubing line.
pump_group	PeristalticPumps	Linked pump controller.

Important Methods

Method	Returns	Description
from_config(index, pump_group, config_file, path)	PumpDispenser	Load dispenser configuration from a JSON file.
add_waste(location)	None	Define a waste basin location.
dispense(vol, location, dispense_head_index=None)	None	Dispense a volume at a location using one or more dispense heads.
prime_lines(volume=None, location=None)	None	Fill tubing lines with liquid to prime the system.
empty_lines(volume=None)	None	Return line contents back to source by reversing pumps.

Method Details

From Config

PumpDispenser.from_config(index, pump_group, config_file, path)

Initialize a PumpDispenser instance from a JSON config file containing tip offsets, line volume, etc.

Add Waste

add_waste(location)

Assign a well or location to receive excess liquid from line priming or flushing.

Dispense

dispense(vol, location, dispense_head_index=None)

Dispense liquid through one or multiple dispense tips.

• If vol is a list, each dispense head can have a different volume.
• If vol is a single number and dispense_head_index is provided, that dispense head alone will dispense.
• If vol is a single number and dispense_head_index is omitted, all heads will dispense that volume.

Moves precisely to each dispense tip’s offset before actuating the pumps.

Prime Lines

prime_lines(volume=None, location=None)

Fill all tubing lines by pumping forward, typically into a waste container.

• If volume is omitted, uses line_volume preset.
• If location is omitted, uses the assigned waste container.

Empty Lines

empty_lines(volume=None)

Reverse pumps to withdraw liquids from tubing lines back to the source.

Typically used to clear tubing after dispensing runs.

Usage Flow Example

# Initialize from config
dispenser = PumpDispenser.from_config(index=2, pump_group=pump_controller, config_file="pump_dispenser_config.json")

# Add waste basin
dispenser.add_waste(my_waste_basin)

# Prime all lines
dispenser.prime_lines()

# Dispense 2 mL from dispense head 1
dispenser.dispense(2, my_target_well, dispense_head_index=1)

# Or dispense 1 mL simultaneously from all heads
dispenser.dispense(1, my_target_well)

# After experiment, empty the lines
dispenser.empty_lines()

Important Notes

• All dispenser tips have individual X/Y offsets relative to the tool mounting point.
• Priming is required after startup or tubing replacement.
• Supports flexible dispensing patterns (single, simultaneous, or unique-volume across heads).

Related Concepts

• PeristalticPumps
• Labware
• Well