# yzeit/mogphh architecture

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

- Interactive diagram: https://gitdiagram.com/yzeit/mogphh
- Repository: https://github.com/yzeit/mogphh

## Overview

##### Project type and purpose
- From the file tree and README, this is not a web‐service or UI application but a research‐oriented algorithmic framework (“MOGPHH”) that evolves multi‐objective dispatching rules using genetic programming hyper‐heuristics (GP‐HH), with surrogate models to speed up fitness evaluation.
- It targets dynamic job shop scheduling experiments, comparing surrogate‐assisted and simulation‐only approaches.

##### File structure
- Top-level scripts:
- main.py – orchestrates 30 runs of the GP‐HH framework
- GPHH.py – defines terminals, functions, GP parameters
- simulation.py – discrete‐event simulation for true fitness
- surrogates.py – implementations of surrogate models (SR, RF, DT, NB)
- phenotypic_generator.py – computes feature vectors for individuals
- testing.py – evaluates final populations on hold‐out instances
- deap/algorithms.py – contains NSGA‐II loops and implementations of 6 experiment algorithms (with/without surrogates, duplicate elimination)
- experiments/ – post‐processing scripts (Experiment1–Experiment5) to generate visualizations (accuracy/time, convergence curves, boxplots, population analyses, testing results)
- LICENSE, README.md – documentation

##### Extract architecture cues from the README
- The README outlines components (“pre‐selection task in NSGA‐II,” phenotypic characterization, surrogate categories) and the data flow: GP evolution → fitness evaluation (simulation or surrogate) → post‐processing → visualization.
- Key external dependencies: DEAP library for GP, machine learning libs (e.g., scikit‐learn) for surrogates.

##### Main components
a. Orchestrator (main.py)
b. GP Engine
– GPHH.py (GP settings, terminals/functions)
– deap/algorithms.py (evolution loop, NSGA‐II)
c. Fitness‐Evaluation Layer
– Simulation Engine (simulation.py)
– Surrogate Module (surrogates.py)
– Phenotypic Feature Generator (phenotypic_generator.py)
d. Evaluation & Testing (testing.py)
e. Experiments & Visualization (experiments/Experiment*.py)
f. External Dependencies
– DEAP
– ML libraries (scikit‐learn)

##### Relationships and data flow
- main.py → invokes one of the six GP‐HH algorithms in deap/algorithms.py
- GP loop (in deap/algorithms.py):
– Population initialization → phenotypic_generator →
– if using surrogate: surrogate.predict(fitness)
– else: simulation.simulate(fitness)
– Selection, crossover, mutation → next generation
– repeat until termination
- Final Pareto set → testing.py → generate performance metrics
- experiments/*.py consume logs and results → generate plots and tables

##### Architectural patterns & principles
- Modular pipeline: clear separation between orchestration, algorithm core, evaluation (simulation vs. surrogate), and post‐processing
- Strategy pattern: interchangeable fitness evaluators (simulation or various surrogates) plugged into the same GP loop
- Single Responsibility: each module handles one concern (GP settings, simulation, surrogate, feature extraction, testing, visualization)

##### Elements
- Blue – Core GP Engine
- Green – Fitness Evaluation (Simulation vs. Surrogate)
- Orange – Feature Extraction (phenotypic)
- Gray – Post‐Processing & Visualization
– Annotations for external dependencies (DEAP, scikit‐learn)

##### Final remarks
- Be very detailed: capture each algorithm variant (WS, SR, RF, RF_dup, DT_dup, NB_dup) as options in the surrogate module.
- Data flows and decision points (surrogate vs. true simulation).
- Use labels and callouts to show key file‐to‐module mappings (e.g., deap/algorithms.py ≡ GP Engine loop).
- This level of granularity ensures that any new engineer can see exactly how each piece of code fits into the overall research pipeline.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Orchestrator
    main["Orchestrator\n(main.py)"]:::orchestrator
    click main "https://github.com/yzeit/mogphh/blob/main/main.py"

    %% GP Engine
    subgraph "GP Engine"
        config["GP Configuration & Operators\n(GPHH.py)"]:::coreGP
        loop["Evolution Loop (NSGA-II & variants)\n(deap/algorithms.py)"]:::coreGP
        click config "https://github.com/yzeit/mogphh/blob/main/GPHH.py"
        click loop "https://github.com/yzeit/mogphh/blob/main/deap/algorithms.py"
    end

    %% Fitness Evaluation
    subgraph "Fitness Evaluation Layer"
        feature["Phenotypic Feature Extraction\n(phenotypic_generator.py)"]:::feature
        simulation["Simulation Engine\n(simulation.py)"]:::fitness
        surrogate["Surrogate Models (SR, RF, DT, NB, dup)\n(surrogates.py)"]:::fitness
        click feature "https://github.com/yzeit/mogphh/blob/main/phenotypic_generator.py"
        click simulation "https://github.com/yzeit/mogphh/blob/main/simulation.py"
        click surrogate "https://github.com/yzeit/mogphh/blob/main/surrogates.py"
    end

    %% Final Population
    final["Final Pareto Population"]:::coreGP

    %% Testing
    test["Evaluation & Testing\n(testing.py)"]:::post
    click test "https://github.com/yzeit/mogphh/blob/main/testing.py"

    %% Experiments & Visualization
    subgraph "Experiments & Visualization"
        exp1["Experiment1:\nAccuracy vs. Time\n(experiments/Experiment1.py)"]:::post
        exp2["Experiment2:\nConvergence Curves\n(experiments/Experiment2.py)"]:::post
        exp3["Experiment3:\nBoxplots\n(experiments/Experiment3.py)"]:::post
        exp4["Experiment4:\nPopulation Analyses\n(experiments/Experiment4.py)"]:::post
        exp5["Experiment5:\nHold-out Testing Results\n(experiments/Experiment5.py)"]:::post
        click exp1 "https://github.com/yzeit/mogphh/blob/main/experiments/Experiment1.py"
        click exp2 "https://github.com/yzeit/mogphh/blob/main/experiments/Experiment2.py"
        click exp3 "https://github.com/yzeit/mogphh/blob/main/experiments/Experiment3.py"
        click exp4 "https://github.com/yzeit/mogphh/blob/main/experiments/Experiment4.py"
        click exp5 "https://github.com/yzeit/mogphh/blob/main/experiments/Experiment5.py"
    end

    %% External Dependencies
    deap["DEAP Library"]:::external
    skl["Scikit-learn\n(ML Libraries)"]:::external

    %% Flows
    main -->|"invoke GP algorithms"| config
    config --> loop
    loop -->|"generate features"| feature
    feature -->|"evaluate via surrogate"| surrogate
    feature -->|"evaluate via simulation"| simulation
    surrogate -->|"fitness results"| loop
    simulation -->|"fitness results"| loop
    loop -->|"final population"| final
    final -->|"evaluate on hold-out"| test
    test -->|"produce results"| exp1
    exp1 --> exp2
    exp2 --> exp3
    exp3 --> exp4
    exp4 --> exp5

    %% Dependencies links
    config --> deap
    loop --> deap
    surrogate --> skl

    %% Styles
    classDef orchestrator fill:#AED6F1,stroke:#1B4F72,color:#1B2631;
    classDef coreGP fill:#85C1E9,stroke:#1B4F72,color:#1B2631;
    classDef fitness fill:#82E0AA,stroke:#1D8348,color:#1B2631;
    classDef feature fill:#F8C471,stroke:#B9770E,color:#1B2631;
    classDef post fill:#D7DBDD,stroke:#566573,color:#1B2631;
    classDef external fill:#F5B7B1,stroke:#922B21,color:#1B2631;
```
