Metadata-Version: 2.4
Name: matterlab_pumps
Version: 1.1.0
Summary: A Python API for the pumps in the Matter Lab.
Author: Han Hao, Martin Seifrid, Tony C. Wu
License-Expression: MIT
Project-URL: homepage, https://gitlab.com/aspuru-guzik-group/self-driving-lab/devices/pumps
Keywords: pump,automation,matterlab
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: System :: Hardware
Classifier: Topic :: System :: Hardware :: Hardware Drivers
Classifier: Topic :: System :: Hardware :: Universal Serial Bus (USB)
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: matterlab_serial_device
Provides-Extra: dev
Requires-Dist: mypy>=0; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: pytest-cov>=3; extra == "dev"
Requires-Dist: pytest-mock>=3; extra == "dev"
Requires-Dist: pytest-rerunfailures; extra == "dev"
Requires-Dist: pytest-timeout; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Dynamic: license-file

# 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:

```bash
pip install matterlab_pumps
```

For development:

```bash
pip install -e .[dev]
```

The package depends on `matterlab_serial_device`, which is installed automatically.

## Quick Start

Example with a Tecan XC syringe pump:

```python
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:

```bash
python examples/test_sim.py
```

Direct pytest run:

```bash
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:

```bash
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:

```bash
pytest
ruff check .
ruff format .
```

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

## Package Layout

```text
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.
