matterlab-pumps 1.1.0

A Python API for the pumps in the Matter Lab.

matterlab_pumps

matterlab_pumps is a Python package for controlling several syringe and peristaltic pump controllers used in the Matter Lab. It provides shared base classes plus device-specific drivers built on top of matterlab_serial_device.

Supported Devices

• SyringePump: shared abstract base class for syringe-style pumps
• TecanXCPump
• TecanXLPPump
• TecanCentrisPump
• RunzePump
• JKemPump
• LongerPeristalticPump
• ContinuousDualSyringe

Installation

Install the package:

pip install matterlab_pumps

For development:

pip install -e .[dev]

The package depends on matterlab_serial_device, which is installed automatically.

Quick Start

Example with a Tecan XC syringe pump:

from matterlab_pumps import TecanXCPump

pump = TecanXCPump(
    com_port="COM5",
    address=0,
    syringe_volume=1e-3,
    num_valve_port=12,
    ports={"source": 12, "reactor": 1},
)

pump.draw(0.25, "source", speed=0.5)
pump.dispense(0.25, "reactor")

Core concepts:

• syringe_volume is given in liters
• draw(...) and dispense(...) use milliliters
• port exposes the active valve position
• named ports can be supplied through the ports mapping

Core API

The shared SyringePump base class provides the main high-level workflow methods:

• draw(volume, valve_port=None, speed=None)
• dispense(volume, valve_port=None, speed=None)
• draw_and_dispense(volume, draw_valve_port, dispense_valve_port, speed=None, wait=0)
• draw_full(...)
• dispense_all(...)
• switch_port(...)

Concrete device classes implement:

• port
• volume
• top_speed_ml
• set_default_speeds()

Testing

Simulation Tests

Simulation tests are the default validation layer and are safe for CI.

One-click run:

python examples/test_sim.py

Direct pytest run:

pytest tests/test_base_pump.py tests/test_jkem_sim.py tests/test_tecan_xlp_sim.py tests/test_tecan_centris_sim.py tests/test_tecan_xc_sim.py tests/test_runze_sim.py tests/test_longer_peri_sim.py tests/test_continuous_dual_syringe_sim.py

Hardware Tests

Hardware tests are opt-in because real devices may not be connected in every environment.

Available hardware test files:

• tests/test_jkem_real.py
• tests/test_tecan_xlp_real.py
• tests/test_tecan_centris_real.py
• tests/test_tecan_xc_real.py
• tests/test_runze_real.py
• tests/test_longer_peri_real.py
• tests/test_continuous_dual_syringe_real.py

They are marked with @pytest.mark.real and are skipped unless --run-real is supplied.

Example:

pytest tests/test_tecan_xc_real.py --run-real --com-port COM5 --address 0 --syringe-volume 1e-3 --num-valve-port 12

You can also provide hardware configuration through environment variables:

• PUMP_COM_PORT
• PUMP_ADDRESS
• PUMP_SYRINGE_VOLUME
• PUMP_NUM_VALVE_PORT

Examples

The examples/ directory contains the recommended entry points:

• examples/test_sim.py: one-click simulation-only test runner
• examples/real_devices.py: human-readable examples for all currently supported pump families
• examples/README.md: short guide to the examples directory

Development

Useful commands:

pytest
ruff check .
ruff format .

The default pytest configuration includes a timeout and colorized output from pyproject.toml.

Package Layout

src/matterlab_pumps/
  base_pump.py
  jkem_pump.py
  runze_pump.py
  tecan_centris_pump.py
  tecan_xc_pump.py
  tecan_xlp_pump.py
  longer_peri.py
  continuous_dual_syringe.py
tests/
examples/

License

This project is distributed under the MIT License. See LICENSE for details.