Skip to main content
API Reference: qbraid.runtime.aws

​
Installation & Setup

To interface with Amazon Braket supported devices, install the braket extra: 
pip install 'qbraid[braket]'
Then, follow instructions to configure your AWS credentials.

​
Basic Usage

Submit a Quantum Task to an AWS device using the BraketProvider: 
from qbraid.runtime import BraketProvider

provider = BraketProvider()

provider.get_devices()
# [<qbraid.runtime.aws.device.BraketDevice('.../qpu/rigetti/Ankaa-3')>,
#  <qbraid.runtime.aws.device.BraketDevice('.../qpu/quera/Aquila')>,
#  <qbraid.runtime.aws.device.BraketDevice('.../qpu/ionq/Aria-1')>,
#  <qbraid.runtime.aws.device.BraketDevice('.../qpu/ionq/Aria-2')>,
#  <qbraid.runtime.aws.device.BraketDevice('.../qpu/ionq/Forte-1')>,
#  <qbraid.runtime.aws.device.BraketDevice('.../qpu/ionq/Forte-Enterprise-1')>,
#  <qbraid.runtime.aws.device.BraketDevice('.../qpu/iqm/Garnet')>,
#  <qbraid.runtime.aws.device.BraketDevice('.../quantum-simulator/amazon/sv1')>,
#  <qbraid.runtime.aws.device.BraketDevice('.../quantum-simulator/amazon/tn1')>,
#  <qbraid.runtime.aws.device.BraketDevice('.../quantum-simulator/amazon/dm1')>]

device = provider.get_device("arn:aws:braket:::device/quantum-simulator/amazon/sv1")

type(device)
# qbraid.runtime.aws.device.BraketDevice

device.metadata()
# {'device_id': 'arn:aws:braket:::device/quantum-simulator/amazon/sv1',
#  'device_type': 'SIMULATOR',
#  'num_qubits': 34,
#  'provider_name': 'Amazon Braket',
#  'status': 'ONLINE',
#  'queue_depth': 0}
Now that we’ve instantiated our device, in this case the AWS SV1 simulator, we can construct a quantum circuit and submit a task using the .run method: 
from braket.circuits import Circuit

circuit = Circuit().h(0).cnot(0, 1)
job = device.run(circuit, shots=10)
We now have job which is of type BraketQuantumTask, which inherits from QuantumJob. To see the results, we can do the following: 
res = job.result()

res.data.get_counts()
# {'00': 6, '11': 4}

res.data.measurements
# array([[0, 0],
#        [0, 0],
#        [1, 1],
#        [1, 1],
#        [0, 0],
#        [0, 0],
#        [0, 0],
#        [1, 1],
#        [0, 0],
#        [0, 0]])
See how to visualize these results in the Visualization section.

​
Runtime Options

The BraketDevice.run() method accepts additional keyword arguments that are passed through to the underlying Amazon Braket SDK’s AwsDevice.run(). These options let you control device-specific behavior such as qubit rewiring, error mitigation, experimental capabilities, and more.

​
Disable Qubit Rewiring

By default, Braket may remap the logical qubits in your circuit to physical qubits on the device. To force the use of the exact qubits specified in your circuit, disable qubit rewiring: 
job = device.run(circuit, shots=1000, disable_qubit_rewiring=True)
This is required when using verbatim compilation or pulse-level gate definitions.

​
Error Mitigation (IonQ)

IonQ devices on Braket support error mitigation through debiasing, which creates variations of your circuit to reduce the effects of hardware noise: 
from braket.error_mitigation import Debias

device = provider.get_device("arn:aws:braket:us-east-1::device/qpu/ionq/Aria-1")

job = device.run(
    circuit,
    shots=2500,  # Minimum 2500 shots required for debiasing
    device_parameters={"errorMitigation": Debias()},
)

​
Experimental Capabilities

Some devices offer experimental features that must be explicitly enabled. For example, QuEra Aquila supports tight atom geometries and local detuning, and IQM devices support dynamic circuits with mid-circuit measurement: 
device = provider.get_device("arn:aws:braket:us-east-1::device/qpu/quera/Aquila")

job = device.run(
    program,
    shots=1000,
    experimental_capabilities="ALL",
)
See Experimental Capabilities for a full list of available features per device.

​
Parametric Circuits

For OpenQASM programs with input parameters, pass values at runtime: 
job = device.run(
    openqasm_program,
    shots=1000,
    inputs={"theta": 1.57, "phi": 0.785},
)

​
Reservation ARN

If you have a Braket Direct reservation for exclusive device access, provide the reservation ARN: 
job = device.run(
    circuit,
    shots=1000,
    reservation_arn="arn:aws:braket:us-east-1:123456789012:reservation/abc123",
)

​
Tags

Attach metadata tags to your quantum tasks for tracking and organization: 
job = device.run(
    circuit,
    shots=1000,
    tags={"experiment": "bell-state", "team": "quantum-research"},
)

​
Options Reference

ParameterTypeDescription
disable_qubit_rewiringboolForce use of exact qubits without remapping
device_parametersdictDevice-specific config (e.g. error mitigation)
experimental_capabilitiesstrSet to "ALL" to enable experimental features
inputsdict[str, float]Parameter values for parametric circuits
reservation_arnstrBraket Direct reservation ARN
tagsdict[str, str]Metadata tags for the quantum task

​
Via qBraid Runtime API

When submitting jobs through the QbraidProvider, these same options can be passed via the runtimeOptions field. The runtime API forwards them as keyword arguments to the Braket device.run() call: 
from qbraid.runtime import QbraidProvider

provider = QbraidProvider()

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

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

device = provider.get_device("aws:ionq:qpu:aria-1")

job = device.run(
    circuit,
    shots=2500,
    runtime_options={"device_parameters": {"errorMitigation": "Debias"}},
)