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

# 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={null}
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/home/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 theme={null}
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={null}
provider = QbraidProvider()
```

### Load account from environment variables

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

```bash theme={null}
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={null}
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={null}
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.

```python theme={null}
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={null}
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:

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

Run with a hardware noise profile on the IonQ simulator:

```python theme={null}
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](/v2/sdk/user-guide/providers/azure#runtime-options) for provider-specific options.

## Next Steps

See [Job Execution](/v2/sdk/user-guide/providers/native/jobs) for single job submission, group jobs, and cross-device workflows.