Metadata-Version: 2.4
Name: matterlab_shakers
Version: 1.1.0
Summary: A Python API for the shakers 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/serial-device
Keywords: shaker,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_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:

```bash
pip install matterlab_shakers
```

For development:

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

The package depends on `matterlab_serial_device`.

## Quick Start

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

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

Direct pytest run:

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

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

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

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