Fix surface-code hook errors with an orientation-aware CNOT schedule

[bmhowe23]

Description

The surface-code stabilizer kernel executed every plaquette's CNOTs in ascending data-qubit index order — the flattened parity matrices it receives carry no ordering information, so an optimized schedule could not even be expressed. With the same row-major order on both X and Z plaquettes, a mid-round ancilla fault ("hook error", Dennis et al., arXiv:quant-ph/0110143) propagates onto a data-qubit pair aligned with one of the logical operators, halving the effective circuit-level distance of one memory basis.

Measured impact (before this PR, ZH orientation, prep0): effective distance 2 instead of 3 at d=3, and 3 instead of 5 at d=5. Which basis is damaged depends on the code orientation; prepp was coincidentally unaffected for ZH.

This PR gives the surface code the standard zigzag CNOT schedule (Tomita & Svore, arXiv:1404.3747), selected per orientation so hook pairs land perpendicular to the same-type logical, and executes the X and Z checks interleaved over four shared timesteps (one depth-4 extraction round).

Design, with no breaking interface changes:

• stabilizer_grid::get_cnot_schedule_x/z(): schedule matrices with the same shape/support as the parity matrices; entry 0 = no support, k ∈ 1..4 = CNOT timestep. Rows match the sorted parity-matrix rows (enforced: a first-support tie throws instead of silently misaligning ancilla wiring). get_cnot_schedule_pairs_x/z() provides the flat (stabilizer, data) pair-list form used by the realtime examples.
• code::get_stabilizer_schedule_x/z(): new virtuals defaulting to the parity matrices, so the stabilizer_round kernel signature is untouched and repetition/Steane receive byte-identical inputs. The memory-circuit drivers pass these to the kernel.
• The surface kernel executes CNOTs timestep-major with X and Z checks interleaved; the zigzag pair is conflict-free and commutation-valid under interleaving (proven by the DEM tests — stim rejects non-deterministic detectors).
• The four realtime C++ app examples and the Python example consume the grid API instead of five copy-pasted ascending-order schedule builders; Python bindings return the schedule as numpy arrays consistent with get_parity_x/z().
• Docs: the QEC introduction page documents the schedule-matrix kernel contract and the surface-code CNOT schedule, cross-referencing the Doxygen API docs as the single source of truth for the encoding.

Validation:

• New effective-distance test (test_qec_stim): builds the DEM from the actual kernel under two-qubit depolarizing noise and asserts the shortest undetectable logical error has weight d, for d=3,5 × both bases × all four orientations. Fails with weight ⌈d/2⌉ against the previous ordering.
• New schedule-property test (test_qec): d=3,5,7 × all orientations — parity-row alignment, valid distinct timesteps, hook-pair perpendicularity, no data qubit touched twice per timestep.
• The schedule matches ising-decoding's up to a left–right mirror (theirs starts each plaquette at NE, ours at NW) — same hook orientation and validity class; flipping the corner order is a one-line change if exact equivalence with predecoder training circuits is ever needed.

Runtime / performance impact

Monte Carlo (pymatching, CX depolarizing noise, 100k shots, rounds = d): at p=0.002 the prep0 logical error rate improves 14× at d=3 (0.030 → 0.0018) and 5.8× at d=5 (0.0057 → 0.00098); prepp is statistically unchanged and the two bases are balanced after the fix. The pre-fix DEM also contained parallel edges with identical detector signatures but different observable effects — fundamentally undecodable mechanisms that pymatching's default merge strategy rejects outright; these disappear with the fix.

Build/test-time cost: the new tests add ~50 ms to the two unit-test binaries. Kernel classical overhead adds a constant-factor scan per stabilizer round (negligible on stim, which traces the kernel once).

Self-review checklist

Before requesting review

• I reviewed my own full diff in GitHub or my editor.
• PR is in Draft if it is not yet ready for review.
• Temporary / debugging changes have been removed.
• Local test logs reviewed; no unexplained warnings or errors.
• CI logs reviewed; no unexplained warnings or errors.
• Full CI has been run.

Scope and size

• PR is under ~1000 lines, or an exception is justified in the description.
• Refactoring-only changes are isolated in their own PR(s). (the self-review hardening/dedup is a separate commit within this PR)
• No existing tests were disabled or modified just to make this PR pass.

Tests

• New functionality has new tests.
• Tests fail if the new functionality is broken (including crashes), not just when it is missing. (effective-distance test verified to fail against the previous ordering)
• Negative tests added where exceptions are expected. The new no-tie guard in build_cnot_schedule is unreachable for any valid rotated surface code by construction (geometric argument in the code comment), so it cannot be exercised without an artificial grid; existing invalid-orientation/invalid-distance exception tests still cover the public entry points.
• Truth data added where simple EXPECT_* / assert checks are insufficient for algorithmic correctness. (effective distance == d via graphlike-DEM shortest-error search; Monte Carlo numbers above)
• CI runtime impact considered; team notified if significant. (~50 ms added)

Documentation

• Public-facing APIs have Doxygen docs.
• User-visible behavior changes have public docs. (QEC introduction page updated; full docs build verified locally — zero new warnings, new cross-references resolve)

Code style

• Naming follows the existing convention (snake_case) for the area being modified.

Dependencies

• No new third-party dependencies.

🤖 Generated with Claude Code

[eliotheinrich]

Left a few suggestions, but looks good to me. Most substantial is probably the Python support, but that's maybe best suited for a follow-up.

[kvmto]

Looks good thanks, Ben!