Skip to main content
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': 64,
#  '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:ankaa-3")

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},
)
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}},
)
See AzureQuantumProvider - Runtime Options for provider-specific options.