[{"data":1,"prerenderedAt":4},["ShallowReactive",2],{"am2alNJdKF":3},"# Quantum Error Correction in Lean\n\n[![Lean V4](https://img.shields.io/badge/Lean-V4-blueviolet)](https://lean-lang.org/)\n[![Blueprint](https://img.shields.io/badge/blueprint-live-success)](https://stavan-jain.github.io/QECLean/)\n[![Dashboard](https://img.shields.io/badge/pipeline%20dashboard-live-success)](https://stavan-jain.github.io/qec-lab/)\n[![Research: qec-lab](https://img.shields.io/badge/research-qec--lab-informational)](https://github.com/Stavan-Jain/qec-lab)\n[![Open in Codespaces](https://img.shields.io/badge/Codespaces-open-blue?logo=github)](https://codespaces.new/Stavan-Jain/QECLean)\n[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)\n\nThis project formalizes the stabilizer formalism for quantum error correction in\nthe Lean 4 proof assistant, with the long-term goal of a broad formalization of\nstabilizer codes.\n\nAlong the way, it develops definitions and lemmas for reasoning about qubits,\nquantum states, and unitary operations, contributing toward a verified\nfoundation for quantum computing and fault tolerance in Lean.\n\n## Overview\n\nModules are written in Lean 4 and rely on\n[mathlib](https://github.com/leanprover-community/mathlib4) for linear algebra\nand other foundations. Import everything via `QEC`.\n\n### Features\n\n- **Quantum computing foundations**: qubits, state vectors, norms, ket\n  notation, single- and two-qubit gates (Paulis, Hadamard, phase, CNOT), tensor\n  products, and the Clifford conjugation tableau.\n- **Pauli groups**: single- and n-qubit Pauli groups, matrix representations,\n  commutation theory (including tactics), and the `σ[XZZXI]` notation for\n  literal Pauli strings.\n- **Binary symplectic representation**: check matrices, the symplectic inner\n  product, symplectic span, and the equivalence between independent generators\n  and linearly independent check-matrix rows.\n- **Stabilizer framework**: stabilizer groups, codespaces, centralizers,\n  logical operators, logical gates, code distance, and CSS structure. Codes come\n  in three layers: `StabilizerCode n k` (`Code[[n, k]]`, a stabilizer group\n  with exactly `2^(n−k)` elements, so `k` is determined by the group),\n  `StabilizerCodeWithLogicals n k` (`Code[[n, k]]ₗ`, adding a chosen logical\n  basis), and `StabilizerCodeWithDistance n k d` (`Code[[n, k, d]]`, adding a\n  distance proof). Concrete codes are built from a generator list through\n  `StabilizerCode.Presentation`.\n- **Homological framework**: chain-complex (CSS) codes, the\n  logical-operator-to-homology correspondence, and the bivariate-bicycle\n  doubling layer (`Framework/Homological/BB*`): cover transfer, deck homotopy,\n  deck towers, Bockstein rank, and small-cycle base floors.\n- **CSS concatenation framework**: a parametric `[[n₁n₂, k₂, ≥ d₁d₂]]`\n  concatenation construction (`Framework/Concatenation/`).\n- **Concrete codes**: see the list below.\n\n### Codes\n\nEvery distance `d` listed in the parameters below is proved.\n\n| Code | Parameters | Where |\n|---|---|---|\n| Gross (bivariate bicycle) | `[[144, 12, 12]]` | `Codes/BivariateBicycle/Gross/` |\n| Toric code, `L ≥ 2` | `[[2L², 2, L]]` | `Codes/Toric/` |\n| Rotated surface code, odd `L ≥ 3` | `[[L², 1, L]]` | `Codes/RotatedSurface/` |\n| Iceberg family, `m ≥ 2` | `[[2m, 2m − 2, 2]]` | `Codes/Iceberg/N.lean` |\n| Five-qubit perfect code (non-CSS) | `[[5, 1, 3]]` | `Codes/Small/FiveQubit_5_1_3*.lean` |\n| Steane code | `[[7, 1, 3]]` | `Codes/Small/Steane7*.lean` |\n| `C_6` (Knill) | `[[6, 2, 2]]` | `Codes/Small/SixQubit_6_2_2*.lean` |\n| `[[4, 2, 2]]` | `[[4, 2, 2]]` | `Codes/Small/FourQubit_4_2_2*.lean` |\n| LNCY code | `[[4, 1, 2]]` | `Codes/Small/CSS_4_1_2*.lean` |\n| 3-qubit repetition | `[[3, 1, 1]]` | `Codes/Repetition/Three*.lean` |\n| n-qubit repetition, `n ≥ 2` | `[[n, 1, 1]]` | `Codes/Repetition/N*.lean` |\n| Shor code | `[[9, 1, 3]]` | `Codes/Small/Shor9*.lean` |\n| Quantum Hamming, `r ≥ 3` | `[[2^r − 1, 2^r − 1 − 2r, 3]]` | `Codes/Small/QuantumHamming*.lean` |\n\nEach code is presented by a generator list (`StabilizerCode.Presentation`) whose\nproved obligations are generator count, linear independence of the check-matrix\nrows, pairwise commutation, and exclusion of `-I`; `Presentation.toCode` turns\nit into a `StabilizerCode`, whose stabilizer group provably has `2^(n−k)`\nelements.\nMost codes also provide a `StabilizerCodeWithLogicals` (logical operators in the\ncentralizer, with the required anticommutation) and, where the distance is\nproved, a `StabilizerCodeWithDistance`. In addition, for the Steane code,\ntransversal `H` and `S` are verified as the logical Hadamard and phase gates.\n\nThe single-instance and repetition codes (`Codes/Small/`, `Codes/Repetition/`)\nshare one layout: `\u003CCode>.lean` runs from the generators to the distance proof\nand `stabilizerCodeWithDistance`, and `\u003CCode>Logicals.lean` adds the chosen\nlogical basis and `stabilizerCodeWithLogicals`. The distance proof does not\ndepend on the logical basis.\n\n## Headline results\n\n**The gross code.** IBM's `[[144,12,12]]` bivariate-bicycle code is a verified\n`StabilizerCodeWithDistance 144 12 12`, along with its `[[72,12,6]]` base code.\n\n```lean\ngrossStabilizerCodeWithDistance : StabilizerCodeWithDistance 144 12 12\n```\n\nSee\n[`Codes/BivariateBicycle/README.md`](QEC/Stabilizer/Codes/BivariateBicycle/README.md)\nfor the proof spine.\n\n**The toric family.** For every `L ≥ 2`, the toric code defined on a `L × L` grid is a verified\n`[[2L², 2, L]]` stabilizer code:\n\n```lean\ntheorem toricCodeN_distance_eq_L (L : ℕ) [Fact (2 ≤ L)] :\n    HasCodeDistance (toricStabilizerCode L) L\n\ntoricStabilizerCodeWithDistance L : StabilizerCodeWithDistance (2 * L * L) 2 L\n```\n\nThe homological distance argument is mechanized:\n\n- **Chain complex.** `∂₁ ∘ ∂₂ = 0` over `𝔽₂`.\n- **Homology.** `dim(H₁) = 2` via rank-nullity on `∂₁` and `∂₂`.\n- **Wrapping invariants.** `h(c)` and `v(c)` are well defined on cycles, vanish\n  on boundaries, and give an isomorphism `H₁ ≅ 𝔽₂²`.\n- **Distance lower bound.** Any nontrivial cycle has weight `≥ L`. One of `h`\n  and `v` is `1`, which forces at least one edge in each of `L` disjoint slices.\n- **CSS bridge.** `d = min(d_X, d_Z)`, and both equal `L` by symmetry.\n\n**The rotated surface family.** For every odd `L ≥ 3`, the rotated surface code\nis a verified `[[L², 1, L]]` code (`rotatedSurfaceCodeN_distance_eq_L`). It is\nbuilt on the same homological framework as the toric code.\n\n## Project structure\n\n```\nQEC/\n├── Foundations/        # Qubits, states, gates, tensor products, Clifford tableau\n└── Stabilizer/\n    ├── Foundations/    # Pauli groups + binary-symplectic algebra\n    ├── Framework/      # Core (stabilizer / logical / CSS), Symplectic,\n    │                   # Homological (incl. BB doubling), Concatenation\n    ├── Geometry/       # Lattice-family-agnostic primitives\n    └── Codes/          # BivariateBicycle, Toric, RotatedSurface, Iceberg,\n                        # Repetition, Small\n```\n\nLower layers never import higher ones:\n`Foundations \u003C {Geometry, Framework.Core} \u003C Framework.{Symplectic, Homological} \u003C Codes`.\n\nThe repo also contains these companion libraries, all outside the default\n`lake build` target:\n\n- **`QECLight`**: the library without the bivariate-bicycle family, for\n  memory-constrained environments. [`Playground.lean`](Playground.lean) imports\n  it.\n\n- **`QECWidgets`**: ProofWidgets-based infoview widgets (`#pauli_strip`,\n  `#toric_chain`, `#check_matrix`, and the `pauli_strip?` suggestion tactic).\n  See [`QECWidgets/README.md`](QECWidgets/README.md).\n\nThe research program behind the library lives in the sibling repo\n[qec-lab](https://github.com/Stavan-Jain/qec-lab). It holds the bivariate-bicycle\ndistance lab, the catalog-driven formalization pipeline, and the narrative\nwrite-ups.\n\n## Axiom policy\n\nEverything on `main` is sorry-free and depends on exactly\nmathlib's three standard axioms: `propext`, `Classical.choice`, and\n`Quot.sound`. There is no `native_decide` and there are no custom `axiom`s;\nfinite checks go through the kernel (`decide`, `decide +kernel`, or explicit\ncertificates). CI enforces this over every declaration under `QEC/` with\n[`scripts/AxiomCheck.lean`](scripts/AxiomCheck.lean). You can check any result\nyourself with `#print axioms Your.Theorem`.\n\n## Getting started\n\n### Try it without installing\n\nOpen the repo in\n[GitHub Codespaces](https://codespaces.new/Stavan-Jain/QECLean). The container\ninstalls the toolchain, fetches mathlib's cache, builds `QECLight`, and opens on\n[`Playground.lean`](Playground.lean). See [`deploy/README.md`](deploy/README.md)\nfor this setup and for self-hosting a lean4web instance.\n\n### Prerequisites\n\n- [Lean 4](https://lean-lang.org/) (this repo uses\n  `leanprover/lean4:v4.30.0-rc2`; see `lean-toolchain`)\n- [Lake](https://github.com/leanprover/lake), which ships with Lean, and\n  mathlib, which Lake pulls in automatically\n\n### Building\n\n```bash\ngit clone https://github.com/Stavan-Jain/QECLean\ncd QECLean\nlake exe cache get   # prebuilt mathlib\nlake build\n```\n\nA full build includes the gross code's kernel-checked leaves, which peak at\nseveral GB of memory each. On a \u003C=16 GB machine, limit parallelism (for example\n`LEAN_NUM_THREADS=3 lake build`), or build `QECLight` instead.\n\nThe companion targets and checks that CI runs are:\n\n```bash\nlake build QECLight && lake build QECBlueprint && lake build QECWidgets\nlake env lean Playground.lean\nlake env lean scripts/AxiomCheck.lean   # axiom policy, needs a completed build\n```\n\n### Working with the code\n\n- Open files in your Lean 4 editor (VS Code with the Lean extension, or Emacs\n  with lean4-mode).\n- Start with [`Playground.lean`](Playground.lean), or with\n  [`QEC/Stabilizer/Codes/_TEMPLATE.lean`](QEC/Stabilizer/Codes/_TEMPLATE.lean),\n  the canonical structure for a new code (including the code-file /\n  logicals-file split).\n- Use `#check` and `#print axioms` to explore definitions and results.\n\n#### Claude Code users (optional)\n\nThis repo ships a project-scoped MCP configuration in `.mcp.json` that wires\nup the [lean-lsp MCP server](https://github.com/oOo0oOo/lean-lsp-mcp), giving\n[Claude Code](https://claude.com/claude-code) agents in-editor access to live\nproof states, mathlib search (LeanSearch, Loogle, Lean Hammer), and Lean\ndiagnostics. Claude Code will prompt you to approve the server on first launch.\n\nRequirements: [`uv`](https://docs.astral.sh/uv/) on `PATH` (provides `uvx`).\n[`ripgrep`](https://github.com/BurntSushi/ripgrep) is recommended for the\nlocal-search tool. See [`CLAUDE.md`](CLAUDE.md) for the agent-side workflow.\n\n## Contributing\n\nContributions are welcome! If you add new modules or definitions, please:\n\n1. **Import new modules in their umbrella file** (for example\n   `QEC/Stabilizer/Codes/Small.lean`). Run `bash scripts/check-umbrellas.sh` to\n   catch orphaned modules.\n2. **Keep the axiom policy.** Don't use `native_decide`, `sorry`, or custom\n   `axiom`s on `main`. If you need an unproven input, make it a named hypothesis\n   on the theorem.\n3. **Follow Lean's [style guide](https://leanprover-community.github.io/style-guide.html)**\n   and the conventions in [`CLAUDE.md`](CLAUDE.md), and document key\n   definitions with docstrings.\n4. **Run the full check list** under \"Building\" above, not just `lake build`.\n5. **Update this README** if you add a code family or rename top-level\n   modules.\n\n## Acknowledgments\n\nBuilt using [Lean 4](https://lean-lang.org/) and\n[mathlib](https://github.com/leanprover-community/mathlib4).\n\n## License\n\nReleased under the [Apache License 2.0](LICENSE).\n\n## Maintainer\n\nMaintained by Stavan Jain\n\nA project from the **University of Wisconsin–Madison**.\n",1793473238231]