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

# 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

| Feature | What it gives you |
|---|---|

**Cross-architecture reproducibility is tested, not asserted.** The full test
suite passes under `wasm32-wasip2` on wasmtime as well as natively, and the
floating-point results — entropy, the Holevo bound — are pinned to their exact
IEEE-754 bits, so a platform that computes something different fails the suite
instead of quietly returning a different number:

```text
CARGO_TARGET_WASM32_WASIP2_RUNNER=wasmtime cargo test --release --target wasm32-wasip2 --features full
```


The same binary answers what a state *carries*, not only what a circuit does:

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

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

| `quantum` | byte-exact statevector simulation (dyadic Clifford+T+P(k)) |
| `quantum_toolchain` | algorithm library, backend recommendation, **OpenQASM 2/3 ingest of what the mainstream toolchains actually export** — both register and both measurement spellings, `rx`/`ry`/`rz`/`sx`/`u`/`u2`/`u3`/`crz`, and exact rational-multiple-of-pi angles (non-dyadic angles are refused, never rounded) — 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, 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 — 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_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 |
| `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