IBM Qiskit Runtime Client

0.46.1 · active · verified Tue Apr 14

Qiskit IBM Runtime is the official client library for interacting with the IBM Quantum Platform's Qiskit Runtime service. It streamlines quantum computations by providing optimized implementations of Qiskit primitives (Sampler and Estimator) for IBM Quantum hardware, leveraging classical computing resources for tasks like error suppression and mitigation. The library is currently at version 0.46.1 and requires Python >=3.10.

Warnings

breaking Qiskit Runtime V1 primitives (`Sampler`, `Estimator`, and the `Options` class) are deprecated and have been removed. All code should migrate to use the V2 interfaces (`SamplerV2`, `EstimatorV2`).
Fix: Replace `from qiskit_ibm_runtime import Sampler` with `from qiskit_ibm_runtime import SamplerV2 as Sampler`. Similarly for `Estimator`. Remove usage of the `Options` class, as V2 primitives manage options differently. Refer to the official migration guide.
breaking The `ibm_quantum` channel option for `QiskitRuntimeService` is no longer supported due to the sunset of IBM Quantum Platform Classic. The only valid channels are `ibm_cloud` and `ibm_quantum_platform` (which is the new default).
Fix: When initializing `QiskitRuntimeService`, explicitly set `channel="ibm_cloud"` or `channel="ibm_quantum_platform"` if you were previously using `ibm_quantum`. If no channel is specified, `ibm_quantum_platform` is used by default.
breaking The `fake_provider` module, which provides fake backends for testing, has been migrated from `qiskit.providers.fake_provider` to `qiskit_ibm_runtime.fake_provider`.
Fix: Update import statements from `from qiskit.providers.fake_provider import ...` to `from qiskit_ibm_runtime.fake_provider import ...`.
deprecated The `QiskitRuntimeService.delete_job()` method is deprecated and not supported on the new IBM Quantum Platform.
Fix: Avoid using `QiskitRuntimeService.delete_job()`. Manage jobs via the IBM Quantum Platform dashboard directly.
gotcha Initializing a primitive (Sampler/Estimator) outside of a `Session` or `Batch` context manager will result in jobs running in 'job mode'. This means subsequent jobs will not be prioritized, and iterative calls will incur queuing delays.
Fix: Always execute primitives within a `with Session(...) as session:` block to leverage session benefits like prioritized execution and reduced latency for iterative tasks.
gotcha As of March 2024, Qiskit Runtime primitives only accept Instruction Set Architecture (ISA) circuits and observables. Non-ISA inputs must be transpiled before submission.
Fix: Ensure circuits are transpiled to the target backend's ISA using `qiskit.transpile()` before submitting them to the runtime primitives. The Composer on the IBM Quantum Platform can handle this automatically.
gotcha Connections to the Qiskit Runtime service can be disrupted, leading to `WebsocketError` when retrieving results, potentially causing loss of computation for long-running jobs.
Fix: The client library has implemented measures to suppress frequent websocket errors. For critical or long-running jobs, consider implementing robust error handling and retry mechanisms in your application code, especially when reading result objects. Update to `qiskit-ibm-runtime >=0.24.0` for improved resilience.

Install

pip install qiskit-ibm-runtime Install qiskit-ibm-runtime

Imports

QiskitRuntimeService

from qiskit_ibm_runtime import QiskitRuntimeService

SamplerV2

from qiskit_ibm_runtime import SamplerV2

EstimatorV2

from qiskit_ibm_runtime import EstimatorV2

Session
```
from qiskit_ibm_runtime import Session
```
Sampler
```
from qiskit_ibm_runtime import SamplerV2 as Sampler
```
The original V1 `Sampler` is deprecated/removed. Use `SamplerV2` and alias it if desired for easier migration.
Estimator
```
from qiskit_ibm_runtime import EstimatorV2 as Estimator
```
The original V1 `Estimator` is deprecated/removed. Use `EstimatorV2` and alias it if desired for easier migration.
Options
```
from qiskit_ibm_runtime.options import Options
```
The `Options` class is not used by V2 primitives and should generally be removed for V2 workflows.
fake_provider
```
from qiskit_ibm_runtime.fake_provider import FakeSherbrooke
```
Fake backends were migrated from `qiskit.providers.fake_provider` to `qiskit_ibm_runtime.fake_provider` in Qiskit 1.0.

Quickstart

This quickstart guides you through authenticating with the IBM Quantum Platform, creating a simple Bell state quantum circuit, and executing it on a real quantum backend using the `SamplerV2` primitive within a session. It emphasizes setting up credentials via environment variables for security and finding a suitable backend.

import os
from qiskit import QuantumCircuit
from qiskit_ibm_runtime import QiskitRuntimeService, SamplerV2 as Sampler, Session

# Set your IBM Quantum Platform API token and instance CRN as environment variables
# Or save them locally with QiskitRuntimeService.save_account(token="YOUR_API_TOKEN", instance="YOUR_CRN")
# API token: From your IBM Quantum Platform account page (https://quantum.ibm.com/account)
# CRN: From the Instances page on the IBM Quantum Platform (e.g., ibm-q/open/main)

# Initialize the service (ensure API token and instance are set via env vars or saved)
service = QiskitRuntimeService(channel="ibm_quantum_platform")

# Get a least busy backend that supports Sampler
backend = service.least_busy(simulator=False, min_num_qubits=2, max_credits=10)
print(f"Using backend: {backend.name}")

# Create a simple Bell state circuit
qc = QuantumCircuit(2)
qc.h(0)
qc.cx(0, 1)
qc.measure_all()

# Define the input for Sampler (a PUB: Primitive Unified Bloc)
pubs = [(qc,)] # A single circuit to run

# Run the circuit using SamplerV2 within a session
with Session(service=service, backend=backend) as session:
    sampler = Sampler()
    job = sampler.run(pubs=pubs)
    print(f"Job ID: {job.job_id}")
    result = job.result()

    # Get the quasi-probability distribution result for the first PUB
    quasi_dists = result[0].data.meas.get_counts()
    print(f"Quasi-probability distribution: {quasi_dists}")

view raw JSON →