QECLean: Quantum Error Correction in Lean
QECLean is a Lean-based framework for formally specifying and verifying quantum error-correcting (QEC) codes. It consists of:
- Algebraic abstractions for specifying stabilizer codes and code families, including chain complexes and check matrices.
- Proof techniques and algorithmic infrastructure for establishing the
parameters of codes and code families.
See our paper for technical details.
Highlights
- Code families: the first mechanized distance proofs for code families, including the
toric codes, rotated surface codes, and triangular color codes. - Gross code: formalization of the
gross code and BB code of Bravyi et al., including the first proof that the latter has distance 24, previously known only as an upper bound. - Mitten code: formalization of the
Mitten code of Bhardwaj et al.
Overview
Modules are written in Lean 4 and rely on
mathlib for linear algebra
and other foundations. Import everything via QEC.
Codes
Our central abstraction is the dependent type Code[[n, k, d]], which is a Code[[n, k, d]]s:
| Code | Parameters | Where |
|---|---|---|
| Bravyi360 (downstream) | [[360, 12, 24]] | bb-distance-lean |
Toric code, L ≥ 2 | [[2L², 2, L]] | Codes/Toric/ |
| Mitten (downstream) | [[150, 30, 10]] | mitten-distance-lean |
| Gross (downstream) | [[144, 12, 12]] | bb-distance-lean |
Rotated surface code, odd L ≥ 3 | [[L², 1, L]] | Codes/RotatedSurface/ |
Triangular color code, every r | [[3r(r+1) + 1, 1, 2r + 1]] | Codes/Color/ |
| Five-qubit perfect code (non-CSS) | [[5, 1, 3]] | Codes/Small/FiveQubit_5_1_3*.lean |
| Steane code | [[7, 1, 3]] | Codes/Small/Steane7*.lean |
| Concatenated Steane code | [[49, 1, 9]] | Codes/Concat/SteaneSteane.lean |
We also formalize many more more smaller, toy codes like the
Project structure
QEC/
├── Foundations/ # Qubits, states, gates, tensor products, Clifford tableau
└── Stabilizer/
├── Foundations/ # Pauli groups + binary-symplectic algebra
├── Framework/ # Core (stabilizer / logical / CSS), Symplectic,
│ # Homological (incl. BB doubling), Concatenation,
│ # FoldDouble
├── Geometry/ # Lattice-family-agnostic primitives
└── Codes/ # BivariateBicycle, Toric, RotatedSurface, Color,
# Iceberg, Repetition, Small, Concat
Axiom policy
Everything on main is sorry-free and depends on exactly
mathlib's three standard axioms: propext, Classical.choice, and
Quot.sound. There is no native_decide and there are no custom axioms.
CI enforces this with
scripts/AxiomCheck.lean. You can check any result
yourself with #print axioms Your.Theorem.
Getting started
Try it without installing
Open the repo in
GitHub Codespaces. The container
installs the toolchain, fetches mathlib's cache, builds QECLight, and opens on
Playground.lean. See deploy/README.md
for this setup and for self-hosting a lean4web instance.
Prerequisites
- Lean 4 (this repo uses
leanprover/lean4:v4.36.0-rc2; seelean-toolchain)
Building
git clone https://github.com/QECLean/QECLean
cd QECLean
lake exe cache get # prebuilt mathlib
lake build
Contributing
Contributions are welcome! If you add new modules or definitions, please:
- Import new modules in their umbrella file (for example
QEC/Stabilizer/Codes/Small.lean). Runbash scripts/check-umbrellas.shto catch orphaned modules. The library uses Lean's module system: a new file starts withmodule, usespublic import, and opens with@[expose] public section(seeCLAUDE.md§ "Module system"). - Keep the axiom policy. Don't use
native_decide,sorry, or customaxioms onmain. If you need an unproven input, make it a named hypothesis on the theorem. - Follow Lean's style guide
and the conventions in
CLAUDE.md, and document key definitions with docstrings. - Run the full check list under "Building" above, not just
lake build. - Update this README if you add a code family or rename top-level modules.
Citation
Our preprint providing an exposition to QECLean can be found here: Specifying and Verifying Quantum Error-Correcting Codes. If you use QECLean in your research, please cite the paper as follows, and name the library version you used (a v0.x release; see CHANGELOG.md and CITATION.cff):
@misc{jain2026specifyingverifyingquantum,
title={Specifying & Verifying Quantum Error-Correcting Codes},
author={Stavan Jain and Nithin Raveendran and Aws Albarghouthi},
year={2026},
eprint={2611.21236},
archivePrefix={arXiv},
primaryClass={quant-ph},
url={https://arxiv.org/abs/2611.21236},
}
Maintainer
Maintained by Stavan Jain
A project from the University of Wisconsin–Madison.