QbraidProvider

Runtime integration for streamlined access to quantum devices supported by qBraid.

API Reference: qbraid.runtime.native

Installation & Setup

To interface with the qBraid QIR simulator or any of the 10+ quantum devices supported by qBraid’s managed access, install the relevant qbraid runtime extra(s) based on your device(s) of choice:

pip install qbraid

qbraid versions <0.11 are not compatible with qBraid API V2. See migration guide.

To ensure compatibility with the new platform, use qbraid ≥ 0.11.0.

Next, obtain your qBraid API key:

1. Login or create an account at account.qbraid.com.
2. Navigate to Account > API Keys in the left-sidebar, and then click “Create API Key”.

See also: Account - API Keys

Save account to disk

Once you have your API key, you can save it locally in a configuration file ~/.qbraid/qbraidrc, where ~ corresponds to your home ($HOME) directory:

Account credentials are saved in plain text, so only do so if you are using a trusted device.

from qbraid.runtime import QbraidProvider

provider = QbraidProvider(api_key='API_KEY')
provider.save_config()

Once the account is saved on disk, you can instantiate the provider without any arguments:

provider = QbraidProvider()

Load account from environment variables

Alternatively, the qBraid-SDK can discover credentials from environment variables:

export QBRAID_API_KEY='QBRAID_API_KEY'

Basic Usage

Given a device “QRN” (qBraid Resource Name), a QbraidDevice object can be created as follows:

from qbraid import QbraidProvider

provider = QbraidProvider()
provider.get_devices()
# [<qbraid.runtime.native.device.QbraidDevice('qbraid:qbraid:sim:qir-sv')>]

device = provider.get_device('qbraid:qbraid:sim:qir-sv')

type(device)
# <class 'qbraid.runtime.native.device.QbraidDevice'>

From here, class methods are available to get information about the device, execute quantum programs, access the wrapped device object directly, and more.

device.metadata()
# {'device_id': 'qbraid:qbraid:sim:qir-sv',
#  'device_type': 'SIMULATOR',
#  'num_qubits': 30,
#  'status': 'ONLINE',
#  'queue_depth': 0}

Then you can submit quantum jobs to the device.

run_input = [qiskit_circuit, braket_circuit, cirq_circuit, qasm3_str]

jobs = device.run(run_input, shots=100)

results = [job.result() for job in jobs]

print(results[0].data.get_counts())
# {'00': 50, '01': 2, '10': 47, '11': 1}

See how to visualize these results in the Visualization section.

Runtime Options

When submitting jobs through the QbraidProvider, you can pass provider-specific options using the runtime_options keyword argument. These options are forwarded directly to the underlying cloud provider’s submission API, giving you access to device-specific features without needing to configure provider credentials yourself.

job = device.run(circuit, shots=100, runtime_options={"key": "value"})

The runtime_options dictionary is passed through as-is to the provider backend:

• Amazon Braket devices: options are unpacked as keyword arguments to the Braket device.run() call
• Azure Quantum devices: options are passed as input_params to the Azure device.run() or device.submit() call
• qBraid devices: options are merged into the job submission payload

Amazon Braket Examples

Enable experimental capabilities on supported devices:

device = provider.get_device("aws:quera:qpu:aquila")

job = device.run(
    program,
    shots=1000,
    runtime_options={"experimental_capabilities": "ALL"},
)

Disable qubit rewiring for verbatim compilation on Rigetti:

device = provider.get_device("aws:rigetti:qpu:cepheus-1-108q")

job = device.run(
    circuit,
    shots=1000,
    runtime_options={"disable_qubit_rewiring": True},
)

See BraketProvider - Runtime Options for the full list of supported options.

Azure Quantum Examples

Use the stabilizer simulator on Quantinuum emulators:

device = provider.get_device("azure:quantinuum:sim:h2-1e")

job = device.run(
    circuit,
    shots=100,
    runtime_options={"simulator": "stabilizer"},
)

Disable noise model and compiler optimization:

job = device.run(
    circuit,
    shots=100,
    runtime_options={"error-model": False, "no-opt": True},
)

See AzureQuantumProvider - Runtime Options for provider-specific options.

IonQ Examples

Run with a hardware noise profile on the IonQ simulator:

device = provider.get_device("azure:ionq:sim:simulator")

job = device.run(
    circuit,
    shots=1000,
    runtime_options={"noise": {"model": "aria-1", "seed": 42}},
)

“Noise” options include: ideal, harmony, harmony-1, harmony-2, aria-1, aria-2, forte-1, forte-enterprise-1

Next Steps

See Job Execution for single job submission, group jobs, and cross-device workflows.