Experimental parameter documents for strobo 2.0

This directory holds machine-readable parameter documents that describe the calibrated experimental apparatus, in the form the simulation consumes. The intent is that the lab runs a calibration sequence and emits a JSON file of this format, then the simulation runs against that file — no hand-copying of numbers between notebook margins and run_sweep.py.

Files

File	Purpose
strobo2p0_params.json	Current configuration for the strobo 2.0 sweep (v0.3, π/2-calibrated).
load_params.py	Loader: JSON → engine kwargs. Also a CLI validator/summariser.
../../schemas/experimental_params_v1.schema.json	JSON Schema definition (v1.0).

Shape of the document

schema_version, document_id, calibration_date, operator, apparatus_reference
ion:                 species, qubit_transition
trap.motional_modes: omega_m, eta, <n>_thermal, ...              (per mode)
beams:               rabi, eta_per_mode, wavelength, ...         (per beam)
pulse_sequences:     beam, mode, n_pulses, pulse_duration,
                     inter_pulse_spacing, rabi_override,
                     analysis_phase_deg                          (per sequence)
decoherence:         spin_T2, motional_heating_rate, ...
initial_state:       spin_preparation, motional_preparation,
                     displacement_amplitudes
notes:               free-form audit trail

Every quantity is {value, unit, stderr, source, notes} — bare floats are forbidden by design. stderr may be null (unknown) or 0 (exact by construction). source names the calibration routine, the design choice, or the literature citation that fixed the value.

Using it

As a CLI sanity check / summary

python3 load_params.py strobo2p0_params.json

Prints every measured value + its source, and for each pulse sequence derives and prints the engine kwargs that it would produce.

In Python

from load_params import load_params, engine_kwargs_for_sequence

doc = load_params("strobo2p0_params.json")
kwargs = engine_kwargs_for_sequence(doc, "T2_short_pi2")
# kwargs -> omega_m, omega_r, eta, n_pulses, delta_t_us, t_sep_factor,
#           ac_phase_deg  (ready for stroboscopic_sweep.run_single)

From the sweep runner

python3 ../numerics/run_sweep.py --params strobo2p0_params.json

run_sweep.py overrides its in-file defaults from the parameter document and records the document's document_id + calibration_date in the output manifest for provenance. Running without --params keeps the current hard-coded defaults (identical to the committed v0.3 values).

What belongs in a parameter document

Yes: calibrated lab parameters with a trace back to how they were fixed (ω_m, η, Ω, δt, spacing, T2, n̄_th, |α| calibration amplitudes).

No: observation grids (detuning range, ϑ₀ density, Nmax) — those are numerical-method choices and stay in run_sweep.py / plotting scripts.

No: derived convenience values (Ω_eff, N·θ_pulse, Δφ_strobo) — derive them at load time, don't store them.

No: observables / outputs — the manifest schema (schemas/manifest_v2.schema.json) covers those.

Adding another configuration

Copy strobo2p0_params.json, change document_id and calibration_date.
Edit the calibrated values. Keep source and stderr fields accurate — the history is the point.
Sanity-check with python3 load_params.py your_new.json.
Optionally run python3 ../numerics/run_sweep.py --params your_new.json to produce a companion sweep dataset.

Version policy

The schema is versioned (schema_version: "1.0"). Additive changes (new optional fields) can stay at 1.x. Any breaking change requires a 1.0 → 2.0 bump plus a schemas/experimental_params_v2.schema.json file and a new load_params_v2.py loader — the old loader keeps working for old documents.