QbraidProvider

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

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”.

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:

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

qBraid Simulator Examples

Pass a seed to make a simulation reproducible. Two runs of the same circuit with the same seed return identical measurement counts:

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

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

print(job.result().data.get_counts())
# {'00': 48, '11': 52}

Submitting the same circuit again with "seed": 42 returns those same counts. Change the seed, or leave it out, and the simulator draws a fresh sample on every run.

This is useful for tutorials and course material where the output in the text should match what the reader sees, for regression tests that assert on exact counts, and for sharing a result someone else can reproduce.

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 Amazon Braket devices for how compilation, qubit placement, and bit ordering work on aws:* devices, and 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("ionq: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.