Configuration
Configuration Reference
Generated field reference for pmoke config schema version 7.
Generated from the typed config metadata registry. Manual edits are overwritten.
JSON Schema · pmoke config explain
version
| Path | Type | Required | Default / values | Description and constraints |
|---|---|---|---|---|
version | integer | required | 6, 7 | Configuration schema version. New and migrated configurations use schema version 7; version 6 stays accepted. Constraints: must equal 6 or 7 |
scope
| Path | Type | Required | Default / values | Description and constraints |
|---|---|---|---|---|
scope | table | required | - | Oscilloscope configuration. Selects one registered scope model and its transport URI. |
scope.model | string | required | DHO5108 | Oscilloscope driver model. The model must match an oscilloscope registered by the instruments crate. Constraints: must be a registered oscilloscope model |
scope.connection | connection URI | required | tcp://, visa:, gpib:// | Oscilloscope transport URI. DHO5108 normally uses direct TCP/IP and never uses a Prologix transport. Constraints: transport must be supported by the model and build features |
generator
| Path | Type | Required | Default / values | Description and constraints |
|---|---|---|---|---|
generator | table | optional | absent | Optional function-generator configuration. Required only by commands that trigger or automate a measurement. Constraints: required by trigger, autoshot, automeasure, and auto |
generator.model | string | conditional | WF1946B | Function-generator driver model. Required when the generator table is present. Constraints: must be a registered generator model |
generator.connection | connection URI | conditional | gpib://, prologix-tcp://, prologix-serial:// | Function-generator transport URI. The URI selects native GPIB or a Prologix TCP/serial controller. Constraints: transport must be supported by the model and build features |
data
| Path | Type | Required | Default / values | Description and constraints |
|---|---|---|---|---|
data | table | required | - | Acquisition storage and analysis-input policy. Controls canonical waveform formats and optional screenshot capture. |
data.output | string enum | required | csv, raw, both | Waveform format written by acquisition. Raw is preferred for very large captures; both also writes CSV. |
data.input | string enum | required | csv, raw, auto | Waveform source used by analysis. Auto selects available canonical data, preferring verified raw data. |
data.screenshot | boolean | optional | false; true, false | Oscilloscope screenshot capture. Capture requires a scope and transport that support display transfer. Constraints: DHO5108 capture requires TCP/IP or USB-TMC |
sensors
| Path | Type | Required | Default / values | Description and constraints |
|---|---|---|---|---|
sensors | array of tables | conditional | [] | Sensor-channel metadata and scaling. Each entry assigns one channel and exactly one scaling strategy. Constraints: channels must not overlap reference or lock-in signal channels |
sensors[]
| Path | Type | Required | Default / values | Description and constraints |
|---|---|---|---|---|
sensors[].channel | integer | required | - | Oscilloscope sensor channel. The current DHO5108 mapping accepts channels 1 through 8. Constraints: 1 <= value <= 8; must be unique across all channel roles |
sensors[].scale | inline table union | required | { factor = ... }, { max_abs = ..., polarity = ... } | Sensor conversion rule. Choose direct multiplication or maximum-absolute normalization. Constraints: factor and max_abs forms are mutually exclusive |
sensors[].scale.factor | float | conditional | - | Linear sensor conversion factor. Multiplies the integrated sensor values directly. Constraints: must be finite and non-zero |
sensors[].scale.max_abs | float | conditional | - | Target maximum absolute sensor value. Normalizes the measured absolute maximum to this positive target. Constraints: must be finite and positive |
sensors[].scale.polarity | integer enum | conditional | -1, 1 | Polarity for maximum-absolute scaling. Required with max_abs scaling. Constraints: must equal -1 or 1 |
sensors[].label | string | required | - | Plot label for the sensor. Matplotlib mathtext may be supplied as a TOML literal string. Constraints: must not be empty |
sensors[].unit | string | required | - | Output unit for the scaled sensor. Used in tables, plots, and saved analysis headers. Constraints: must not be empty |
pulse
| Path | Type | Required | Default / values | Description and constraints |
|---|---|---|---|---|
pulse | table | required | - | Pulse background windows. Defines baseline regions before and after the pulse. Constraints: background windows must not overlap |
pulse.background_before | inline time window · s | required | - | Background window before the pulse. An inline table with finite start and end values. Constraints: start < end |
pulse.background_after | inline time window · s | required | - | Background window after the pulse. An inline table with finite start and end values. Constraints: start < end |
reference
| Path | Type | Required | Default / values | Description and constraints |
|---|---|---|---|---|
reference | table | required | - | Recorded EOM-drive signal analysis settings. Controls the channel that records the function-generator sine wave sent to the EOM, the FFT region, and fit decimation. |
reference.channel | integer | required | - | Recorded EOM-drive signal channel. The current DHO5108 mapping accepts channels 1 through 8; assign the function-generator sine wave sent to the EOM. Constraints: 1 <= value <= 8; must be unique across all channel roles |
reference.fft_window | inline time window · s | required | - | Time range used by the EOM-drive FFT. Choose a stable segment of the recorded sine wave with finite start and end values. Constraints: start < end |
reference.stride_samples | integer · samples | required | - | EOM-drive sine-fit decimation stride. Larger values reduce fitting cost at the expense of temporal detail. Constraints: must be positive |
reference.window_samples | integer · samples | required | - | Local EOM-drive sine-fitting window size. Used around the FFT estimate by EOM-drive signal analysis. Constraints: must be positive |
lockin
| Path | Type | Required | Default / values | Description and constraints |
|---|---|---|---|---|
lockin | table | required | - | Numerical lock-in settings. Defines signal channels, parallelism, output stride, and low-pass filtering. |
lockin.channels | integer array | conditional | - | Channels demodulated by lock-in analysis. At least one channel is required by lock-in and downstream analysis. Constraints: each value must be in 1..=8; must be unique across all channel roles |
lockin.workers | integer | required | - | Parallel lock-in worker count. Values near the physical CPU count are a practical starting point. Constraints: must be positive |
lockin.stride_samples | integer · samples | required | - | Lock-in output stride in input samples. Input sample rate divided by this value gives the output sample rate. Constraints: must be positive |
lockin.window | table | required | - | Lock-in analysis window contract (schema v7). Replaces lockin.filter in v7 with an explicit window/estimator split. Schema v6 and earlier use lockin.filter instead. |
lockin.window.kind | string enum | required | reference_cycles | Lock-in window kind. reference_cycles is the only v1 window: the half window is measured in reference cycles. |
lockin.window.half_window_cycles | float · reference cycles | required | - | Half-window scale in reference cycles. The boxcar integration window extends symmetrically by this many reference cycles. Constraints: must be finite and positive |
lockin.window.edge_policy | string enum | required | legacy_trim | Lock-in edge policy. legacy_trim keeps the historical boxcar edge trimming behavior. |
lockin.estimator | tagged table | required | - | Lock-in estimator selection (schema v7). boxcar_legacy keeps the historical estimator; joint_harmonic_gls is an explicit opt-in with its own settings. Estimator selection is never a filter kind. Constraints: GLS-only settings are rejected under boxcar_legacy |
lockin.estimator.kind | string enum | required | boxcar_legacy, joint_harmonic_gls | Lock-in estimator algorithm. boxcar_legacy is the historical estimator. joint_harmonic_gls selects the phase-aware joint harmonic estimator and requires its settings block. |
lockin.estimator.fit_harmonics | integer array | required | - | Harmonics spanned by the joint fit. Ascending unique positive harmonics. Must contain every output harmonic; the model size 1 + 2 * len must stay within the parameter limit. Constraints: must be ascending unique positive harmonics |
lockin.estimator.output_harmonics | integer array | required | 1, 2, 3, 4, 5, 6 | Harmonics reported by the joint estimator. Exactly 1 through 6 in v1. Constraints: must be exactly [1, 2, 3, 4, 5, 6] |
lockin.estimator.envelope_degree | integer | optional | 0; 0 | Envelope polynomial degree. Exactly 0 in v1: no envelope drift terms are supported. Constraints: must be exactly 0 |
lockin.estimator.noise_mode | string enum | required | identity, phase_diagonal, stationary_correlated, phase_correlated | GLS noise model family. Selects the whitening contract: identity, per-phase diagonal, stationary correlated, or phase-correlated. |
lockin.estimator.covariance_output | string enum | optional | diagonal; none, diagonal, full | XY covariance serialization mode. Controls how much of the estimator covariance is written to run artifacts. |
lockin.estimator.failure_policy | string enum | optional | error; error | Estimator failure policy. Exactly error in v1: any estimator failure aborts the run instead of falling back. |
lockin.estimator.calibration_source | string enum | optional | artifact; artifact, prepulse | Calibration source for the joint estimator. artifact keeps the file-bound behavior: one immutable calibration artifact per lock-in channel. prepulse derives each channel noise model once per LI run from pulse.background_before and records prepulse_calibration_digest in the LI provenance; calibrations must be empty alongside prepulse. |
lockin.estimator.calibrations | table array | optional | [] | Immutable calibration bindings, one per lock-in channel. Each entry binds a channel to a calibration artifact path plus its expected SHA-256 digest. Unexpanded template placeholders are rejected. Required exactly once per channel in artifact mode; must be empty when calibration_source is prepulse. Constraints: exactly one entry per lockin.channels value (artifact mode) |
lockin.estimator.solver_tolerances | table | optional | defaults | Joint solver tolerance overrides. Optional TOL-06/07 policy carriers for the joint estimator and the pre-pulse nuisance fit. Every key is optional; an absent table or absent key keeps the frozen default, so existing v7 configs behave byte-identically. |
lockin.estimator.solver_tolerances.rank_tol | float | optional | 1e-10 | Relative singular-value floor for rank decisions. Must be finite and positive. Smaller values keep weaker singular directions; larger values reject them earlier. Constraints: must be finite and positive |
lockin.estimator.solver_tolerances.max_condition | float | optional | 1e8 | Scaled-design condition rejection threshold. Must be finite and positive. Windows whose scaled-design condition exceeds it fail instead of publishing. Constraints: must be finite and positive |
lockin.estimator.solver_tolerances.max_noise_condition | float | optional | 1e10 | Realized noise-covariance condition cap. Must be finite and positive. Caps the executed covariance conditioning (TOL-07). Constraints: must be finite and positive |
lockin.estimator.solver_tolerances.max_jitter_v2 | float · normalized-lag units | optional | 0.0 | Bounded-jitter ceiling in normalized-lag units. Must be finite and non-negative. Zero (default) disables jitter: a non-SPD Toeplitz factor fails instead of regularizing silently. Constraints: must be finite and non-negative |
lockin.estimator.scs_adequacy | table | optional | defaults | SCS adequacy gate overrides. Optional FR-06 split-half policy for pre-pulse derivation. Every key is optional; an absent table or absent key keeps the frozen default. The gate stays mandatory for every noise mode. |
lockin.estimator.scs_adequacy.lags | integer | optional | 4 | Adequacy lag count. Must be positive. Lags compared across phase octants in the split-half check. Constraints: must be positive |
lockin.estimator.scs_adequacy.min_pairs_per_cell | integer | optional | 10 | Minimum lag pairs per phase cell. Must be positive. Cells below this coverage carry no adequacy evidence. Constraints: must be positive |
lockin.estimator.scs_adequacy.max_phase_spread | float | optional | 0.2 | Training phase-spread gate. Must be finite and non-negative. Training/half splits disagreeing beyond it refuse derivation. Relaxing the bar needs approval; on failure retake the interval or data. Constraints: must be finite and non-negative |
lockin.estimator.scs_adequacy.max_reserved_shift | float | optional | 0.2 | Reserved-shift gate. Must be finite and non-negative. Pooled training-vs-reserved shifts beyond it refuse derivation. Constraints: must be finite and non-negative |
lockin.filter | tagged inline table | required | - | Lock-in low-pass filter configuration. Schema v6 and earlier: the runtime accepts the boxcar_legacy kind; fields from other kinds are rejected. Schema v7 replaces this table with lockin.window and lockin.estimator. Constraints: fields from other filter kinds are rejected |
lockin.filter.kind | string enum | required | boxcar_legacy | Lock-in filter algorithm. boxcar_legacy is the only active LPF. Historical FIR and IIR kinds are readable only for migration diagnostics. |
lockin.filter.half_window_cycles | float · reference cycles | required | - | Half-window scale in reference cycles. The boxcar integration window extends symmetrically by this many reference cycles. Constraints: must be finite and positive |
lockin.debug_output | boolean | optional | false; true, false | Lock-in debug artifact output. Enable only for filter inspection because artifacts can be large. |
lockin.debug_label | string | optional | absent | Safe suffix for debug artifacts. The label is restricted to a short ASCII filename-safe subset. Constraints: 1-64 ASCII alphanumeric, '.', '_', or '-'; must not be '.' or '..' |
lockin.debug_overwrite | boolean | optional | false; true, false | Debug artifact overwrite policy. Allows replacement of an existing matching debug output. |
lockin.snr_background_window | inline time window · s | optional | absent | Optional background window for SNR diagnostics. An inline table with finite start and end values. Constraints: start < end |
lockin.snr_signal_window | inline time window · s | optional | absent | Optional signal window for SNR diagnostics. An inline table with finite start and end values. Constraints: start < end |
lockin.save_npy | boolean | optional | false; true, false | NumPy output for lock-in results. Writes NPY artifacts in addition to canonical CSV results. |
phase
| Path | Type | Required | Default / values | Description and constraints |
|---|---|---|---|---|
phase | table | required | - | Phase-rotation settings. Contains offsets for the first six harmonic components. |
phase.offsets | float or expression array · rad | required | - | Six harmonic phase offsets. Numeric expressions such as pi/2 are accepted. Constraints: must contain exactly 6 finite values |
moke
| Path | Type | Required | Default / values | Description and constraints |
|---|---|---|---|---|
moke | table | required | - | MOKE analysis settings. Specifies the calibration sensor, calculation method, and final factor. |
moke.sensor | integer | required | - | Sensor channel used for Kerr-angle calibration. The channel must also exist in the sensors array. Constraints: must reference sensors[].channel |
moke.method | string enum | required | standard, harmonics | Kerr-angle calculation method. Selects the standard or harmonics-based analysis implementation. |
moke.factor | float | required | - | Final Kerr-angle conversion factor. Applied after the selected Kerr-angle calculation. Constraints: must be finite |
signals
| Path | Type | Required | Default / values | Description and constraints |
|---|---|---|---|---|
signals | array of tables | optional | [] | Raw-signal readout entries. Each entry averages one channel over the lock-in window. Constraints: channels must not overlap sensor, reference, or lock-in channels |
signals[]
| Path | Type | Required | Default / values | Description and constraints |
|---|---|---|---|---|
signals[].channel | integer | required | - | Oscilloscope signal channel. The current DHO5108 mapping accepts channels 1 through 8. Constraints: 1 <= value <= 8; must be unique across all channel roles |
signals[].label | string | required | - | Plot label for the signal. Matplotlib mathtext may be supplied as a TOML literal string. Constraints: must not be empty |
signals[].unit | string | required | - | Output unit for the averaged signal. Used in tables, plots, and saved analysis headers. Constraints: must not be empty |
plot
| Path | Type | Required | Default / values | Description and constraints |
|---|---|---|---|---|
plot | table | optional | defaults | Plot generation settings. Controls display/save behavior, decimation, and error policy. |
plot.mode | string enum | optional | save; off, save, interactive, both | Plot output mode. Batch use normally selects save; interactive opens Matplotlib windows. |
plot.max_points | integer · points per series | optional | 100000 | Maximum points passed to plotting. Lower values improve Matplotlib responsiveness on large captures. Constraints: must be positive |
plot.decimation | string enum | optional | stride; none, stride, min_max | Plot downsampling algorithm. min_max preserves narrow extrema better than stride decimation. |
plot.on_error | string enum | optional | warn; warn, fail | Plot failure policy. Warn preserves successful analysis; fail makes plotting errors fatal. |
plot.output_dir | string | optional | absent | Deprecated plot directory compatibility field. Version 6 accepts but ignores this field; artifacts use the canonical run layout. Constraints: ignored with a warning |