How google-deepmind/alphageometry works
Project type and purpose
• This is a research‐quality, CLI-driven Python application that implements two geometry theorem provers—DDAR (a purely symbolic Depth-Difference + Angle-Razor solver) and AlphaGeometry (a hybrid symbolic + transformer-based solver).
• It reads geometry problems from text files, constructs a proof state graph, attempts a symbolic proof (DDAR), and—if that fails—invokes a transformer language model to propose new auxiliary constructions, feeding them back into the symbolic engine until the proof is found or resources are exhausted.
Key components (based on file structure and README)
A. CLI / Orchestration
• alphageometry.py: main entrypoint.
• run.sh, download.sh, run_tests.sh: automation scripts.
B. Configuration
• Gin config files (e.g., geometry_150M_generate.gin) + gin-config library.
• defs.txt, rules.txt: symbolic-engine definitions and deduction rules.
C. Input layer
• problem.py, examples.txt, imo_ag_30.txt, jgex_ag_231.txt: problem loading and parsing.
D. Symbolic engine
• graph.py + graph_utils.py: build and manipulate proof‐state graphs.
• geometry.py, numericals.py: geometry primitives and numeric reasoning.
• dd.py, ar.py, trace_back.py: DD and AR algorithms and traceback.
• ddar.py: orchestrates DD+AR.
• pretty.py: formats and prints proofs.
E. ML engine
• transformer_layer.py, decoder_stack.py, models.py: defines the Transformer model in Flax/JAX.
• lm_inference.py: tokenization (SentencePiece) and LM interface.
• beam_search.py: beam-search decoding logic.
F. External dependencies
• Meliad library (external git subtree).
• JAX, Flax, Abseil, NumPy, SciPy, TensorFlow, SentencePiece, Gin.
G. Data artifacts
• Model checkpoint & vocabulary (downloaded via download.sh).
• defs.txt, rules.txt, gin files.
Relationships & data flow
1. User invokes “python -m alphageometry …” (or run.sh).
2. The CLI loads Gin configs + flags, reads the problem file.
3. problem.py → graph_utils.py → graph.py: builds the initial proof state graph.
4. Call ddar.py (DD+AR) with defs.txt & rules.txt:
– If a proof is found, pretty.py formats & prints it.
– Else, in “alphageometry” mode:
a. Export current graph state into a linearized input.
b. lm_inference.py + beam_search.py invokes the Transformer (models.py) to propose k auxiliary constructions.
c. Parse LM output back into symbolic construction actions.
d. Append these constructions to the graph and re-invoke ddar.py.
e. Repeat until success or search limits reached.
5. Final output is printed or saved to file.
Architectural patterns & principles
• Layered modular design:
• CLI/Orchestrator layer
• Configuration layer (Gin)
• Core symbolic‐reasoning layer
• ML inference layer
• Data/resource layer
• Clear separation of concerns: symbolic vs ML code, representation vs algorithms, config vs implementation.
• Extensibility points: can plug in different search strategies (beam size, depth, DD/AR), or swap in alternative LM checkpoints.