Creating your first virtual device with Boulder Opal

A virtual device in Boulder Opal Scale Up is a server-side digital representation of your QPU that stores hardware parameters, gate calibrations, and measurement history. Creating a virtual device is the first step toward running experiments and routines on the platform: it registers your QPU with the service, validates its layout against the supported QPU model, and seeds the data model with the initial parameters from your configuration.

In this tutorial, you will learn how to prepare a device configuration YAML, initialize the Boulder Opal client with your credentials, create a virtual device on the platform, verify and select it as the active target for your session, inspect its initial state at both the full-device and component level, and save a snapshot of that state for later restoration.

You will need a Q-CTRL account with an API key and organization slug, the Boulder Opal SDK installed in your Python environment, and a device configuration YAML provided by your Q-CTRL account team. If the SDK is not yet installed or your credentials are not yet confirmed, complete the get started tutorial first.

1. Prepare the configuration YAML

The device configuration YAML describes the layout of your QPU and the wiring of the control hardware that drives it. Q-CTRL provides a template YAML for each supported QPU model, place the file in your working directory and adjust hardware-specific values such as IP addresses and channel mappings before proceeding. The file contains four top-level sections.

Note: Do not modify device_arch or qpu_model unless instructed by Q-CTRL. Incorrect values will cause device creation to fail.

2. Initialize the client

Create the client and runtime. Replace the placeholder strings with your API key and organization slug. Set up the Runtime object depending on your controller. You can check the documentation specific to Qblox and Quantum Machines.

from boulderopalscaleup import QctrlScaleUpClient
from boulderopalscaleup.runtime import Runtime

runtime = Runtime.new()

client = QctrlScaleUpClient(
    runtime=runtime, api_key="<your-api-key>", organization_slug="<your-org-slug>"
)

3. Create the device

The create_device() call uploads the configuration file, parses the YAML, validates the layout against the QPU model, and registers the new virtual device under your organization. Supply a unique name for the device and the path to the configuration YAML. The returned job ID lets you track the creation process if you need to monitor its progress.

from pathlib import Path

device_name = "<your-device-name>"
config_path = Path("<path-to-your-config>.yaml")

creation_job_id = await client.create_device(
    device_name=device_name, device_config=config_path
)

4. Verify and select the device

Listing the devices registered under your organization confirms that the new entry was created successfully. The display() helper renders the result as a summary table showing device names and creation timestamps. Once you have identified the new device in the listing, call set_current_device() to mark it as the active target for all subsequent operations in this session.

devices = await client.get_devices()
client.display(devices)

await client.set_current_device(device_name=device_name)

5. View the device data sheet

The device data sheet renders a summary of QPU components alongside their current parameter values. Calling it without arguments displays every component on the active device, which is the quickest way to confirm that the configuration was loaded as expected.

await client.display_device_data_sheet()

6. Inspect a specific component

Passing a node_name filters the data sheet to a single component. This view is useful for verifying that the initial parameters of a particular qubit or resonator match your expectations before running experiments against it.

await client.display_device_data_sheet(node_name="q0")

Next steps

• Run your first job: submit an experiment on your new device and retrieve the results.
• OPX+ user guide and Qblox user guide: backend-specific configuration details for your control hardware.
• Retrieving and displaying data user guide: methods to retrieve information about your device.
• Experiments and routines reference: full list of available experiments and routines.