Quickstart

This page gets you using PLESTY: run a complete experiment without any hardware, drive a real instrument through a hub device module, and see how the pieces fit together. If you want to build modules yourself, the contributing section at the bottom points you to the right guides.

Prerequisites

You do not need to install Python yourself — uv sync downloads and manages the right Python version for each module automatically. uv also replaces pip, poetry, and conda; no other Python tooling is required.

Try it in five minutes — no hardware needed

The demo experiment runs a complete PLESTY measurement workflow with simulated data:

git clone https://gitlab.com/plesty/hub/experiments/demo.git
cd demo
uv sync
uv run python -m plesty.demo_experiment --points 5

Every run produces a self-describing result directory — this layout is the same for every PLESTY experiment:

runs/<run_id>/
├── plan.json        # frozen measurement schedule + content hash
├── journal.jsonl    # append-only event log
└── data/            # per-step results: raw blob + JSON metadata

Interrupt it and run uv run python -m plesty.demo_experiment --resume <run_id> — completed steps are skipped. That is the checkpoint/resume behaviour every PLESTY experiment inherits for free.

Use a device module

Hub modules live under gitlab.com/plesty/hub, organized as devices/<vendor>/<module>, analyzers/, and experiments/. Install one by cloning it — for example the Thorlabs PM100D power meter:

git clone https://gitlab.com/plesty/hub/devices/thorlab/plesty-pm100d.git
cd plesty-pm100d
uv sync

Use it directly from Python — connecting is a context manager, so the instrument is always released cleanly:

from plesty.pm100d import Device

with Device() as dev:  # connects to the instrument
    result = dev.configure_and_measure_power(wavelength=780.0)
    print(result)

Every device module shares the same standard API (connect, write, query, reset, …) on top of its instrument-specific operations, so once you know one PLESTY device, you know them all. Each module's own documentation (linked from its repository) lists its parameters and operations.

Compose devices over the network

Any device can also run as a TCP server, so analyzers and experiments — possibly on another machine — can use it remotely:

uv run python -m plesty.pm100d --tcp-port 5555

This is how full setups are built: device modules serve the instruments, analyzers turn raw readings into results, and experiment modules orchestrate all of them into a measurement workflow.

The ecosystem at a glance

• plesty-lib — the runtime every module builds on: device base classes, the data layer, and the experiment framework. Published on PyPI.
• plesty-sdk — the plesty CLI for module developers: scaffolding, quality checks, docs. Published on PyPI.
• The hub — the module catalog: devices, analyzers, and experiments.

Every hub module passes the same quality gates before it is released, so any module you clone follows the same structure, API conventions, and documentation standard.

Contributing at a glance

Missing an instrument? Any module you need for your own setup can become a hub module — that is how the hub grows. In short: scaffold a project with plesty init, implement against the plesty-lib base classes, and let plesty check guide you until the module meets the standard. The detailed guides cover everything:

• Build a Device — from scaffold to a working instrument API
• Build an Experiment — plans, journaling, resume
• Workflow — branch discipline, CI, publishing
• Quality Gates — what plesty check verifies and why

The remaining quickstart pages walk through the contributor setup at introductory level:

• Workspace Setup — clone a module, dev environment, key files
• Your First Check — run plesty check and read the output
• Fixing Failures — triage and fix gate failures