openquantum-sdk-qiskit

Qiskit 2.x addon for the Open Quantum SDK.

Installation

# Plugin (and core SDK)
pip install openquantum-sdk-qiskit

# or via extras:
pip install "openquantum-sdk[qiskit]"

Authentication

The OpenQuantum Qiskit Service tries a saved account first. If that account is missing or fails to load, it uses environment credentials (OPENQUANTUM_TOKEN, OPENQUANTUM_SDK_KEY, or OPENQUANTUM_CLIENT_ID + OPENQUANTUM_CLIENT_SECRET). An explicit token or creds still wins. Set OPENQUANTUM_NO_AUTOLOAD=1 to skip the saved account.

OpenQuantumService() does not read OPENQUANTUM_SCHEDULER_URL, OPENQUANTUM_MANAGEMENT_URL, OPENQUANTUM_KEYCLOAK_BASE, or OPENQUANTUM_KEYCLOAK_REALM. Call OpenQuantumService.from_env() for those. from_env() does not autoload a saved account and raises AuthenticationError when no credential resolves.

Option 1: Saved Account (Recommended)

Save your credentials once using the ClientCredentials model from the core SDK. This is the recommended, secure, one-time setup.

from openquantum_sdk.auth import ClientCredentials
from openquantum_sdk.qiskit import OpenQuantumService

OpenQuantumService.save_account(
    name="default", # The name to refer to this account later
    creds=ClientCredentials(client_id="s_...", client_secret="e460c8..."),
    use_keyring=True, # Recommended for secure storage
)

# Then, load it automatically:
svc = OpenQuantumService()

Option 2: Direct in Code

You can also pass the credentials directly when instantiating the service.

from openquantum_sdk.qiskit import OpenQuantumService
from openquantum_sdk.auth import ClientCredentials

creds=ClientCredentials(client_id="s_...", client_secret="e460c8...")

svc = OpenQuantumService(creds=creds)

Quickstart: SamplerV2

# 1) Imports — just change import path from qiskit.* to openquantum.qiskit for SamplerV2 and EstimatorV2
from openquantum_sdk.qiskit import OpenQuantumService, SamplerV2, list_backends, get_backend

# Qiskit tools
from qiskit import QuantumCircuit, transpile
from qiskit.visualization import plot_histogram

# 2) Auth — load saved account
svc = OpenQuantumService()  # saved account, then environment credentials

# 3) Discover backends (client-side filters, optional)
bks = list_backends(service = svc, name="iqm", device_type="QPU", online=True)
print(bks)

# 4) Select a backend (by id, name, or short code).
# organization_id falls back to OPENQUANTUM_ORGANIZATION_ID.
# job_subcategory_id defaults to "oth:oth".
# OQ_ORG_ID and OQ_SUBCATEGORY_ID are not read.
# The returned backend keeps its service session open.
backend = get_backend("iqm:emerald")

# 5) Build a circuit, transpile against the backend if desired
qc = QuantumCircuit(2)
qc.h(0)
qc.cx(0, 1)
qc.measure_all()

tqc = transpile(
    qc,
    backend=backend,
    optimization_level=1,
)

# 6) Create a Sampler and **run**

CONFIG = {
    "backend_class_id": "iqm:emerald",  # UUID or short code
    "job_subcategory_id": "phys:hds",  # Short code for Hamiltonian Dynamics Simulation
    "name": "bell-demo",  # optional job name prefix
    "execution_plan": "auto",  # "auto" (default), "public", or "private"
    "queue_priority": "auto",  # "auto" (default), "standard", "priority", or "instant"
}

sampler = SamplerV2(
    backend=backend,
    scheduler=svc.scheduler,
    config=CONFIG,
    export_format="qasm3",
)

# Run a job (circuit, pub for params, shots)
job = sampler.run([(tqc, None, 1000)])
result = job.result()
counts = result[0].data.meas.get_counts()
print(counts)

# 7) Plot
plot_histogram(counts)

EstimatorV2 Quickstart

# Import EstimatorV2
from openquantum_sdk.qiskit import EstimatorV2
from qiskit.quantum_info import SparsePauliOp
# Create an Estimator
est = EstimatorV2(
    backend=backend,
    scheduler=svc.scheduler,
    config=CONFIG
)
layout = tqc.layout
obs = SparsePauliOp.from_list([("II", 1), ("IZ", 2), ("XI", 3)]).apply_layout(layout) # Define observations for estimator to evaluate
# Run (circuit, observables)
job = est.run([(tqc, obs)])
result = job.result()
print(f"Expectation value: {result[0].data.evs}")

Execution Plans & Queue Priority

Both create_sampler() and create_estimator() accept execution_plan and queue_priority parameters:

sampler = svc.create_sampler(
    backend=backend,
    execution_plan="private",    # "auto", "public", or "private"
    queue_priority="priority",   # "auto", "standard", "priority", or "instant"
)

create_sampler, create_estimator, return_backend, and backend.run all accept verbose and job_timeout_seconds. A value on the sampler or estimator overrides the backend. A value on run() overrides the backend for that call. Omit them to keep the defaults (False and one day). You can also put either key in the config dict passed to return_backend.

return_backend(name) accepts an optional config dict for submission defaults (e.g. organization, execution plan). The backend name is used as backend_class_id. job_subcategory_id (and similar job metadata) lives on the actual job creation — either at backend.run(..., job_subcategory_id=...) or when calling create_sampler/create_estimator.

backend = svc.return_backend("ionq:forte-1")
job = backend.run(qc, shots=1024)  # subcategory defaults to "oth:oth" here

You can override at run time or supply defaults via config for repeated use:

backend = svc.return_backend("forte-1", config={
    "execution_plan": "private",
    "queue_priority": "instant",
})
# or pass per-run:
# job = backend.run(qc, shots=1024, job_subcategory_id="phys:oth")

Export a circuit to OpenQASM

export_circuit_to_qasm is a public function on openquantum_sdk_qiskit. Other plugins (Qrisp) import it from there. Do not import openquantum_sdk_qiskit._qasm.

from openquantum_sdk_qiskit import export_circuit_to_qasm

payload = export_circuit_to_qasm(circuit, "qasm3")  # or "qasm2"

Job Subcategory

The job_subcategory_id parameter classifies the type of workload you're running. It defaults to "oth:oth" (Other) but you should set it to the most specific subcategory that matches your use case. See the core SDK README for the full list of subcategory short codes.

sampler = svc.create_sampler(
    backend=backend,
    job_subcategory_id="phys:hds",  # Hamiltonian Dynamics Simulation
)

API Reference

OpenQuantumService Helpers

Qiskit Primitives

Capabilities & Device Features

The SDK loads full device capabilities (from constraint_data) for every backend.

Key behaviors:

• The backend.target (used by Qiskit's transpiler) is built from native_ops + supported_ops + topology. It is also augmented with instructions such as reset and barrier when the device advertises the corresponding features ("reset", "barriers"). This helps the transpiler produce circuits that the platform precompilers will accept.
• Custom gates: By default, most hardware backends do not allow user-defined gate ... { ... } definitions in submitted QASM.
  • If a device advertises "custom_gates" in its features, custom gates are permitted.
  • Otherwise, backend.validate_circuit(circuit) (and internal submission) will raise a clear error.
• Reset, barriers, mid-circuit measurement, dynamic circuits: The backend performs client-side validation (in validate_circuit and before submission) according to the advertised features. Using reset / Barrier / non-terminal measurements when the device does not advertise the feature raises a descriptive ValueError with remediation advice. The server precompilers remain the final authority and provide detailed errors.
• Transpile before submit (required for hardware-like backends): backends that do not advertise "custom_gates" hard-reject circuits whose op names are not in the backend Target (untranspiled / out-of-basis). Flexible simulators that advertise "custom_gates" soft-warn instead. Always:

tqc = transpile(circuit, backend=backend)
# then
backend.validate_circuit(tqc, shots=1024)

You can inspect device policy programmatically (new helpers beyond just custom gates):

print(backend.allows_custom_gates())
print(backend.allows_reset())
print(backend.allows_barriers())
print(backend.allows_mid_circuit_measure())
print(backend.allows_dynamic_circuits())
print(backend.features)          # the raw set from constraint_data
backend.validate_circuit(my_circuit)   # raises on violation of any policy

The backend exposes max_shots directly (common Qiskit pattern), and a limits dict for other constraints:

print(backend.max_shots)
print(backend.limits)   # contains min_shots, max_qubits_per_job, etc.

# Full validation including shots
backend.validate_circuit(circuit, shots=1024)

| EstimatorV2 | Qiskit 2.x Estimator compatible primitive that submits jobs to the Open Quantum platform. |