# lucasgabriel-cp/tcc architecture

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

- Interactive diagram: https://gitdiagram.com/lucasgabriel-cp/tcc
- Repository: https://github.com/lucasgabriel-cp/tcc

## Overview

##### Project type and purpose
- The README shows the title “TCC” ("Trem de Comer Cedo"), which appears to be a specific application (possibly a research or academic project) in which the objective is to solve complex optimization problems.
- The project is split between an “exact model” and “metaheuristics” approaches. This indicates that the system is designed to compare or integrate both an exact optimization method (using Gurobi via Python) and various heuristic/metaheuristic algorithms (implemented in C++).

##### File structure
- At the top level, there are two main directories: “exact_model” and “metaheuristics.”
- The “exact_model” folder contains Python files:
- gurobi_opt.py – likely orchestrating the optimization using Gurobi.
- instance_vars.py and optimization.py – possibly setting up the mathematical model.
- A configuration folder “gurobi_conf” indicating that configuration files for Gurobi are maintained separately.
- A results file (results_LKM.txt) for output from the optimization process.
- The “metaheuristics” folder includes C++ source files and a Makefile:
- Several runner files (ga_runner.cpp, hibrid_runner.cpp, ts_runner.cpp, vns_runner.cpp) denote that different metaheuristic strategies (genetic algorithm, tabu search, variable neighborhood search, and a hybrid approach) are implemented.
- Additional source files (genetic_algorithm.cpp, individuo.cpp, initial_solution.cpp, neighbor.cpp) and utility implementations (Constants.cpp, DebugTemplate.cpp, segtree.cpp, string_hash.cpp).
- A “problems” subfolder with leasing.cpp suggests example problem definitions for the metaheuristic algorithms.
- A shell script (script.sh) likely assists in running or compiling components.
- No traditional “frontend” or “database” components are present; the focus here is algorithmic optimization.

a. Main components:
- Exact Optimization Module: This encompasses the Python scripts under “exact_model” plus its Gurobi configuration. It is responsible for solving the optimization exactly using a solver.
- Metaheuristics Module: This includes the multiple C++ implementations of different heuristics (Genetic Algorithm, Hybrid, Tabu Search, VNS, etc.) provided in “metaheuristics”.
- Shared Problem Instance: There is likely a common problem definition or data file that is used as input for both the exact model and the metaheuristics. Although the file tree does not explicitly include a “data” directory, the presence of “instance_vars.py” and “problems/leasing.cpp” hints at a shared problem abstraction.
- (Optional) External Dependencies: Gurobi solver for the exact model. The C++ module might depend on standard libraries or custom libraries compiled using the Makefile.

b. Relationships and interactions:
- Both modules receive the same problem instance(s) or parameter settings.
- The exact model module calls out to the Gurobi solver (either via a direct API in gurobi_opt.py or via configuration files) to return an optimal solution.
- The metaheuristics module, which is compiled via its Makefile and executed using provided runner scripts, produces approximate solutions.
- There might be a higher-level orchestration or benchmarking mechanism (possibly executed through external scripts/sequencing) that compares the outcomes from both approaches.

c. Architectural patterns:
- Separation of Concerns: The two modules (exact vs. heuristic) are separated to allow independent development and testing.
- Modular Design: Each metaheuristic algorithm is implemented in its own runner file and helper modules, while the exact model consolidates configuration and logic in Python, showing a clean division of responsibilities.
- Integration via Common Interfaces: Both methods target the same underlying problem instance, which is abstracted to allow algorithmic comparisons (benchmarking).

d. Relevant technologies:
- Python and Gurobi: Used in the exact optimization pipeline.
- C++ (with a Makefile for build automation): Used for the metaheuristic implementations.
- Shell scripting may be used for launching or automating execution.
- The design should note that configuration files (in gurobi_conf) influence the behavior of the exact model.

- Use clear labels for every component (e.g., “Gurobi Solver”, “Python Optimization Code”, “C++ GA Module”, “C++ Tabu Search Module”).
- From “Problem Instance” to both “Exact Optimization Module” and “Metaheuristics Module.”
- From “Exact Optimization Module” to “Gurobi Solver” (denoting API/configuration flow).
- From each metaheuristic sub-component to a collective “Solution Output” or “Benchmarking Interface.”
- Rectangles for software modules.
- Configuration files and build scripts as auxiliary nodes to hint at how modules are deployed or compiled.

##### Detail and modular separation
- As the principal software engineer, include as many detailed components as possible: break down the metaheuristics into their individual strategies, highlight the exact model’s dependency on Gurobi, and illustrate the overall data flow from problem definition to solution output.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Shared Problem Instance
    sp1["Problem Instance (leasing.cpp)"]:::shared

    %% Exact Optimization Module Subgraph
    subgraph "Exact Optimization Module"
        eo2["Instance Variables (instance_vars.py)"]:::python
        eo3["Optimization Logic (optimization.py)"]:::python
        eo1["Optimization Script (gurobi_opt.py)"]:::python
        eo4["Gurobi Configuration (gurobi_conf)"]:::python
        eo5["Result Output (results_LKM.txt)"]:::python
    end

    %% External Dependency: Gurobi Solver
    ext1["Gurobi Solver"]:::external

    %% Metaheuristics Module Subgraph
    subgraph "Metaheuristics Module"
        mh1["Genetic Algorithm Runner (ga_runner.cpp)"]:::cpp
        mh2["Genetic Algorithm Core (genetic_algorithm.cpp)"]:::cpp
        mh3["Hybrid Runner (hibrid_runner.cpp)"]:::cpp
        mh4["Tabu Search Runner (ts_runner.cpp)"]:::cpp
        mh5["Tabu Search Component (tabu_search.cpp)"]:::cpp
        mh6["VNS Runner (vns_runner.cpp)"]:::cpp
        mh7["Variable Neighborhood (variable_neighborhood.cpp)"]:::cpp
        mh8["Individuo (individuo.cpp)"]:::cpp
        mh9["Initial Solution (initial_solution.cpp)"]:::cpp
        mh10["Neighbor Evaluation (neighbor.cpp)"]:::cpp
        mh11["Utility Modules (util)"]:::cpp
        mh12["Makefile"]:::cpp
        mh13["Shell Script (script.sh)"]:::cpp
    end

    %% Final Solution Output / Benchmarking Node
    so1["Solution Output / Benchmarking"]:::solution

    %% Connections from Shared Problem Instance to Modules
    sp1 -->|"feeds"| eo2
    sp1 -->|"feeds"| mh1

    %% Exact Optimization Module internal flow
    eo2 -->|"configures"| eo3
    eo3 -->|"invokes"| eo1
    eo4 -->|"configures"| ext1
    eo1 -->|"calls"| ext1
    ext1 -->|"returns"| eo5

    %% Metaheuristics Module internal flow
    mh1 -->|"triggers"| mh2
    mh1 -->|"along with"| mh3
    mh4 -->|"executes"| mh5
    mh6 -->|"uses"| mh7
    mh8 -->|"forms part of"| mh9
    mh10 -->|"assists"| mh8
    %% Connect build and utility scripts (auxiliary)
    mh11 -->|"supports"| mh1
    mh12 -->|"builds"| mh1
    mh13 -->|"runs"| mh1

    %% Aggregating outputs from Exact and Metaheuristics modules
    eo5 -->|"outputs to"| so1
    mh1 -->|"outputs to"| so1
    mh3 -->|"outputs to"| so1
    mh4 -->|"outputs to"| so1
    mh6 -->|"outputs to"| so1

    %% Class Definitions for styling
    classDef python fill:#FAD7A0,stroke:#E67E22,stroke-width:2px;
    classDef cpp fill:#AED6F1,stroke:#2980B9,stroke-width:2px;
    classDef external fill:#A9DFBF,stroke:#27AE60,stroke-width:2px;
    classDef shared fill:#F9E79F,stroke:#F1C40F,stroke-width:2px;
    classDef solution fill:#D2B4DE,stroke:#8E44AD,stroke-width:2px;

    %% Click Events for Exact Optimization Module
    click eo1 "https://github.com/lucasgabriel-cp/tcc/blob/main/exact_model/gurobi_opt.py"
    click eo2 "https://github.com/lucasgabriel-cp/tcc/blob/main/exact_model/instance_vars.py"
    click eo3 "https://github.com/lucasgabriel-cp/tcc/blob/main/exact_model/optimization.py"
    click eo4 "https://github.com/lucasgabriel-cp/tcc/tree/main/exact_model/gurobi_conf"
    click eo5 "https://github.com/lucasgabriel-cp/tcc/blob/main/exact_model/results_LKM.txt"

    %% Click Events for Metaheuristics Module
    click mh1 "https://github.com/lucasgabriel-cp/tcc/blob/main/metaheuristics/ga_runner.cpp"
    click mh2 "https://github.com/lucasgabriel-cp/tcc/blob/main/metaheuristics/genetic_algorithm.cpp"
    click mh3 "https://github.com/lucasgabriel-cp/tcc/blob/main/metaheuristics/hibrid_runner.cpp"
    click mh4 "https://github.com/lucasgabriel-cp/tcc/blob/main/metaheuristics/ts_runner.cpp"
    click mh5 "https://github.com/lucasgabriel-cp/tcc/blob/main/metaheuristics/tabu_search.cpp"
    click mh6 "https://github.com/lucasgabriel-cp/tcc/blob/main/metaheuristics/vns_runner.cpp"
    click mh7 "https://github.com/lucasgabriel-cp/tcc/blob/main/metaheuristics/variable_neighborhood.cpp"
    click mh8 "https://github.com/lucasgabriel-cp/tcc/blob/main/metaheuristics/individuo.cpp"
    click mh9 "https://github.com/lucasgabriel-cp/tcc/blob/main/metaheuristics/initial_solution.cpp"
    click mh10 "https://github.com/lucasgabriel-cp/tcc/blob/main/metaheuristics/neighbor.cpp"
    click mh11 "https://github.com/lucasgabriel-cp/tcc/tree/main/metaheuristics/util"
    click mh12 "https://github.com/lucasgabriel-cp/tcc/tree/main/metaheuristics/makefile"
    click mh13 "https://github.com/lucasgabriel-cp/tcc/blob/main/metaheuristics/script.sh"

    %% Click Event for Shared Problem Instance
    click sp1 "https://github.com/lucasgabriel-cp/tcc/blob/main/metaheuristics/problems/leasing.cpp"
```
