Metadata-Version: 2.5
Name: plesty-lib
Version: 0.6.2
Summary: A library for the Plesty ecosystem.
Author: Plesty Development Team
Author-email: Yunshuang Yuan <yunshuang.yuan@fkp.uni-hannover.de>
Maintainer-email: Plesty Development Team <yunshuang.yuan@fkp.uni-hannover.de>
License-Expression: LGPL-3.0-or-later
License-File: LICENSE
License-File: LICENSES/LGPL-3.0-or-later.txt
Requires-Python: >=3.12
Requires-Dist: numpy>=1.24
Requires-Dist: pyserial>=3.5
Requires-Dist: pyusb>=1.2.1
Requires-Dist: pyvisa>=1.13
Requires-Dist: pyyaml>=6.0
Requires-Dist: pyzmq>=25.0
Provides-Extra: fit
Requires-Dist: scipy>=1.11; extra == 'fit'
Provides-Extra: gui
Requires-Dist: pyqtgraph>=0.13; extra == 'gui'
Requires-Dist: pyside6>=6.6; extra == 'gui'
Provides-Extra: hdf5
Requires-Dist: h5py>=3.10; extra == 'hdf5'
Provides-Extra: record
Requires-Dist: imageio-ffmpeg>=0.4; extra == 'record'
Requires-Dist: imageio>=2.31; extra == 'record'
Requires-Dist: pillow>=10.0; extra == 'record'
Provides-Extra: report
Requires-Dist: latex2mathml>=3.77; extra == 'report'
Description-Content-Type: text/markdown

# PlestyLib

PlestyLib is the core Python library of PLESTY, a platform for automating lab
measurements. Code built on it comes in three kinds, each a **module** of its own:

- a **device** controls one instrument;
- an **experiment** runs a measurement with devices and records it;
- an **analyzer** turns recorded data into a result.

PlestyLib gives each kind a standard shape, so every instrument is driven the same
way and every measurement is recorded the same way. It provides:

1. Base classes for devices, with parameter and operation systems, status
   snapshots, and serving a device over the network
2. Connections to instruments: serial, VISA, TCP/IP, and Thorlabs APT controllers
   (including those Kinesis has bound to FTDI's D2XX driver)
3. Command solvers that translate standard calls into an instrument's own protocol,
   such as SCPI
4. Experiments: a standard command line, run folders on a shared data disk,
   resuming, stopping, and a journal of every run
5. Analyzers, HTML reports, and a viewer that plots a measurement live or replays
   it afterwards
6. Test helpers for all three kinds of module

Full documentation: <https://docs.plesty.net/plesty-lib/>.

## Requirements

- Python 3.12+


## Installation

Install from package index:

```bash
pip install plesty-lib
# or 
uv add plesty-lib
```

### Optional dependencies

Features that need a heavy or platform-specific package keep it out of the
base install and behind an extra. Without the extra the feature raises an
`ImportError` naming it; nothing else is affected.

| Extra | Adds | Enables |
|---|---|---|
| `gui` | `pyside6`, `pyqtgraph` | windows: device control panels and the viewer that plots a measurement |
| `record` | `pillow`, `imageio`, `imageio-ffmpeg` | saving a measurement's plots as a video (MP4, or GIF with Pillow alone) |
| `report` | `latex2mathml` | equations in reports opened as HTML; without it they show as LaTeX source |
| `fit` | `scipy` | `SpectrumFit` analyzer — Gaussian / Lorentzian / Voigt spectrum fits |
| `hdf5` | `h5py` | `convert_to_hdf5` — packs saved results into one HDF5 archive |

```bash
pip install "plesty-lib[gui,record]"
# or
uv add "plesty-lib[gui,record]"
```

For development, install from source and sync the dev dependency group:

```bash
uv sync --group dev
# or
pip install -e .
pip install plesty-sdk
```

## Quick Start

### 1. Create a device class from a base device

```python
from plesty.lib.device.base_visa_scpi_device import BaseVisaScpiDevice


class PowermeterDevice(BaseVisaScpiDevice):
	def __init__(self, address: str):
		super().__init__(address)
		self.register_config("POWER", dtype=float, read_only=True, command="MEAS:SCAL:POW")
		self.register_config("WAVELENGTH", dtype=int, unit="nm", command="SENS:CORR:WAV")
```

### 2. Use the device

```python
# replace the serial number P0000001 with that of your own device
address = "USB0::0x1313::0x8078::P0000001::INSTR"

with PowermeterDevice(address) as dev:
	print(dev.identity())
	print(dev.query("POWER"))
```

The documentation's quick start continues from here: serving the device over the
network, using it without the instrument, then
[an experiment](https://docs.plesty.net/plesty-lib/latest/quickstart/experiment.html) and
[an analyzer](https://docs.plesty.net/plesty-lib/latest/quickstart/analyzer.html).

## Architecture Overview

A device is built in layers, and a module's author only writes the lower ones:

1. Traffic manager: the connection to the instrument (serial, VISA, TCP/IP, APT)
2. Command solver: maps standard calls to the instrument's protocol
3. Synchronous device: the class the author writes, with its parameters and operations
4. Provided by PlestyLib: the asynchronous wrapper, the network server, and a client
   that drives a remote device with the same calls as a local one

An experiment then drives devices through those clients, and an analyzer reads what
the experiment recorded. [Concepts](https://docs.plesty.net/plesty-lib/latest/concepts/index.html)
explains how the parts fit together.


## License

Plesty is licensed under the GNU Lesser General Public License v3.0 or later
(LGPL-3.0-or-later). See the LICENSE file.
