Running on Simulators¶
Open Quantum offers simulators alongside real QPUs. They are ideal for
development, debugging, and noiseless or large-width runs, and they usually have
no queue. Simulators appear in backend discovery with
type set to "Simulator" (Quantum Rings, Qiskit Aer, PennyLane, and Cirq).
Submitting to a simulator is the same flow as a QPU
(Job Submission) with one addition: each simulator takes
backend-specific options through JobSubmissionConfig.configuration_data.
Every simulator requires shots and an engine; the rest are optional knobs
documented per backend below.
Simulators are in beta
Simulator support is currently in beta. The available simulators and their options can change. This page was last updated on the date below; the live, authoritative source is always the platform API. Query it as shown in Discover a backend's schema before you submit.
Last updated¶
The tables below were last updated on 2026-11-02 and we keep them as accurate as we can. They are not the source of truth. Each backend carries a JSON Schema for its job parameters, served by the platform, and the job validator enforces exactly that schema. When this page and the API disagree, the API wins.
Always confirm the current set of simulators and each one's parameters against the API (next section). We document from that same schema.
Available simulators¶
| Short code | Simulator | Underlying engine | Default engine |
|---|---|---|---|
qr:sim |
Quantum Rings | Quantum Rings SDK | SCARLET_CPU |
ibm:qiskit |
Qiskit Aer | Qiskit Aer (AerSimulator) |
AER_STATEVECTOR_CPU |
xanadu:pennylane |
PennyLane | PennyLane Lightning / default devices | LIGHTNING_STATEVECTOR_CPU |
google:cirq |
Cirq | Google qsim / quimb (MPS) | QSIM_STATEVECTOR_CPU |
This list can change. Query the platform for the current set with
ManagementClient.list_backend_classes() filtered on type == "Simulator".
Discover a backend's configuration schema¶
Every backend class defines a JSON Schema for its job parameters. Fetch it to
see exactly which configuration_data fields are required, their allowed
values, and their defaults:
details = scheduler.get_backend_class("ibm:qiskit")
schema = details["configuration_schema"]
print(schema["required"]) # e.g. ['shots', 'engine']
print(list(schema["properties"])) # all accepted keys
scheduler.configuration_options("ibm:qiskit") returns the same schema as one
record per field, in schema order. Each choice's value is what a job submits
and title is the label. visible_when is empty when the field always
applies; otherwise every pair in it must match before the field is used (for
example, Quantum Rings threshold applies only when performance is
CUSTOM).
for option in scheduler.configuration_options("ibm:qiskit"):
print(option.key, option.default, option.visible_when)
The Qiskit, Cirq, PennyLane, and Qrisp plugins expose the same information
through their backend/device objects (for example
backend.configuration_options()), loading the schema from the platform when
you call it.
This is the source of truth the portal's submit form and the job-prep validator
use. If you submit without a required field, or send a value outside the
schema, you get a 400 VALIDATION_ERROR naming the offending property.
Shots and engine (all simulators)¶
Two fields are required on every simulator:
| Field | Type | Notes |
|---|---|---|
shots |
integer | Number of measurement shots. Range is 1–10000 (Quantum Rings starts at 2). Default 100. |
engine |
string | Which simulation method to run. Allowed values and the default differ per backend (below). The engine value is the token you send; it maps to a specific device and method inside the underlying package. |
Automatic measurement
On Quantum Rings and Qiskit Aer, a circuit that declares no classical bits and contains no measurements has a measurement of every qubit appended automatically, so you still get counts back. A circuit that declares classical bits but never measures is rejected. PennyLane and Cirq circuits must include their own measurements.
Quantum Rings simulator (qr:sim)¶
Scarlet is the CPU engine. The simulator defaults to SCARLET_CPU, DOUBLE
precision, and AUTOMATIC performance.
| Field | Required | Default | Allowed values | Maps to | Notes |
|---|---|---|---|---|---|
shots |
yes | 100 |
integer, 2–10000 |
SDK backend.run(shots=…) |
Per-shot counts are kept in memory for the first 10,000 shots. |
engine |
yes | SCARLET_CPU |
SCARLET_CPU |
SDK engine scarlet_quantum_rings |
Scarlet (CPU). |
precision |
no | DOUBLE |
SINGLE, DOUBLE |
SDK get_backend(…, precision="single"|"double") |
Single is faster; double is more accurate. |
performance |
no | AUTOMATIC |
HIGHEST_EFFICIENCY, BALANCED_ACCURACY, HIGHEST_ACCURACY, AUTOMATIC, CUSTOM |
SDK backend.run(performance=…) |
Speed/accuracy trade-off. The token is forwarded with underscores removed (for example HIGHEST_ACCURACY becomes HIGHESTACCURACY). |
threshold |
only when performance="CUSTOM" |
64 |
integer, ≥1 |
SDK backend.run(threshold=…) |
Do not send threshold unless performance is CUSTOM, it is rejected otherwise. |
configuration_data={
"shots": 1024,
"engine": "SCARLET_CPU",
"precision": "DOUBLE",
"performance": "AUTOMATIC",
}
Qiskit Aer (ibm:qiskit)¶
Each engine selects both the Aer device and the Aer simulation method.
Statevector is exact. Density matrix needs much more memory.
Stabilizer (and extended stabilizer) are only correct for Clifford circuits.
Matrix product state is approximate. Automatic lets Aer choose.
| Field | Required | Default | Allowed values | Maps to |
|---|---|---|---|---|
shots |
yes | 100 |
integer, 1–10000 |
AerSimulator.run(shots=…) |
engine |
yes | AER_STATEVECTOR_CPU |
AER_STATEVECTOR_CPU, AER_DENSITY_MATRIX_CPU, AER_STABILIZER_CPU, AER_EXTENDED_STABILIZER, AER_MPS, AER_AUTOMATIC |
Aer method (statevector, density_matrix, stabilizer, extended_stabilizer, matrix_product_state, automatic) |
bond_dimension |
no | AUTOMATIC |
AUTOMATIC, CUSTOM |
Controls whether max_bond_dim is applied |
max_bond_dim |
only when bond_dimension="CUSTOM" |
128 |
integer, 1–512 |
Aer option matrix_product_state_max_bond_dimension |
# Exact statevector
configuration_data={"shots": 1024, "engine": "AER_STATEVECTOR_CPU"}
# Approximate MPS. Omitting bond_dimension is the same as AUTOMATIC:
# the Aer bond stays uncapped.
configuration_data={"shots": 1024, "engine": "AER_MPS"}
# Approximate MPS with a capped bond dimension
configuration_data={
"shots": 1024,
"engine": "AER_MPS",
"bond_dimension": "CUSTOM",
"max_bond_dim": 256,
}
PennyLane (xanadu:pennylane)¶
Lightning is the fast C++ statevector suite and the usual choice. The
default.* engines are separate CPU devices: mixed state is a density matrix,
and Clifford is only correct for Clifford circuits.
| Field | Required | Default | Allowed values | Maps to |
|---|---|---|---|---|
shots |
yes | 100 |
integer, 1–10000 |
qml.device(…, shots=…) |
engine |
yes | LIGHTNING_STATEVECTOR_CPU |
LIGHTNING_STATEVECTOR_CPU, DEFAULT_STATEVECTOR_CPU, DEFAULT_MIXED_CPU, DEFAULT_CLIFFORD_CPU |
PennyLane device (lightning.qubit, default.qubit, default.mixed, default.clifford) |
Cirq (google:cirq)¶
qsim is the full state-vector simulator. MPS is an approximate tensor network (via quimb) and uses the bond dimension.
| Field | Required | Default | Allowed values | Maps to |
|---|---|---|---|---|
shots |
yes | 100 |
integer, 1–10000 |
Cirq run(repetitions=…) |
engine |
yes | QSIM_STATEVECTOR_CPU |
QSIM_STATEVECTOR_CPU, QUIMB_MPS_CPU |
qsim statevector, or Cirq-contrib + quimb MPS |
max_bond_dim |
no | 128 |
integer, 1–4096 |
quimb MPSOptions(max_bond=…) |
# Exact statevector
configuration_data={"shots": 1024, "engine": "QSIM_STATEVECTOR_CPU"}
# Approximate MPS
configuration_data={"shots": 1024, "engine": "QUIMB_MPS_CPU", "max_bond_dim": 256}
End-to-end example¶
Build a circuit (here with Cirq, exported to OpenQASM with cirq.qasm),
then submit it to qr:sim:
import cirq
from openquantum_sdk.auth import ClientCredentials, ClientCredentialsAuth
from openquantum_sdk.clients import SchedulerClient, JobSubmissionConfig
# --- Auth (see Authentication) ---
auth = ClientCredentialsAuth(
creds=ClientCredentials(
client_id="s_your_client_id",
client_secret="your_client_secret",
)
)
scheduler = SchedulerClient(auth=auth)
# --- Build a circuit in Cirq and export OpenQASM ---
q = cirq.LineQubit.range(3)
circuit = cirq.Circuit(
cirq.H(q[0]),
cirq.CNOT(q[0], q[1]),
cirq.CNOT(q[1], q[2]),
cirq.measure(*q, key="m"),
)
qasm = cirq.qasm(circuit)
# --- Submit to the Quantum Rings simulator ---
config = JobSubmissionConfig(
backend_class_id="qr:sim",
name="GHZ on Quantum Rings",
job_subcategory_id="oth:oth",
configuration_data={
"shots": 1024,
"engine": "SCARLET_CPU",
"precision": "DOUBLE",
"performance": "AUTOMATIC",
},
)
job = scheduler.submit_job(config, file_content=qasm.encode("utf-8"))
print(scheduler.download_job_output(job))
# {'000': 512, '111': 512}
Finding the backend short code
List simulators with
ManagementClient.list_backend_classes() and filter on type == "Simulator",
or browse them on the Open Quantum Portal. See
Backend Discovery.
Related Pages¶
- Job Submission: the full submission flow and
configuration_data. - Backend Discovery: list backends and read their capabilities.
- Authentication: credentials and SDK keys.