# timcrose/gator architecture

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

- Interactive diagram: https://gitdiagram.com/timcrose/gator
- Repository: https://github.com/timcrose/gator

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Controller Layer"
        Master["GAtor_master.py"]:::orchestration
        WorkerEntry["run_GA_mpi.py"]:::orchestration
    end

    subgraph "Core I/O & Config"
        CheckConf["check_conf.py"]:::orchestration
        UserInput["user_input.py"]:::orchestration
        FileHandler["file_handler.py"]:::orchestration
        Output["output.py"]:::orchestration
        DataTools["data_tools.py"]:::orchestration
        DefaultConf["default.conf"]:::orchestration
    end

    subgraph "GA Worker Pipeline"
        InitPool["Initial Pool Generator"]:::plugins
        Selection["Selection Plugins"]:::plugins
        Crossover["Crossover Plugins"]:::plugins
        Mutation["Mutation Plugins"]:::plugins
        Optimization["Optimization (FHI-AIMS)"]:::external
    end

    subgraph "Data Models"
        Structure["structure.py"]:::data
        Collection["structure_collection.py"]:::data
        Handling["structure_handling.py"]:::data
    end

    subgraph "Analysis Modules"
        Clustering["cluster.py"]:::orchestration
        Comparison["structure_comparison.py"]:::orchestration
    end

    subgraph "Utilities & External Libraries"
        ExternalLibs["external_libs"]:::external
        Utilities["utilities"]:::external
    end

    subgraph "External Services"
        MPI["MPI Runtime"]:::external
        FHIAIMS["FHI-AIMS via mpi4py"]:::external
    end

    Master -->|spawn ranks| WorkerEntry
    WorkerEntry -->|load config| UserInput
    UserInput --> CheckConf
    WorkerEntry --> InitPool
    InitPool --> Selection
    Selection --> Crossover
    Crossover --> Mutation
    Mutation --> Optimization
    Optimization --> Clustering
    Clustering --> Comparison
    Comparison --> Output
    FileHandler --> InitPool
    FileHandler --> Output
    DataTools --> WorkerEntry
    Structure --> Optimization
    Structure --> Clustering
    Utilities --> WorkerEntry
    ExternalLibs --> WorkerEntry
    MPI --> Master
    FHIAIMS --> Optimization

    click Master "https://github.com/timcrose/gator/blob/gator_python3_mpi/src/GAtor_master.py"
    click WorkerEntry "https://github.com/timcrose/gator/blob/gator_python3_mpi/src/core/run_GA_mpi.py"
    click InitPool "https://github.com/timcrose/gator/tree/gator_python3_mpi/src/initial_pool/"
    click Selection "https://github.com/timcrose/gator/tree/gator_python3_mpi/src/selection/"
    click Crossover "https://github.com/timcrose/gator/tree/gator_python3_mpi/src/crossover/"
    click Mutation "https://github.com/timcrose/gator/tree/gator_python3_mpi/src/mutation/"
    click Optimization "https://github.com/timcrose/gator/blob/gator_python3_mpi/src/optimization/FHI_aims_mpi4py.py"
    click CheckConf "https://github.com/timcrose/gator/blob/gator_python3_mpi/src/core/check_conf.py"
    click UserInput "https://github.com/timcrose/gator/blob/gator_python3_mpi/src/core/user_input.py"
    click FileHandler "https://github.com/timcrose/gator/blob/gator_python3_mpi/src/core/file_handler.py"
    click Output "https://github.com/timcrose/gator/blob/gator_python3_mpi/src/core/output.py"
    click DataTools "https://github.com/timcrose/gator/blob/gator_python3_mpi/src/core/data_tools.py"
    click DefaultConf "https://github.com/timcrose/gator/blob/gator_python3_mpi/src/core/default.conf"
    click Structure "https://github.com/timcrose/gator/blob/gator_python3_mpi/src/structures/structure.py"
    click Collection "https://github.com/timcrose/gator/blob/gator_python3_mpi/src/structures/structure_collection.py"
    click Handling "https://github.com/timcrose/gator/blob/gator_python3_mpi/src/structures/structure_handling.py"
    click Clustering "https://github.com/timcrose/gator/blob/gator_python3_mpi/src/clustering/cluster.py"
    click Comparison "https://github.com/timcrose/gator/blob/gator_python3_mpi/src/comparison/structure_comparison.py"
    click ExternalLibs "https://github.com/timcrose/gator/tree/gator_python3_mpi/src/external_libs/"
    click Utilities "https://github.com/timcrose/gator/tree/gator_python3_mpi/src/utilities/"

    classDef orchestration fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef plugins fill:#90EE90,stroke:#000,stroke-width:1px
    classDef data fill:#FFD580,stroke:#000,stroke-width:1px
    classDef external fill:#DDA0DD,stroke:#000,stroke-width:1px
```
