> ## Documentation Index
> Fetch the complete documentation index at: https://docs.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 theme={"dark"}
pip install qbraid
```

<Warning>
  qbraid versions \<0.11 are *not* compatible with qBraid API V2. See [migration guide](/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](/v2/account/overview#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 theme={"dark"}
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 theme={"dark"}
provider = QbraidProvider()
```

### Load account from environment variables

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

```bash theme={"dark"}
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 theme={"dark"}
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 theme={"dark"}
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 theme={"dark"}
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](/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 theme={"dark"}
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 theme={"dark"}
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 theme={"dark"}
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 theme={"dark"}
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](/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 theme={"dark"}
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 theme={"dark"}
job = device.run(
    circuit,
    shots=100,
    runtime_options={"error-model": False, "no-opt": True},
)
```

See [AzureQuantumProvider - Runtime Options](/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 theme={"dark"}
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](/v2/sdk/user-guide/providers/native/jobs) for single job submission, group jobs, and cross-device workflows.