START NOW
Providers

QuantinuumProvider

Runtime integration for access to Quantinuum trapped-ion quantum processors via Quantinuum Nexus.

API Reference: qbraid.runtime.quantinuum

Overview

The qbraid.runtime.QuantinuumProvider provides support for Quantinuum’s trapped-ion quantum systems through the Quantinuum Nexus platform. This means you can write quantum circuits using pytket, compile and execute them on Quantinuum’s H-series processors and emulators, all from within the qBraid Runtime framework.

Getting started

Before you begin, make sure you have:

  1. A Quantinuum Nexus account with valid credentials.
  2. The qnexus CLI tool installed and authenticated (see Authentication below).
  3. Python >= 3.10

Set up the qBraid-SDK

Install qBraid with the quantinuum extra from PyPI using pip:

pip install 'qbraid[quantinuum]'

This installs the required dependencies: pytket, pytket-quantinuum, and qnexus.

Note: The qBraid-SDK requires Python 3.10 or greater. You can check your Python version by running python --version from the command line.

Authentication

The QuantinuumProvider authenticates through the qnexus library. Before using the provider, you must log in using the qnexus CLI:

qnx login

This opens a browser-based authentication flow and stores your credentials locally. Once authenticated, the provider will automatically use your stored credentials — no API keys or environment variables are needed.

Then initialize the provider:

from qbraid.runtime.quantinuum import QuantinuumProvider

provider = QuantinuumProvider()

List available devices

Use the QuantinuumProvider to list all devices to which you have access:

from qbraid.runtime.quantinuum import QuantinuumProvider

provider = QuantinuumProvider()

devices = provider.get_devices()
print(devices)

Get a specific device by its ID:

device = provider.get_device("H1-1")

print(device.status())
# <DeviceStatus.ONLINE>

Devices with an “E” suffix (e.g., H1-1E) are emulators (simulators) that model the behavior of the corresponding hardware device.

Submitting jobs

The QuantinuumProvider accepts quantum programs written as pytket Circuit objects.

Create a circuit

from pytket.circuit import Circuit

# Bell state circuit
circuit = Circuit(2)
circuit.H(0)
circuit.CX(0, 1)
circuit.measure_all()

Run a job

Use device.run() to compile and submit a circuit:

from pytket.circuit import Circuit
from qbraid.runtime.quantinuum import QuantinuumProvider

provider = QuantinuumProvider()
device = provider.get_device("H1-1E")

circuit = Circuit(2)
circuit.H(0)
circuit.CX(0, 1)
circuit.measure_all()

job = device.run(circuit, shots=1000)
print(f"Job ID: {job.id}")

Batch submission

Submit multiple circuits in a single call. All circuits are bundled into one Nexus job:

from pytket.circuit import Circuit
from qbraid.runtime.quantinuum import QuantinuumProvider

provider = QuantinuumProvider()
device = provider.get_device("H1-1E")

circuits = [
    Circuit(1).H(0).measure_all(),
    Circuit(1).X(0).measure_all(),
    Circuit(2).H(0).CX(0, 1).measure_all(),
]

job = device.run(circuits, shots=500)
print(f"Job ID: {job.id}")

When submitting a list of circuits, all circuits are compiled and executed as a single batch job on Quantinuum Nexus. The returned measurement_counts will be a list of dictionaries, one per circuit.

Retrieving results

result = job.result()

# Measurement counts
print(result.data.measurement_counts)
# {'00': 512, '11': 488}

# Job metadata
print(f"Device: {result.device_id}")
print(f"Job ID: {result.job_id}")
print(f"Success: {result.success}")

Check job status

from qbraid.runtime.enums import JobStatus

status = job.status()
print(status)
# <JobStatus.COMPLETED>

Cancel a job

job.cancel()

Cancellation is best-effort. Jobs already in a terminal state (COMPLETED, FAILED, CANCELLED) cannot be cancelled.

Execution time

You can retrieve the wall-clock execution time (in seconds) for a completed job:

print(f"Execution time: {job.execution_time_s()} seconds")

Configuration options

The device.run() method accepts additional keyword arguments to control compilation and project scoping:

ParameterTypeDefaultDescription
shotsint1000Number of measurement shots per circuit.
project_namestr"qbraid"Nexus project name to scope compile/execute jobs.
optimisation_levelint1pytket optimization level (0-2).

The project_name and optimisation_level parameters can also be set via environment variables:

VariableDescription
QUANTINUUM_NEXUS_PROJECT_NAMEDefault Nexus project name.
QUANTINUUM_NEXUS_OPT_LEVELDefault pytket optimization level.

Full example

A complete end-to-end workflow targeting a Quantinuum emulator:

from pytket.circuit import Circuit
from qbraid.runtime.quantinuum import QuantinuumProvider

# 1. Initialize provider (assumes qnx login was run)
provider = QuantinuumProvider()

# 2. Get an emulator device
device = provider.get_device("H1-1E")
print(f"Device status: {device.status()}")

# 3. Define a GHZ state circuit
circuit = Circuit(3)
circuit.H(0)
circuit.CX(0, 1)
circuit.CX(1, 2)
circuit.measure_all()

# 4. Submit the job
job = device.run(circuit, shots=1000, optimisation_level=2)
print(f"Submitted job: {job.id}")

# 5. Retrieve results
result = job.result()
print(f"Counts: {result.data.measurement_counts}")
# Expected output (approximate): {'000': ~500, '111': ~500}