# congiuntivo/pepo architecture

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

- Interactive diagram: https://gitdiagram.com/congiuntivo/pepo
- Repository: https://github.com/congiuntivo/pepo

## Overview

##### Project type and purpose
- This is a command-line, high-performance computing tool written in C that implements the Emperor Penguin Optimization (EPO) metaheuristic.
- It targets parallel execution on distributed (MPI) and shared-memory (OpenMP) environments.
- It produces CSV logs of optimization runs and ships with Python plotting scripts and a LaTeX report.

##### File structure
- Top level
- main.c: entry point, MPI/OpenMP initialization, calls into the library
- Makefile: build rules (`make run`, `make clean`)
- README.md: description, usage, algorithm background
- .gitignore
- lib/
- cli.{c,h}: command-line parsing
- agent.{c,h}: represents a solution candidate (position, fitness)
- space.{c,h}: holds the population, search bounds
- epo.{c,h}: core EPO algorithm logic (movement, huddle, temperature)
- f_functions.{c,h}: benchmark fitness functions
- csv.{c,h}: CSV logging of iteration data
- utils.{c,h}: RNG, math helpers
- plots/: Python scripts to read CSV output and generate graphs
- report/: LaTeX files to build a written report of experiments
- visual.py: possibly a Python helper for plotting/visualization

##### README for additional insights
- Describes algorithm phases: huddle formation, temperature, distance, mover selection
- Shows social force equation and behavior plots
- Details MPI + OpenMP parallel execution examples
- Lists CLI flags and their meanings

##### Detail
- Key files and their responsibilities so no component is omitted.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Layer 1: User & CLI
    User["User"]:::external
    CLI["CLI & Configuration Loader\n(lib/cli.c/h)"]:::io
    User -->|"invokes"| CLI

    %% Layer 2: Runtime
    CLI -->|"executes"| RuntimeInit
    RuntimeInit["MPI & OpenMP Initialization\n(main.c)"]:::runtime
    click RuntimeInit "https://github.com/congiuntivo/pepo/blob/main/main.c"

    subgraph "MPI Domain" style dashed
        subgraph "MPI Process" 
            direction TB
            ThreadPool["OpenMP Thread Pool"]:::runtime
            ThreadPool --> Thread1["Thread"]:::runtime
            ThreadPool --> Thread2["Thread"]:::runtime
            ThreadPool --> Thread3["Thread"]:::runtime
        end
    end
    RuntimeInit -->|"spawns processes/threads"| ThreadPool

    %% Layer 3: Core Modules
    subgraph "Core Modules"
        direction TB
        EPO["EPO Core Engine\n(lib/epo.c/h)"]:::compute
        Agent["Agent Representation\n(lib/agent.c/h)"]:::compute
        Space["Search Space & Population\n(lib/space.c/h)"]:::compute
        Fitness["Fitness Function Module\n(lib/f_functions.c/h)"]:::compute
        Utils["Utility Helpers\n(lib/utils.c/h)"]:::compute
        CSV["CSV Logger\n(lib/csv.c/h)"]:::io
    end

    ThreadPool -->|starts| EPO
    EPO -->|"uses"| Agent
    EPO -->|"uses"| Space
    EPO -->|"calculates"| Fitness
    EPO -->|"calls RNG/math"| Utils
    EPO -->|"logs iteration stats"| CSV

    Fitness -->|"returns fitness values"| EPO

    %% Layer 4: Post-Processing
    subgraph "Post-Processing"
        direction TB
        AccPlot["accuracy.py"]:::io
        NodesPlot["nodes_parallelization_metrics.py"]:::io
        ThreadsPlot["threads_parallelization_metrics.py"]:::io
        Visual["visual.py"]:::io
        Results["Plot Results Directory\n(plots/results/)"]:::io
        Report["LaTeX Report Generator\n(report/)"]:::io
    end

    CSV -->|"writes CSV"| Results
    Results -->|"read by"| AccPlot
    Results -->|"read by"| NodesPlot
    Results -->|"read by"| ThreadsPlot
    Results -->|"read by"| Visual
    AccPlot --> Report
    NodesPlot --> Report
    ThreadsPlot --> Report
    Visual --> Report

    %% Click Events
    click CLI "https://github.com/congiuntivo/pepo/blob/main/lib/cli.c"
    click EPO "https://github.com/congiuntivo/pepo/blob/main/lib/epo.c"
    click Agent "https://github.com/congiuntivo/pepo/blob/main/lib/agent.c"
    click Space "https://github.com/congiuntivo/pepo/blob/main/lib/space.c"
    click Fitness "https://github.com/congiuntivo/pepo/blob/main/lib/f_functions.c"
    click Utils "https://github.com/congiuntivo/pepo/blob/main/lib/utils.c"
    click CSV "https://github.com/congiuntivo/pepo/blob/main/lib/csv.c"
    click AccPlot "https://github.com/congiuntivo/pepo/blob/main/plots/accuracy.py"
    click NodesPlot "https://github.com/congiuntivo/pepo/blob/main/plots/nodes_parallelization_metrics.py"
    click ThreadsPlot "https://github.com/congiuntivo/pepo/blob/main/plots/threads_parallelization_metrics.py"
    click Visual "https://github.com/congiuntivo/pepo/blob/main/visual.py"
    click Results "https://github.com/congiuntivo/pepo/tree/main/plots/results/"
    click Report "https://github.com/congiuntivo/pepo/tree/main/report/Makefile"

    %% Styles
    classDef compute fill:#ADD8E6,stroke:#000;
    classDef io fill:#90EE90,stroke:#000;
    classDef runtime fill:#FFA500,stroke:#000;
    classDef external fill:#CCCCCC,stroke:#000;
```
