# andreastocco01/or2 architecture

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

- Interactive diagram: https://gitdiagram.com/andreastocco01/or2
- Repository: https://github.com/andreastocco01/or2

## Overview

- Core Execution Module: Represented by main.c, which likely orchestrates the overall execution.
- TSP variants (tsp.c, tsp_greedy.c, tsp_diving.c, tsp_tabu.c, tsp_vns.c, tsp_localbranching.c, tsp_cplex.c)
- Mincut (mincut.c) and other optimization related modules like eventlog.c, chrono.c, util.c.
- Experiment and Results Management: The “runs” directory, where output files (for exact, mathematical, and other experiments) are stored.
- Tools: The “tools” directory (Python scripts like experiment.py, finalrun.sh, plot.py, etc.) which handle running experiments, profiling, and processing results.
- Configuration & Meta Information: The README and Makefile that guide experiment configurations (with hyperparameter settings indicated in the README e.g., config 0, 1, etc.).

##### Relationships and Data Flow
- Algorithm modules to the “Utility” components (chrono, eventlog, and util) which provide common functionality.
- That these modules output experiment data (results, logs) into the “runs” directory.
- That the “tools” (Python scripts) process the data from “runs” to generate plots, perform profiling, and possibly refine experiments.

##### Architectural Patterns and Design Principles
- Modularity: Each heuristic and algorithm is implemented in a separate module which not only supports comparative experimentation (as suggested by the hyperparameter tuning configurations) but also facilitates experimenting with different approaches.
- Separation of Concerns: The separation between the computational core (C modules for algorithms), experiment orchestration/analysis tools (Python scripts), and documentation (LaTeX files) should be clearly exposed.
- Experiment Management Flow: Include the “configuration” aspect (tuning parameters provided in the README) and illustrate how different configurations map to different experimental outcomes. This side-by-side comparison is central to the thesis research.

##### Specific Technologies and Tools
- That the project uses C for implementing heuristics and other computation-heavy components.
- Python is used as a support tool for experiments and analysis.
- LaTeX is an integral part of the reporting/documentation process.
- There is integration with CPLEX (as seen in tsp_cplex.c/h) indicating that some exact methods rely on external optimization libraries.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Configuration & Meta"
        readme["README.md"]:::config
        makefile["Makefile"]:::config
    end

    subgraph "Core Execution"
        mainExec["Core Execution (main.c)"]:::c_source
    end

    subgraph "Algorithm Modules"
        tsp["TSP (tsp.c)"]:::c_source
        tspGreedy["TSP Greedy (tsp_greedy.c)"]:::c_source
        tspDiving["TSP Diving (tsp_diving.c)"]:::c_source
        tspTabu["TSP Tabu (tsp_tabu.c)"]:::c_source
        tspVNS["TSP VNS (tsp_vns.c)"]:::c_source
        tspLocal["TSP Local Branching (tsp_localbranching.c)"]:::c_source
        tspCPLEX["TSP CPLEX (tsp_cplex.c)"]:::c_source
        mincut["Mincut (mincut.c)"]:::c_source
    end

    subgraph "Utility Modules"
        chrono["Chrono (chrono.c)"]:::c_source
        eventlog["Eventlog (eventlog.c)"]:::c_source
        util["Util (util.c)"]:::c_source
    end

    experiments["Experiment Data (runs/)"]:::experiment
    tools["Analysis Tools (tools/)"]:::python
    docs["Reporting (LaTeX)"]:::docs

    readme --> mainExec
    makefile --> mainExec

    mainExec -->|"triggers"| tsp
    mainExec -->|"triggers"| tspGreedy
    mainExec -->|"triggers"| tspDiving
    mainExec -->|"triggers"| tspTabu
    mainExec -->|"triggers"| tspVNS
    mainExec -->|"triggers"| tspLocal
    mainExec -->|"triggers"| tspCPLEX
    mainExec -->|"triggers"| mincut

    tsp -->|"uses"| chrono
    tsp -->|"uses"| eventlog
    tsp -->|"uses"| util
    mincut -->|"uses"| chrono
    mincut -->|"uses"| eventlog
    mincut -->|"uses"| util

    tsp -->|"outputs"| experiments
    mincut -->|"outputs"| experiments

    experiments -->|"processed_by"| tools
    tools -->|"feeds"| docs

    click mainExec "https://github.com/andreastocco01/or2/blob/main/main.c"
    click tsp "https://github.com/andreastocco01/or2/blob/main/tsp.c"
    click tspGreedy "https://github.com/andreastocco01/or2/blob/main/tsp_greedy.c"
    click tspDiving "https://github.com/andreastocco01/or2/blob/main/tsp_diving.c"
    click tspTabu "https://github.com/andreastocco01/or2/blob/main/tsp_tabu.c"
    click tspVNS "https://github.com/andreastocco01/or2/blob/main/tsp_vns.c"
    click tspLocal "https://github.com/andreastocco01/or2/blob/main/tsp_localbranching.c"
    click tspCPLEX "https://github.com/andreastocco01/or2/blob/main/tsp_cplex.c"
    click mincut "https://github.com/andreastocco01/or2/blob/main/mincut.c"
    click chrono "https://github.com/andreastocco01/or2/blob/main/chrono.c"
    click eventlog "https://github.com/andreastocco01/or2/blob/main/eventlog.c"
    click util "https://github.com/andreastocco01/or2/blob/main/util.c"
    click experiments "https://github.com/andreastocco01/or2/tree/main/runs/"
    click tools "https://github.com/andreastocco01/or2/tree/main/tools/"
    click docs "https://github.com/andreastocco01/or2/tree/main/latex/"
    click readme "https://github.com/andreastocco01/or2/blob/main/README.md"
    click makefile "https://github.com/andreastocco01/or2/tree/main/Makefile"

    classDef c_source fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef experiment fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef python fill:#FFCC99,stroke:#000,stroke-width:1px;
    classDef docs fill:#FF9999,stroke:#000,stroke-width:1px;
    classDef config fill:#DCDCDC,stroke:#000,stroke-width:1px;
```
