QECLean: Quantum Error Correction in Lean

Lean V4 Open in Codespaces License: Apache 2.0 arXiv

QECLean is a Lean-based framework for formally specifying and verifying quantum error-correcting (QEC) codes. It consists of:

  1. Algebraic abstractions for specifying stabilizer codes and code families, including chain complexes and check matrices.
  2. 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 stabilizer code together with lean proofs that it uses physical qubit to encode logical qubits with code distance . We formalize the following codes as Code[[n, k, d]]s:

CodeParametersWhere
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 3-qubit repetition code.

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; see lean-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:

  1. Import new modules in their umbrella file (for example QEC/Stabilizer/Codes/Small.lean). Run bash scripts/check-umbrellas.sh to catch orphaned modules. The library uses Lean's module system: a new file starts with module, uses public import, and opens with @[expose] public section (see CLAUDE.md § "Module system").
  2. Keep the axiom policy. Don't use native_decide, sorry, or custom axioms on main. If you need an unproven input, make it a named hypothesis on the theorem.
  3. Follow Lean's style guide and the conventions in CLAUDE.md, and document key definitions with docstrings.
  4. Run the full check list under "Building" above, not just lake build.
  5. 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.