Running your first job with Boulder Opal

Boulder Opal executes quantum characterization and calibration tasks to define the parameters and state of a physical device. Each experiment, routine, or solution you submit is executed on connected control hardware and recorded as a job that you can later retrieve and inspect.

In this tutorial, you will submit a single resonator spectroscopy experiment, retrieve the job ID returned by the submission, and confirm that the run completed by inspecting both the job summary and the full measurement data.

This tutorial assumes you have a Boulder Opal client session, a virtual device that has been created and registered, and control hardware connected to the runtime. If you have not yet completed those steps, work through the getting started tutorial first.

1. Set the active device

Select the target device. All experiments and routines submitted in this session run against the device you set here, until you call set_current_device() again with a different name. Replace the placeholder string with your device name.

await client.set_current_device("<your-device-name>")

2. Workflow hierarchy

Boulder Opal organizes work into a three-tier hierarchy. Understanding this hierarchy helps you choose the right level of abstraction for your task.

Solutions orchestrate routines, and routines orchestrate experiments. You can submit work at any level. Use experiments for targeted measurements and routines for automated multi-step calibration. For a full walkthrough of how the three tiers compose and share data, see The hierarchy of workflows in Boulder Opal.

3. Define the experiment

Construct a ResonatorSpectroscopy experiment targeting readout resonator r0. The experiment sweeps the readout tone frequency to locate the resonator's resonance, and the resulting frequency profile is what later analysis fits to extract the resonance position. The shot_count parameter sets the number of repeated measurements taken at each frequency point, with higher counts improving signal-to-noise.

from boulderopalscaleup.experiments import ResonatorSpectroscopy

experiment = ResonatorSpectroscopy(resonator="r0", shot_count=100)

4. Submit the job

The client.run_experiment() method serializes the experiment configuration and submits it to the Boulder Opal server, which in turn schedules pulses on the active device. The call returns a job ID that you use in the following sections to monitor execution and retrieve results.

The generic client.run() method accepts any of the three top-level workflow objects (Experiment, Routine, or Solution) and is convenient when you want a single code path that dispatches whatever object the caller provides.

Note: The job executes on your control hardware in real time. Execution time depends on the sweep range and shot count.

job_id = await client.run_experiment(experiment)

5. Get the job summary

A job summary returns metadata about the execution without the full result payload. Key attributes include the job ID, the experiment or routine name, the current status, and the creation timestamp. Use this to confirm that the job completed successfully before fetching the larger data payload in the next section

summary = await client.get_job_summary(job_id)
client.display(summary)

6. Get the full data

Calling get_job_data() with the same job ID returns the full result payload for the completed job. The payload contains the complete measurement results, any fitted parameters extracted from the data, and diagnostic plots. Passing the result to client.display() renders the data in a structured format with inline plots and the numeric fit summary.

job_data = await client.get_job_data(job_id)
client.display(job_data)

Next steps

• Reviewing job results and device history: navigate job history and inspect device state in depth.
• How to run coherence measurements: T1, T2, and T2 echo experiments on a single transmon.
• Experiments and routines reference: full parameter documentation for every experiment and routine.