How to run an automated routine with Boulder Opal
Execute autonomous Routines to automatically characterize or calibrate a component(s) on your quantum hardware
A routine runs a set of experiments to accomplish a specific characterization or calibration goal, while extracting the relevant parameters to the virtual device. The available routines cover discovering and characterizing all system components (resonators, qubits, and couplers) and calibrating their respective gate operations (readout, 1Q, 2Q).
Running a routine requires a virtual device with some prerequisite data. If you do not have virtual device, complete the get started tutorial first. The relevant prerequisite data depends on the routine you intend to run. See the chart below for specifics.
1. Set the device context
Select the target device. All experiments run against the currently active device.
await client.set_current_device("<your-device-name>")2. Available routines
Seven routines are available. Each one runs a set of interdependent experiments and writes the resulting parameters to the device data, so later routines and experiments act on up-to-date values.
| Routine | Target component | Purpose | Inputs | Parameter outputs |
|---|---|---|---|---|
ResonatorMapping | Feedline | Characterize readout resonators and pair them to respective transmons. | feedlines, run_mixer_calibration | Readout resonator frequencies, resonator-to-transmon map |
TransmonDiscovery | Qubit | Locate transmon frequencies and drive parameters. | transmon, spectroscopy_waveform | Qubit frequency, anharmonicity, drive amplitude |
OneQubitCalibration | Qubit | Calibrate single-qubit gates (π and π/2 pulses). | transmon, gate ("x" or "sx"), force_rerun | Gate amplitude, gate duration, DRAG coefficient |
TransmonCoherence | Qubit | Measure T1, T2, and T2 echo coherence times. | transmon, run_mixer_calibration | T1, T2, T2 echo |
TransmonRetuning | Qubit | Re-tune transmon frequencies compensating for drift. | transmon, spectroscopy_waveform | Updated qubit frequency |
CouplerDiscovery | Qubit pair | Characterize coupler interactions between transmons. | control_transmon, target_transmon, biases | Coupling strength, coupler bias point |
CZCalibrationFixedCoupler | Qubit pair | Calibrate CZ gate operating point for fixed-coupler architectures. | transmons, flux_vp_bounds (optional), coupling_rate, force_rerun | Flux pulse operating point, CZ phase/leakage calibration parameters |
3. Configure and run a routine
Import the routine class from boulderopalscaleup.routines, instantiate it with the parameters from the table above, and submit it with run_routine(). The call is asynchronous and returns a job ID, which you use to query status and fetch results. The example below runs OneQubitCalibration for the X gate on transmon q0.
from boulderopalscaleup.routines import OneQubitCalibration
routine = OneQubitCalibration(transmon="q0", gate="x")
job_id = await client.run_routine(routine)4. Restrict qubit targets
By default routines assume all qubits might be targeted. Use enable_qubits() to limit execution to a subset, for example when some qubits are already characterized or offline. The restriction persists across routines and experiments until you call enable_all_qubits() to restore the full set.
await client.enable_qubits("q0", "q1")await client.enable_all_qubits()5. Monitor results
Use get_job_summary() to check the routine status while the job is running. Use get_job_data() once the job finishes to retrieve the job data. client.display() renders either object inline.
job_summary = await client.get_job_summary(job_id)
client.display(job_summary)job_data = await client.get_job_data(job_id)
client.display(job_data)6. When a routine fails
If a routine job reports a failed status, inspect the results in the job data to identify which internal experiment did not converge or returned measurements outside the expected range. See How to debug failed routines for the diagnosis workflow.
Next steps
- Run individual experiments for targeted measurements: see How to run a custom experiment.
- Measure coherence times separately: see How to run coherence measurements.
- Understand how routines work internally: see Calibration routines.
