Proposal: neural surface-code decoder (QEC) example?

Hi, I built a small MLX example I think could fit here and wanted to check scope before putting together a PR.

maxwell is a transformer-based decoder for the surface code (quantum error correction). It reads a syndrome and predicts whether the logical qubit flipped, benchmarked against minimum-weight perfect matching (MWPM), the standard classical decoder. At distance 3, trained on simulated shots from Stim (circuit-level depolarizing noise) and evaluated on 200k fresh shots per physical error rate, the model beats MWPM on logical error rate at every rate tested (3-13% relative reduction, largest at low noise). It's upfront about the tradeoff: single-shot decode latency is ~200x slower than MWPM, so this is an accuracy result, not a real-time one.

I also tried scaling to distance 5 (120 detector tokens vs 24), and that one isn't a win: under a compute budget capped at 3 epochs on a single M1 with no cloud GPU, the neural decoder trails MWPM at every rate (3.3x-23.6x higher logical error rate, worse at low noise, narrower gap as noise increases). Validation accuracy climbed steadily across all 3 epochs (84.9% -> 85.9% -> 86.5%), so this looks like an undertrained model on a hardware budget rather than a dead end, but I'm reporting it as what it is: a partial result.

Given the repo already hosts some scientific/non-mainstream examples (gcn, normalizing_flow), would a QEC decoder like this be something you'd want here? Repo is at https://github.com/rajanshxrma/maxwell if useful context before I put time into packaging it to your conventions (flat scripts, black formatting, requirements.txt instead of the current uv/pyproject setup). Happy to adjust scope based on what you think.

Start by reviewing the linked maxwell repository and the existing gcn and normalizing_flow examples to compare structure and conventions. First confirm whether a neural surface-code decoder fits the repository scope; done would be an accepted example packaged to the project's requested conventions, with its reported distance-3 and distance-5 results preserved.