# Setup

## The devices

![The rig: two device servers, and the spectra on the shared disk](media/rig.svg)

| Sub-device | Instrument | Package | Bench |
|---|---|---|---|
| `hwp` | Thorlabs K10CR1 rotation stage carrying the half-wave plate | `plesty-k10cr1` | `bench-local` |
| `spec` | Princeton Instruments LightField spectrometer | `plesty-lightfield-spectrometer` | `bench-local` |

`setup.yaml` names both, each on the bench it runs on (`host_name`); another
bench is shown commented out, as an example. The servers are installed and run
from their own repositories, on the computers the hardware is attached to.
Spectra never cross the network: the spectrometer writes them to the shared
data disk and only their paths travel.

## The plan

![Light passed against the rotator angle, for a half-wave plate and a polarizer](media/polarization.svg)

One step is one plate angle of one dot. The dots run in the order of `qds`,
each through every angle from `hwp.start_deg` to `hwp.stop_deg` in `step_deg`,
then one analysis step. The plate turns the polarization by twice its angle, so
the pattern repeats every 90°; the default 0–178° in 2° steps covers it twice.
`--dry-run` prints the plan without touching a device.

## What to set before a run

1. `.env.example` → `.env`: `LOCAL_DATA`, where this machine sees the shared
   data disk, and the address, token and data path of any other bench
   `setup.yaml` names. A bench writes this file when it installs the module.
2. `qds`: each dot's `id` and stage coordinates. The run does not move the
   sample — each dot must be on the spectrometer when its sweep starts.
3. `analysis.fit_options`: the lines to follow, by position (`peaks`) or by
   how far they stand above their surroundings (`prominence`).

## Configuration

`config/default.yaml`, frozen into each run's plan: a resumed run refuses a
changed one. Sections left out take the module defaults.

| Group | Acts on | Keys |
|---|---|---|
| — | the whole run | `sample`, `qds` (each `{id, x_um, y_um}`), `step_settle_s` |
| `hwp` | **Move the plate to θ** | `start_deg`, `stop_deg` (inclusive), `step_deg` |
| `spectra` | **Take a spectrum** | `exposure_ms`, `frames` (summed), `filename_prefix`, `file_visibility_timeout_s` |
| `analysis` | ② | `enabled`, `rotator` `hwp`/`polarizer`, `fit_options` — `peaks` or `prominence` + `average`, `window`, `center_tolerance` |

`--prominence COUNTS` replaces `analysis.fit_options.prominence` for one run;
the run saves the value it used. `--manifest` prints every key with its type,
unit, bounds and meaning, from `SCHEMA` in `plesty/pol_pl/__main__.py`. The
time windows and the 0.01° tolerance of ① are properties of the hardware, fixed
in the packaged `plesty/pol_pl/config.yaml`.

```{literalinclude} ../config/default.yaml
:language: yaml
```