How timcrose/gator works
Project type and purpose
• GAtor is a command-line, high-performance scientific application implementing a genetic-algorithm pipeline for molecular crystal structure prediction.
• It is written in Python 2.7, uses MPI for parallel replicas, and relies on numpy, pymatgen, and scikit-learn.
File structure
Top‐level:
• src/ ← all source modules
• tutorial/ ← example inputs, run‐scripts, configs
• GAtor_Documentation_Manual.pdf, README, LICENSE
src/ submodules:
• GAtor_master.py ← MPI master entry point
• core/ ← orchestration: configuration, I/O, GA driver
– run_GA_mpi.py ← per‐process GA main loop
– user_input.py ← parse control files
– file_handler.py, output.py
– check_conf.py, data_tools.py
• initial_pool/ ← generate initial population
• selection/ ← parent selection strategies (roulette, tournament)
• crossover/ ← recombination operators
• mutation/ ← mutation operators
• optimization/ ← energy evaluation wrapper (e.g. FHI-AIMS via mpi4py)
• clustering/ ← cluster analysis of structures
• comparison/ ← structure‐to‐structure comparison
• structures/ ← data models for crystal structures
• utilities/ ← descriptors, parsers, debug, external_libs/ for third-party helpers
Readme insights
• Master script launches N parallel replicas.
• Each replica runs run_GA: input→pool initialization→selection→crossover/mutation→energy evaluation→clustering/comparison→output.
• Modules are swappable plugins: easy to extend new mutation or crossover strategies.
Main components
a. Controller layer:
• GAtor_master.py (MPI coordinator)
• core/run_GA_mpi.py
b. GA engine (per replica):
• core/run_GA.py
• initial_pool
• selection
• crossover
• mutation
• optimization (external FHI-AIMS)
c. Data models & I/O:
• structures/*
• core/file_handler.py, output.py
• core/user_input.py
d. Analysis modules:
• clustering
• comparison
e. External services:
• MPI runtime / cluster scheduler (submit_MPI_theta.sh etc.)
• FHI-AIMS via mpi4py (in optimization)
• Python ecosystem (numpy, pymatgen, scikit-learn)
Relationships & data flow
• GAtor_master.py spawns MPI ranks → each rank executes run_GA_mpi → read user_input → initial_pool → loop: selection→crossover/mutation → pass candidates to optimization → receive energy & properties → clustering/comparison for convergence → write outputs.
• Data flows from disk (control.in, initial JSON pool) → memory structures → compute modules → back to disk.
• Cross‐rank communication only at master level for work distribution; replicas work independently.
Architectural patterns & design principles
• Modular “plugin” architecture for GA operators (mutation, crossover, selection)
• Pipeline pattern: clear stages with pluggable components
• Master/worker pattern via MPI for parallel replicas
• Separation of concerns: I/O, data models, GA logic, optimizers, analysis
Technologies & frameworks to annotate
• Python 2.7 runtime
• MPI (via mpi4py in run_GA_mpi and optimization)
• numpy, pymatgen, scikit-learn
• External FHI-AIMS code invoked through optimization wrapper
Detail without over‐breaking
• I/O and configuration loads at the start, and outputs at the end