matterlab-shakers 1.1.0

A Python API for the shakers in the Matter Lab.

matterlab_shakers

matterlab_shakers provides serial drivers for the shakers used in the Matter Lab. It includes a shared shaker interface and a driver for Torrey Pines temperature-controlled shakers.

Supported Devices

• Shaker: shared abstract base class
• TorreyPinesShaker

Installation

Install the package:

pip install matterlab_shakers

For development:

pip install -e .[dev]

The package depends on matterlab_serial_device.

Quick Start

from matterlab_shakers import TorreyPinesShaker

shaker = TorreyPinesShaker(com_port="COM5")

print("Current temperature:", shaker.temp)
print("Current speed level:", shaker.speed)

shaker.temp = 40
shaker.speed = 3
shaker.idle = True

Core API

The shared Shaker interface exposes:

• temp
• target_temp
• speed
• idle

The Torrey Pines driver adds:

• device_model
• serial_number
• connect()
• error_reporting(...)

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_shaker.py tests/test_torrey_pines_sim.py

Hardware Tests

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

Available hardware test files:

• tests/test_torrey_pines_real.py

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

Example:

pytest tests/test_torrey_pines_real.py --run-real --com-port COM5

You can also provide hardware configuration through an environment variable:

• SHAKER_COM_PORT

Examples

The examples/ directory contains the recommended entry points:

• examples/test_sim.py: one-click simulation-only test runner
• examples/real_devices.py: readable examples for real Torrey Pines hardware
• examples/README.md: short guide to the examples directory

Development

Useful commands:

pytest
ruff check .
ruff format .

The default pytest configuration includes retries, timeouts, coverage output, and uses src as the import root for local development.

Package Layout

src/matterlab_shakers/
  base_shaker.py
  torrey_pines_shakers.py
tests/
examples/

License

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