open-standards/wai/quantum-conformance/qec-text/README.md

# qec-text

The error-correction text formats, as the engine reads and writes them: noisy
Clifford circuits with detectors and observables (`circuits/`), and detector
error models (`models/`). The reader and writer are
`wai_quantum::quantum_qec_text`; the circuits' meaning, sampling and models
are `wai_quantum::quantum_frame`.

Every file here is in the writer's layout (`NAME[tag](a, b) t1 t2`, a block's
body four spaces in), so each must come back from reading and writing byte for
byte. `vectors.json` pins, for each:

| field | what |
|---|---|
| `qubits`, `measurements`, `detectors`, `observables` | the circuit's counts after its blocks are unrolled |
| `tags` | the tags its instructions carry, each once, in order |
| `text_blake3` | BLAKE3 of the file |
| `model`, `model_blake3`, `mechanisms` | the file holding the circuit's detector error model, as the engine writes it (coordinates, tags, decompositions), and its hash and size |
| `generator` | for a circuit the crate writes, the call that writes it: the file must be what the code writes today |
| `reference` | one noiseless run of the circuit, every random result reading 0: how many results are `random`, and `record_blake3`, BLAKE3 of the record as 8-byte little-endian words of 64 measurements |
| `samples` | at `shots` shots of `seed`: `detections_blake3` and `measurements_blake3`, the digests of the detection events and of the measurement records. The algorithm and the digests are fixed in `extensions/quantum-sim.md` §10, so a second implementation can produce them |

A model's vector gives its detectors, observables and mechanisms after its
`repeat` blocks are unrolled and `shift_detectors` applied, how many are
decomposed (parts joined by `^`) and how many tagged.

The files:

- `surface_z_d3_r3`, `surface_z_d5_r1`: the rotated surface-code memory
  experiment, Z basis, every noise knob at `p`.
- `bb72_z_c2`, `bb72_x_c1`: the `[[72,12,6]]` bivariate-bicycle memory, its
  depth-8 syndrome cycle, in each basis.
- `cultivate_d3_k2`, `cultivate_d5_k2`: the Clifford form of a magic-state
  cultivation circuit in the triangular colour code (`quantum_cultivate`:
  every `T` an `S`), noise at 0.001, a detector on every measurement. The
  circuits themselves, `T` gates and all, are `cultivation/*.qasm`; the
  `cultivation` list pins each one's counts, the order its checks meet the
  data qubits in, its text's BLAKE3 and `unseen_faults`: the fewest faults
  of the Clifford form that fire no detector and flip the observable,
  searched to four.
- `tagged`: written by hand. Tags on a gate, on noise and on a `REPEAT`;
  Pauli-target observables (`OBSERVABLE_INCLUDE(1) X0 X1 X2` on a
  three-qubit cat state, `OBSERVABLE_INCLUDE(0) rec[-1] Z2` beside a
  measurement record); an inverted measurement target (`M !0 1`);
  coordinates shifted by `SHIFT_COORDS`. A tag on a noise instruction is the
  tag of every mechanism it makes, and mechanisms with one symptom set but
  different tags stay apart.
- `correlated`: written by hand. `C_XYZ` and `C_ZYX` on a qubit that a
  detector reads through them; `E` and `CORRELATED_ERROR` on Pauli targets, so
  the circuit holds one qubit more than its text names; `PAULI_CHANNEL_1`, as
  the independent flips with its law, one rate above 1/2.
- `refuse/no_independent_flips.circuit`: `PAULI_CHANNEL_1(0.1, 0.1, 0)`, which
  no independent flips give.
- `models/decomposed.dem`: written by hand. Decomposed errors, a tagged one,
  a `repeat` block with `shift_detectors`, detector coordinates and a
  declared observable no error flips.

`refuse/` holds text the engine must refuse, each with its line and the words
of its refusal in `vectors.json`: an instruction it does not implement (`T`,
and a Pauli product measurement it reads but does not run), an observable
that is random without noise, a record before the first measurement, a tag
left open, an empty part of a decomposed error, and an unknown model
instruction.

The test is `wai/wai-quantum/tests/qec_text_conformance.rs`:

```sh
cargo test --release --features full --test qec_text_conformance
WAI_QUANTUM_BLESS=1 cargo test --release --features full --test qec_text_conformance   # rewrite the generated files
```