open-standards/wai/wai-quantum-qpu/README.md

wai-quantum-qpu

Quantum processors as members of the wai-quantum fabric: clients for the services that run circuits on them, and the person's own providers, brought without a client written for them (Bring your own quantum).

For every circuit, a QpuSampler:

1. reads the device's native gates and connectivity from the service;
2. compiles the circuit to them exactly, with wai_quantum::quantum_toolchain::native, and checks the program against the circuit by simulation before anything is sent;
3. submits it, waits for the job, and reads the counts back onto the circuit's qubits: logical qubit i is measured into classical bit i, which is bit i of the counts' index, whatever physical qubit it ended on.

A queue can outlast any wait, so job::start records a job before it is sent (ledger), and job::check, job::follow and job::cancel come back to it by its record, from any process. Running out of patience leaves the job where it is. job::run keeps no record, so it cancels what does not finish within its bound.

QpuSampler::member certifies the device statistically against the exact distribution of every circuit of a corpus, as the fabric certifies any sampler. Its certificates carry the device's provenance: silicon for a processor, a simulator for a service's simulator. Placement ranks a simulator after silicon.

Services

Module	Protocol	Native gates	Angles on the wire
sampler_v2	Sampler V2 jobs: an IAM bearer token, one OpenQASM 3 circuit per job, placed by the backend's published calibration (its properties) and refused when it ran under another; on a free plan free, with what is left of its limit, and each job's charge sealed in quantum seconds	rz, sx, x, cz on physical qubits $p; with the setting basis=rzsxxczrxrzz, also rx and rzz where the backend lists them (each angle between two qubits one rzz)	radians
prx_circuits	circuit jobs of native instructions on named qubits, one measurement key per classical bit, each job pinned to the calibration set it was compiled against and placed by that set's quality metrics; on a star device, move into and out of its computational resonator	prx, cz, move	radians
native_turns	circuit jobs in a native gateset that runs as written: each backend read from the service (its status, its gates, its characterization's pairs), a simulator with device noise models and a seed; results read from shot records (their leakage flags sealed), the service's counts or its probabilities; cancel, and an estimate held to the rate card	gpi, gpi2, and zz or ms as the backend (or the noise model's device) runs	turns, so every dyadic angle is exact
cloud_tasks	quantum tasks on your own cloud account: OpenQASM 3, a verbatim box on a processor, requests signed with your keys, results in your own bucket	a processor's prx cz, gpi gpi2 zz, or prx xx rz (each cz as one xx(pi/2)); rz v x cz on a simulator	multiples of pi, written exactly

Each module's BASE constant is the endpoint it is written against. Each client is configured from the environment (from_env) or in code. Keys and tokens are held in Secret, which never prints:

Module	Variables
sampler_v2	WAI_QPU_SAMPLER_API_KEY, WAI_QPU_SAMPLER_CRN, WAI_QPU_SAMPLER_BACKEND
prx_circuits	WAI_QPU_PRX_TOKEN, WAI_QPU_PRX_QC
native_turns	WAI_QPU_TURNS_KEY, WAI_QPU_TURNS_BACKEND (default simulator), WAI_QPU_TURNS_NOISE
cloud_tasks	the account's usual key variables, WAI_QPU_TASKS_REGION, WAI_QPU_TASKS_DEVICE, WAI_QPU_TASKS_BUCKET, WAI_QPU_TASKS_PREFIX (default wai-quantum), WAI_QPU_TASKS_BASIS (a simulator only: compile to a processor's basis)

use wai_quantum_qpu::{QpuSampler, check_probe, probe_circuit, transport::Curl};
use wai_quantum_qpu::native_turns::NativeTurns;

let sampler = QpuSampler::new(NativeTurns::from_env(Curl::new(120))?)?;
// The first job on any service: an X on qubit 0, whose counts must land on index 1.
let (counts, job) = sampler.run(&probe_circuit(3), 1000)?;
check_probe(&counts, 0.95)?;

Bring your own quantum

A device needs no client written for it here: it speaks the open provider protocol, wai.quantum.provider/1, over HTTP or as a local process, and the person lists it in their registry. Bring your own quantum is the guide.

Module	What it is
open_provider	the protocol's client: Http (through curl; a credential only over https or to this machine) and Process (one JSON line each way; the credential in the program's environment, never its command line), and OpenProvider, a Provider over either
reference	the reference provider: the protocol around this crate's exact simulator, served over HTTP or standard input and output, taking energy-landscape jobs of both versions on the extension's reference too (--no-landscape for none, --landscape-protocol 1 or 2 for one version alone, --qubits 0 for those alone); the tests run against it, and it is the template to copy
conformance	the checker, and its vectors in conformance/provider-v1.json with the reference's counts pinned
registry	the person's list of providers (~/.config/wai/quantum-providers.json, holding no credential), and the credential stores: the keychain (the system security tool on macOS, secret-tool on Linux), else a file only its owner reads, labelled so
job	the dry run (the exact compile, the check by simulation, the provider's estimate and billing unit), the refusal of a run that is not free until it is confirmed, and the seal of its counts by the engine (wai_quantum::engine::provider), labelled measured from a processor and simulated from a simulator, with the counts' source and the execution each client states from the very request it sends
landscape	an energy-landscape job (wai.quantum.landscape/1, or wai.quantum.landscape/2 where the request names it) on a provider whose description offers them, in a version it lists (the protocol's §11): the job's operations and memory counted as the extension counts them before anything is asked, the provider's estimate held to that count, a run that is not free refused until it is confirmed, and the answer checked by the extension's §5.4, as the job's version reads it, and by its program before it is sealed, naming the provider, its job and its cost; a job of a version the device does not list is refused before anything is sent

Provider gains details (the protocol, the calibration snapshot, the billing), device_target (the device's errors in its service's own form, read as a target), estimate, a seeded submit_seeded and cancel, each with a default, so a client that has none keeps working: its cost is then unknown, and a run on it is never taken to be free.

When a client reads its device's errors itself (device_target: prx_circuits reads the quality metrics its service publishes for the calibration set the device is under), or a provider's describe states its calibration (errors per qubit or per pair) and is read as one, the program is placed on the qubits and routes most likely to succeed (wai_quantum::engine::targets::layout). It is still in the device's own gates and checked against the circuit before it is sent. The plan and the receipt's compiled.placement say how it was placed, with the target's hash and what it was read from. A device whose service publishes no errors keeps the compiler's own layout, and the placement says why.

prx_circuits sends each job pinned to the calibration set whose architecture it compiled against (calibration_set_id), so a recalibration between the read and the run is either refused by the service, with an error that says so, or run as planned; it sends the service's modes as it wants them (dynamical decoupling disabled, heralding none, move validation strict, move frame tracking full); the result names the calibration set the service says it compiled the job against, and one other than the pin is refused, by the client that sent it and by any later process that collects the job from its record; and it cancels a job (POST /jobs/{id}/cancel).

The command line carries it all: wai-quantum providers add|list|remove|describe|test|free|reference and wai-quantum run --provider NAME [--dry-run] [--yes] (its README).

The command

wai-qpu device  <service>                          # the device: qubits, basis, provenance
wai-qpu probe   <service> [--qubits N] [--shots N] [--yes] # the bit-order probe
wai-qpu certify <service> [--shots N] [--cases N] [--report FILE] [--yes]
wai-qpu reference --stdio | --http ADDR [device options]   # the reference provider

<service> is sampler-v2, prx-circuits, native-turns or cloud-tasks, configured from its variables above. A certification runs every circuit of the corpus in both gatesets as a job. On a device whose provenance is silicon, or one the service does not state is free, a job spends the service's quota or the person's money, so a probe and a certification there run only with --yes. --report writes each certificate with its hash, and every job, as JSON.

Transport

transport::Curl runs curl as a program, so the crate carries no TLS stack. Headers, keys and tokens included, go in a curl configuration file that only this user can read, removed when the request ends. The body goes on curl's standard input. Nothing secret appears on a command line. transport::Scripted answers from a function, for tests.

What is checked here, and what only a service can check

The tests run each client against a service that follows that provider's published contract. The fake parses the submitted program in the provider's own format, runs it on the crate's simulator, and answers in the provider's result shape and bit order. A client whose request, units or bit order departs from the contract reads back the wrong distribution, and the tests fail. A probe test shows that a service using the other bit order is caught.

A real service settles its own conventions. The first job on each should be probe_circuit, checked with check_probe, before any other result is trusted.

prx_circuits has a second fake of its own (tests/prx_circuits.rs), built from the service's published request and response models and stricter than the service: a member the models do not name, a mode outside its values, a calibration set id that is not a UUID, a gate on a locus its calibration set does not list (a cz in either order, a move the qubit first) are each refused; a job pinned to a calibration set the service does not run is taken and fails at compilation (Calibration set not found), and a cancel of a job that has ended is refused 403 illegal_job_status, as the service's mock answered them on 2026-11-12. Against it: a recalibration between the read and the submission, the job pinned and compiled against the set it was planned on; a service that says it compiled against another, refused; a retired set, failing the job; a job past its wait cancelled; the quality metrics placing a Bell pair on the best pair and readouts; providers test; and the token read from the credential store and sent as a bearer over curl. On the service's mock quantum computer (2026-11-12), the pinned request and its modes were taken, the job's record named the pinned set as the one it compiled against, a cancel stopped a running job, and the calibration's quality metrics read as a target; no processor has run a job of it.

Two device shapes are checked against fakes only, as every client is. A processor of prx, xx and rz (cloud_tasks): its fake reads the service's prx(θ, φ) and xx(θ) = exp(−iθ/2·X⊗X) and refuses an angle outside the ranges such devices take (xx 0 to π/2, prx 0 to π), so each cz reaches it as one xx(pi/2). A star device (prx_circuits): five qubits round a computational resonator, one moving into it; its fake holds the resonator to its turns and runs each move as the exchange with a phase the device leaves undefined, which only the move back cancels. Whether a real service of either shape takes these programs as written is settled by its probe.

The open protocol is tested end to end (tests/providers.rs): every operation against the reference provider as a process and over HTTP; the conformance vectors over both, in each basis, and on the reference as an xx device and as a star (--star: its qubits round one resonator, describe's resonators and moves); the reference's pinned counts; the registry with its credential in a file only its owner reads (and, on macOS, the keychain in a keychain file made for the test); a run that is not free refused until it is confirmed; receipts that verify with the engine's verifier; and no credential in anything a run returns. Nothing there spends money: the priced runs are the reference's.

The work runs at the service, so every run is unmetered here. An energy figure the service reports, such as a per-job estimate, is kept in the job record as the service's figure (JobRecord::service_kwh). It is never recorded as a measurement.

Every circuit a certification runs is a job on the service, and spends that service's quota.

Versions

The open provider protocol is wai.quantum.provider/1 (the extension, section 10); its messages, program and answers are a JSON Schema, schemas/provider.v1.json, which every message the client sends and every answer the reference provider gives is held to. What is stable in this crate and the protocol, and how a change is announced: the policy; what is deprecated: the deprecations.

Licence

Apache-2.0.