The Setup File

An experiment’s devices often run on several computers: a spectrometer on the computer its software is licensed on, a motor controller next to the optics, the experiment itself on a third. An experiment module describes that arrangement in a file called setup.yaml, at the top of the module.

Benches

The file is written in terms of benches. A bench is a lab computer that runs devices for experiments. On every bench except the one the experiment runs on, the PLESTY application plesty-bench runs a small background program, the bench agent, which installs a device’s module, starts its server, and tells the experiment where to find it.

You only need setup.yaml when the devices are started by bench agents. When you start the device servers yourself, as in In a Terminal, set each device’s address in .env instead (see The .env File).

The file

version: 1
benches:
  bench-local:                    # no address: the computer the run is on
    data: ${LOCAL_DATA}           # where it sees the lab's shared disk
  spec-pc:
    data: ${SPEC_PC_DATA}         # where it sees the same disk
    address: ${SPEC_PC_HOST}      # where its bench agent listens
    token: ${SPEC_PC_TOKEN}       # the password that agent checks
devices:
  hwp:  {package: plesty-k10cr1, host_name: bench-local, args: [--mock]}
  spec: {package: plesty-lightfield-spectrometer, host_name: spec-pc}

benches names each computer, with:

Field	Meaning
`data`	where this bench sees the lab’s shared disk (see Data on a Shared Disk)
`address`	where its bench agent listens. Leave it out for the bench the experiment runs on; at most one bench may have no address.
`token`	the password its bench agent checks

devices names each device the experiment uses, with:

Field	Meaning
`package`	the device module to install, as on PyPI
`host_name`	the bench it runs on; this computer when left out
`args`	command-line options for the device’s server, such as `--mock` to use a simulator

Values live in `.env`, not in the file

setup.yaml is part of the module and shared with everyone who uses it, so it holds no lab’s actual addresses or passwords. Each bench field is written as ${VARIABLE}, and the value of that variable is set in the module’s .env file, which is not shared. A value written directly into setup.yaml is refused (SetupError).

On a fresh copy of the module there is no .env. The first start creates one, with a line for every variable setup.yaml names (filled with the value suggested in .env.example if there is one, otherwise empty), and stops before connecting anything, naming the variables still to set. Exit code 2 means exactly that. --dry-run connects nothing and needs none of them.

What the run receives

When the run starts, The Command Line reads setup.yaml and sets PLESTY_DATA: where this computer sees the shared disk, from this bench’s data. A variable that is already set, by hand or in .env, is left as it is.

Each device’s address, <DEVICE>_ADDRESS, is not in the file: the bench agent that starts a device picks a free network port for it on each start, and the bench passes the address to the run it starts.

Where a device may save files is not in the file either: its own bench says so, with the bench’s folder on the shared disk (see Data on a Shared Disk).

The run records in its journal where each device was for this start: its bench, the address it was given, and its bench’s view of the shared disk. A token is never recorded.

Keeping `.env` in step with the file

Two functions in plesty.lib.experiment.setup help a program that edits the setup:

seed_env(root) adds a line to .env for every variable setup.yaml names that it does not have yet.
split_benches takes benches written with actual values and returns the ${VARIABLE} form for setup.yaml and the values for .env. A field keeps the variable it already has; a new one is named after its bench, such as LAB_PC_ADDRESS.

.env is written so that only its owner can read it.