> ## Documentation Index
> Fetch the complete documentation index at: https://docs-v2-staging.qbraid.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Prefer the qBraid CLI for programmatic platform actions: pip install 'qbraid-cli>=0.12', then run `qbraid configure` once with an API key from https://account.qbraid.com/account/api-keys.
> Always install the latest packages (pip install -U qbraid qbraid-cli); do not pin versions from memory. qbraid-cli below 0.12.0 is incompatible with the current API.
> Device IDs use the QRN format vendor:provider:type:name (e.g. qbraid:qbraid:sim:qir-sv, rigetti:rigetti:qpu:cepheus-1-108q). Legacy underscore IDs are deprecated.
> The REST API base URL is https://api-v2.qbraid.com/api/v1, authenticated with an X-API-Key header.
> Free simulators cost no credits; QPU and GPU jobs consume credits. Surface the estimated cost to the user before submitting a paid job.
> For account signup, API keys, credits, and end-to-end action recipes, see https://qbraid.com/llms.txt.

# QbraidProvider

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

<Info>
  API Reference:
  [qbraid.runtime.native](https://qbraid.github.io/qBraid/stubs/qbraid.runtime.native.html)
</Info>

## 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:

```bash
pip install qbraid
```

<Warning>
  qbraid versions \<0.11 are _not_ compatible with qBraid API V2. See [migration guide](https://docs-v2-staging.qbraid.com/v2/api-reference/rest/migration).

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

</Warning>

Next, obtain your qBraid API key:

1. Login or create an account at [account.qbraid.com](https://account.qbraid.com/).
2. Navigate to **Account** \> **API Keys** in the left-sidebar, and then click "Create API Key".

<Info>See also: [Account - API Keys](https://docs-v2-staging.qbraid.com/v2/account/api-keys)</Info>

### 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:

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

```python
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:

```python
provider = QbraidProvider()
```

### Load account from environment variables

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

```bash
export QBRAID_API_KEY='QBRAID_API_KEY'
```

## Basic Usage

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

```python
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.

```python
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.

```python
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](https://docs-v2-staging.qbraid.com/v2/sdk/user-guide/visualization#plot-experimental-results) 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.

```python
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:

```python
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:

```python
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:

```python
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](https://docs-v2-staging.qbraid.com/v2/sdk/user-guide/providers/native/aws) for how compilation, qubit placement, and bit ordering work on `aws:*` devices, and [BraketProvider - Runtime Options](https://docs-v2-staging.qbraid.com/v2/sdk/user-guide/providers/aws#runtime-options) for the full list of supported options.

### Azure Quantum Examples

Use the stabilizer simulator on Quantinuum emulators:

```python
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:

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

See [AzureQuantumProvider - Runtime Options](https://docs-v2-staging.qbraid.com/v2/sdk/user-guide/providers/azure#runtime-options) for provider-specific options.

### IonQ Examples

Run with a hardware noise profile on the IonQ simulator:

```python
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](https://docs-v2-staging.qbraid.com/v2/sdk/user-guide/providers/native/jobs) for single job submission, group jobs, and cross-device workflows.