Hands-On Examples for the Spatial Surface-Code Decoder

Four interactive demos — the lattice and what MWPM does, the capacity knee, the threshold sweep, and how the network must be sized

Companion to the tutorial and to the paper “Sizing and Capacity Boundaries of Spatial Convolutional Decoders for Surface-Code Quantum Error Correction” (B. Guarraci, Galatheus, May 2026). The tutorial explains why a pure spatial decoder must be sized to the code distance and where it stops; this page lets you see it. Every widget below runs entirely offline with hand-written canvas + JavaScript — no libraries, MathJax aside. The rotated-lattice picture in Widget 1 is an illustrative schematic of the code geometry (§2.1–2.2 of the tutorial); it is the only schematic element, disclosed as such. Every number on this page (Widgets 2–4) is taken verbatim from the multi-seed reproduction artifact surface_code_qec/data/qec_clean_knee_multiseed.json (seeds 42/43/44, disjoint test split) and the per-run JSONs in data/qec_clean_knee_multiseed_json/, cross-checked against Tables 2–3 of main.tex. Nothing is invented.

The one idea to hold onto A pure spatial (3D convolutional) surface-code decoder beats MWPM at small code distance — \(+13.7\%\) at \(d=3\), \(+16.9\%\) at \(d=5\), \(+11.4\%\) at \(d=7\) on logical error rate at \(p=0.003\) — then hits a capacity boundary: at \(d=9\) it ties MWPM with exploding seed variance, and at \(d=11\) the selected knee is under-capacity and falls far below MWPM (\(-453\%\)). The paper's claim is not “neural beats MWPM” (others already showed that); it is an honest map of how big the network must be per distance, and exactly where the pure-spatial approach runs out. Widget 2 lets you watch that knee.

1. The surface code and what MWPM does

Rotated surface-code lattice — place errors, light the syndrome, watch matching pair them

What this teaches: pick a code distance \(d\) and click data qubits to place \(X\) errors. Each error flips its neighbouring \(Z\) stabilizers (ancillas), which light up as a syndrome. A minimum-weight-matching decoder then pairs each lit ancilla — to another lit ancilla or to the nearest boundary — with the cheapest connecting path. That fixed combinatorial pairing is MWPM: a hand-designed rule that never learns. The neural decoder of this paper replaces that rule with a learned function of the same lattice.

data qubit (clickable) X error placed Z ancilla (quiet) lit ancilla (syndrome) MWPM pairing path

Why this geometry is labelled schematic The lattice drawing is an illustrative rendering of the rotated surface code — \(d^2\) data qubits with \(d^2-1\) stabilizers in a checkerboard, weight-4 in the bulk and weight-2 at the boundary, exactly as the tutorial describes (§2.2). The syndrome lights and the matching path are computed live from where you click. But this is a single static round; the actual decoder sees a 3D detector volume \((d{+}1)\times(d{+}1)\times(d{+}1)\) — two spatial axes plus one time axis from \(d\) measurement rounds — whose size grows as \(d^3\). That \(d^3\) growth is the whole reason capacity must scale with distance, which is the next widget.

2. The capacity knee

Neural improvement over MWPM vs. code distance — the win, the boundary, the collapse

What this teaches: the spatial decoder beats MWPM (green, positive) at \(d=3,5,7\), ties it at \(d=9\), then collapses (red, negative) at \(d=11\) where the selected knee is under-capacity. Toggle the block type and the physical error rate. The crossover near \(d=9\) is the capacity boundary: a pure-spatial decoder of fixed budget cannot keep pace with the \(d^3\) detector volume — not a smooth power law, but a wall where seed variance explodes.

The win is real and significant at \(d\le7\) At \(p=0.003\) the three-seed mean test LER beats MWPM by \(+13.7\%\) (\(d=3\): \(0.005681\) vs \(0.006587\)), \(+16.9\%\) (\(d=5\): \(0.002734\) vs \(0.003290\)), and \(+11.4\%\) (\(d=7\), classic: \(0.001237\) vs \(0.001396\)); the LC0 block stretches \(d=7\) to \(+25.6\%\) (\(0.001037\) vs \(0.001396\)). Per-seed McNemar tests on the same shots favour the neural decoder at every distance \(\le7\). These are the kind of margins prior hybrid decoders already report — the contribution here is mapping where they end.
The boundary and the collapse (\(d=9\), \(d=11\)) At \(d=9\) the classic decoder is statistically tied with MWPM: per-seed LERs \(\{0.000591,0.000451,0.000723\}\) straddle MWPM's \(0.000557\) (one seed wins, two lose), and the SEM jumps an order of magnitude. At \(d=11\) the selected \(96{\times}12\) knee is openly under-capacity: classic LER \(0.001049\) vs MWPM \(0.000203\) at \(p=0.003\) (\(-453\%\)), LC0 worse still (\(-1192\%\)). This is reported as a boundary, not a failure of the idea — see the next note.
The \(d=9\) boundary is under-resourcing, not a wall A follow-up probe at \(d=9\) — same architecture (classic, \(w{=}96\), depth 12) but \(5\times\) the training data — beats MWPM across the board: three-seed mean LER \(0.000232\) vs MWPM \(0.000537\) at \(p=0.003\) (\(+56.5\%\)), \(0.00346\) vs \(0.006785\) at \(p=0.005\) (\(+49\%\)), and \(0.0201\) vs \(0.0312\) at \(p=0.007\) (\(+36\%\)), with per-seed McNemar \(p\sim10^{-7}\)–\(10^{-11}\). So the \(d=9\) “tie” of the headline table is an under-training artifact of the knee, not a fundamental capacity limit. (Source: data/d9_dataarm_reproduction.json.)

3. The threshold sweep

Logical error rate vs. physical error rate — how suppression depends on \(d\) and \(p\)

What this teaches: pick a decoder and watch logical error rate (LER) climb with physical error rate \(p\in\{0.001,0.003,0.005,0.007\}\), one curve per distance. Below threshold, bigger \(d\) gives a lower LER (more suppression) — you can see the \(d=3,5,7\) curves fan apart at low \(p\). At the capacity boundary the \(d=9,11\) curves stop behaving: with the selected knee they cross back above smaller-distance curves, the visual signature of under-capacity.

Reading the fan-out (and where it breaks) At \(p=0.003\), classic neural LER falls \(0.00568\,(d{=}3)\rightarrow0.00273\,(d{=}5)\rightarrow0.00124\,(d{=}7)\) — suppression improving with distance, as a code below threshold should. Then it reverses: \(d=9\) sits at \(0.00059\) (still low, but tied with MWPM) and \(d=11\) jumps back up to \(0.00105\), worse than \(d=7\). A properly-resourced decoder would keep falling; the reversal is exactly the capacity boundary made visible. The vertical axis is log-scaled so the four-decade spread across \(p\) and \(d\) is legible.

4. How the network must be sized

The per-distance capacity knee — width \(\times\) depth, Classic vs LC0

What this teaches: there is no one-size network. For each distance the paper selects the smallest \(\textrm{width}\times\textrm{depth}\) cell within tolerance of the best capacity-scan result (the “knee”). Capacity grows with distance — the detector volume scales as \(d^3\) — and the two block designs need different sizes: LC0 buys its \(d=7\) win by going to \(96{\times}12\) where classic stays at \(64{\times}8\). Toggle to see the rough parameter-proxy \(w^2\!\cdot\!\text{depth}\) climb.

Selected per-distance knees (\(\textrm{width}\times\textrm{depth}\)), each evaluated at seeds 42/43/44 on the disjoint test split. From Table 1 (tab:knees) of main.tex. The bold green cell at \(d=7\) marks where LC0 spends extra capacity (\(96{\times}12\) vs classic's \(64{\times}8\)) and earns its \(+16.1\%\) edge over the classic block.

Block design is distance-dependent, not second-order The two blocks are indistinguishable at \(d=3,5\) (LC0 is \(+0.4\%\) and \(+2.4\%\) over classic at \(p=0.003\)), but at \(d=7\) the LC0 block is a clear win — \(+16.1\%\) over classic, i.e.\ \(+25.6\%\) vs MWPM against the classic block's \(+11.4\%\). At the \(d=9/11\) boundary LC0 does not help and is in fact worse. So architecture is not a tie-breaker you can ignore once capacity is set: it extends the useful regime at intermediate distance and offers no rescue at the wall. (Aggregate, unpaired — the two blocks trained on different shots; a paired same-shot test is future work.)

Companion to the tutorial and main.tex (“Sizing and Capacity Boundaries of Spatial Convolutional Decoders for Surface-Code Quantum Error Correction”, B. Guarraci, Galatheus). Widget 1 is an illustrative schematic of the rotated-surface-code lattice (tutorial §2.1–2.2); the syndrome and matching path are computed live, but no value in it is load-bearing. Widgets 2–4 numbers are verbatim from surface_code_qec/data/qec_clean_knee_multiseed.json (three-seed mean test LER, per-seed values, MWPM baselines, and relative improvements; seeds 42/43/44, disjoint test split) and the per-run JSONs in data/qec_clean_knee_multiseed_json/, cross-checked against Tables 1–3 of main.tex; the \(d=9\) follow-up figures are from data/d9_dataarm_reproduction.json. No results were invented.