EPR automation

epr_auto is a YAML protocol runner for unattended pulsed-EPR tune-up and measurement on the endstation's X-band pulsed machine. Instead of clicking through the phasing, field, and acquisition tools by hand for every sample, you declare the run as a list of steps in a text file; the runner tunes the spectrometer, judges every result, adapts the scan count to a signal-to-noise target, and records a manifest of what it did.

A protocol is a short, diffable description of intent. Each step names a primitive — set the temperature, find the line, calibrate the pulses, zero the phase, measure a relaxation curve — with per-step parameter overrides. The runner executes them in order, applies a pass/fail judge to each result, carries calibrations forward (a measured field or phase feeds later steps), and pauses or notifies according to the protocol's autonomy policy.

It ships only with Atomize_ITC, the EPR-endstation variant of Atomize — not with plain Atomize and not from PyPI. The machine it drives is described on the endstation page.

How it relates to the GUI tools

epr_auto does not re-implement the spectrometer. Its engine reuses the AWG phasing tool's own acquisition worker (the Worker class from awg_phasing_insys.py), the same hardware-validated scan loop the GUI pickles when you press Start. The engine only rebuilds the argument tuples the GUI would have built from a preset, so an engine run is argument-identical to a GUI-launched run of the same *.phase_awg preset. Because the acquisition path is unchanged, a run started from a terminal while the Atomize GUI is open plots live into that GUI exactly as an interactive scan does — the runner reaches the same LivePlot socket. This is also why the command-line runner changes its working directory into libs/ before touching hardware: the Insys FPGA driver reads its brd.ini / exam_adc.ini relative to the current directory at instantiation time.

The preliminary-tuning workflow adds a ringing check, an optional resonator scan, echo search and optimization, and a preset handoff for fine tuning. Start from protocols/preliminary_tuning.yaml in the ITC repository.

Launch protocols with Run protocol on the EPR Endstation Control tab, or from a terminal while the Atomize GUI is open for live plotting. The launcher has a separate Dry run checkbox, checked by default. See Running from the main window.

A protocol at a glance

sample: RO2411
autonomy: checkpointed        # supervised | checkpointed | autonomous
notify: none                  # telegram: notify on checkpoint/finish/abort

steps:
  - tune.power_for_length:    # coarse: rotary vane sets the power regime
      target_length: 32 ns
      amplitude: 95
  - field.edfs:               # find the line, center from h*nu/(g*mu_B)
      range: auto
      pick: max
  - tune.echo_window          # integration window from the averaged echo
  - tune.auto_phase           # zero the signal phase (runs after the window)
  - tune.pi_calibration:      # fine: per-pulse AWG amplitude sweep
      mode: amplitude
      retries: 1

Steps with no parameters are written as a bare name; everything else is a key/value block. Full step and parameter details are on the Step reference page and are also available offline from epr-auto steps.

Current status

Fine-tuning and relaxation steps have been used on the spectrometer. Preliminary tuning is implemented and dry-run tested; its complete hardware workflow is still being validated. Use supervised mode for initial live runs.

Where to go next

Page	What it covers
Quickstart	Install, validate, and dry-run a protocol
Writing protocols	The YAML schema, autonomy, foreach series, value substitution
Step reference	Every step, its parameters, defaults, and constraints
The tune-up chain	How the calibration steps compose and invalidate each other
Presets	What a step expects of a .phase_awg preset, and what the runner overrides
Examples	Two annotated protocols: a single T2 and a field series
Troubleshooting	Common failures, verbatim, and what they mean