# jazir555/math-proofs architecture

> Architecture diagram of the GitHub repository jazir555/math-proofs, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jazir555/math-proofs
- Repository: https://github.com/jazir555/math-proofs

## Overview

##### Project Type and Purpose
- This is an open-source formal-verification library/tool built on Lean 4 + Mathlib4.
- Its purpose is to encode, prove, and document the Transfer Matrix method and related theorems for 1D inhomogeneous lattice gases.

##### File Structure
- Top-level proof modules (.lean):
–  “lean” files that define the model (Hamiltonian, partition functions):
- latticeGasH_K.lean, Z_ED_K.lean, T_local_full.lean, T_prod_full, Z_TM_full, etc.
–  “foundation.lean” and “complete lean file” that pull together the core definitions and proofs.
–  Theorems modules:
- Analyticity of Free Energy…, Exact Nearest-Neighbor…, Equivalence of Partition Function…, Formal Verification of the Transfer Matrix Method…, etc.
- Documentation (.md):
– README.md (project overview, “to-do”)
– paper drafts: Formal Verification…paper.md, Proof Creation Ruleset.md, Proofs simply explained.md
- There is no traditional “frontend/backend,” but rather:
– A **Proof Engine** component (Lean 4 compiler + Mathlib4)
– **Source Modules** (the `.lean` files organized by functionality)
– **Documentation** (the Markdown files)
– **Tooling/CI** (you may add a Lakefile, CI config later)

##### README for Insights
- Key external dependencies:
– Lean 4 proof assistant
– Mathlib4 library
– Gemini-generated proofs
- Workflow: “build these, you get machine-checked proofs → write paper → prepare for submission.”

##### Main Components & Their Interactions
a.  Proof Engine
– Lean 4 compiler + Mathlib4 (external service)
– Inputs: `.lean` modules, Mathlib imports
– Outputs: compiled proof artifacts, error logs, documentation stubs
b.  Core Definition Modules
– Parameter spaces (`FullParamSpace`, `KSpace`, `MuSpace`)
– Hamiltonian & partition functions (`latticeGasH_local_K`, `Z_ED_K`, `Z_TM_full`)
– Transfer Matrix definitions (`T_local_full`, `T_prod_full`)
c.  Theorem Modules
– Equivalence of Partition Functions
– Analyticity of Free Energy
– Thermodynamic Derivative Relations (density, nearest-neighbor correlation)
d.  Documentation & Paper Drafts
– README and Markdown drafts serve as external interface to users and paper authors
e.  Tooling/CI (future)
– Lakefile.toml (Lean project configuration)
– GitHub Actions for building proofs, linting, generating HTML docs

Relationships & Data Flow
– Editors/Users → modify `.lean` and `.md` → invoke Lean 4 build → Proof Engine
– Proof Engine + Mathlib4 → validates definitions & theorems → produces success/failure
– On success → generate documentation pages (via Lean’s doc generator) → publish to GitHub Pages/arXiv supplement
– Documentation authors pull in theorem summaries from the verified code

##### Architectural Patterns & Design Principles
- Modular decomposition by mathematical concept:
– Definitions (model) vs. Methods (ED vs. TM) vs. Theorems (equivalence, analyticity, derivatives) vs. Tools (utils, conversion functions)
- Separation of concerns:
– Pure mathematics code (.lean) vs. human-readable papers (.md)
- Dependency injection via Lean’s import mechanism: each module only depends on the minimal upstream modules + Mathlib4
- Formal-verification pipeline:
– Source → Type-checking → Tactic evaluation → Fully-checked proof

##### Elements
– Proof Engine (Lean 4 + Mathlib4)
– Model Definitions (parameter spaces, Hamiltonian)
– Computational Methods (ED module, TM module)
– Theorem Provers (equivalence, analyticity, derivative theorems)
– Documentation Generation (Lean doc gen, Markdown drafts)
– CI/CD (future)
– Imports/dependencies (which module uses which)
– Build flow (source → compiler → docs)
– Data flow (parameters → proofs → theorems → papers)
– Documentation (.md) in another

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Entities
    Editors["Editors/Users"]:::external
    ProofEngine["Proof Engine<br/>(Lean 4 + Mathlib4)"]:::external
    GitHub["GitHub Pages / Repo"]:::external
    arXiv["arXiv Supplement"]:::external

    %% Core Definitions
    subgraph "Core Definitions" 
        direction TB
        coreComplete["complete lean file"]:::source
        coreGen["completelygeneralized.lean"]:::source
    end

    %% Computational Methods
    subgraph "Computational Methods" 
        direction TB
        compTM["Lean 4 verification for exact transfer matrix.lean"]:::source
    end

    %% Theorem Modules
    subgraph "Theorem Modules"
        direction TB
        theoremAnalyticA["Analyticity of Free Energy and Absence of Sharp Transitions (Finite N).lean"]:::source
        theoremAnalyticR["The Free Energy F_TM is Real Analytic (AnalyticOn ℝ) on the domain where beta > 0.lean"]:::source
        theoremEquiv["Equivalence of Partition Function Calculations for the Inhomogeneous 1D Lattice Gas with Periodic Boundary Conditions.lean"]:::source
        theoremNearest["Exact Nearest-Neighbor Correlation Function via Partition Function Derivatives for the Inhomogeneous 1D Lattice Gas foundation.lean"]:::source
    end

    %% Final Aggregators
    subgraph "Final Theorem Aggregators"
        direction TB
        finalAgg1["Final With Theorem 4.lean"]:::source
        finalAgg2["final.lean"]:::source
    end

    %% Documentation
    subgraph "Documentation & Drafts"
        direction TB
        README["README.md"]:::doc
        paper1["Formal Verification of an Exact Transfer Matrix Solution for the Inhomogeneous 1D Lattice Gas with Periodic Boundary Conditions paper.md"]:::doc
        paper2["Formal Verification of the Transfer Matrix Method and Derived Properties for the Inhomogeneous 1D Lattice Gas with Periodic Boundary Conditions Paper.md"]:::doc
        ruleset["Proof Creation Ruleset.md"]:::doc
        proofsExpl["Proofs simply explained.md"]:::doc
    end

    %% Tooling/CI
    subgraph "Tooling / CI (Future)" 
        direction TB
        Lakefile["Lakefile.toml"]:::future
        Actions["GitHub Actions"]:::future
    end

    %% Relationships
    Editors -->|modify / edit| coreComplete
    Editors -->|modify / edit| coreGen
    Editors -->|modify / edit| compTM
    Editors -->|modify / edit| theoremAnalyticA
    Editors -->|modify / edit| theoremAnalyticR
    Editors -->|modify / edit| theoremEquiv
    Editors -->|modify / edit| theoremNearest
    Editors -->|modify / edit| finalAgg1
    Editors -->|modify / edit| finalAgg2
    Editors -->|modify / edit| README
    Editors -->|modify / edit| paper1
    Editors -->|modify / edit| paper2
    Editors -->|modify / edit| ruleset
    Editors -->|modify / edit| proofsExpl

    coreComplete -.->|imports| compTM
    coreComplete -.->|imports| theoremAnalyticA
    coreComplete -.->|imports| theoremEquiv
    coreComplete -.->|imports| theoremNearest
    coreGen -.->|imports| theoremAnalyticR

    compTM -.->|imports| finalAgg1
    theoremAnalyticA -.->|imports| finalAgg1
    theoremAnalyticR -.->|imports| finalAgg2
    theoremEquiv -.->|imports| finalAgg2
    theoremNearest -.->|imports| finalAgg2

    coreComplete -->|build| ProofEngine
    coreGen -->|build| ProofEngine
    compTM -->|build| ProofEngine
    theoremAnalyticA -->|build| ProofEngine
    theoremAnalyticR -->|build| ProofEngine
    theoremEquiv -->|build| ProofEngine
    theoremNearest -->|build| ProofEngine
    finalAgg1 -->|build| ProofEngine
    finalAgg2 -->|build| ProofEngine

    ProofEngine -->|generates docs| README
    ProofEngine -->|generates docs| paper1
    ProofEngine -->|generates docs| paper2

    ProofEngine -->|publishes| GitHub
    ProofEngine -->|publishes| arXiv

    Lakefile -.->|configures| ProofEngine
    Actions -.->|orchestrates build| ProofEngine

    %% Click Events
    click coreComplete "https://github.com/jazir555/math-proofs/blob/main/complete lean file/final.lean"
    click coreGen "https://github.com/jazir555/math-proofs/blob/main/completelygeneralized.lean"
    click compTM "https://github.com/jazir555/math-proofs/blob/main/Lean 4 verification for exact transfer matrix.lean"
    click theoremAnalyticA "https://github.com/jazir555/math-proofs/blob/main/Analyticity of Free Energy and Absence of Sharp Transitions (Finite N).lean"
    click theoremAnalyticR "https://github.com/jazir555/math-proofs/blob/main/The Free Energy F_TM is Real Analytic (AnalyticOn ℝ) on the domain where beta > 0.lean"
    click theoremEquiv "https://github.com/jazir555/math-proofs/blob/main/Equivalence of Partition Function Calculations for the Inhomogeneous 1D Lattice Gas with Periodic Boundary Conditions.lean"
    click theoremNearest "https://github.com/jazir555/math-proofs/blob/main/Exact Nearest-Neighbor Correlation Function via Partition Function Derivatives for the Inhomogeneous 1D Lattice Gas foundation.lean"
    click finalAgg1 "https://github.com/jazir555/math-proofs/blob/main/Final With Theorem 4.lean"
    click finalAgg2 "https://github.com/jazir555/math-proofs/blob/main/final.lean"
    click README "https://github.com/jazir555/math-proofs/blob/main/README.md"
    click paper1 "https://github.com/jazir555/math-proofs/blob/main/Formal Verification of an Exact Transfer Matrix Solution for the Inhomogeneous 1D Lattice Gas with Periodic Boundary Conditions paper.md"
    click paper2 "https://github.com/jazir555/math-proofs/blob/main/Formal Verification of the Transfer Matrix Method and Derived Properties for the Inhomogeneous 1D Lattice Gas with Periodic Boundary Conditions Paper.md"
    click ruleset "https://github.com/jazir555/math-proofs/blob/main/Proof Creation Ruleset.md"
    click proofsExpl "https://github.com/jazir555/math-proofs/blob/main/Proofs simply explained.md"

    %% Styles
    classDef source fill:#cfe2f3,stroke:#2a5d84,stroke-width:1px
    classDef doc fill:#f9cb9c,stroke:#a65f00,stroke-width:1px
    classDef external fill:#d9ead3,stroke:#38761d,stroke-width:1px,stroke-dasharray: 5 5
    classDef future fill:#f4cccc,stroke:#cc0000,stroke-width:1px,stroke-dasharray: 5 5
```
