Reading a Run

Everything a run produced is in its folder (see The run folder), and Run reads it back, from any program, while the run is going on or years later. Run only reads: it cannot change the run or disturb the measurement.

Finding a run

A run’s id, which is also the name of its folder, is the experiment’s name and the time it started: powerscan_20260925-101534.

from plesty.lib.experiment import Run, latest_run, list_runs

list_runs("runs")                       # every run folder in runs/, oldest first
list_runs("runs", name="powerscan")     # only this experiment's runs
latest_run("runs", name="powerscan")    # the newest one

run = Run("runs/powerscan_20260925-101534")

The helpers in plesty.lib.experiment.runs work with ids directly: run_id(name) makes one for the current time, parse_run_id(text) splits one into the experiment’s name and start time, and check_run_id(text) refuses a name that cannot be a folder name, which is what --run-id uses.

What a run tells you

Call	Gives
run.id, run.name, run.started	the run’s id, the experiment’s name, and when it started
run.plan	the saved Plan
run.config	the settings the plan was built from
run.status()	state ("not_started", "running", "paused", "completed", "canceled" or "aborted"), and the counts of completed and failed steps
run.progress()	the same, plus the plan’s total steps, the fraction done, the time since the start (elapsed_s), the mean time per step (step_s), an estimate of the time left (eta_s, None until a step has finished), and what the current step last reported (step)
run.records()	the records, one dictionary per finished step, in order
run.provenance	which versions of which packages produced the run
run.local(path)	a recorded path on the shared disk, as a path on this computer (see Data on a Shared Disk)
run.path	the run’s folder

run = Run(latest_run("runs", name="powerscan"))
print(run.status()["state"])            # "completed"
print(run.progress()["fraction"])       # 1.0
for record in run.records():
    print(record["wavelength_nm"], record["power_w"])

status() and progress() read the journal again at each call, so they are current while the run goes on.

Watching a run as it goes

To follow a run’s data as it arrives, use a viewer made with Viz (see The Viewer: Viz); it reads the same folder and redraws as records arrive.