Setting up Boulder Opal with QuantumMachines OPX controllers

Quantum Machines OPX controllers handle drive, readout, and flux on a single programmable platform; the Octave companion module provides microwave up- and down-conversion. The boulderopalscaleup package connects to an OPX+ system through a Runtime object that manages the controller connection.

In this tutorial, you will configure a connection to an OPX+ system, register it with the Boulder Opal runtime, instantiate the client, and create a virtual device from a YAML configuration.

You will need a Q-CTRL account with an API key and organization slug, an OPX+ cluster reachable on your network with any required Octaves powered and addressable, and a device configuration YAML provided by Q-CTRL.

1. Connect to the OPX+ system

Describe the OPX with an OPXSystemInfo object that carries the cluster name, host IP address, and port number. Replace the placeholder strings with the ones that apply to your device.

Once the system is described, you create the runtime with Runtime.new() and register the hardware with runtime.add_system(opx_system).

Note: It is important to configure the OPXSystemSystemInfo object properly to reflect your controller's setup. Read the reference documentation for a complete explanation of all its parameters.

from boulderopalscaleup.runtime import Runtime
from boulderopalscaleup.runtime.systems.quantum_machines import OPXSystemInfo

opx_system = OPXSystemInfo(
    host="<cluster IP address>",
    port=int("<cluster port>"),
    cluster_name="<cluster name>",
)

runtime = Runtime.new()
runtime.add_system(opx_system)

2. Initialize the client

Create the client and pass it the runtime you just configured along with your Q-CTRL API key and organization slug. Replace the placeholder strings with the credentials issued by Q-CTRL.

from boulderopalscaleup import QctrlScaleUpClient

client = QctrlScaleUpClient(
    runtime=runtime,
    api_key="<your API key>",
    organization_slug="<your organization slug>",
)

3. Create and select the virtual device

Before running any programs on your physical device, you must create a virtual device in the Q-CTRL environment. The create_device() call uploads a YAML configuration file that describes the layout of your QPU and the wiring of the control hardware that drives it, and registers the new virtual device under your organization. During this step, make sure you use the correct configuration files that are specifically for Quantum Machines controllers. This ensures the setup complies with the respective Quantum Machines syntax and support modules.

Note: Q-CTRL provides a template YAML for each supported QPU model and supported controller. Replace ./device_config.yaml with the name of the file provided to you.

from pathlib import Path

# The YAML file defines the wiring and other configurations for your device
device_yaml_path = Path("./device_config.yaml")

# Give the virtual device a unique name
device_name = "device_name"

# Add this named virtual device to the Q-CTRL environment, if not already present
if device_name not in [device.name for device in await client.get_devices()]:
    await client.create_device(device_name, device_config=device_yaml_path)

# Mark that device as the current device to use in subsequent routines and experiments
await client.set_current_device(device_name)