SDK: backends and the Qiskit bridge

How circuits get from your Qiskit code to a simulator, a noise model or a quantum computer. In your workflow you only touch the bridge objects in ctx (ctx.backend, ctx.sampler, ctx.estimator); the backends behind them are the platform's. Targets and what they cost are explained in Backends and targets. Back to the SDK reference.

Targets

qsolve.backends

from qsolve.backends import (AerBackend, AsyncBackend, Backend, ProviderJobFailed,
                             SampleResult, get_backend)

The package __all__ holds exactly those six names. FakeHardwareBackend, IBMBackend and RemoteBackend live in the submodules qsolve.backends.fake, .ibm and .remote and are imported lazily so the optional dependencies load only when needed.

get_backend

get_backend(target: str) -> Backend

Resolves a target string to a backend object. Called by run_workflow when you pass no backend. It takes no other arguments: an unknown keyword argument raises TypeError, and an unknown or malformed target raises ValueError (for example a non-numeric noise scale in fake:fez@fast).

Other exceptions: RuntimeError when the ibm extra is missing or QSOLVE_IBM_TOKEN is not set; ValueError for an unknown fake device, a scale outside 1 to 10, or a scale that is not a number. run_workflow turns ValueError, RuntimeError and ImportError from this call into WorkflowError.

SampleResult

@dataclass
class SampleResult:
    counts: dict[str, int]
    shots: int
    exec_time_s: float = 0.0
    metadata: dict[str, Any] = field(default_factory=dict)

What a backend returns for one circuit. counts maps bit strings to counts in Qiskit order (qubit 0 is the rightmost character; spaces from multiple registers are tolerated by consumers). metadata varies by backend:

MAX_BATCH and sample_all

MAX_BATCH = 300 (in qsolve.backends.base): circuits per batch, bounded by provider job limits and the executor's message size.

sample_all(backend: Backend, circuits: Sequence[QuantumCircuit], shots: int,
           seeds: Sequence[int]) -> list[SampleResult]

backend.sample_batch in chunks of MAX_BATCH. For code that talks to a Backend directly, with circuits that do not depend on each other's results.

Backend

class Backend(ABC):
    target: str      # "sim-cpu" | "sim-gpu" | "qpu"
    provider: str
    device: str

    @abstractmethod
    def sample(self, circuit: QuantumCircuit, shots: int, seed: int) -> SampleResult
    def sample_batch(self, circuits: Sequence[QuantumCircuit], shots: int,
                     seeds: Sequence[int]) -> list[SampleResult]
    def calibration_snapshot(self) -> dict[str, Any]
    @property
    def max_qubits(self) -> int

Executes measured circuits and returns counts. Workflows never touch a Backend; the harness does. Subclass it only to test the harness with your own fake.

AsyncBackend

class AsyncBackend(Backend):
    batches: bool = False
    def submit(self, circuit, shots, seed) -> str            # abstract
    def collect(self, job_id: str) -> SampleResult           # abstract
    def cancel(self, job_id: str) -> None                    # default: does nothing
    def submit_batch(self, circuits, shots, seeds) -> str    # default: NotImplementedError
    def collect_batch(self, job_id: str) -> list[SampleResult]  # default: NotImplementedError

A backend whose jobs live at the provider and can be collected later by id (QPUs). The platform records the job id between submit and collect, so a run interrupted while waiting in a hardware queue re-attaches to the same job instead of paying twice. sample is collect(submit(...)). sample_batch uses submit_batch and collect_batch when batches is true (one provider job, one queue wait) and otherwise falls back to one job per circuit. submit and collect are abstract; the batch pair must be implemented when batches is true. cancel should cancel a job still waiting at the provider.

ProviderJobFailed

class ProviderJobFailed(RuntimeError). The provider finished a job without a result (failed or cancelled on their side). Resubmitting is the right response; any other exception may be transient. Raised by IBMBackend.collect_batch when IBM reports ERROR or CANCELLED.

AerBackend

AerBackend(gpu: bool = False)

Local Qiskit Aer simulator. gpu=True needs qiskit-aer-gpu and sets target="sim-gpu", device="aer-gpu"; otherwise sim-cpu and aer-cpu. provider is aer. max_qubits is 30 on GPU, 26 on CPU.

FakeHardwareBackend

from qsolve.backends.fake import FakeHardwareBackend
FakeHardwareBackend(device: str = "fez", scale: float = 1.0)

A real device's published noise, simulated: the free rehearsal for hardware runs. target="qpu", provider="fake", device="fake_<name>" with "@<scale:g>" appended when scale != 1. Needs the ibm extra.

sample_batch transpiles the circuits exactly as for the device (transpile_best) and runs them as one Aer job with the noise model. Aer takes one seed per job, so for a batch every circuit's seed is mixed into it (a hash of the whole list): changing any one seed changes the job, and the same seeds always give the same counts. A single circuit keeps its own seed. Each result carries readout, two_qubit_gates, physical_qubits and (for a few circuits) device_circuit metadata, the same as IBMBackend, so workflows exercise their hardware path end to end. sample is a batch of one. calibration_snapshot() returns {"backend": device, "noise_scale": scale}. max_qubits is the simulated device's qubit count. Building the noise model takes several seconds for a 156-qubit device.

IBMBackend

from qsolve.backends.ibm import IBMBackend
IBMBackend(device: str, token: str | None = None, instance: str | None = None)

IBM Quantum hardware through qiskit-ibm-runtime. An AsyncBackend with batches = True. Credentials come from the environment, never from workflow code.

RuntimeError if the ibm extra is missing. The constructor connects (channel ibm_quantum_platform) and looks up the device, so it needs network access.

Module constants in qsolve.backends.ibm: S_PER_JOB = 2.4 and S_PER_SHOT = 0.00023, an empirical fit to billed quantum time on ibm_fez (IBM can change its billing; re-fit if estimates drift from the bill), and

max_execution_seconds(n_circuits: int, shots: int) -> int

which returns ceil(10 + 3 * (S_PER_JOB + S_PER_SHOT * n_circuits * shots)): three times the expected bill plus 10 s, so a job that somehow needs more is stopped by IBM instead of draining the account.

Hardware helpers (qsolve.backends.hardware)

Shared by the fake and IBM backends; not needed by workflows.

RemoteBackend and the executor (internal)

qsolve.backends.remote is the protocol by which a sandboxed workflow reaches a backend without holding any credentials. The project's contributing notes list it as internal and subject to change, so this is a summary, not a contract.

Inside the sandbox there is no network and no provider secret. RemoteBackend(addr=None, token=None) talks to the platform's executor over a local socket: addr defaults to QSOLVE_EXECUTOR_ADDR (unix:<path> or tcp:<host>:<port>), token to QSOLVE_EXECUTOR_TOKEN. It asks the executor for info and copies its target, provider, device, max_qubits and calibration. sample and sample_batch send circuits as base64 QPY, one JSON object per line, in chunks of MAX_BATCH; replies larger than MAX_LINE_BYTES (8 MiB) are refused. Executor errors become RuntimeError("executor error: ..."). The executor owns credentials and enforces credit holds, shot and qubit caps and writes the provenance.

serve_executor(backend, host="127.0.0.1", port=0, *, address=None, max_shots=100_000, max_qubits=32, token=None) -> (server, address) is the reference executor the tests use: it serves backend on unix:<path> or tcp:<host>:<port> and returns the server and the resolved address. The platform wraps it with metering. A request with shots outside 1..max_shots, a circuit above the qubit cap or a wrong token is refused.

qsolve.bridge

from qsolve.bridge import DEFAULT_SHOTS, QsolveBackend, QsolveEstimator, QsolveSampler

Qiskit-native execution. A workflow written in plain Qiskit runs through these unchanged. Behind them is whatever target the run was given. Circuits are sent as the workflow built them (the platform transpiles for the device); every dispatch is recorded by the run's Recorder (Metering and cost). DEFAULT_SHOTS = 1024.

QsolveBackend

QsolveBackend(inner: Backend, recorder: Recorder, *, seed: int = 0, allow_quantum: bool = True)

A Qiskit BackendV2 over a Qsolve target. It is ctx.backend. The harness builds it; you use it.

Attributes: name is qsolve-<inner.device>, backend_version is "1", inner, recorder, allow_quantum. target is a Qiskit Target with a generic gate set (id x y z h s sdg t tdg sx sxdg rx ry rz p u cx cy cz ch swap crx cry crz cp rxx ryy rzz ecr ccx) sized to inner.max_qubits. max_circuits is None (batches are split internally). Default options: shots=1024 and seed_simulator=None. With seed_simulator set (as an option of run, or with set_options), circuit k of that call is seeded seed_simulator + k, so a call is reproducible whatever ran before it; left None, seeds continue from seed plus a running count.

dispatch

dispatch(self, circuits: Sequence[QuantumCircuit], shots: int) -> list[SampleResult]

The one place circuits leave the workflow. Splits into batches of MAX_BATCH, copies each circuit (so what is recorded is what is sent, even if your code edits its circuit afterwards), assigns seeds, calls inner.sample_batch, records circuit, shots, counts, metadata and time in the Recorder, and adds metadata["dispatch"] (the recorded index) to each result. Thread-safe. Raises QuantumNotAllowed when allow_quantum is false. Called by run, by the sampler and by the estimator; you rarely call it directly.

run

run(self, run_input: QuantumCircuit | Sequence[QuantumCircuit], **options) -> JobV1

Qiskit's BackendV2.run. run_input is one circuit or a sequence. The only option read is shots (default 1024). Returns an already-finished job (runs are synchronous from the workflow's point of view) whose result() is a Qiskit Result with counts per circuit, so backend.run(qc, shots=2000).result().get_counts() works as usual.

qc = QuantumCircuit(2); qc.h(0); qc.cx(0, 1); qc.measure_all()
counts = ctx.backend.run(qc, shots=2000).result().get_counts()

QsolveSampler

QsolveSampler(backend: QsolveBackend, *, default_shots: int = 1024)

A SamplerV2 over a QsolveBackend. It is ctx.sampler.

run(self, pubs: Iterable[SamplerPubLike], *, shots: int | None = None) -> BasePrimitiveJob

Returns a finished job; .result() is a PrimitiveResult with one pub result per pub. Each pub result has a data field per classical register of the circuit (so measure_all() gives data.meas), each a BitArray, and metadata with shots, circuit_metadata and qsolve, a list with one entry per bound circuit (in flattened parameter order) holding the backend's metadata, including dispatch and, on qpu targets, readout and two_qubit_gates. All circuits of all pubs with the same shot count go to the backend as one batch (on a QPU: one job, one queue wait). A result always holds exactly the requested number of shots: when a device rounds the count up (5000 asked, 5024 returned) a random subset of the requested size is kept; fewer than requested raises ValueError.

counts = ctx.sampler.run([(measured, theta, shots)]).result()[0].data.meas.get_counts()

Gotchas. A circuit must contain measurements. Bit strings are in Qiskit order (clbit 0 on the right), so variable 0 is the last character; reverse before decoding. The result is always synchronous.

QsolveEstimator

QsolveEstimator(backend: QsolveBackend, *, default_precision: float = 0.015625)

An EstimatorV2 over a QsolveBackend. It is ctx.estimator. It measures each group of qubit-wise commuting Pauli terms of an observable in its own basis and combines the results. No error mitigation is applied.

run(self, pubs: Iterable[EstimatorPubLike], *, precision: float | None = None) -> BasePrimitiveJob

For each value the shots per group are ceil(1 / precision**2). Returns a finished job; each pub result holds data.evs and data.stds (arrays of the broadcast shape) and metadata["target_precision"]. Cost note: every parameter set and every observable is a separate dispatch with one circuit per basis group, so many observables or tight precision quickly mean many circuits and shots; the run is billed for what is sent, and estimate() should account for it.