How teorth/equational_theories works
Main Components
• Core Formal Verification Engine – The Lean files (found under “equational_theories”, “Generated”, and related Lean source files). This is where the formal definitions, theorems, and verification proofs are developed using Lean and built via Lake.
• Data Management & Storage – The “data” directory holds raw inputs (edge lists, outcomes, CSV/JSON files), forcing rules, dual equations, and lists of magmas and equations. This component is the seed for the graph of implications.
• Scripted Processing & Analysis – The “scripts” folder contains many scripts (in Python, Ruby, etc.) that:
– Process implications extracted from Lean (e.g. extract_implications, process_implications)
– Explore magma structures (explore_magma, gather_small_magmas)
– Generate visualizations and graphs (generate_image, generate_graphviz_graph, transitive_reduction)
– Interface with external automated provers (Z3, Prover9/Mace4, Vampire, etc.)
• Document & Blueprint Components – The “blueprint” and “paper” directories hold LaTeX source files that document the theory, results, and overall research narrative.
• Web Front–Ends & Visualization – Directories like “home_page”, “widget”, “tools/fme”, and “graphiti” provide interactive dashboards, equation explorers, graph visualizations, and finite magma explorers. These components transform processed data and proof outcomes into visual and interactive formats.
• Miscellaneous Supporting Elements – Commentary (notes on individual equations in Markdown), GitHub configurations (workflows, CI/CD), and configuration files (lakefile.toml, flake.nix) which support integration and collaborative development.
Relationships & Data Flow
– Data originates from the “data” directory and/or is generated by manual input. Processing scripts extract, analyze, and transform this data.
– The Lean proofs (and the Generated directory) are continuously updated based on both human-written formalizations and results produced by automated scripts.
– Communication between these areas is orchestrated by automated tasks (in “scripts”) and integrated workflows (GitHub Actions and documented CI scripts).
– External dependencies (e.g. interactive theorem provers, external solvers like Z3) play a role in validating or refuting proposed implications, and their results are then reintegrated into the project’s Lean code base and visualization tools.
Architectural Patterns & Design Principles
– Modularity is central: separate directories for formal proofs, data, scripts, documentation, and web UX keep concerns distinct.
– There is a pipeline-like data flow: raw data → processing scripts → Lean verification → generation of derived artifacts → web-based dashboards.
– Emphasis on reproducibility and automation is evident with continuous integration workflows and automated updates (e.g., “update-dependencies.yml”, “update-labels.yml”).
– Multiple languages work together: Lean for theorem proving, Python and Ruby for scripting and data manipulation, LaTeX for scholarly documents, and Elm/TypeScript for visualization.
Relevant Technologies, Frameworks, and Libraries
– Lean (via lake build) for formal proofs and validation.
– Python/Ruby for scripting tasks (data extraction, transitive closure, graph generation).
– LaTeX (with accompanying .sty files and chapter files) for the paper/blueprint.
– Web technologies: HTML, CSS/SCSS, Elm, TypeScript/React (for the widget) to provide interactive interfaces.
– External theorem provers (Z3, Prover9/Mace4, Vampire) interfaced through scripts.
– GitHub Actions and Nix/flake for build automation and dependency management.