Metadata-Version: 2.4
Name: matterlab_hotplates
Version: 1.1.1
Summary: A Python API for the hotplates 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/hotplates
Keywords: hotplate,automation,matterlab
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
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_hotplates

`matterlab_hotplates` provides serial drivers for the heat-stir devices used in the Matter Lab. The package wraps device-specific command sets behind a small common interface so automation code can read temperatures, set heating targets, and control stirring without dealing with raw serial commands.

## Supported Devices

- `HeatStirPlate`: shared abstract base class
- `IKAHotplate`
- `HeidolphHotplate`
- `IKAHBHotbath`

## Installation

Install the package:

```bash
pip install matterlab_hotplates
```

For development:

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

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

## Quick Start

Example with an IKA hotplate:

```python
from matterlab_hotplates import IKAHotplate

hotplate = IKAHotplate(com_port="COM5")

print("Current temperature:", hotplate.temp)
print("Current stirring speed:", hotplate.rpm)

hotplate.temp = 80
hotplate.rpm = 400
hotplate.stand_by()
```

## Core API

The shared `HeatStirPlate` interface exposes:

- `temp`
- `target_temp`
- `rpm`
- `target_rpm`
- `stand_by()`

Device-specific classes add their own helpers:

- `IKAHotplate`: `reset()`, `tare()`, `weight`
- `HeidolphHotplate`: `_set_new_interface_protocol()`
- `IKAHBHotbath`: `name`, `maxtemp`

## 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_heat_stir_plate.py tests/test_ika_sim.py tests/test_heidolph_sim.py tests/test_ika_hotbath_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_ika_real.py`
- `tests/test_heidolph_real.py`
- `tests/test_ika_hotbath_real.py`

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

Example:

```bash
pytest tests/test_ika_real.py --run-real --com-port COM5
```

You can also provide hardware configuration through an environment variable:

- `HOTPLATE_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 IKA, Heidolph, and hotbath 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_hotplates/
  base_hotplate.py
  heidolph_hotplate.py
  ika_hotbath.py
  ika_hotplate.py
tests/
examples/
```

## License

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