Hub
Docs

Plesty Documentation

Run Setup

What decides which instruments a run starts and on which bench — setup.yaml as the run's contract, variables in it, choosing the devices per run with @cli.needs, and where a run's settings are saved.

The Rig names the instruments the experiment calls. Which of them a run starts, on which PC, with which options, is the run's setup. It comes from three places, each owned by someone else:

Written by Holds
setup.yaml you, the module author — committed with the module the benches and devices the experiment can use
.env beside it each lab, on its own PC — never committed the values setup.yaml names: addresses, tokens, where the shared disk is
the run's configuration the operator, per run the settings — and, through them, which devices this run uses

setup.yaml is the run's contract

A bench is a lab PC running PLESTY Bench. setup.yaml lists the benches the experiment may use and, for each device of the rig, the module that serves it and the bench it runs on:

version: 1
benches:
  bench-local:                    # no address: the PC the run is on
    data: ${LOCAL_DATA}           # where it sees the shared data disk
  spec-pc:
    data: ${SPEC_PC_DATA}
    address: ${SPEC_PC_ADDRESS}   # where its bench agent listens
    token: ${SPEC_PC_TOKEN}
devices:
  hwp:  {package: plesty-k10cr1, host_name: bench-local, args: [--mock]}
  spec: {package: plesty-lightfield-spectrometer, host_name: spec-pc}
  pm:   {package: plesty-pm100d, host_name: bench-local}

The names under devices are the names of RIG. A bench's fields are always a ${VARIABLE}: a value written into the file is refused, because the file travels with the module to every lab. The values go in .env; a fresh checkout has none, and the first start writes a line for each variable and stops, naming the ones still to set. --dry-run connects nothing and needs none of them.

Before anything connects, the command line reads setup.yaml. The run gets PLESTY_DATA, where this PC sees the shared disk, and each device's <NAME>_ADDRESS comes from the bench that started it. The lib's setup file reference has every field.

Variables in a device's options

From PLESTY Bench 0.5.0, a device's args may name a variable too. It is read from the experiment's .env or its declaration, the same way as a bench's fields:

  spec:
    package: plesty-lightfield-spectrometer
    host_name: bench-local
    args: [--replay-run-root, "${LOCAL_DATA}/pol-pl"]

A variable that nothing sets stops the start with its name, before the device is started.

A variable for one device only

On a bench, the experiment has a declaration: its entry in the bench's fleet file, with the module, its source and an env: for its runs. From PLESTY Bench 0.5.0, <STEM>__<NAME> in that env: sets NAME for one device of the setup, and only while this experiment serves it. <STEM> is the device's name in capitals, as in SPEC_ADDRESS:

experiments:
  pol-pl:
    package: plesty-pol-pl
    env:
      SPEC__DEVICE_DATA_PATH: demo/spec     # DEVICE_DATA_PATH, for spec only

The setting stays with this experiment. Written into the device's own .env, it would reach every later experiment that serves a spec on that bench.

Choose devices per run

One module often measures in more than one way. Suppose this one also has a power calibration, config/calibration.yaml with spectra: false, which turns the plate and reads the power meter but takes no spectra. Without more code, every run still starts all three devices, and a calibration on its own PC stops on spec-pc's unset address.

From plesty-lib 0.6.0 the module can say, from the settings alone, which devices a run uses:

# __main__.py, beside @cli.rig and @cli.build
@cli.needs
def needs(config):
    return ["hwp", "pm"] if config.get("spectra") is False else None   # None: all of them

The function gets the run's settings before anything connects. It returns the names under devices in setup.yaml, or None for all of them. Ask it from a terminal:

uv run python -m plesty.demo_pow_pl --devices --config config/calibration.yaml

{"devices": ["hwp", "pm"]}

With @cli.needs registered, the manifest says "chooses_devices": true. Before a run, PLESTY Bench 0.5.0 then asks the module for its devices. It starts and checks the shared disk on only those devices and the benches that serve them, and it does not ask for the others' addresses. The run reads the same choice: only the benches of the chosen devices need their variables set. The bench the run is on is always kept. A name that setup.yaml does not have is refused before anything connects, for example no device cam in setup.yaml (it has hwp, spec, pm).

The step methods must agree with the choice. With spectra: false, the plan must not call spec, because spec is not started. A module without @cli.needs gets every device, as before. A program that reads the setup itself does the same with Setup.only(devices) or apply_setup(devices=…) from plesty.lib.experiment.setup.

Where a run's settings are saved

The operator changes a run's settings in PLESTY Bench's Configure… (see Run It from the Bench). From PLESTY Bench 0.5.0, saving never touches the module's own files:

  • On a run, the settings go to that run's config.yaml, in its folder.
  • On an experiment with no run yet, they go to the bench's own copy, <home>/run/<experiment>/config/…, which new runs start from.
  • Device Setup writes the values into the checkout's .env, which only the operator can read. Into setup.yaml it writes only the name of each variable.

So the config/*.yaml files you ship are what a new install starts from, and they change only through the module's repository.

Once the run knows its devices, setup() tells each one where to save into the run's folder. See Plan & Steps.

Next: Plan & Steps.