Build an Experiment

What is an experiment?

An experiment is the top tier of the PLESTY pipeline. It connects to one or more device TCP servers, defines the measurement schedule, and persists every result — so that a crashed or interrupted measurement can resume exactly where it stopped instead of re-measuring from scratch.

Experiments are built on the async plesty.lib.experiment.Experiment base class:

• The measurement is expressed as a frozen plan of atomic steps — each step either completes (its result is persisted and journaled) or is re-run on resume
• Devices are held in a CompositeDevice — an experiment receives device clients, never raw hardware
• Every run writes a crash-safe journal and stores each step result as raw blob + JSON metadata
• Experiments do not run as TCP servers — they are the client side of the pipeline

The development path

1. Scaffold — plesty init experiment, the generated layout, and the config/credentials split
2. The Experiment class — the lifecycle hooks your subclass implements
3. Plan & step operations — designing the atomic schedule and writing measurement steps
4. CompositeDevice — grouping device clients under named attributes
5. Runs, data & resume — what a run persists and how resume works
6. Testing — the ExperimentPipeline contract gates and mocking devices

Reference examples

• demo experiment (plesty-demo-experiment) — the minimal reference: a mock line scan that runs with no hardware attached and exercises the full lifecycle (plan, journal, checkpointing, resume). Published on the TestPyPI channel; install and run it as shown in Publishing.
• plesty-pl-image-scan — a production experiment: a photoluminescence image scan of a QD chip driving a piezo stage and camera. Shows the .env credentials / config/scan.yaml tuning split, atomic journaled steps (an interrupted scan resumes at the cell where it stopped), and a --dry-run flag that prints the planned steps.

pyproject.toml for experiments

[tool.plesty]
# standard derives from the release version; pin with standard = "quantum".
module_type = "experiment"

[project]
dependencies = [
    "plesty-lib",
    "pyyaml",
]

Experiments follow the same quantum standard as devices; gate d1 does not apply (module_type != "device").