# singularitty/genetic-algorithm-structure-prediction architecture

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

- Interactive diagram: https://gitdiagram.com/singularitty/genetic-algorithm-structure-prediction
- Repository: https://github.com/singularitty/genetic-algorithm-structure-prediction

## Overview

##### Project type and purpose
- This is an open-source, command-line Python tool that uses a genetic algorithm (GA) to predict equilibrium crystal structures in 2D for a user-specified potential. It’s not a full-stack app but a scientific computation/algorithm library with pluggable potential models and optional parallel execution.

##### File structure
- Top-level:
- “Genetic Algorithm/” directory containing core modules.
- LICENSE and README.md.
- Inside “Genetic Algorithm/”:
- GA.py – serial GA driver
- GA_Parallel.py (mentioned in README; if present, this is the parallel driver)
- Structure.py – data structures and representation for crystal configurations
- daoud_cotton_model.py – current potential implementation (fitness function)
- settings.py – central configuration (GA parameters, potential selection, parallel flags)

##### README for additional insights
- Purpose: predict ground-state (GS) structures for a given potential.
- Extensible: swap or add potential modules by dropping new “*.py” into the folder and selecting it in settings.py.
- Two modes: serial (GA.py) and parallel (GA_Parallel.py).

a. Main components:
- Configuration (settings.py)
- GA Engine (GA.py / GA_Parallel.py)
- Data Model (Structure.py)
- Potential Modules (daoud_cotton_model.py + future plugins)
- Parallelization Layer (multiprocessing wrapper in GA_Parallel.py)
- Output/Reporting (final structure files, logs, console output)
b. Relationships & interactions:
1. User edits settings.py → defines GA parameters, selects potential, toggles parallel flag.
2. Main driver (GA.py or GA_Parallel.py) reads settings → initializes the GA Engine.
3. GA Engine uses Structure.py to generate and mutate candidate configurations.
4. For each candidate, the Engine calls the selected potential module to compute fitness.
5. In parallel mode, evaluations are forked to worker processes (via Python’s multiprocessing).
6. Results flow back to the GA Engine (selection, crossover, mutation).
7. After termination, Engine writes output structures and logs.
c. Architectural patterns & principles:
- Modular separation: core GA logic vs. potential implementations vs. configuration.
- Plugin pattern for potentials: drop-in fitness modules.
- Strategy pattern: interchangeable fitness evaluation.
- Optionally parallel execution via process pool.
d. Key technologies & libraries:
- Python 3.x
- multiprocessing (for GA_Parallel.py)
- Standard library modules (os, sys, argparse if used)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Configuration
    subgraph "Configuration Layer"
        ConfigurationNode["Configuration\n(settings.py)"]:::config
    end

    %% GA Engine
    subgraph "GA Engine"
        GAEngineSerial["GA.py\n(Serial Driver)"]:::engine
        GAEngineParallel["GA_Parallel.py\n(Parallel Driver)"]:::engine
    end

    %% Data Model
    DataModel["Structure.py\n(Data Model)"]:::model

    %% Potential Modules
    subgraph "Potential Modules (Plugin)"
        DaoudModule["daoud_cotton_model.py\n(Current Potential)"]:::plugin
        PotentialExt["<Add new potential plugin>"]:::plugin
    end

    %% Parallelization Layer
    ParallelLayer["Multiprocessing Pool\n(GA_Parallel)"]:::parallel

    %% Output / Reporting
    Output["Output & Reporting\n(structure files, logs)"]:::output

    %% Documentation
    subgraph "Project Documentation"
        README["README.md"]:::doc
        LICENSE["LICENSE"]:::doc
    end

    %% Connections
    ConfigurationNode -->|"reads settings"| GAEngineSerial
    ConfigurationNode -->|"reads settings"| GAEngineParallel

    GAEngineSerial -->|"uses Structure model"| DataModel
    GAEngineParallel -->|"uses Structure model"| DataModel
    DataModel -->|"population data"| GAEngineSerial
    DataModel -->|"population data"| GAEngineParallel

    GAEngineSerial -->|"calls fitness"| DaoudModule
    GAEngineParallel -->|"calls fitness"| DaoudModule
    DaoudModule -->|"fitness score"| GAEngineSerial
    DaoudModule -->|"fitness score"| GAEngineParallel

    GAEngineParallel -->|"forks evaluations"| ParallelLayer
    ParallelLayer -->|"worker results"| GAEngineParallel

    GAEngineSerial -->|"writes results"| Output
    GAEngineParallel -->|"writes results"| Output

    %% Click Events
    click ConfigurationNode "https://github.com/singularitty/genetic-algorithm-structure-prediction/blob/main/Genetic Algorithm/settings.py"
    click GAEngineSerial "https://github.com/singularitty/genetic-algorithm-structure-prediction/blob/main/Genetic Algorithm/GA.py"
    click DataModel "https://github.com/singularitty/genetic-algorithm-structure-prediction/blob/main/Genetic Algorithm/Structure.py"
    click DaoudModule "https://github.com/singularitty/genetic-algorithm-structure-prediction/blob/main/Genetic Algorithm/daoud_cotton_model.py"
    click README "https://github.com/singularitty/genetic-algorithm-structure-prediction/blob/main/README.md"
    click LICENSE "https://github.com/singularitty/genetic-algorithm-structure-prediction/tree/main/LICENSE"

    %% Styles
    classDef config fill:#e0ffe0,stroke:#006600
    classDef engine fill:#cce0ff,stroke:#003399
    classDef model fill:#cce0ff,stroke:#003399
    classDef plugin fill:#ffe0cc,stroke:#cc6600
    classDef parallel fill:#e0ccff,stroke:#660099
    classDef output fill:#ffffcc,stroke:#999900
    classDef doc fill:#f2f2f2,stroke:#666666
```
