# markusorsi/pdga architecture

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

- Interactive diagram: https://gitdiagram.com/markusorsi/pdga
- Repository: https://github.com/markusorsi/pdga

## Overview

##### Project Type and Purpose
- PDGA is a modular genetic algorithm framework focused on peptide design. It uses genetic operators (fitness, selection, crossover, mutation) to iteratively generate peptide sequences with desired properties.
- The README highlights that the project handles building blocks (chemical monomers, N-terminal caps, branches, additional blocks) and modular genetic operators. The design encourages flexibility via interchangeable modules and configuration through CLI.

##### File Structure
- Key Directories/Files:
- bblocks: Contains CSV files with chemical building blocks and the BuildingBlockManager (bbmanager.py) responsible for data loading and sequence translation.
- operators: Contains subdirectories for each type of genetic operator:
▸ crossover: Different crossover implementations (e.g., single point, skip).
▸ fitness: Various fitness functions (e.g., atompair, map4c, mxfp).
▸ mutation: Mutation operators.
▸ selection: Selection strategies (maximize, minimize, randomize).
- config.py: Default configuration settings.
- main.py and pdga.py: Serve as entry points and core implementation of the genetic algorithm.
- utils.py: Implements the ResultsHandler, which manages the output and logging of experimental hits.
- logs and results: Directories for logging experiments and storing output CSVs respectively.
- Architectural Indicators:
- Clear separation of concerns: building blocks handling, genetic operator implementations, configuration, main algorithm core, and results processing.
- Modular design enabling easy swapping of components.

a. Main Components:
- Configuration & CLI: Represented by config.py and command-line argument parsing in main.py.
- Building Block Manager: Module in bblocks (bbmanager.py) that loads CSV files and manages building block data.
- Genetic Algorithm Core (PDGA): Central component (pdga.py) that orchestrates population initialization, iteration across generations, and integration of genetic operators.
▸ Selection (operators/selection)
▸ Fitness Evaluation (operators/fitness)
▸ Crossover (operators/crossover)
▸ Mutation (operators/mutation)
- Results Handler: Shown as the component managed by utils.py, linked to the results directory, responsible for aggregating hit sequences.
- Logging: Represented with the logs folder where experiment logs are stored.

b. Relationships and Interactions:
- The Building Block Manager is called early in the process to load peptide building block data from the CSV files.
- The PDGA core engine then creates an initial population and, for each generation, sequentially uses:
- The selection operator to choose parent candidates.
- Crossover and mutation operators to generate offspring.
- Fitness functions to evaluate each individual’s performance against the target query.
- After each iteration (or at a predefined cutoff), the Results Handler collects sequences that meet the fitness threshold and writes them to CSV files in the results directory.
- Logging of operations occurs throughout and is stored in the logs directory.

c. Architectural Patterns and Design Principles:
- Modularity: Organize genetic operators and building block management as swappable modules.
- Separation of Concerns: Each primary component (data management, genetic operations, output handling) handles a clearly defined responsibility.
- Extensibility: The design supports plugging in new operators or modifying configurations with minimal changes.
- Configuration-Driven: The system is designed to be activated and adapted through both CLI arguments and configuration files (config.py).

d. Technologies and Frameworks:
- Language: Python (version 3.9.5 as indicated by the badge).
- Dependencies: Listed in requirements.txt.
- CSV for data (the building block files) and standard logging mechanisms.
- Basic command-line interface for flexible parameter configuration.

##### Final Advice
- Be very thorough in capturing the interaction between modules.
- Avoid oversimplification – even if the algorithm is iterative and modular, break down each stage (data input, processing, and output) with individual nodes.
- Review the README and file structure to ensure all critical components, such as the modular operators and configuration settings, are included.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Input Layer
    subgraph "Input Layer"
        configCLI["Configuration & CLI"]:::config
        bbmanager["Building Block Manager"]:::data
    end

    %% Process Layer
    subgraph "Process Layer"
        pdga["Genetic Algorithm Core"]:::core
        subgraph "Genetic Operators"
            selection["Selection Operator"]:::operator
            crossover["Crossover Operator"]:::operator
            mutation["Mutation Operator"]:::operator
            fitness["Fitness Evaluation"]:::operator
        end
    end

    %% Output Layer
    subgraph "Output Layer"
        results["Results Handler"]:::output
        logs["Logging"]:::output
    end

    %% Connections
    configCLI -->|"loads"| bbmanager
    configCLI -->|"initiates"| pdga
    bbmanager -->|"supplies data to"| pdga

    pdga -->|"applies"| selection
    pdga -->|"applies"| crossover
    pdga -->|"applies"| mutation
    pdga -->|"applies"| fitness

    pdga -->|"outputs to"| results
    pdga -->|"logs to"| logs

    %% Click Events
    click configCLI "https://github.com/markusorsi/pdga/blob/main/config.py"
    click bbmanager "https://github.com/markusorsi/pdga/blob/main/bblocks/bbmanager.py"
    click pdga "https://github.com/markusorsi/pdga/blob/main/pdga.py"
    click selection "https://github.com/markusorsi/pdga/tree/main/operators/selection/"
    click crossover "https://github.com/markusorsi/pdga/tree/main/operators/crossover/"
    click mutation "https://github.com/markusorsi/pdga/blob/main/operators/mutation/mutations.py"
    click fitness "https://github.com/markusorsi/pdga/tree/main/operators/fitness/"
    click results "https://github.com/markusorsi/pdga/blob/main/utils.py"
    click logs "https://github.com/markusorsi/pdga/tree/main/logs/"

    %% Styles
    classDef config fill:#ffcccc,stroke:#990000,stroke-width:2px;
    classDef data fill:#cce5ff,stroke:#003399,stroke-width:2px;
    classDef core fill:#ccffcc,stroke:#006600,stroke-width:2px;
    classDef operator fill:#fff2cc,stroke:#996600,stroke-width:2px;
    classDef output fill:#e6e6fa,stroke:#6600cc,stroke-width:2px;
```
