open-standards/wai/wai-quantum

wai-quantum

A deterministic quantum stack in pure Rust. Byte-exact circuit simulation, the operational layer around it, and signed energy-accounted receipts binding every stage.

No QPU, no cloud service, no vendor SDK, and no system libraries — so the same source runs natively, in the browser via wasm, and as a WASI component at the edge, producing byte-identical results and receipts on all three. Nine opt-in features reach outside the crate: quantum_fabric_webgpu (the platform's GPU interface), quantum_fabric_cuda (the CUDA driver and runtime compiler) and quantum_fabric_opencl (the OpenCL ICD loader), the last two loaded when first used, quantum_fabric_fpga (Verilator, run as a program when first used), quantum_fabric_npu (the platform's model runtime, on macOS), quantum_fabric_sme (the processor's streaming vector mode, by inline assembly), quantum_fabric_vector (the processor's vector extension), quantum_fabric_dsp (the signal processor's vector unit, in a build for that processor) and quantum_fabric_dataflow (a dataflow device's library, loaded when first used); no default feature reaches a system library.

[dependencies]
wai-quantum = "0.7"

use wai_quantum::quantum::Circuit;
use wai_quantum::quantum_toolchain as qt;

let mut c = Circuit::new(3);
c.h(0).cx(0, 1).cx(1, 2);              // GHZ
let sv = c.simulate().unwrap();
println!("{:?}", qt::top_outcomes(&sv, 2));   // |000> 0.5, |111> 0.5
// a portable identity for the reconstruction — same on every machine
let h: [u8; 32] = sv.statevector_hash();

What's in it

Cross-architecture reproducibility is tested, not asserted. CI runs the floating-point results (entropy, the Holevo bound) pinned to their exact IEEE-754 bits, and the unit tests of the circuit core, under wasm32-wasip2 on wasmtime as well as natively, so a platform that computes something different fails the suite instead of quietly returning a different number (.github/workflows/wai-conformance.yml, its quantum-wasip2 job):

CARGO_TARGET_WASM32_WASIP2_RUNNER=wasmtime cargo test --locked --target wasm32-wasip2 --features full --test bit_identity

The command line's research tools answer what a state carries, not only what a circuit does:

wai-quantum lab entropy bell --keep 0    # half a Bell pair: 1 bit, invisible to a state vector
wai-quantum lab channel depolarizing --prob 0.5
wai-quantum lab bb84 --eavesdrop         # interception shows up in the error rate
wai-quantum lab chsh                     # 2 sqrt(2), exactly, not sampled
wai-quantum lab qutrit                   # d = 3, not just qubits

channel prints the Holevo bound before and after, and it can only fall: noise never creates information.

Feature	What it gives you
quantum	byte-exact statevector simulation (dyadic Clifford+T+P(k)), as wai.quantum.circuit2 by default or as the frozen wai.quantum.circuit
quantum_toolchain	algorithm library, backend recommendation, OpenQASM 2/3 import through the one reader (from_qasm): everything the reader takes, under the bit-exact circuit's restriction, dyadic angles and measurements at the end, refused with the reader's codes otherwise (non-dyadic angles are refused, never rounded); a controlled gate the modifiers write is held whole, so to_qasm's output reads back gate for gate; device-ready OpenQASM 2/3 (device::device_qasm): every gate lowered exactly to its dialect's standard library, multi-controlled gates included, every qubit measured into c[i], and the service's counts read back onto the crate's basis; native programs (native::compile): a processor's own basis (rz/sx/x/cz; prx/cz; or gpi/gpi2/zz with angles in turns, written exactly; the Z rotations carried in the phases of the last two) on its own qubits, routed over its coupling map, and checked against the circuit by simulation before it is sent — Bloch / entanglement / purity analysis
quantum_lang	the OpenQASM reader, one grammar for every surface (qasm::read, qasm::parse): the job service, the command line, both MCP servers, the Studio, the desktop app, the edge component and the in-browser IDE all read through it. OpenQASM 3.1 and the OpenQASM 2 forms in common use, read in three stages with the source position of everything: registers, aliases and slices; gate definitions; every modifier (ctrl @, negctrl @, inv @, pow(k) @, exact fractional powers) on any gate, lowered exactly; def subroutines, inlined, a returned measurement written into the caller's bit; classical types (int, uint, float, angle[n], complex, bool, bit, arrays), their arithmetic, casts and built-in functions, computed on reading with the same bits on every platform; for, while (unrolled when known, or run at most @wai.max_iterations N times on measured bits), switch, break, continue, end; conditions on measured bits with comparisons, &&, `
quantum_qasm	the reader's program lowered to each method's input, exactly up to a global phase: dense matrices, two-qubit matrices for the matrix product state, Pauli rotations, Clifford gates, and the dyadic circuit (Program::dyadic); qasm::dyadic_circuit gives the exact state vector's circuit for a program whose measurements all come at the end, and refuses any other with its code
quantum_engine	the quantum job service's engine, for every host: a job (an OpenQASM program and what is asked of it: shots, Pauli expectation values, amplitudes, noise) planned onto the strongest method it admits, with the reason and the memory and work it will take; run; answered in the service's JSON with its accuracy class; and sealed over the request and the result in their canonical JSON (engine::job, engine::receipt), so a result from the service, the command line or a browser tab checks the same way. Also a program's circuit drawn as text (engine::draw) and as a standalone SVG drawing, the Studio's picture with each gate marked by whose hand it is in (engine::svg, which the Python package draws in notebooks: wai/wai-quantum-py); the specification-and-evaluator workbench (engine::discover: a specification, the engine's verdict on a generator at every size, and an archive of the cheapest verified generator in every cell of two measures, sealed); a program's history, attributed (engine::versions: versions in a sealed chain, each with who made it and how, proposals reviewed change by change, and each line and gate in the hand that wrote it, which a job's receipt can bind); the person's rules for proposals (engine::locks: held blocks, the gates allowed, the qubit declarations, what to avoid and a region, checked change by change); what is new in a program (engine::novelty: its structural distance to the known constructions and to programs given, each known construction it is proved to be and whether by a different route, and the strengths a cost did not ask for; a workbench candidate that breaks only a rule is an aberration, with the cost it would have); a study (engine::study: a protocol sealed before any data, each participant's condition fixed by their key, their record sealed with it, the measures computed by the engine from what they made, and a cohort report with seeded bootstrap intervals and Cronbach's alpha); convergence (engine::converge: along a program's history, how far the person's versions are built from a model's proposals and the model's share of the gates, with the versions made on their own set beside the rest; and a cohort's diversity, its Vendi score, centroid and narrowing over time); rewrites that keep a circuit's meaning (engine::rewrite: cancellations, merges, Hadamard conjugations and gates carried past what they commute with, each checked on the qubits it touches, so a chain of them proves two programs equal at any width, explains an optimisation, and offers a person one rewrite at a time); a person's taste (engine::taste: a Bradley–Terry model of their own choices between programs the engine proves equal, part by part of a rubric, with typicality shown beside it and moved only by a dial, and how well it predicts them measured); what an agent is told (engine::guide: the language the reader takes, its diagnostics, each held to the reader by a test, the methods and their accuracy classes, worked examples each with its intent, and the rules an agent keeps, which both MCP servers serve as resources and prompts); the language service an editor needs (engine::editor: the reader's refusal and the critique's smells as diagnostics on their lines, completion by what the cursor's place takes, hover with each standard gate's matrix written exactly and held to the engine's own, a user gate's computed from its gates, and each gate's cost as the engine counts it, definitions, references, renames, an outline, folding, and a formatter with one layout that keeps every token, all pure and with no protocol in it); compilation with a certificate (engine::compile: checked passes, every rotation written in Clifford+T within an ε budget by engine::synth, one sealed record of each pass and the distance; see docs/compiler.md); resource estimation from programs (engine::estimate: logical counts with each rotation at its synthesised T count, the physical estimate with the code model fitted to the crate's own decoders, the frontier, every estimate sealed; see docs/estimate.md); the debugger (engine::debug: a program stepped forward and back one operation at a time on the bit-exact or double-precision state vector, or the density matrix under noise beside its noiseless state, stopped before a line, and probed anywhere for its amplitudes and phases, each qubit's Bloch vector and purity, the reduced density matrix of chosen qubits and the entanglement across a cut; every branch at its measurements in the middle with its weight, exact fractions by the tableau for a noiseless Clifford program; a recorded path replayed; a state seen twice the same bits, and the exact method's state after the last gate the exact run's, by its hash; refused past 16 qubits, or 8 under noise); the circuit as LaTeX in plain TikZ (engine::latex) and in words for a screen reader (engine::describe); the circuit edited by its drawing, a gate put on a wire, moved or deleted as an edit to the program's own text through its syntax tree (engine::visual); Pearson's chi-squared test and the G-test of sampled outcomes against a stated distribution, the p-value the same bits everywhere (engine::stats); sets and sweeps (engine::sets: a list of programs, or one program over a grid of its integer, float and angle inputs, run as plain jobs, each item sealed and one receipt over the head that holds the Merkle root of every item's leaf, with each item's path to it); a result's provenance under the categories provenance surveys use (engine::run::run_with_provenance: the program's digest, the method, each pass a compile ran with its check's verdict and the certificate's digest, the shots, seed and plan, the engine's version); and the energy a job spent (engine::energy: the CPU energy the kernel counts for one process on macOS, and on Linux the processor packages' counters over a window, read only when live and labelled with no attribution to the job). It builds for wasm32-unknown-unknown, where it runs on one thread and claims no time
quantum_stabilizer	stabilizer (CHP) tableau — O(n²), scales far past statevector
quantum_mps	tensor-network (matrix-product-state) backend
quantum_pauli	sparse-Pauli / Heisenberg observable propagation over the dyadic gate set (up to 64 qubits)
quantum_spd	sparse Pauli dynamics at utility scale: arbitrary-angle Pauli rotations on up to 1024 qubits, exact Clifford and quarter-turn rotations, a rigorous bound on what truncation can move a result, and the 127-qubit heavy-hex kicked-Ising circuits — whose exactly computed 5-step magnetization it reproduces on all 127 qubits
quantum_spd_receipt	a signed, energy-accounted receipt over a sparse-Pauli-dynamics run, re-checkable bit for bit on any machine
quantum_bptn	tensor-network states on the hardware graph: simple-update evolution with belief-propagation environments and re-gauging, the device's couplings applied a layer at a time in parallel (bit-identical to one at a time). Exact on trees; on the 127-qubit lattice it gives the exactly computed 5-step magnetization to 4e-7 at bond dimension 32 — an independent check on sparse Pauli dynamics, whose errors it does not share
quantum_resource	fault-tolerant resource estimation: from a program's logical counts (qubits, T, Toffoli and rotation gates, measurements) to code distance, T-state factories found by exhaustive search, physical qubits and runtime, on six reference qubits and three codes, with the qubits-versus-time frontier. Reproduces the published worked examples to their printed precision
quantum_resource_receipt	a signed, energy-accounted receipt over an estimate, re-checkable bit for bit on any machine
quantum_qio	quantum-inspired optimisation: Ising and Max-Cut problems (G-set reader, spin-glass generator), simulated bifurcation in its ballistic, discrete and heated forms (batched eight trials per pass, bit-identical to one at a time), simulated annealing, single-flip descent, an exact Gray-code referee up to 34 spins, and step-to-solution. Reaches the best-known cut on seven G-set instances
quantum_uf	union-find decoding in near-linear time over the same matching graph: event-driven cluster growth on integer weights (a radix heap orders the fill events), merges, and peeling. Measured against exact matching on the same shots: within 0.92–1.18× the failures, up to 77× faster at d = 11
quantum_dmrg	ground states of spin chains by DMRG: matrix-product operators for nearest-neighbour chains (XXZ Heisenberg in a field, transverse-field Ising), two-site sweeps with Lanczos and density-matrix truncation, entanglement entropies, a symmetric eigensolver, and two exact referees: full diagonalisation up to 22 sites, and the free-fermion solution of the Ising chain at any length. The critical Ising chain is reproduced to about 10⁻¹¹ per site at 200 sites
quantum_tdvp	time evolution of spin chains by TDVP: two-site sweeps forward and back, Lanczos exponentials that halve a step they cannot converge, bonds split by singular value decomposition, and every basis completed with null vectors so a product state's small bonds do not hold the evolution back. Measures site and bond observables, entanglement at every bond, energy and the Loschmidt echo. Held to two exact referees: Krylov evolution of all amplitudes up to 20 sites, and the free-fermion solution of an Ising quench at any length. On a 100-site critical quench at bond 64 it stays within 10⁻⁹ of the exact answer until the entanglement fills the bond, and past that its error follows the discarded weight it reports
quantum_chem	molecules by DMRG: FCIDUMP integrals, the second-quantised Hamiltonian on spin orbitals compiled into an exact MPO (minimum vertex covers, no numerical compression), DMRG from Hartree–Fock with complete bases, and full configuration interaction as the referee. LiH and H₂O reach full CI to 10⁻¹³
quantum_nqs	neural quantum states: spin models on any graph (Heisenberg, frustrated J₁–J₂, transverse-field Ising), a restricted Boltzmann machine with real parameters (and Marshall's sign on bipartite lattices) or complex ones that learn a sign structure nobody supplied, projected onto a momentum and spin-flip sector, variational Monte Carlo by Metropolis chains or exact enumeration, and stochastic reconfiguration solved in whichever of parameter or sample space is smaller. Held to exact diagonalisation and to DMRG on the same operator sum
quantum_noisy	noisy circuits: quantum trajectories on the state vector (depolarizing, dephasing, amplitude damping, readout), an exact density-matrix referee up to 12 qubits that reuses the same kernels, linear cross-entropy fidelity (sampled, exact and the circuit's own), and the digital error model. Measures where that model is off: below the true fidelity by a margin that grows with the error rate, not with depth
quantum_ldpc	qLDPC memory at circuit level: bivariate-bicycle codes from their two polynomials (k by rank, logical bases), the depth-8 syndrome cycle with circuit-level noise, its detector error model, and BP-OSD decoding (min-sum with adaptive scaling, ordered statistics with a combination sweep). The error model has the same columns as the source's own decoding matrices, and on identical syndromes the decoder makes the source's decisions shot for shot
quantum_arch	architecture-level estimation: yoked surface-code storage (row and grid parity checks over patches, hot and cold), magic-state cultivation read off the published simulation curves, CCZ factories, and a clock set by whichever is slowest of lattice surgery, the magic-state supply and the control loop. Assembles whole-machine estimates; its storage search matches the source's footprint tool layout for layout
quantum_receipt	signed, energy-accounted receipt over a reconstruction
quantum_ops	the operations/attestation layer
quantum_cal, quantum_control, quantum_noise	calibration, filter-function robust control, DD noise spectroscopy, Cycle-Benchmarking noise learning
quantum_mitigate	zero-noise extrapolation, readout M3, classical shadows; in a job, engine::mitigate (with quantum_noise): zero-noise extrapolation, error amplification and cancellation from a learned noise model, Clifford data regression, virtual distillation and readout inversion, each value raw and mitigated with its error bar and the method's assumptions (docs/qec.md)
quantum_qec	CSS codes (distance verified by exhaustive search, not asserted) — rotated surface [[d²,1,d]], toric, bivariate-bicycle, and the [[7,1,3]] colour code, whose self-duality buys a transversal logical Hadamard — one round, no ancillas, no surgery — verified on the simulator, with the surface code shown failing the same move — and the triangular 6.6.6 colour codes (quantum_color, decoded by restriction to matching), each code's distance certified by an exhaustive search over connected supports (quantum_distance) — with decoders: union-find (weighted matching, single-shot, space-time with faulty measurement, and circuit-level with hook errors; imports and exports Stim-syntax detector error models, so other tools' noise models decode here and ours decode there) and Relay-BP (for qLDPC)
quantum_frame	noisy Clifford circuits at QEC scale: reads the ecosystem's circuit text (quantum_qec_text: tags, Pauli-target observables, coordinates, and the error-model text with its ^ decompositions, read as written and written back; conformance vectors); samples detection events by bit-packed Pauli-frame simulation (64 shots per word); derives the detector error model by backward sensitivity, refusing non-deterministic detectors; generates the rotated surface-code memory experiment byte for byte as the reference layout; and decodes by exact minimum-weight perfect matching (Edmonds' blossom on integer weights). Measures logical error rates and fits the code model resource estimates assume. Correlated matching through a model's decomposed faults (quantum_match), and sliding-window decoding as the syndrome arrives (quantum_window)
quantum_tn	tensor-network contraction: circuits (any unitary on any qubits) become networks; a seeded hyper-optimiser finds contraction trees from randomised-greedy and multilevel-partition families, reconfigures them optimally in subtrees, and slices them to a memory cap with a second search around the slices; slices contract in a fixed order, threaded, to the same bits everywhere. Single amplitudes or open-output batches
quantum_cutrank	Clifford circuits measured in a product basis, exactly: the stabilizer state's graph form (Tableau::graph_form) and one closing layer of single-qubit gates at any angles, summed one qubit at a time along an order in a table of 2^{cut-rank} entries. Exact amplitudes, probabilities and samples (by Parseval), at a cost set by the entanglement across the order's cuts, not by the number of qubits; orders annealed for less work; tables in double or single precision; the same bits at any thread count
quantum_gbs	Gaussian boson sampling, exactly: hafnians (power traces, Hessenberg + characteristic polynomial, O(n³ 2^{n/2})), torontonians, lossy Gaussian states from squeezers and an interferometer, exact click and photon-number probabilities, exact samples drawn mode by mode, and a check of observed samples against the exact one- and two-mode click statistics
quantum_sv	the dense state vector at any angle: one-, two- and k-qubit kernels with a diagonal fast path, gate fusion around multi-qubit gates, threads over independent blocks; every kernel path computes each amplitude in the same order, so threading never changes a bit. Agrees with an independent simulator to 2·10⁻¹⁶
quantum_compile	Clifford routing + stabilizer-tableau equivalence proof
quantum_atom	neutral-atom register preparation (Hungarian / LSAP)
quantum_qir	QIR export + ingest — emit and parse QIR (the QIR Alliance's LLVM-based IR); emitted modules validated with llvm-as, and 9 of 10 catalog algorithms re-ingest to a bit-identical statevector
quantum_comm	key distribution and security: BB84 with an intercept-resend eavesdropper (a quiet channel gives a perfect key; interception costs a quarter of it), and the no-cloning theorem priced
quantum_qudit	qubits and qutrits: the Weyl–Heisenberg group, the Fourier gate over Z_d, the controlled sum — exact for d = 2 and 3
quantum_info	mixed states: density matrices, the partial trace, purity, exact Pauli expectations, and CHSH against the classical and Tsirelson bounds
quantum_source	the limits on encoding and transport: von Neumann entropy, the Schumacher limit, and the Holevo bound — which says n qubits carry at most n classical bits, so quantum does not compress classical media
quantum_channel	transport itself: Kraus channels (bit flip, dephasing, depolarizing, amplitude damping), and linear-inversion tomography to see what actually arrived — with the law that a channel can only lose information, never create it
quantum_qbom	Quantum Bill of Materials — stage receipts into one manifest
quantum_vml, quantum_phasor, quantum_qfhrr, quantum_kernel, quantum_qdata, quantum_phasor_meter	the interference / phasor ML layer
quantum_fabric	the compute fabric: members (the CPU and accelerators, quantum processors among them), each kernel implementation certified against the CPU reference in the process that uses it (bit-exact, within a stated tolerance, or statistical by classical fidelity over stated shots), with the certificate saying where it was earned (silicon, an emulator, or a simulator); placement by parity, provenance and metered energy; a signed receipt naming the member and implementation behind a result. Two kernels: apply (a circuit's state) and sample (its measurement counts), the latter with the CPU reference sampler, a corpus shaped for quantum processors, and a virtual quantum processor whose stated noise model lets every step of a processor's path run and be tested without one; its certificates say they were earned in a simulator. quantum_fabric::stablehlo writes the gate as a portable tensor program (StableHLO), every value a 64-bit integer that never overflows, for any tensor compiler to build for its own devices; the stablehlo_gate example writes it with a batch of inputs and the exact outputs a build must give, and ci/tensor-program/check.sh runs a build and holds it to them
quantum_fabric_webgpu	the fabric's WebGPU member, opt-in and not in full: the 32-bit-lane gate kernel in WGSL, one dispatch per gate, through Metal, Vulkan or DX12 natively and through a browser's WebGPU on wasm32-unknown-unknown; a second implementation applies runs of gates tile by tile, one dispatch per run, and is certified on its own. Each adapter is probed against the CPU's arithmetic in the process that uses it and certified bit-exact by reproducing the CPU reference's pinned corpus digests; a result that would leave 32 bits is refused, never returned. One of the features that reach outside the crate
quantum_fabric_cuda	the fabric's CUDA member, opt-in and not in full, native targets only: the gate kernel in CUDA C with exact 64-bit integers, compiled at run time for each device's own architecture, one launch per gate. The CUDA driver and runtime compiler are loaded when first used, so a build with the feature runs on a host without CUDA and finds no member there, saying why. Each device is probed against the CPU's arithmetic in the process that uses it and certified bit-exact by reproducing the CPU reference's pinned corpus digests; a result that would leave 32 bits is refused, never returned. On a device of compute capability 8.0 or later, a second kernel runs every product on the tensor cores (CudaMember::tensor): each value as four 8-bit limbs in bf16, accumulated in f32, which holds every partial sum exactly; probed and certified under its own implementation id, with its own mutants. With quantum_sv too, the dense f64 state vector runs on the device bit for bit as on the CPU: the CPU's own launches (diagonal, one-qubit and grouped formulas), each an IEEE binary64 operation with no fused multiply-add, certified against a pinned corpus digest
quantum_fabric_metal	the fabric's Metal member, opt-in and not in full, macOS: the gate kernel in the Metal shading language with exact 64-bit integers, compiled at run time by the operating system's own compiler, one serial dispatch per gate in one command buffer, the state in memory the GPU and the host share. Elsewhere the build finds no member and says why. Each device is probed against the CPU's arithmetic in the process that uses it and certified bit-exact by reproducing the CPU reference's pinned corpus digests, keyed by its GPU family number (gpu-msl-<family>). On a GPU with SIMD-group matrices, a second kernel forms every product with the matrix multiply (MetalMember::matrix): each value as four 8-bit limbs in bf16, accumulated in f32, which holds every partial sum exactly; probed and certified under its own implementation id, with its own mutants. Under operating system 26 or later, a third kernel forms every product with the shading language's tensor operation (MetalMember::tensor_ops), which the platform maps to the GPU's matrix hardware where it has it: offset-binary 8-bit limbs in bf16, accumulated in f32, through per-threadgroup scratch
quantum_fabric_hip	the fabric's HIP member, opt-in and not in full, Linux: the CUDA member's kernel text, unchanged, compiled at run time by HIP's runtime compiler for each device's own architecture, one launch per gate. The runtime and its compiler are loaded when first used, so a build with the feature runs on a host without them and finds no member there, saying why; the device's properties are read in the runtime's frozen layout or the device is refused. Probed and certified as the CUDA member is, under its own implementation id, and with quantum_sv the dense f64 state vector runs bit for bit as on the CPU. On a gfx11 GPU, a second kernel forms every product with the bf16 matrix instruction (HipMember::wmma): each value offset-binary, as four unsigned 8-bit limbs, because the instruction's accumulation is not exact once a negative term enters a sum; the offset is removed in 64-bit integers. Probed and certified under its own implementation id, with its own mutants
quantum_fabric_opencl	the fabric's OpenCL member, opt-in and not in full, native targets only: the same exact 64-bit kernel in OpenCL C, built at run time by each device's own compiler, one launch per gate, on any OpenCL GPU or CPU (an OpenCL accelerator is refused: no fabric class names it). The ICD loader is opened when first used, so a build with the feature runs on a host without OpenCL and finds no member there, saying why. Each device is probed and certified as the CUDA member's are, and keyed by its vendor id (opencl-<kind>-<vendor id>). With quantum_sv too, the dense f64 state vector runs bit for bit as on the CPU on every device with binary64 (contraction off); a device without it refuses, saying so
quantum_fabric_fpga	the fabric's FPGA member, simulated, opt-in and not in full, native targets only: the gate datapath in Verilog (each 32×32 product from four 16-bit partial products, the size of an FPGA's multiplier blocks; a state RAM; one pair per two cycles), compiled at run time by Verilator into a cycle-accurate simulation driven over a pipe. Probed and certified as the other members are, and every certificate says it was earned in a simulator, so placement ranks it after silicon. A host without Verilator finds no member and says why
quantum_fabric_npu	the fabric's neural-processor member, opt-in and not in full, macOS only: each 32-bit operand split into eight 4-bit limbs, every limb product and limb sum formed in fp16 on the platform's neural processor (each value an integer fp16 holds exactly, whatever order it is added in), the host assembling each product and applying the fixed-point arithmetic. The member exists only where the platform model runtime's compute plan places every operation of the model on the neural processor; a model it would run elsewhere is refused with the placement it reported. Probed and certified as every member is
quantum_fabric_npu_cores	the fabric's npu-cores member, opt-in and not in full, Linux: the gate's fixed-point arithmetic on one compute core of a neural processor's tile array, programmed directly rather than through a model runtime: exact 64-bit products on the core, the host gathering each gate's pairs and checking each row's range. At run time the member finds the device by its driver, builds the core's program with the tile array's open toolchain (WAI_QUANTUM_NPU_CORES_PYTHON names its Python; the program is cached per variant, generation and toolchain) and compiles its host side against the device runtime. Each of the three kernel mutants is its own program and must be caught. Probed and certified as the other members are; its certificates' provenance is silicon
quantum_fabric_tensor_engine	the fabric's tensor-engine member, opt-in and not in full: the gate's products as exact limb convolutions on a tensor processor's matrix engine, one bf16 matrix multiply per tile of pairs accumulated in fp32 (four 8-bit limbs per value, which bf16 holds exactly; every partial sum an integer below 2^24, which fp32 holds exactly in any order), the host assembling the products and applying the fixed-point arithmetic. The kernel runs as a helper under the engine's kernel toolchain (WAI_QUANTUM_TENSOR_ENGINE_PYTHON); where its target is that toolchain's simulator, every certificate says so. Four mutants must be caught, nine-bit limbs the engine cannot hold among them
quantum_fabric_sme	the fabric's matrix-extension member, opt-in and not in full, aarch64 only: the gate's fixed-point arithmetic in the processor's streaming vector mode (SME), 64-bit lanes, the host gathering each gate's pairs and checking each row's range. Every instruction it uses exists only in that mode, so a kernel that ran, ran there. Detected by the processor's feature flags (on Linux, the kernel's AT_HWCAP2, which a user-mode emulator supplies); under an emulator the runner says so (WAI_QUANTUM_SME_EMULATOR) and every certificate carries it. Three kernel mutants are compiled in and must be caught
quantum_fabric_dsp	the fabric's DSP vector-unit member, opt-in and not in full, in a build for the signal processor with its vector unit in 128-byte mode: the gate's fixed-point arithmetic in 32-bit lanes, each 64-bit value a pair of words, every product the vector unit's exact 32×32 multiply and every carry and borrow kept; the host gathers each gate's pairs and checks each row's range. Its instructions exist only on that unit, so a kernel that ran, ran there. Under an emulator the runner says so (WAI_QUANTUM_DSP_EMULATOR) and every certificate carries it. Three kernel mutants are compiled in and must be caught. Its class is dsp
quantum_fabric_vector	the fabric's CPU vector-unit members, opt-in and not in full: the gate's fixed-point arithmetic in the processor's own vector extension, one kernel per instruction set, and one member per set the processor has — avx2 (x86-64, 256-bit), avx512 (x86-64, 512-bit, with the unit's own 64-bit arithmetic shift), sve (aarch64, the scalable vector extension, any length) and rvv (riscv64, the vector extension 1.0, any length) — each operand sign-extended to 64-bit lanes, the host gathering each gate's pairs and checking each row's range. The scalable kernels set their length per pass; the member reads the length from the unit and names it in its id and detail. Detected by the processor's feature flags (on Linux, AT_HWCAP for the vector extension, which a user-mode emulator supplies); under an emulator the runner says so (WAI_QUANTUM_VECTOR_EMULATOR). Its id extends the CPU reference's, so placement with no energy figures keeps the reference. Three kernel mutants per instruction set are compiled in and must be caught
quantum_fabric_dataflow	the fabric's dataflow member, opt-in and not in full, Linux: the gate's fixed-point arithmetic on the first RISC-V core of each of 32 compute tiles of a dataflow accelerator, each over a contiguous slice of a gate's pairs. The program is built in this crate (quantum_fabric::rv32, an RV32IM encoder whose listings an independent assembler reproduces word for word): every 64-bit value a pair of words, mul/mulh for products, sltu for carries and borrows. The device's library (WAI_QUANTUM_DATAFLOW_LIB, loaded at run time) presents the device as a PCI endpoint; the host opens two memory windows on each tile, holds its cores in reset, writes the program at the reset address and that tile's parameters and slice beside it, releases the first cores and clocks the device until every tile reports done. The device is named by its PCI ids (dataflow-1e52-<device>); the library is a simulator, and every certificate says so (WAI_QUANTUM_DATAFLOW_SIMULATOR). Three kernel mutants are compiled in. On the device generation whose vector engine multiplies 23-bit numbers, a second member (-vector) runs the gate on that engine, 32 lanes at a time: the first core configures the tile's unpacker and packer and hands the tile its instructions inline (quantum_fabric::tensix, transcribed from the simulator's own table and checked against it; quantum_fabric::vector_engine), each 32×32 product from four 23-bit partial products
full	everything

Default features are quantum, quantum_toolchain, quantum_receipt.

Speed

Byte-exactness is the contract, so the simulator is optimised only in ways that cannot move a single amplitude: identity does nothing, a diagonal gate phases half the state with one multiply rather than four, and X — so CX — is a swap with no arithmetic at all. fxmul(ONE, x) == x exactly in this fixed point, which is what makes those paths provably identical rather than merely close, and they are checked against the previous implementation amplitude by amplitude.

An all-real matrix — H, and any real rotation — halves its multiplies too, since the imaginary cross terms are multiplications by exactly zero.

At 20 qubits that is 8.9x on Z, 7.1x on X, 4.6x on CZ, 4.3x on CX, 3.4x on T, 1.9x on Y and 1.8x on H.

Utility scale

quantum_spd evolves an observable instead of a state, so a circuit costs what its non-Clifford rotations make it cost rather than 2ⁿ:

cargo run --release --example utility --features quantum_spd -- 0.2 20 1e-4

computes ⟨Z₆₂⟩ after 20 Trotter steps of the 127-qubit heavy-hex kicked-Ising circuit in a fraction of a second, with the bound on how far truncation can have moved it. --example utility_mz checks the 5-step magnetization against the exactly computed values for every angle, and tests/utility_reference.rs holds the published references. quantum_bptn computes the same circuits as tensor networks (--example utility_bptn), so a result can be checked by a second method that does not share the first one's approximation.

Fault-tolerant resources

What a program would need on a machine that does not exist yet is a resource estimate, and claims about that machine stand on one. quantum_resource makes the estimate a deterministic function of its inputs:

wai-quantum lab estimate factoring                    # 2048-bit factoring, six reference qubits
wai-quantum lab estimate chemistry --qubit ns-e4 --frontier
wai-quantum lab estimate factoring --qubit ns-e4 --receipt | wai-quantum verify
wai-quantum estimate prog.qasm                        # from a program's own counts (below)

The model is the planar-ISA one of arXiv:2211.07629: surface and Floquet-code patches, lattice surgery, and 15-to-1 distillation factories chosen by exhaustive search over unit types, distances and copy counts. The tests reproduce that source's own tables:

• every code distance and factory of its per-qubit factoring table, down to the copy counts;
• the distance, factory count, physical qubits and runtime of all twelve factoring and chemistry rows of its summary table;
• all twelve factory counts of its dynamics rows. Factoring on the (ns, 10⁻⁴) qubit comes out at d = 13, 18 factories, 8,716,258 physical qubits and 17 h 43 min.

Holding the model to those tables exposed places where the source's prose and its numbers disagree, and one factory that is not the minimum of its own model. Each is documented in the module and settled by the tables.

A sealed estimate names its whole job (counts, qubit, code, budget, slowdown and search limits, to the bit). Re-running it anywhere must reproduce every figure, down to each factory round, and the bytes are the same natively and as a WASI component.

Optimisation

wai-quantum lab qio --gset G22 --method dsb --dt 0.5 --steps 20000 --trials 64 --target 13359   # the G-set benchmark's G22 file
wai-quantum lab qio --gset G14 --method sa --steps 300000 --beta0 0.2 --beta1 4 --target 3064

wai-quantum lab qio --sk 24 --method exact --spins          # the true ground state, for small problems

Optimisation is the claim made most often for quantum hardware, and every such claim is a comparison against a classical solver. quantum_qio is a re-runnable one. It offers:

• simulated bifurcation (ballistic, discrete, and both with heating);
• simulated annealing;
• single-flip descent;
• an exact referee that settles small instances.

A result is a spin configuration, so anyone can re-check its cut or energy in one pass. On the G-set Max-Cut benchmark the best-known cut is reached on G1, G2, G3, G11, G14, G22 and G43. On G55 the best found is 10,292 against 10,299. The module documents each setting and success rate, and the bound that sparse graphs put on the time step.

Spin chains

wai-quantum lab dmrg -n 200 --bond 64 --sweeps 4                 # critical Ising chain, against its exact energy
wai-quantum lab dmrg --chain heisenberg -n 100 --bond 128         # entanglement profile and discarded weight included

Claims that classical computers cannot simulate a material are claims about entanglement. For one-dimensional systems the density-matrix renormalization group usually can simulate it, with an error it reports itself. quantum_dmrg is that method, held to exact answers:

• full diagonalisation for short chains;
• the free-fermion solution of the transverse-field Ising chain at any length.

At 200 sites the critical Ising chain comes out within about 10⁻¹¹ per site of its exact energy. Runs repeat bit for bit at any thread count, natively and as WebAssembly.

Time evolution

wai-quantum lab tdvp -n 100 --bond 64 --dt 0.1 --t 4             # critical Ising quench, against free fermions
wai-quantum lab tdvp --chain heisenberg -n 100 --bond 64 --t 3    # the Néel state melting, entanglement included

A quantum simulation of dynamics is checkable when a classical method can follow it. quantum_tdvp evolves a matrix-product state by the time-dependent variational principle and reports what it gave up: the discarded weight, the energy drift and the entanglement at every bond. It is held to exact evolution of every amplitude on short chains, and to the free-fermion solution of the Ising quench at any length, including the Loschmidt echo.

On the 100-site critical Ising quench at bond 64, every site's σˣ stays within 10⁻⁹ of the exact answer through t = 3, with the Loschmidt rate agreeing to seven digits. When the entanglement outgrows the bond, the error rises with the discarded weight, and the run says so. A chain small enough to fit the bond evolves exactly, to rounding, at any time step. Runs repeat bit for bit at any thread count, natively and as WebAssembly.

Molecules

wai-quantum lab chem --fcidump h2o.fcidump --bond 64 --sweeps 2   # a molecule's integrals, from a chemistry package: against Hartree–Fock and full CI

Quantum chemistry is where quantum computers are most often said to pay off, and an energy claim for a molecule is checkable when a classical method reaches the same number. quantum_chem reads a molecule's integrals, writes its Hamiltonian as an exact matrix-product operator, and finds the ground state by DMRG, held to full configuration interaction computed in the same crate. LiH and water reach full CI to 10⁻¹³ in one sweep. N₂, on 20 spin orbitals at bond 64, comes within 4·10⁻⁴ of it, and reports the discarded weight that accounts for the difference.

Neural quantum states

wai-quantum lab nqs --lx 8 --exact --steps 200 --lr 0.1          # every configuration enumerated: no sampling noise
wai-quantum lab nqs --model ising --lx 4 --ly 4 --h 3.044 --alpha 1 --steps 400
wai-quantum lab nqs --model j1j2 --lx 8 --periodic --complex --exact --steps 250 --lr 0.1   # frustrated: the sign is learned
wai-quantum lab nqs --lx 10 --periodic --complex --project --kpi --odd --exact --steps 200 --lr 0.1   # held in its sector

Neural-network wavefunctions are offered as evidence about systems that no exact method reaches. quantum_nqs trains one the standard way and holds it to exact answers. On a 4 × 4 lattice at the Ising model's critical field, it lands within its own error bar of exact diagonalisation. Past exact reach, the same Hamiltonian goes to DMRG through its exact MPO, so two independent methods meet on one number. For frustrated models, whose signs no rule gives, a complex network learns them. On the Majumdar–Ghosh ring it reaches the exact energy to rounding. Projected onto a lattice's translations and the global spin flip, a network is held in the sector the ground state lives in. Rings reach their exact energies to rounding, and the frustrated 4 × 4 torus at J₂ = 0.5 comes within a percent.

Noisy circuits

wai-quantum lab noisy --file circuit.jsonl --depol2 0.01 --depol1 0.001 --readout 0.01 --trajectories 4000 --xeb
wai-quantum lab noisy --file circuit.jsonl --damping 0.02 --expect "Z0; X3 X4" --exact

Every quantum-advantage experiment so far runs on noisy hardware and reports a fidelity. For random-circuit sampling that fidelity is a cross-entropy estimate, compared against a digital error model that multiplies the success probabilities of every gate and readout. quantum_noisy checks that arithmetic three ways:

• quantum trajectories on the state vector;
• the exact density matrix, for registers up to 12 qubits;
• the model itself.

On random brickwork circuits under depolarizing noise, the exact fidelity sits above the model's prediction by a few percent. The margin grows with the error rate, not with depth, and it is wider for circuits that do not scramble. The module tabulates the margin.

Device targets

wai-quantum targets import props.json --name lab        # a device's calibration snapshot, kept as "lab"
wai-quantum run bell.qasm --target lab                  # run as the device would
wai-quantum run ghz.qasm --target synthetic-heavy-hex-27 --json

engine::targets (with quantum_engine and quantum_receipt) knows real devices: their qubits with T1, T2, frequency, readout assignment errors and measurement time; their native gates with per-qubit and per-pair errors and durations; the coupling map; and the calibration snapshot's id and time. A target is one strictly read JSON document, wai.quantum.target/1, with a JSON Schema (targets::schema), and its RFC 8785 text's BLAKE3 hash names the snapshot in a receipt.

• Importers (targets::import) read the per-qubit and per-gate calibration properties a superconducting-device service publishes, alone or beside the device's configuration (the form published snapshot devices ship in); an instruction-properties target; the device-capabilities document a cloud quantum service returns for a gate-model device; and the open provider protocol's describe. A source that names no snapshot gets a content id.
• Noise (targets::noise): the compiled program is scheduled as soon as each gate's qubits are free. Each gate's reported error becomes the depolarising channel that, with the relaxation its duration gives, has exactly that average infidelity. T1 and T2 give amplitude damping and dephasing during gates and while qubits idle, and each qubit's readout is its assignment matrix. The density matrix and the trajectories take it as a schedule of channels (quantum_noisy::Schedule), each with its own strength. It is a model of the device, and every result says so.
• Layout (targets::layout): many layouts and their most reliable routes are compared, and the highest expected success kept (each gate's success and each measured qubit's readout). The compiler's own choice, the fewest swaps, wins unless it is beaten, and the program is checked against the circuit by the bit-exact simulator. A target whose two-qubit gate is cx, ecr, ms or zz rather than cz is costed by its own gate, and the plan says the one-qubit corrections are not counted.
• Jobs (targets::job): a job's target is a document or a built-in target's name. The plan states the layout, its expected success beside the fewest swaps', and the noise derived; the result carries the same with the target's hash, inside the receipt, and how far its distribution is from the circuit's ideal one. Every angle must be a dyadic multiple of 2π, since the program is compiled exactly.

The four built-in targets (targets::library) are synthetic, one in each format's shape, their numbers made up by a fixed-seed generator: a 5-qubit line, an 8-qubit ring, a 27-qubit heavy-hexagon lattice and 5 qubits all coupled. Checked against ground truth: a target with no errors gives the ideal distribution to 1e-12 in each of the three gate sets; T1 decay, T2 coherence and the assignment matrix give their closed forms; each gate's channels have exactly its reported average infidelity, by its Choi state; and on a line the layout chosen is the best an exhaustive search finds. A run on a target gives the same bytes natively and as a WASI component.

Fast decoding

wai-quantum lab qec -d 9 --p 0.005 --shots 20000 --decoder uf     # union-find
wai-quantum lab qec -d 9 --p 0.005 --shots 20000 --decoder exact  # exact matching, same shots

A fault-tolerant machine must decode each round of syndromes before the next arrives. quantum_uf is the union-find decoder over the matching graph that exact matching uses. Clusters grow from the fired detectors and merge as edges fill, then each cluster's spanning tree is peeled to a correction. Its time per shot grows linearly with the number of fired detectors. On the same shots it fails between 0.92 and 1.18 times as often as exact matching. The module tabulates both decoders by distance and noise, with the time each takes.

qLDPC memory

wai-quantum lab ldpc --code 144 --p 0.004 --cycles 12 --shots 1000   # failures per cycle, both halves
wai-quantum lab ldpc --circuit --code 72 --cycles 6 --p 0.003        # the circuit itself

High-rate codes are where most of the projected qubit savings in fault tolerance come from, and their headline numbers are logical failure rates per syndrome cycle under circuit noise. quantum_ldpc re-derives them for the bivariate-bicycle family (arXiv:2308.07915):

• the codes are built from their polynomials;
• the depth-8 syndrome cycle is written out gate by gate;
• the circuit is sampled with the Pauli-frame simulator;
• its error model is decoded with belief propagation plus ordered statistics.

The source published its simulation software, and running it gives the oracle. On the 72-qubit code the derived error model has the source's columns, detector for detector, and on identical syndromes the decoder makes the source's decision shot for shot. Logical failure rates track the source's; the one open residual, 2.3σ on one half at the highest noise, is documented in the module. On the 144-qubit code the rates land on the source's published curve.

Architecture

wai-quantum lab arch factoring --bits 2048     # the whole machine, region by region
wai-quantum lab arch storage --target 1e-15    # cheapest plain, row- and grid-yoked layouts
wai-quantum lab arch cultivate --p 1e-3 --target 1e-7

Most of the recent fall in projected fault-tolerant cost comes from the architecture around the code, not from better qubits. Idle qubits sit in yoked storage (arXiv:2312.04522). T states are cultivated inside one patch rather than distilled (arXiv:2409.17595). The clock runs at the pace of the slowest of lattice surgery, the magic-state supply and the control loop. quantum_arch prices each of these.

It re-runs the 2025 estimate that 2048-bit factoring takes under a week on under a million noisy qubits (arXiv:2505.15917).

• Reproduced. Its 897,864 physical qubits, its storage density of 429.03 qubits per logical qubit, and its Toffoli counts for every tabulated key size, each to the reference implementation's own rounding.
• Corrected. Re-running it surfaced six places where the source disagrees with itself, each documented in the module. Its hot-storage count is below its own peak formula. Its cold storage assumes fractional blocks. Its printed runtime is 14% above its own tallies. With every correction applied, the machine needs 958,480 qubits and 4.3 days. The conclusion holds.

Error correction at circuit level

An error-correction experiment is a noisy Clifford circuit, its detectors and its logical observable. quantum_frame samples it, derives its detector error model, and decodes it exactly:

wai-quantum lab qec -d 5 --p 0.003 --shots 100000       # surface-code memory, per-round logical error
wai-quantum lab qec --circuit -d 3 > circuit.txt         # the circuit, in the ecosystem's text
wai-quantum lab qec --file circuit.txt --shots 100000    # any circuit in that text
wai-quantum lab qec --dem -d 3                           # its detector error model
wai-quantum lab qec --fit                                # measure a and p* of P(d) = a·(p/p*)^((d+1)/2)

The model is checked against an independent implementation:

• the generated circuits are identical, byte for byte, across distances 2–15 and 1–8 rounds;
• the derived error models match mechanism for mechanism, to 10⁻¹² in probability, across surface codes in both bases (rotated and unrotated) and repetition codes;
• decoded logical error rates agree point by point within sampling error.

tests/frame_reference.rs keeps two of those fixtures in the repository. The fitted code model comes out at a ≈ 0.023, p* ≈ 0.0100. That is a measured value for the constants a resource estimate (quantum_resource) otherwise takes on trust, and it can be fed straight into one.

Error correction on every surface

wai-quantum qec code color:7                           # checks, k, decoders, its distance certified
wai-quantum qec decode --code surface:5 --error 3,12   # the syndrome decoded, the residual judged
wai-quantum qec decode --memory 5,5,0.003 --shots 20000 --decoder correlated
wai-quantum qec decode --model run.dem --detectors 4,9 # a model's text, decompositions read
wai-quantum qec threshold --distances 3,5,7 --p 0.002,0.004 --shots 20000

engine::qec is one call for the command line, both MCP servers (qec_code, qec_decode, qec_threshold), the job service (POST /v1/qec/{code,decode,threshold}), the Studio's error-correction pane, the desktop app and Python (wai_quantum.qec_code, …), each answer sealed in a job's form. A code comes with a distance certificate: in each sector, the least weight of a logical found, a witness of that weight, and every lighter support ruled out by an exhaustive search over connected supports, re-checkable node for node. Every decoder is held to the same exhaustive test: every error below half the distance corrects to a trivial residual (on circuit-level models, every edge set below half the graph distance). What each decoder guarantees, the window's latency budget, and each mitigation method's assumptions are on docs/qec.md.

State vector

wai-quantum lab sv --file circuit.jsonl --top 8            # likeliest outcomes
wai-quantum lab sv --file circuit.jsonl --expect "Z0 Z1; X3"
wai-quantum lab sv --file circuit.jsonl --sample 1000 --seed 7

quantum_sv runs any gate at any angle on up to 32 qubits, in double precision. gates provides the standard gates by name (H, S, T, √X, √Y, √W, rotations, CX, CZ, iSWAP, fSim, …) for it and for the tensor networks. A 26-qubit, depth-20 random circuit runs in about nine seconds on one machine, and the bits do not depend on how many threads ran it.

Tensor networks

An amplitude of a circuit is a tensor network, and the order it is contracted in decides whether it costs 2³⁰ operations or 2⁶⁰. quantum_tn searches for that order, slices it to fit memory, and contracts it:

wai-quantum lab tn --file circuit.jsonl --bits 0110010110   # one amplitude
wai-quantum lab tn --file circuit.jsonl --open 0,5,9        # a batch over three open outputs
wai-quantum lab tn --file circuit.jsonl --plan-only --cap-log2 30

Circuits are JSON lines, one gate per line: {"q":[a,b],"m":[re,im, …]}.

Each gate is split at the qubits it is block-diagonal on: a control, or a qubit it is diagonal on. That qubit's part is an exact three-index delta, joined to the rest of the gate by a bond of dimension 2, so a cut through a controlled-Z costs 2 instead of the 4 of its two wires. Then every index that some tensor allows only one value of is fixed there, so the input and output projections run through diagonal gates: a controlled-Z beside a projected output becomes scalars. On 61-qubit controlled-Z circuits of depth 8 to 20, the trees found on split, reduced networks cost 2.7 to 5.4 decades less than on whole-gate ones. --whole-gates keeps every gate one tensor and the network as built.

On single amplitudes of random circuits on the 54-qubit advantage-experiment grid, the search finds trees of 10¹⁰·⁵ operations at 10 cycles and 10¹⁸·⁸ at 20, in seconds. An independently developed hyper-optimiser, given the same networks, lands within a factor of 2.5 of these at every depth, in either direction. The 54-qubit, 10-cycle amplitude, contracted here in 16 slices, agrees with an independent contraction to 12 significant figures. The module documentation states what slicing costs on deep circuits and what the scalar executor can and cannot contract.

Compilation with a certificate

wai-quantum compile prog.qasm --epsilon 1e-6 --level 2 > prog.ct.qasm
wai-quantum run prog.qasm --compile 1e-6 --shots 1000     # compiled, then bit-exact

engine::compile takes a program through named passes: lowering, the engine's checked rewrites, phase folding, one- and two-qubit resynthesis (Clifford+T runs in their normal form with the fewest T, two-qubit blocks by KAK in at most three CNOTs) and, for the basis clifford_t, every rotation written as a Clifford+T word within its share of the budget ε (the Ross–Selinger method, in exact arithmetic over Z[1/√2, i]). Each pass is checked where it acts: by exact ring arithmetic or a recomputed phase polynomial (a proof), or on dense matrices (exact to rounding). The certificate records every pass's counts and check, and a bound on the operator-norm distance between the output and the program, up to a global phase, never above ε; up to eight qubits the whole output is also measured against the whole program. A rotation's word has about 3·log₂(1/ε) T gates. docs/compiler.md has the passes, the levels, the certificate's fields and how to read ε.

Resource estimation from programs

wai-quantum estimate prog.qasm --qubit us-e3 --budget 1e-4   # counts, estimate, frontier; signed
wai-quantum estimate prog.qasm --json > est.json && wai-quantum verify est.json
wai-quantum estimate --counts counts.json                    # or a logical-counts document
wai-quantum estimate prog.qasm --export routine              # the counts as a routine document

engine::estimate takes the program itself. It writes it in Clifford gates, T, rotations, Toffolis and measurements (a gate under several controls through clean ancillas, a ladder of Toffolis), synthesises each rotation at its own angle within its share of the error budget (its T count the word's, not a formula), and counts T gates, Toffolis, rotations, measurements, the T depth, the total depth and the logical qubits with their ancillas. The planar model lays those counts out and estimates the code distance, factories, physical qubits and runtime on a physical qubit, with the frontier between qubits and time. On gate-based qubits the code model's a and p* are fitted to this crate's own decoders on the surface-code memory experiment (exact matching: a = 0.0233, p* = 0.01004; union-find: a = 0.0214, p* = 0.00952), from a table of measured points a release test measures again. Every estimate is sealed in the resource-estimate receipt family with the program's digest and its ε budget, and verify re-runs it. The logical-counts JSON and the routine interchange format go in and out. The same estimate is POST /v1/estimate, the MCP tool estimate_resources, the Studio's Estimate pane and wai_quantum.estimate. docs/estimate.md explains every number and what it assumes.

Verdicts: how far the engine checked

wai-quantum run prog.qasm --intent ref.qasm              # the same circuit? the verdict, sealed
wai-quantum run prog.qasm --intent dist.json             # {"000": 0.5, "111": 0.5}: the exact distribution
wai-quantum repair prog.qasm > fixed.qasm                # the mechanical fixes, on the flagged lines alone

engine::verdict gives every answer about a program one level of an ordered ladder: refused, parsed, executed, evidence (checked, one intent by random product states or a statistical test of samples) or proof (every intent checked by proof), with whether the intents hold and the level in one plain line. A job asks for it with "intent" (an exact distribution, a reference program it must equal, or one whose state it must prepare) or "verdict": true, and its result carries it, sealed by the receipt; a job that asks for neither gives the bytes it always gave. engine::repair makes the fixes that are mechanical on the lines a diagnostic flags (a missing ;, an undeclared register's size, a measurement with no target, an unbounded while given its bound, a non-dyadic angle rounded to the bits chosen with its rounding stated), rejects a proposed repair that changes any other line, and says what needs a person. Refusals of what is asked of a program end with a job-layer code (J…), beside the reader's (Q…). docs/verdicts.md has the ladder, the fields, the intents and the rules; docs/job-refusals.md the codes.

Answers a model gives, drawn and checked

root = Answer([bell, counts, check, seal])
```qasm bell
OPENQASM 3.0;
qubit[2] q;
bit[2] c;
h q[0];
cx q[0], q[1];
c = measure q;
```
counts = Histogram(@Sample(bell, 1000))
check = Verdict(@Check(bell, {"00": 0.5, "11": 0.5}))
seal = Receipt(@Seal([bell, counts, check]))

engine::answer reads the answer view layer (extensions/quantum-answers.md): view statements over an OpenQASM 3 program, each view's numbers bound to an engine call written with @, so an answer shows numbers the engine computed and none the model wrote. The reader streams (Stream::push, snapshot, finish): each statement is ready, pending on one still to come, or dropped with its code, and the finished answer is the whole text's however it was split. A statement's problems have codes J100–J112 (dropped, defaulted or warned); a program's keep the reader's Q…. answer::eval carries the calls out, seals what @Seal names in a job's form, and checks a stored answer's receipt marker by running it again. Its conformance set is quantum-conformance/answers/.

engine::views serves six interactive views of the engine's answers (a circuit, a result with its verdict, a receipt, a critique, an estimate's frontier, a device target's map) to an agent host through the Model Context Protocol's extension for them (io.modelcontextprotocol/ui, 2026-01-26): ui://wai-quantum/* resources, one self-contained page of 802 KB held under 1 MiB (views/, built by wai/wai-quantum-views/build.sh), which checks the receipt of what it shows with the engine inside it, as WebAssembly or, under a policy that refuses WebAssembly, translated to JavaScript. Both MCP servers serve them; views::text gives each answer in plain words for a host that draws none.

engine::telemetry is the correctness record a host keeps when the person turns it on: per answer, its codes, the verdict's level, the repairs, the person's accept or reject and its receipt; telemetry::corpus turns the failures into an evaluation corpus in the conformance format.

Clifford circuits in a product basis

A Clifford circuit followed by one layer of single-qubit gates, any gates at any angles, is out of the stabilizer tableau's reach. Its amplitudes are still a sum over a graph state, and quantum_cutrank takes that sum one qubit at a time. The table it carries has 2^r entries, where r is the state's cut-rank (its entanglement, in bits) across the cut the sum has reached. So the cost is set by the widest cut along the order, not by the number of qubits. anneal_order searches for an order with narrower cuts, and work reports the entries the passes touch.

cargo run --release --example cutrank_qasm --features quantum_cutrank -- circuit.qasm cuts
cargo run --release --example cutrank_qasm --features quantum_cutrank -- circuit.qasm order 300000 1 > order.txt
CUTRANK_ORDER=order.txt CUTRANK_PRECISION=single \
  cargo run --release --example cutrank_qasm --features quantum_cutrank -- circuit.qasm sample 1000 7

order anneals for the least work and prints the order it found. A move of the search takes one qubit to another place, and only the cuts between the two places are recounted, so 300 000 moves on the 70-qubit circuit below take a few seconds. sample prints each exact sample with 2^n · p.

A stabilizer tableau fixes a state only up to a global phase, and the graph form inherits that. PhasedTableau carries the phase: alongside the tableau it tracks one basis state of the support and its exact amplitude, a power of 2^{-1/2} times an eighth root of unity, gate by gate. A Hadamard reads the stabilizer whose X part is that one qubit, which is a reduction of the stabilizers. ProductMeasured::scale then brings every amplitude to the circuit's own phase: by the ratio of the tracked amplitude to the graph form's at the same basis state (with_last with identities), times whatever phase the caller's lowering to Clifford gates dropped.

A 70-qubit graph-state sampling circuit has a nearest-neighbour Clifford bulk, then a non-Clifford basis on every qubit. With an annealed order, every cut is 29 bits or fewer. On one workstation, one amplitude takes about half a second and one exact sample 1.1 to 1.5 s, with a largest table of 4 GiB in single precision. Amplitudes agree between orders and between precisions to about 10⁻⁷ relative.

Gaussian boson sampling

wai-quantum lab gbs --squeezing 0.9,0.7,0.8,0.6 --eta 0.5 --seed 3            # exact click statistics
wai-quantum lab gbs --squeezing 0.9,0.7,0.8,0.6 --eta 0.5 --seed 3 --sample 20000 > s.txt
wai-quantum lab gbs --squeezing 0.9,0.7,0.8,0.6 --eta 0.5 --seed 3 --check s.txt

A photonic sampler's outcome probabilities are hafnians (photon-number detection) or torontonians (threshold detection) of its Gaussian state. quantum_gbs computes both exactly. They agree with an independent implementation:

• 10⁻¹² for probabilities and for hafnians up to 20 × 20;
• 10⁻⁷ at 36 × 36.

--check holds a file of observed click patterns to the state's exact one- and two-mode statistics. Those are computable for any number of modes, and every sampler of the state must reproduce them.

Determinism

Simulation is byte-exact: amplitudes are dyadic fixed-point, so a circuit reconstructs to the same statevector_hash on every machine and every target. The approximate methods (MPS truncation, sparse Pauli dynamics, the phasor/ML layer) are reproducible f64: IEEE-754-strict, and identical given the same inputs and seed on every platform. They are documented as such rather than claimed byte-exact. Their sin, cos, ln and atan2 are computed in-crate from + − × ÷, because platform math libraries differ in the last place — enough that four of these layers once gave different bits natively and as a WASI component. tests/bit_identity.rs pins one result from each, so any platform whose arithmetic differs fails there.

A circuit carries the Gateset its phases come from, and its circuit_hash names it, so the same gates in the two gatesets are different circuits. Circuit::new and Circuit::qft build wai.quantum.circuit2 (Gateset::V2, container magic WQC2), whose table holds the integers nearest to each e^{2πi/2^k}. wai.quantum.circuit (Gateset::V1, WQC1) is kept bit for bit so that every file, hash and receipt made with it reproduces; its table deviates from the ideal phase for P(k ≥ 8) and applies none for k ≥ 19. A circuit read from a container takes the container's gateset, and one derived from another keeps it.

A receipt separates the two halves of a cost honestly: work is portable-exact (n_ops · 2^n amplitude updates, recomputed by the verifier, so a sink cannot inflate it) and energy is measured-attested (only the signer can vouch for its own silicon). Signatures travel between substrates because the computation is reproducible — not because two runtimes agreed to trust each other.

An energy figure is only comparable with another when it says how it was acquired — read from the silicon's own counter, from a calibrated instrument, from a model, or a constant. quantum_energy::Labelled seals that acquisition class, with its declared uncertainty, inside the receipt's signature, and LabelledQbom does the same per entry of a bill of materials. A receipt sealed without a label keeps exactly the bytes it always had. MaybeLabelled parses and verifies a receipt in whichever form it arrives, and checks a job's link to its calibration in either form. A label's declared uncertainty must be at least the 0.5/√3 µJ (≈ 0.289 µJ) that rounding the figure to whole microjoules adds: joules_micro × relative_ppm of at least 288 676.

Versions and stability

What is public in this crate (every item documented on docs.rs, with all features), what a version number promises, the support windows, and how a change is announced before it happens: the policy. Each deprecated item, with the version that deprecated it and its replacement: the deprecations. Before 1.0, a breaking change comes only with a 0.y bump, and CI checks that against the last version published.

Every document the job engine writes has a versioned JSON Schema, committed as data in schemas/ and held by tests to what the code writes: a job's request and result, the job as a host returns it, the receipt, a plan, and the answers of the engine's tools. Every result names the engine that made it and the schema it follows ("engine": {"name": "wai-quantum", "version": …}, "schema": "wai.quantum.job-result/1"), inside what its receipt seals; receipts issued before results carried them verify as they did. engine::schema has the names, the stamp and the versions a host reports.

Upgrading from 0.3

• Circuit::new builds Gateset::V2. To reproduce or verify an artefact made with 0.3, read its WQC1 file, or set c.gateset = Gateset::V1 on a circuit built in code.
• quantum::phase, quantum::inv_sqrt2 and quantum::CAPABILITY are removed; Gateset::phase, Gateset::inv_sqrt2 and Gateset::capability replace them.
• to_wqc, circuit_hash and quantum_toolchain::circuit_id return a Result. They fail only on a circuit its gateset does not allow, so never on one that has simulated.
• Circuit and QuantumError are #[non_exhaustive], and QuantumError has a Contract variant and a kind().
• quantum_fabric::certify_lanes and lanes::random_circuit take a gateset.
• from_wqc refuses the circuit/1 payloads extensions/quantum-sim §8 lists; validate refuses a gate with more than 255 controls, and a receipt's from_json a qubit or op count its fields cannot hold.

Also available

• The command line, wai-quantum (the wai-quantum-cli crate): run, check, draw, compile and estimate programs, seal and verify receipts, serve its tools to agents, and the research tools under wai-quantum lab, native or under wasmtime.
• A WASI-HTTP component serving the stack as an ordinary HTTP handler.
• The circuits course, from a first circuit to resource estimates, each exercise checked by the engine: course/, in the Studio and with wai-quantum learn, in English and Simplified Chinese.
• Browser demos: https://wai.transaction.science/quantum-ide; the course on interference and learning: https://wai.transaction.science/quantum-learn.
• All the documentation, by subject: docs/README.md.
• Your own quantum hardware: wai-quantum-qpu runs a job on a device, an account or a simulator the person brings, through the open provider protocol or a built-in client, its cost shown before it is submitted. engine::provider reads such a job, sets the measured counts beside the circuit's exact distribution and seals them, labelled measured; engine::catalog refuses a job that names a provider, so a host that reaches none never runs one on its own methods.

License

Apache-2.0