Frequency Parameter Policy

QDash frequency parameters distinguish measured device properties from operational drive settings. Input resolution and snapshot semantics follow Parameter Resolution.

Parameter roles

Parameter	Meaning	Independent persistent QDash parameter
coarse_qubit_frequency	Exploration estimate used to start or repeat qubit calibration	Yes
qubit_frequency	Measured qubit frequency obtained from Chevron or Ramsey	Yes
control_frequency	Control drive frequency used by ordinary experiments	Yes
resonator_frequency	Resonator frequency estimated by an experiment	Yes
readout_frequency	Readout drive frequency used by ordinary experiments	Yes

The persistent values are the accepted results used by subsequent tasks. Task history retains measurements regardless of whether they are accepted. A newer history record does not necessarily replace a persistent value.

coarse_qubit_frequency is an exploration input, not simply a less precise alias for qubit_frequency. Keeping the values separate allows spectroscopy to be repeated without replacing a working calibration. They may differ normally. Chevron and Ramsey do not copy their results back into the exploration parameter.

qubit_frequency and resonator_frequency are physical measurement results. They are never treated as sweep knobs. control_frequency and readout_frequency are operational values and may be changed independently. A calibration can publish one measured result to both roles when that result should immediately become the operating value.

Task frequency matrix

Task input precedence and update targets are fixed and have the same meaning in standalone runs and workflows. In the tables, “fallback” means that the second parameter is read only when the first is absent. Publication requires enabled output persistence and successful validation.

Qubit and control frequency

Task or task family	Drive-frequency input	Frequency result	Published database parameters
CheckQubitSpectroscopy	Qubex spectroscopy sweep range; no calibrated control-frequency input	Coarse f01 estimate	coarse_qubit_frequency, control_frequency
CheckControlAmplitude	control_frequency; fallback: coarse_qubit_frequency	Refined coarse f01 estimate	coarse_qubit_frequency, control_frequency
CheckAdaptiveChevron	control_frequency; fallback: coarse_qubit_frequency	Measured qubit frequency	qubit_frequency, control_frequency
CheckChevron	control_frequency; fallback: qubit_frequency	Measured qubit frequency	qubit_frequency, control_frequency
CheckRamsey	control_frequency; fallback: qubit_frequency	Measured qubit frequency	qubit_frequency, control_frequency
Other ordinary one- and two-qubit tasks	control_frequency; fallback: qubit_frequency	No frequency result	None

Qubit Spectroscopy and CheckControlAmplitude treat their estimates as exploration measurements, so they do not update qubit_frequency. They publish the estimate to control_frequency so the next bringup task consumes the value measured in the current workflow instead of a stale operating value. Adaptive Chevron, fixed-grid Chevron, and Ramsey produce a physical qubit-frequency result and also make it the next operating control frequency.

EF and FH frequency and configuration

EF and FH calibration separate measured transitions from operational drive frequencies in the same way as GE calibration.

Task or task family	Frequency input	Frequency result	Published database parameters
CheckAdaptiveEFChevron	Configured control_frequency_ef; otherwise the Qubex missing-anharmonicity default derived from control_frequency	Measured EF transition and qubit anharmonicity	ef_frequency, control_frequency_ef, qubit_anharmonicity
CheckEFRabi, EF pulse creation, and EF readout classification	control_frequency_ef; fallback: ef_frequency	No transition-frequency result	None
CheckAdaptiveFHChevron	Configured control_frequency_fh; otherwise 2 * control_frequency_ef - control_frequency	Measured FH transition	fh_frequency, control_frequency_fh

ConfigureEF must run in the same worker session before an EF- or FH-dependent measurement. It loads and pushes either the ge-ef-cr layout, which is the default, or ge-ef-fh. EF tasks reject a session whose GE and EF targets are not available, and CheckAdaptiveFHChevron additionally requires an FH target. Ordinary Configure defaults to ge-cr-cr, even after an EF configuration task, so a flow returning to CR calibration must run Configure to restore the CR layout.

CheckAdaptiveEFChevron deliberately ignores persisted qubit anharmonicity when selecting its initial search frequency. If Qubex has an explicit control_frequency_ef, the task uses it. Otherwise it uses 18 / 19 * control_frequency, matching Qubex's E_J / E_C = 50 fallback when anharmonicity is unset. Its initial EF drive amplitude is control_amplitude / sqrt(2), matching Qubex's default scaling from the calibrated GE control amplitude. Qubit spectroscopy may still display an f12 estimate for diagnosis, but it does not publish that estimate as calibrated qubit anharmonicity.

CheckAdaptiveFHChevron requires the ge-ef-fh layout, a calibrated GE HPI pulse, and a calibrated EF pi pulse. It uses the configured control_frequency_fh as its initial search frequency when present. Otherwise it derives the initial frequency from the measured GE and EF transition frequencies without reading persisted anharmonicity. Its initial FH drive amplitude is control_amplitude / sqrt(3), matching Qubex's default scaling. The task is available for explicit task lists but is not part of the ef_calibration template.

The ef_calibration template keeps all EF tasks in one synchronized CustomOneQubit step. It starts from existing GE control and readout frequencies and readout amplitude, then runs ConfigureEF, calibrates GE Rabi and HPI, measures the EF transition, and calibrates EF pulses and three-state readout. CheckAdaptiveEFChevron therefore receives the HPI parameters created earlier in the same task list; a pre-existing HPI calibration is not required by the template.

CheckEFRabi records the GE HPI inputs used by the task, but Qubex currently prepares the |e> state through x180(). CheckAdaptiveFHChevron likewise uses x180() for its GE and EF preparation pulses. For GE, that call can prefer a stored DRAG PI, PI, or DRAG HPI pulse over the restored HPI. For EF, a stored DRAG PI can take precedence over the restored EF PI. Existing calibration-note entries can therefore change state preparation even when the recorded task inputs match. Starting a new QDash execution does not remove those entries.

Resonator and readout frequency

Task or task family	Readout-frequency input	Frequency result	Published database parameters
CheckResonatorSpectroscopy	Qubex spectroscopy sweep range; no calibrated readout-frequency input	Measured resonator frequency	resonator_frequency, readout_frequency
CheckCKP	readout_frequency	Measured resonator frequency and photon-limited optimal drive	resonator_frequency, readout_frequency
CheckCoarseReadoutParams	readout_frequency; fallback: resonator_frequency	Selected operational readout frequency	readout_frequency
Other ordinary measurement and gate tasks	readout_frequency; fallback: resonator_frequency	No frequency result	None

CheckCoarseReadoutParams selects readout_frequency by maximizing the Rabi IQ response range across readout frequencies and amplitudes. It does not replace resonator_frequency. Resonator Spectroscopy deliberately publishes its measured resonance to both parameters, so a subsequent readout optimization starts from the newly measured device state.

CheckCKP runs Qubex's filtered CKP experiment. It publishes the fitted ground-state resonator frequency as resonator_frequency and the photon-limited optimum as readout_frequency. The task also publishes its fitted Purcell-filter parameters. It rejects every output when the fit R² is not finite and strictly greater than 0.7, or when any required fitted value is invalid.

Update targets are specified per output, not by classifying the entire task as exploration or calibration. Amplitude and other outputs retain their own declared destinations. In particular, Resonator Spectroscopy also produces readout_amplitude; maintaining the readout frequency does not imply that every readout setting remains unchanged.

Replacement within the same parameter

There is no automatic ranking of task names or calibration stages. With publication enabled, a validated Chevron result can replace a Ramsey result in qubit_frequency. A validated Resonator Spectroscopy result can replace a CKP result in resonator_frequency, and a later CKP result can replace it again. This policy protects measured qubit frequencies from exploration updates; it does not guarantee that every accepted recalibration improves precision or device performance.

Runtime frequency resolution

Ordinary experiments declare the operational names and explicitly list the measured names as fallbacks:

input_spec = {
    "control_frequency": InputParameterSpec.required_database(
        fallback_parameter_names=("qubit_frequency",),
    ),
    "readout_frequency": InputParameterSpec.required_database(
        fallback_parameter_names=("resonator_frequency",),
    ),
}

Resolution prefers control_frequency or readout_frequency. It uses the corresponding measured frequency only when the operational parameter is absent. fallback_parameter_names expresses semantic fallback; parameter_aliases remains reserved for legacy names that mean the same thing. The resolved input records the database parameter name that supplied the value, so provenance and snapshot re-execution retain the distinction.

Do not copy coarse_qubit_frequency into qubit_frequency. Bringup tasks may publish a coarse estimate to control_frequency, and legacy snapshots or databases may supply it through the explicit coarse fallback shown in the task matrix. Ordinary post-bringup tasks do not use the coarse fallback.

Permitted per-execution overrides remain explicit inputs. An arbitrary drive override does not become a measured qubit or resonator frequency. Record the actual resolved drive frequencies, their sources, and overrides in execution history.

Snapshot re-execution uses the recorded effective inputs and permitted overrides, not current database values or current YAML defaults. Preserve enough source information in the snapshot to reproduce the frequency selection.

Bringup and repeated measurements

Bringup uses the normal task destinations rather than a separate calibration-stage reset or an all-workflow publication checkpoint:

1. Qubit Spectroscopy updates coarse_qubit_frequency and seeds control_frequency after validation.
2. CheckControlAmplitude consumes control_frequency, falling back to the legacy coarse_qubit_frequency, and refines both values.
3. Adaptive Chevron consumes control_frequency, falling back to the legacy coarse_qubit_frequency, and publishes qubit_frequency plus control_frequency after validation.
4. Subsequent calibration tasks consume the updated calibrated values.

Validated outputs are published as the workflow progresses when persistence is enabled. A failure in a later task does not roll back earlier accepted outputs. Report the outputs already updated and the tasks that did not complete. Failed outputs must not become the normal inputs of downstream tasks.

An initial bringup can reach Adaptive Chevron without an existing qubit_frequency, using the operational seed published by the preceding exploration tasks. Repeating only Qubit Spectroscopy retains qubit_frequency but replaces control_frequency with the new coarse estimate. Repeating bringup can replace both values when Adaptive Chevron succeeds; the start screen identifies bringup as a recalibration operation.

Readout transitions

Operation with publication enabled and validation passed	resonator_frequency	readout_frequency
Resonator Spectroscopy	Update	Update to the measured resonance
Filtered CKP	Update to the fitted ground-state resonance	Update to the photon-limited optimum
Readout frequency optimization	Retain	Update to the optimized drive

Repeating Resonator Spectroscopy intentionally restores the measured resonance as the operational readout starting point. Run readout optimization afterward when the optimal drive should differ.

Frequency selection alone does not establish that an old optimization remains suitable after other readout settings change. Show other updated outputs, such as readout amplitude, alongside the frequency behavior. Do not claim that all readout settings are preserved when only the frequency is retained.

Coarse readout scan settings

CheckCoarseReadoutParams declares the calibration inputs used by both the readout scan and its underlying Rabi measurements:

Input parameter	Purpose	Resolution
control_frequency	Qubit drive frequency for the Rabi measurements	Required operational value; falls back to qubit_frequency
control_amplitude	Control pulse amplitude for the Rabi measurements	Required database value
readout_frequency	Center frequency of the readout scan	Required operational value; falls back to resonator_frequency
readout_amplitude	Reference amplitude of the readout scan	Required database value

All four calibration inputs are recorded for snapshot re-execution. Explicit input overrides define the values for that run; the scan does not independently reload them from Qubex YAML. Drive frequency and amplitude overrides are scoped to the scan and restored on success or failure. The session-scoped readout_duration is recorded as a Run parameter. The Qubex contrib helper has no readout-duration argument, so a task-local adapter forwards that value to each underlying Rabi call without replacing methods on the shared Experiment instance.

Run parameter	Default	Meaning
readout_duration	Qubex session value	Readout pulse duration in ns for all underlying Rabi measurements
detuning_range	(-0.015, 0.015, 13)	Frequency offsets in GHz, as (start, stop, number of points)
readout_amplitude_ratio_range	(0.8, 1.2, 5)	Multipliers of the reference amplitude, as (start, stop, number of points)
time_range	(0, 101, 4)	Rabi drive durations in ns, as (start, exclusive stop, step)
shots	1024	Shots per Rabi drive duration at each readout point
interval	Existing Qubex default	Shot interval in ns

The default scan includes the current frequency and amplitude: 13 frequency points over ±15 MHz and 5 amplitude points over ±20%. Amplitudes are capped at 1 and duplicate points are removed, so a reference near the upper bound can produce fewer than 5 amplitude points. The reference amplitude must be finite and within (0, 1]; invalid references fail rather than being replaced or clipped.

Normally this performs 65 Rabi traces, compared with the previous 147-point grid using ±25 MHz and amplitudes from zero to the configured value. The shot count is halved from 2048 to 1024, while the default Rabi time window and shot interval are retained. These are adjustable starting settings, not a claim of equivalent measurement quality. Operators can widen the scan, change the Rabi time window, or restore 2048 shots using run parameters.

The progress plan uses the effective frequency count multiplied by the effective amplitude count, after clipping and duplicate removal. The UI shows all-sweep progress from the first Rabi trace: normally 65 sweeps, or 39 with a reference amplitude of 1 and the default ranges. The displayed count is completed sweeps out of the total; the percentage also includes progress within the active sweep. After the first sweep completes, the remaining-time estimate extrapolates the total elapsed measurement time across the planned sweeps. It includes time between sweeps and remains an estimate, since measurement speed can vary. The UI hides the inner Rabi time-point count and per-sweep ETA for this search.

Older snapshots without the newly declared reference inputs cannot silently use current settings; handle missing snapshot inputs according to Parameter Resolution.

Coarse readout R² validation

CheckCoarseReadoutParams validates the Rabi fit at the selected readout frequency and amplitude before accepting either output. In the installed Qubex revision pinned by uv.lock, rabi_results contains the scan results in amplitude-major order; each result exposes rabi_params[qubit_label].r2. Use this stored R² without refitting or averaging the scan.

The default threshold is shared with QDash's CheckRabi: 0.6. As with the existing task executor, a value must be strictly greater than the threshold to pass. Missing, non-finite, or greater-than-one R² values also fail validation. Selection metadata that cannot identify the matching scan point is a validation failure, not permission to skip the check.

Do not require every scan point to pass: exploration can include low readout amplitudes and other settings with poor responses. Conversely, a good fit at an unrelated point must not authorize publishing a noisy selected point. Do not silently choose a different candidate when the selected point fails.

Preserve the heatmap and available raw scan data for inspection, mark the task failed, and publish neither frequency nor amplitude on rejection. The selected R² is recorded as task quality metadata when finite. This gate is implemented in the task; it does not establish that the response maximum is the fidelity optimum or guarantee rejection of every possible noise realization.

Manual correction

A manual correction from a spectroscopy Task Result writes operational values only. The measured frequency stays as recorded, because experiments own resonator_frequency, qubit_frequency, and the exploration estimate coarse_qubit_frequency.

Source task	Correctable parameters	Measured value shown for reference
CheckResonatorSpectroscopy	readout_frequency, readout_amplitude	resonator_frequency
CheckQubitSpectroscopy	control_frequency, coarse_control_amplitude	coarse_qubit_frequency

The allowlist is fixed per task in ManualUpdateService and does not depend on the source result's status or recorded output names, so a failed result can still seed the operating values. Diagnostics such as optimal_power, f01_repr_db, and f01_quality_level are never written by hand. A point picked on the figure sets the frequency from x and derives the amplitude from y with the same conversions as the task: 10**(y/20) for readout, and min(10**((y + 10)/20), 1) for the coarse control amplitude.

YAML export

YAML files represent accepted parameter values and the default drive configuration derived from them. They do not export every new measurement automatically.

YAML file	Exported value
qubit_frequency.yaml	Accepted measured qubit frequency
control_frequency.yaml	Accepted operational control frequency
resonator_frequency.yaml	Accepted measured resonator frequency
readout_frequency.yaml	Accepted operational readout frequency

On accepted Chevron or Ramsey updates, update both qubit_frequency.yaml and control_frequency.yaml. On accepted Resonator Spectroscopy or CKP updates, update both resonator_frequency.yaml and readout_frequency.yaml. Readout optimization updates only readout_frequency.yaml.

Seed import is deliberately narrower: only operational frequency and amplitude files may update the calibration database. It cannot import qubit_frequency.yaml or resonator_frequency.yaml; experiments own those measured values.

Execution Controls and Results

The Task Workbench starts with Save calibrated outputs to DB disabled. A run still records its measurements and artifacts, but its outputs do not become current calibration values. Enabling the control publishes validated outputs to every destination declared by the task and can update mapped YAML files when that integration is configured.

Run again opens the same workbench with values from the source result. Saving outputs remains disabled until the operator enables it for that run. Input selection and output publication are independent; publishing an output does not bypass task validation.

The result's Output Parameters table shows Calibration DB updated, Measurement only, or Partially updated from the recorded destination metadata. For an applied value it shows the previous value, the new value, and each database destination. Historical readout_frequency records retain the task that produced them; QDash does not reinterpret an older spectroscopy, CKP, or optimization result as another parameter type.

The user procedure is in Task Parameters.