[{"data":1,"prerenderedAt":4},["ShallowReactive",2],{"Ft9QvWif0z":3},"# FormalRV\n\n**Formally-verified resource estimation for fault-tolerant Shor's algorithm — from the logical algorithm down to the physical surface-code device.**\n\n[![Lean 4](https://img.shields.io/badge/Lean-4.29.1-blue.svg)](https://github.com/leanprover/lean4/releases/tag/v4.29.1)\n[![Mathlib](https://img.shields.io/badge/Mathlib-v4.29.1-orange.svg)](https://github.com/leanprover-community/mathlib4)\n[![CI](https://github.com/yezhuoyang/FormalRV/actions/workflows/lean_action_ci.yml/badge.svg)](https://github.com/yezhuoyang/FormalRV/actions)\n[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](./LICENSE)\n\n📖 **API docs:** \u003Chttps://yezhuoyang.github.io/FormalRV/>\n\n▶ **New here?** Start with [`FormalRV.StandardShor`](FormalRV/StandardShor.lean) — the standard,\ntextbook Shor + surface-code lattice surgery, curated as a four-step learning path\n([guide](FormalRV/StandardShor/README.md)). Read it before the advanced low-overhead papers.\n\n---\n\n## Goal\n\nPut Shor's algorithm, its arithmetic circuits, the logical (Pauli-product) layer, and the\nquantum-error-correction stack into [Lean 4](https://leanprover.github.io/); **prove what can be\nproven, emit the verified circuits as runnable code, and benchmark seven state-of-the-art resource\nestimates against machine-checked bounds** — making the residue that *cannot* be proven explicit.\n\n## Achievements\n\n- **Axiom-free success bound.** `Shor_correct_var` / `Shor_correct_verified_no_modmult_axioms`\n  (start at [`Shor/Main.lean`](FormalRV/Shor/Main.lean)): order-finding succeeds with probability\n  `≥ κ/(log₂N)⁴`, `κ = 4·e⁻²/π²`. Its `#print axioms` is *only* Lean's three standard axioms — no\n  project axioms, no `sorry` — instantiated with a **constructive** modular multiplier (no oracle).\n- **Proof → runnable code.** The same circuits FormalRV *proves* correct are *emitted* as OpenQASM\n  2/3 and Stim, and an **independent** tool (Qiskit, Stim) re-verifies the artifact without trusting\n  Lean — emitted gate counts match the proved counts; Stim `has_flow` re-checks each surgery. The\n  verified schedule also compiles to `tqec`-validated **3D surface-code lattice-surgery layouts**\n  (`.glb` / ray-traced) via [`PyCircuits/ls_compile.py`](PyCircuits/ls_compile.py).\n- **Device scheduling + hard resource bounds.** A unified FT-scheduling framework\n  ([`System/FTFramework`](FormalRV/System/FTFramework.lean)): the full ~10⁹-op RSA-2048 schedule\n  defined recursively and **proven valid for all sizes**; a kernel-clean lower bound\n  `Q·T ≥ K·fq·prod` (≈ 22.4M qubit-hours for RSA-2048) that no schedule can beat; a hardware\n  sensitivity analysis monotone in every device parameter; and a device-program emitter unifying\n  physical operations + system calls, checked against four system invariants.\n- **Seven-paper corpus.** Each estimate is bound to one typed tuple, with a machine-checked bound\n  where the framework allows (table below).\n\n## The four-layer stack\n\n```\n  L1  Algorithm        Shor + QPE + modular exponentiation + Ekerå–Håstad   ┐\n  L2  Logical gadgets  adder · controlled adder · unary lookup · QFT        │ error\n  L3  PPM / logical    Pauli-product measurement · magic-state cultivation  │ bounds\n  L4  QEC code         parity-check matrices · stabilizer schedule · surgery ┘ propagate up\n```\n\nEach layer is a Lean structure with an explicit **inter-layer contract**; three error mechanisms\n(logical/random, approximation, algorithmic-uncertainty) propagate bounds up to the success theorem.\n\n## Worked example — the 2-bit adder, end to end\n\nThe smallest non-trivial slice of the whole stack: the verified **2-bit Cuccaro adder**\n`cuccaro_n_bit_adder_full 2 0` (proven by `cuccaro_n_bit_adder_full_correct`: target `:= a+b`, read\nrestored), pushed through **every layer** onto a zoned hardware architecture, ending in a\n**re-runnable, machine-checked resource verdict**. Full detail — the complete OpenQASM, the full\nPPM program, the 192-SysCall schedule, and a self-verifying parameterized Lean file — lives in\n**[`Example/`](Example/)**. Run it (and re-run it for *your own* hardware) with:\n\n```bash\nlake env lean --run Example/Adder2EndToEnd.lean   # type-checks `schedule_fits` + prints the table below\n```\n\n**Architecture** — 4 zones × 100 logical-patch sites: `Data[0,100)` · `Ancilla[100,200)` ·\n`Factory[200,300)` (`|C̄CZ̄⟩` magic) · `Routing[300,400)`; `Gate2q‖=1`, decoder `‖=4`, `t_react=10µs`\n— **all editable** in the `EDIT HERE` block (change them, re-run, get a new verified verdict).\n\n**Verified resource on that architecture** — every row machine-checked, nothing taken on trust:\n\n| Layer | Resource | Value | Verified by |\n|---|---|---:|---|\n| L2 logical | qubits / Toffoli / T-count | 5 / 4 / 28 | `cuccaro_n_bit_adder_full_correct` (+ Qiskit count re-check) |\n| L3 PPM | `\\|C̄CZ̄⟩` magic / joint measurements | 4 / 12 | `compileArithmeticGateToPPM` |\n| System | SysCalls / **wall-clock** | 192 / **192 µs** | `scheduleWallclockUs`; **fits the architecture** via `schedule_fits` |\n| System | **wall-clock lower bound** | **≥ 72 µs** | `gate2q_capacity_lower_bound_us` (⌈72 Gate2q / 1‖⌉·1µs) |\n| L4 surgery | conflict-free layout / volume | ✓ / 60 | `ls_compile` certificate |\n\nIf you tighten the hardware past feasibility, `schedule_fits` is *rejected* — that is the verdict.\n\n\u003Cp align=\"center\">\u003Cimg src=\"docs/diagrams/ls_adder2_blender.png\" width=\"440\" alt=\"2-bit Cuccaro adder compiled to surface-code lattice surgery, ray-traced\">\u003C/p>\n\n### …and the FULL adder, end to end, on real neutral-atom hardware\n\nThe *same* 2-bit adder runs as a **complete** d=3 surface-code lattice-surgery computation on a\n**neutral-atom** machine ([`Example/neutral_atom/`](Example/neutral_atom)) — every layer present, no\nplaceholders:\n\n1. **It really computes `a+b`** — the measurement-based realization (real `|C̄CZ̄⟩` magic by gate\n   teleportation, measurement-driven Pauli feed-forward) is simulated and matches the adder on **all\n   32 inputs × 30 random measurement branches** ([`logical_adder/verify_mb_adder.py`](Example/neutral_atom/logical_adder/verify_mb_adder.py)).\n2. **d=3 lattice surgery** — each of the 5 logical qubits is a `[[13,1,3]]` patch; every gate is the\n   **full merged-code syndrome** (verified `surface3_zz_merge` 88 CX / `surface3_zzz_merge` 131 CX),\n   each Toffoli a **real `|C̄CZ̄⟩` injection**.\n3. **Detailed system schedule** — 192 SysCalls, machine-checked to fit the architecture\n   (`schedule_fits`), wall-clock 192 µs.\n4. **Neutral-atom compile (ZAC, HPCA 2025)** — **107 atoms** (Memory / Ancilla / Factory / Reservoir\n   zones), **1240 `CZ`**, 95 Rydberg stages, **ZAC-verified**, invariants re-proven under\n   neutral-atom capacities. The GIF shows the atoms physically moving to do it:\n\n\u003Cp align=\"center\">\u003Cimg src=\"Example/neutral_atom/surface3_adder2_d3_neutral_atom.gif\" width=\"560\" alt=\"neutral-atom atoms implementing the full distance-3 surface-code lattice-surgery 2-bit adder\">\u003C/p>\n\n## Repository layout\n\nEach concern is a folder **with its own `README.md`** (purpose, key definitions, key theorems,\nhonest status):\n\n| Folder | What it holds |\n|---|---|\n| [`Core/`](FormalRV/Core) | Gate IR + classical/quantum (matrix) semantics; the 7-T Toffoli = CCX proof |\n| [`Arithmetic/`](FormalRV/Arithmetic) | adders, modular multiplier, unary lookup — with correctness proofs |\n| [`Shor/`](FormalRV/Shor) | ★ the main theorem ([`MainAlgorithm/`](FormalRV/Shor/MainAlgorithm)), QPE, phase kickback, IQFT; the reusable Shor→PPM/emit + windowed pipeline |\n| [`QEC/`](FormalRV/QEC) | qLDPC parity-check matrices, code instances, and `derivedK` (k = n − rank Hₓ − rank H_z) |\n| [`PPM/`](FormalRV/PPM) | Pauli-product measurement, Pauli algebra, magic factories |\n| [`LatticeSurgery/`](FormalRV/LatticeSurgery) | surgery merge/split + system-call contracts; the reusable surgery gadgets + surface-code Shor pipeline |\n| [`System/`](FormalRV/System) | scheduling / device / resource-bound framework (`FTFramework`); the reusable cost / decoder / zone / latency models |\n| [`Framework/`](FormalRV/Framework) | the four inter-layer contract interfaces (L1–L4) |\n| [`Audit/`](FormalRV/Audit) | one folder per paper (uniform Hardware/Zones/L1–L4/Verifier) — paper-specific only; all general/reusable code lives in the framework folders above |\n| [`Qualtran/`](FormalRV/Qualtran) | Qualtran `PhysicalParameters` data bridge |\n| [`Codegen/`](FormalRV/Codegen) | the verified QASM / device-program emitters |\n\nFiles are named for their content and kept small (topical modules behind a `\u003CName>.lean` umbrella).\n\n## Per-paper audit — claim vs. verified\n\nEach paper has its **own folder** under [`FormalRV/Audit/`](FormalRV/Audit) with a **uniform\nstructure** — `Hardware` · `SystemZones` · `L1_Algorithm` · `L2_Arithmetic` · `L3_PPM` · `L4_Code` ·\n`Verifier` · `README`. **All general/reusable code lives in the framework folders** (`LatticeSurgery`,\n`Shor`, `System`, `QEC`, `PPM`, `Framework`, …); a paper folder holds **only that paper's specific\nimplementation + scheduling** and imports *only* general code — never another paper. Rigor is\n**enforced on build**: each folder's `Verifier.lean` runs\n`#verify_clean`, the gate that ACCEPTS a theorem only if its transitive axioms ⊆\n`{propext, Classical.choice, Quot.sound}` — so a `sorry` or native-tainted axiom makes the build\n**fail**. Each layer is exactly one of ✅ *verify-clean semantic* · ➗ *arithmetic-only* (`decide`) ·\n⬜ *documented GAP* (never a counted number masquerading as a proof). Verify one paper with, e.g.,\n`lake build FormalRV.Audit.Gidney2025`. The one cross-cutting ✅ result — order-finding success\n`≥ κ/(log₂N)⁴`, N-parametric — lives in `Audit/Peng2022` and is reused by every paper's L1.\n\n| Paper folder | Headline claim | What is machine-checked (✅ semantic · ➗ arithmetic · ⬜ gap) |\n|---|---|---|\n| [`CainXu2026`](FormalRV/Audit/CainXu2026) (focus) — [2603.28627](https://arxiv.org/abs/2603.28627) | RSA-2048 in ~10⁴ qubits, ~1 week | ✅ modexp PRESERVES the LP code (induction, scale-free) + LP-surgery gadget + lower≤upper soundness + verified resource upper bound + 10⁹-PPM schedule; ➗ k DERIVED from matrices, Eqs E3/E4/E9; ⬜ factory-sharing/parallelism gaps sized |\n| [`GidneyEkera2021`](FormalRV/Audit/GidneyEkera2021) — [1905.09749](https://arxiv.org/abs/1905.09749) | 20M qubits, ~8 h | ✅ CAPSTONE axiom-free: 19.44M ≤ 20M, 8 h sits 2–3× under the verified time ceiling; ✅ finite-zone invariants (over-budget rejected) |\n| [`Gidney2025`](FormalRV/Audit/Gidney2025) — [2505.15917](https://arxiv.org/abs/2505.15917) | \u003C1M qubits, \u003C1 week | ✅ CFS residue-arithmetic engine axiom-clean (faithful RNS, exact CRT, bounded truncation, Ekerå–Håstad); ✅ tally 897,864 \u003C 10⁶; ⬜ Assumption 1 stated-never-asserted; ⬜ quantum half |\n| [`Pinnacle`](FormalRV/Audit/Pinnacle) (webster-2026) — [2602.11457](https://arxiv.org/abs/2602.11457) | RSA-2048 in \u003C100k qubits | ➗ GB code k=12 DERIVED from matrices ([[72,12,6]]); ✅ RSA instance recorded; ⬜ measurement gadget / magic engine / \u003C100k bound (roadmap, OPEN) |\n| [`Babbush2026`](FormalRV/Audit/Babbush2026) — [2603.28846](https://arxiv.org/abs/2603.28846) | ECC-256 in \u003C500k qubits, 18–23 min | ✅ shared bound (confirms modulus-agnostic L1); ➗ verified magic-state spacetime floor; ⬜ first non-RSA, end-to-end OPEN |\n| [`Xu2024`](FormalRV/Audit/Xu2024) — [2308.08648](https://arxiv.org/abs/2308.08648) | constant-overhead FTQC, 24 ms cycle | ➗ the 24,000× cycle-time outlier cross-check; ⬜ tuple (the arch the neutral-atom demo realizes) |\n| [`Peng2022`](FormalRV/Audit/Peng2022) (SQIR/Coq) — [2204.07112](https://arxiv.org/abs/2204.07112) | machine-checked Shor | ✅ **the cross-cutting bound lives here** — order-finding success ≥ κ/(log₂N)⁴, N-parametric (axiom-clean) |\n\nLegend: ✅ *Verified* semantic theorem · ➗ *Arithmetic-only* (`decide`) · ⬜ *Recorded/Assumed*.\n\n## What is proven vs. assumed\n\nStrict honesty taxonomy — only semantic-correctness theorems count as **Verified** (a gate count on\nan unverified circuit is just counting symbols):\n\n**Machine-checked, no custom axioms:** the Shor success-probability chain, the Cuccaro/Gidney\nadders, the constant modular multiplier, the 7-T Toffoli identity, the QPE peak bound, the\nPauli/stabilizer algebra, and the schedule resource lower bound. **Out of scope (assumed by\ncitation):** decoder correctness & runtime, hardware physics, magic-state distillation internals,\nand merged-code distance. See each folder's `README.md` for per-area status.\n\n## Build\n\n```bash\ngit clone https://github.com/yezhuoyang/FormalRV && cd FormalRV\nlake exe cache get      # prebuilt mathlib (≈ minutes)\nlake build              # builds the whole library\n```\n\nCheck a theorem's axioms with `#print axioms FormalRV.Shor_correct_var`\n(expected: `propext, Classical.choice, Quot.sound`). Emit + independently re-verify the circuits:\n`lake env lean --run scripts/EmitQASM.lean` (→ Qiskit re-counts gates) and\n`lake env lean --run emit_shor_demo.lean` (→ Stim `has_flow`).\n\n## License\n\n[MIT](./LICENSE) © 2026 John ye. Built on [mathlib](https://github.com/leanprover-community/mathlib4);\nthe Shor layer ports [SQIR](https://github.com/inQWIRE/SQIR); `Qualtran/` bridges\n[Qualtran](https://github.com/quantumlib/Qualtran).\n",1780846778543]