[{"data":1,"prerenderedAt":4},["ShallowReactive",2],{"RnnhLKluK4":3},"# Quantum4Lean\n\n[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.21197538.svg)](https://doi.org/10.5281/zenodo.21197538)\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n[![Lean 4](https://img.shields.io/badge/Lean-4.31.0-green.svg)](https://leanprover.github.io/)\n\nVerified quantum computing in Lean 4. Bit-exact pure-Lean engine. Complete NISQ stack: StateVector, Observables, adaptive VQE, QAOA, Density Matrix + noise, Jordan-Wigner, quantum chemistry (exact H2), polynomial expansion to arbitrary degree, discrete topology with Hodge and Betti, declarative DSL, OpenQASM 3.0 exporter (including Gate.Unitary), verification tactics, intra-Lean fuzzer, FFI bridge to C++ CPU and Metal GPU engine for up to 30 qubits.\n\nStatus: v0.8.0 — 24 library modules, 7 playgrounds, 12 verified theorems, 208+ tests.\n\n## Build\n\n```bash\ncd Quantum4Lean\nlake build quantum4lean-test && .lake/build/bin/quantum4lean-test\n```\n\nZero external dependencies. Requires Lean 4.31.0 (`lean-toolchain`).\n\n## Architecture\n\n```\nQuantum4Lean (24 modules)\n  Core, Error, Engine, Fuzz, Unitary, Observable, VQE, QAOA,\n  Diophantine, Polynomial, Solver, Simp, Transpile, Clifford,\n  Verify, DSL, Tactic, FFI, QASM, Density, Chemistry, Topology,\n  Ansatz, Runner\n\nQuantum4LeanPlayground (7 demos)\n  Diophantine, Beal, Tijdeman, Riemann, TRDU, FFI, Mobius\n\nQuantum4LeanBridge (C bridge)\n  Quantum4LeanFFI.c/.h  -- Stable C API for FFI\nbuildCPU.sh buildFFI.sh buildMetal.sh  -- CPU/FFI/Metal build scripts\n```\n\n## Quick Start\n\n```lean\nimport Quantum4Lean\nopen Quantum4Lean\nopen Quantum4Lean.DSL.Shortcuts\n\n-- Bell circuit with declarative DSL\ndef bell : Circuit 2 := circuit! {\n  H q[0];\n  CNOT q[0] q[1]\n}\n\n-- Run on the pure-Lean engine\n#eval executeSim bell\n-- Except.ok [1]\n\n-- Verify semantic equivalence\n#eval circuitsEquiv bell bell\n-- true\n\n-- circuit_equiv tactic (Clifford, no H)\nexample : circuitsEquiv\n  (circuit fun c => (c.add (Gate.X q[0])).add (Gate.X q[0]))\n  (Circuit.identity 2) := by\n  circuit_equiv\n```\n\n## API\n\n| Category | Symbols |\n|----------|---------|\n| Types | `Qubit`, `Gate`, `Circuit`, `StateVector`, `Complex`, `UnitaryMatrix` |\n| Pauli | `Pauli`, `PauliString`, `Observable` |\n| Execution | `executeSim`, `executeSimProbs` |\n| Expectation | `expect`, `expectPauliString`, `expectZ`, `expectX`, `expectY` |\n| VQE | `vqe`, `adamVQE`, `isingAnsatz`, `gradient`, `parameterShiftGradient` |\n| QAOA | `qaoaIsing`, `qaoaIsingCircuit`, `qaoaMixingLayer` |\n| Verification | `compile`, `compileSafe`, `validateCircuit`, `circuitsEquiv`, `circuitsEquivSafe`, `circuit_equiv` (tactic) |\n| Clifford | `cliffordEquiv`, `CliffordAmplitude`, `CliffordMatrix` |\n| Optimization | `simplifyCircuit`, `optimizeCircuit`, `verifyOptimization`, `quantumEquivCheck` |\n| DSL | `circuit! { ... }`, `q[i]`, `H`, `X`, `CNOT`, ... (Shortcuts) |\n| Circuit Fuzzer | `FuzzConfig`, `FuzzReport`, `runFullSuite` |\n| Diophantine Fuzzer | `generateWithSolution`, `runDiophantineFuzz`, `diophantineFuzzReport` |\n| Diophantine | `Diophantine`, `toIsing`, `diophantineSolve`, `checkSolution` |\n| Polynomial | `Monomial`, `PolyEquation`, `polyToIsing`, `expandVarPower` (arbitrary degree) |\n| Chemistry | `h2ExactObservable`, `h2Observable`, `lihObservable`, `fermionToObservable` |\n| Topology | `harmonicProjector`, `bettiNumber`, `FirmaPrima`, `topologicalKappa` |\n| FFI | `quantum4LeanInit`, `quantum4LeanApplyGate`, `quantum4LeanMeasure` |\n| QASM | `circuitToQASM`, `exportCircuit`, `printCircuit` (supports Gate.Unitary) |\n\n## DSL\n\n```lean\n-- Full names (always available)\ndef bell : Circuit 2 := circuit! {\n  Gate.H q[0];\n  Gate.CNOT q[0] q[1]\n}\n\n-- Short aliases (requires `open Quantum4Lean.DSL.Shortcuts`)\ndef ghz3 : Circuit 3 := circuit! {\n  H q[0];\n  CNOT q[0] q[1];\n  CNOT q[1] q[2]\n}\n```\n\n## circuit_equiv Tactic\n\n```lean\n-- Works with native_decide for circuits without H (Pauli, CNOT, CZ, SWAP)\nexample : circuitsEquiv\n  (circuit fun c => (c.add (Gate.X q[0])).add (Gate.X q[0]))\n  (Circuit.identity 2) := by\n  circuit_equiv\n\n-- For circuits with H, use #eval\n#eval circuitsEquiv\n  (circuit fun c => (c.add (Gate.H q[0])).add (Gate.H q[0]))\n  (Circuit.identity 2)\n```\n\n## Clifford Verification (Z[i])\n\nFormal proof of equivalences for the 7 Clifford gates (X, Y, Z, S, CNOT, CZ, SWAP) using integer arithmetic in Z[i]. No Float, no √2. 8 theorems proven with `native_decide`.\n\n```lean\n-- Formally proven (0 sorry)\ntheorem rule_X_X_eq_I : cliffordEquiv c (Circuit.identity 2) := by\n  native_decide\n\n-- Runtime verification for any Clifford circuit\n#eval cliffordEquiv myCircuit otherCircuit\n```\n\n## Diophantine Translator\n\nLinear Diophantine equations (ax + by = c) to Ising Hamiltonians.\n\n```lean\nimport Quantum4Lean\n\nlet eq : Diophantine := {\n  vars := [\n    { coeff := 3, name := \"x\", bits := 4 },\n    { coeff := 5, name := \"y\", bits := 4 }\n  ],\n  constant := 22\n}\n\nlet H := toIsing eq 4\nlet result := diophantineSolve eq 4\n#eval checkSolution eq [(\"x\", 4), (\"y\", 2)]  -- true (3*4 + 5*2 = 22)\n```\n\n## Polynomial Translator\n\nPolynomial expansion to any degree n. Z-mask representation with XOR for Z*Z=I.\nGeneralizes the linear translator to multivariate monomials.\nSupports equations such as x^2 = y^3 + 1 (Tijdeman), x^3 + y^3 = z^3 (Fermat n=3), etc.\n\n```lean\nimport Quantum4Lean\n\n-- Equation: x^2 - y^3 = 1\nlet eq : PolyEquation := {\n  monomials := [\n    { coefficient := 1,  exponents := [(0, 2)] },\n    { coefficient := -1, exponents := [(1, 3)] }\n  ],\n  constant := 1,\n  varBits := [4, 4]\n}\n\nlet H := polyToIsing eq    -- Ising Observable\nlet n := polyTotalQubits eq -- 8 qubits\n```\n\n## FFI: C++/Metal Bridge (Apple Silicon)\n\nExternal engine with GPU acceleration via Metal 3. CPU: up to 25 qubits (~1 GB). Metal GPU: Apple Silicon M2/M3 with unified memory.\n\nRequires `../QuantumKit` (sibling repository with the C++ engine). Setup:\n\n```bash\nbash setup.sh          # verify QuantumKit + build libs\n# or step by step:\nbash buildCPU.sh       # libQuantum4LeanCPU.a\nbash buildMetal.sh     # libQuantum4LeanMetal.a\n\n# Run CPU\nLEAN_CC=clang lake build quantum4lean-ffi\n.lake/build/bin/quantum4lean-ffi\n\n# Run Metal GPU\nLEAN_CC=clang lake build quantum4lean-ffi-metal\n.lake/build/bin/quantum4lean-ffi-metal\n```\n\n```lean\nimport Quantum4Lean\nopen Quantum4Lean\n\n-- FFI functions are in Quantum4Lean.FFI and helpers in the playground\n-- Precompiled executable: .lake/build/bin/quantum4lean-ffi\n```\n\nFFI Architecture: Lean (`@[extern]` + `unsafe`) → C bridge (`Quantum4LeanFFI.c`) → C++ Engine (`QuantumKitCore.mm`) with embedded Metal JIT. Zero-copy via `FloatArray` (double*).\n\n## Playground\n\nAdvanced demonstrations extending the library. Independent import.\n\n### Diophantine Solver (QuantumPlaygroundDiophantine)\n\n4 cases with exhaustive search via polyToIsing:\n\n```lean\nimport Quantum4LeanPlayground\n#eval Quantum4LeanPlayground.Diophantine.report\n```\n\nCases: Tijdeman, Pillai n=2, Pillai n=3, Pythagoras.\n\n### Beal's Conjecture (QuantumPlaygroundBeal)\n\nMassive counterexample search at 3 scales (9, 12, 19 qubits):\n\n```lean\n#eval Quantum4LeanPlayground.Beal.report\n```\n\n### ADAM Optimizer\n\nVQE with ADAM optimizer (momentum + adaptive learning rate).\n\n```lean\nlet (energy, params, history) := adamVQE ansatz H initialParams 0.01 200\n```\n\n### Quantum Tijdeman\n\n```lean\n#eval Quantum4LeanPlayground.Tijdeman.report\n-- x^2 = y^3 + 1 via QAOA. Validated against formal proof.\n```\n\n## Fuzzer\n\n```lean\n#eval runFullSuite { maxQubits := 5, numCircuits := 200 }\n#eval reportToString (runFullSuite { numCircuits := 100 })\n```\n\n## Bit-exactness with CoreQU4TRIX\n\n| Algorithm | C++ Source | Lean Implementation |\n|-----------|-----------|---------------------|\n| 1q Unitary | `aplicar_unitaria_cpu` | `applyUnitaryInPlace` |\n| CNOT | `aplicar_cnot_cpu` | `applyCNOTInPlace` |\n| CZ | `aplicar_cz_cpu` | `applyCZInPlace` |\n| SWAP | `aplicar_swap_cpu` | `applySWAPInPlace` |\n| Measurement | `medir_y_colapsar_cpu` | `measure` |\n| LCG | `6364136223846793005` | `lcgNext` |\n\n## Structure\n\n```\nQuantum4Lean/\n+-- lakefile.lean\n+-- Quantum4Lean.lean              -- Main module\n+-- Quantum4Lean/\n|   +-- Quantum4LeanCore.lean      -- Qubit, Gate, Circuit\n|   +-- Quantum4LeanError.lean     -- QuantumError\n|   +-- Quantum4LeanEngine.lean    -- StateVector, simulator\n|   +-- Quantum4LeanFuzz.lean      -- Intra-Lean fuzzer\n|   +-- Quantum4LeanUnitary.lean   -- Complex, UnitaryMatrix\n|   +-- Quantum4LeanObservable.lean-- PauliString, expect\n|   +-- Quantum4LeanVQE.lean       -- Parameter-shift, VQE\n|   +-- Quantum4LeanQAOA.lean      -- Mixing layer, Ising\n|   +-- Quantum4LeanDSL.lean       -- circuito!, q[i]\n|   +-- Quantum4LeanTactic.lean    -- circuit_equiv, quantum_simp\n|   +-- Quantum4LeanSimp.lean      -- Simplifier (12 rules)\n|   +-- Quantum4LeanTranspile.lean -- Transpiler (8 theorems)\n|   +-- Quantum4LeanClifford.lean  -- Clifford verification (Z[i])\n|   +-- Quantum4LeanDiophantine.lean-- Linear Diophantine translator\n|   +-- Quantum4LeanPolynomial.lean -- Polynomial translator\n|   +-- Quantum4LeanRunner.lean    -- Test runner\n+-- Quantum4LeanPlayground.lean    -- Playground root\n+-- Quantum4LeanPlayground/\n|   +-- QuantumPlaygroundDiophantine.lean\n|   +-- QuantumPlaygroundBeal.lean\n|   +-- QuantumPlaygroundTijdeman.lean\n|   +-- QuantumPlaygroundRiemann.lean\n|   +-- QuantumPlaygroundTRDU.lean\n+-- Quantum4LeanBridge/            -- C bridge (FFI)\n|   +-- Quantum4LeanFFI.h / .c\n+-- buildCPU.sh buildFFI.sh buildMetal.sh  -- FFI scripts\n+-- .github/workflows/ci.yml       -- CI\n+-- README.md\n+-- USER_MANUAL.md\n+-- FOUNDATIONAL_MANUSCRIPT.md\n+-- LICENSE\n+-- CITATION.cff\n```\n\n## License\n\nApache 2.0 — see [LICENSE](LICENSE) for full text.\n\n## Citation\n\nIf you use Quantum4Lean in your research, please cite:\n\n```bibtex\n@software{Quantum4Lean_v0.8.0,\n  title   = {Quantum4Lean: Verified Quantum Computing on Apple Silicon},\n  author  = {Izquierdo P\\'erez, Bezalel},\n  orcid   = {0009-0001-5993-4057},\n  doi     = {10.5281/zenodo.21197538},\n  year    = {2026},\n  version = {v0.8.0},\n  url     = {https://github.com/Alektronnik/Quantum4Lean}\n}\n```\n\nSee [CITATION.cff](CITATION.cff) for the full metadata.\n\n## Requirements\n\n- Lean 4 (v4.31.0)\n- macOS / Linux / Windows\n- Apple Silicon + macOS 13+ (FFI/Metal optional, up to 25 qubits)\n- RAM: 512 MB for 20 qubits, 4 GB for 25 qubits\n",1784558046312]