# 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 |

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.
- `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.
- `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
```