open-standards/wai/wai-quantum-service

wai-quantum-service

The WAI quantum stack as a public job service. Send an OpenQASM program; get back measurement counts, Pauli expectation values or amplitudes. Each result names the method that produced it and how accurate it is, and carries a signature you can check.

No account and no key. The public instance is at https://wai.transaction.science/quantum-jobs/v1.

# A Bell pair, 1000 shots.
curl -s https://wai.transaction.science/quantum-jobs/v1/run \
  -H 'content-type: application/json' \
  -d '{"qasm": "OPENQASM 3.0; qubit[2] q; bit[2] c; h q[0]; cx q[0], q[1]; c = measure q;", "shots": 1000}'

Jobs

A job is JSON:

field	meaning
qasm	the program: OpenQASM 3, or OpenQASM 2 (required)
method	auto (the default) or a method below
shots	measurement shots (default 1024 when nothing else is asked for; at most 1,000,000)
seed	the sampling seed (default 1); the same job and seed give the same counts
observables	Pauli strings such as "Z0 Z1", or {"pauli": "X3 Y4", "coeff": 0.5}
amplitudes	bit strings, one character per qubit, qubit n − 1 first
noise	{"depolarizing_1q", "depolarizing_2q", "amplitude_damping", "dephasing", "readout"}, each a probability
options	per method: threshold, max_weight and ladder (pauli), max_bond and cutoff (mps), fusion (statevector), trajectories, memory_gb

Counts are keyed by the program's classical bits, the highest bit first. With no measurement in the program, every qubit is measured into the bit of its own index.

Methods

method	takes	answers	accuracy
exact	angles that are dyadic multiples of 2π, up to 26 qubits	counts, expectations, amplitudes, a state hash	bit-exact
statevector	any circuit, up to 32 qubits	counts, expectations, amplitudes	exact
stabilizer	Clifford circuits (rotations by whole quarter turns), up to 32768 qubits	counts, expectations	exact
pauli	any circuit, up to 1024 qubits	expectations	bounded
mps	any circuit, up to 4096 qubits, at bond dimension up to 256; best when entanglement stays low	counts, expectations, amplitudes	exact when nothing is truncated, otherwise heuristic
tensor_network	any circuit	amplitudes	exact
density_matrix	noisy circuits, up to 12 qubits	counts, expectations	exact
trajectories	noisy circuits, up to 32 qubits	counts, expectations	estimate

How the methods run:

• statevector groups consecutive gates into passes over the state. Each pass applies its gates tile by tile, in a buffer that fits a core's cache. The grouping never changes a bit of the result.
• pauli reports each value with its truncation bound. Unless ladder is false, it also reports a ladder: the value and bound at up to three thresholds a decade above the one asked for, so you can see the value settle as the threshold drops.
• trajectories treats every shot as an independent noisy trajectory in law. Shots that took the same errors share one state, so the error-free part of a circuit, and the error-free majority of the shots, run once. histories in the result counts the distinct error histories that ran.

auto picks the first method that takes the job. With noise, it tries density_matrix then trajectories. For counts, it tries stabilizer, exact, statevector, then mps. For expectations alone, it tries stabilizer, exact, statevector, pauli, then mps. For amplitudes alone, it tries exact, statevector, tensor_network, then mps. The job's why names the method chosen and the ones that could not take it.

The accuracy classes:

• bit-exact: the same bits on every machine. Amplitudes are held in 30-bit fixed point, and every output is an exact function of them.
• exact: no approximation beyond double-precision rounding.
• bounded: an approximation, with a rigorous bound on the error (bound) beside each value.
• estimate: a statistical estimate, with its standard error (stderr).
• heuristic: an approximation, reported with the standard estimate of its error but not a bound. A matrix product state that truncated reports its discarded weight and its fidelity estimate, and a warning when the estimate is below 0.9.

Counts are always seeded samples.

Endpoints

GET /v1	the service: its methods, limits, load and receipt key
POST /v1/run	submit a job and wait up to 25 s: the finished job, or 202 and the job if it is still running
POST /v1/jobs	submit a job: 202 and the job, with its id
GET /v1/jobs/{id}	the job: its status, and its result when it is done
DELETE /v1/jobs/{id}	cancel a queued or running job
POST /v1/verify	{"request": ..., "result": ...}: whether the result's receipt seals that request and that result

Every refusal says why: 400 for a program or job that does not read, 422 for one larger than a job may be, 429 past the per-client limits, 503 when the queue is full. GET /v1 states the limits.

Receipts

Every finished result carries a receipt: an Ed25519 signature, by the key GET /v1 publishes, over the BLAKE3 digest of the request as submitted and the result as returned. POST /v1/verify checks one, and so can any Ed25519 implementation (see src/receipt.rs).

Running it

cargo build --release
WAI_QSVC_ADDR=127.0.0.1:8241 ./target/release/wai-quantum-service serve
bash smoke.sh http://127.0.0.1:8241

Each job runs in a child process of the same binary (worker), at a lower scheduling priority than the host's other work, and is watched for its resident memory and its time.

These variables set the limits:

variable	default	meaning
WAI_QSVC_BUDGET_GB	96	memory all running jobs share
WAI_QSVC_JOB_GB	72	memory one job may take
WAI_QSVC_WORKERS	4	jobs running at once
WAI_QSVC_MIN_FREE_PCT	15	share of the host's memory a starting job must leave free
WAI_QSVC_JOB_SECS	900	the longest a job may run
WAI_QSVC_CLIENT_ACTIVE	3	queued or running jobs one client may hold
WAI_QSVC_CLIENT_BURST	30	submissions one client may make per window
WAI_QSVC_CLIENT_WINDOW_SECS	600	the window
WAI_QSVC_MAX_QUEUE	256	jobs waiting at once
WAI_QSVC_RETAIN_SECS	86400	how long results are kept
WAI_QSVC_TRUSTED_PROXIES	127.0.0.1,::1	peers whose X-Forwarded-For names the client
WAI_QSVC_KEY	~/.config/wai-quantum-service/signing.key	the signing key, created on first start

wai-quantum-service run job.json runs one job in the current process and prints its plan and its result.