# 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**.
```toml
[dependencies]
wai-quantum = "0.3"
```
```rust
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
| `quantum` | byte-exact statevector simulation (dyadic Clifford+T+P(k)) |
| `quantum_toolchain` | algorithm library, backend recommendation, OpenQASM 3.0 in-and-out, Bloch / entanglement / purity analysis |
| `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 |
| `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 |
| `quantum_qec` | CSS codes (distance verified by exhaustive search, not asserted) — **rotated surface** `[[d²,1,d]]`, toric, bivariate-bicycle — with **two 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_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_info` | **mixed states**: density matrices, the partial trace, purity, exact Pauli expectations, and CHSH against the classical and Tsirelson bounds |
| `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 |
| `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`.
## 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, the phasor/ML layer) are
*reproducible f64* — IEEE-754-strict, identical given the same inputs and seed —
and are documented as such rather than claimed byte-exact.
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.
## Also available
- A CLI (`wai-quantum` in the [`wai`](https://crates.io/crates/wai) crate) — run
circuits, emit OpenQASM, seal and verify receipts, native or under `wasmtime`.
- A WASI-HTTP component serving the stack as an ordinary HTTP handler.
- Browser demos and a course: <https://wai.transaction.science/quantum-ide>
## License
Apache-2.0