# flo338/optimization-algos architecture

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

- Interactive diagram: https://gitdiagram.com/flo338/optimization-algos
- Repository: https://github.com/flo338/optimization-algos

## Overview

##### Project Type and Purpose
- This is a Python-based optimization toolkit / CLI tool.
- It’s not a web or full-stack app, nor a compiler. It’s an open-source library/command-line application for running and extending optimization methods.

##### File Structure
Top-level directories and files:
- `app/` – contains the core code.
- `app/main.py` – the CLI or script entrypoint.
- `app/optimization/` – “Optimization Engine” subpackage.
– `algorithm_enum.py` – registry of supported algorithms.
– `backtracking/` – backtracking solver module.
– `local_search/` – local search framework with
· `instance.py` and `local_search.py` (framework)
· `meta_heuristics/` (hill climbing, simulated annealing, taboo search)
· `neighborhood.py`, `objective.py`
– `exceptions.py`, `solution.py`
- `app/problems/` – problem definitions subpackage.
– `box_filling/` – one example problem domain.
· Instance loader, rectangle model, neighborhoods, objectives, solution, utils.
- `tests/` – unit tests.
- `requirements.txt` / `setup.sh` – environment setup.

##### README
- Confirms it’s a CLI library that runs within a Python venv.

##### Main Components & Their Relationships
a. Components:
1. CLI / Entrypoint: `app/main.py`
2. Optimization Engine (`app/optimization`):
– Algorithm Registry (`algorithm_enum.py`)
– Backtracking Module
– Local Search Framework
· Meta-heuristics (hill climbing, simulated annealing, taboo)
· Neighborhood Selector
· Objective Evaluator
– Solution Representation
3. Problem Domains (`app/problems`):
4. External: File system (input data, output logs), Test Suite
b. Interactions:
- User invokes CLI → `main.py` parses arguments (algorithm choice, problem type, input file).
- Main calls into Optimization Engine → picks algorithm via `algorithm_enum`.
- Engine loads a Problem Instance from `app/problems` → uses its neighborhood & objective functions.
- Engine runs the selected algorithm (backtracking or a local search meta-heuristic) → produces a `Solution` object.
- Main writes or prints the solution (to stdout or file).
- Tests invoke various components directly for unit testing.
c. Architectural Patterns:
- Modular separation: engine vs. problems vs. CLI.
- Strategy pattern in meta-heuristics: interchangeable hill climbing, simulated annealing, taboo.
- Factory/registry pattern in `algorithm_enum.py` for selecting algorithms at runtime.
d. Technologies & Libraries:
- Python 3
- Virtual environment (bash setup.sh → `venv/`)
- No external DB; purely in-memory objects.
- pytest or unittest in `tests/`.

## Diagram (Mermaid)

```mermaid
flowchart TD
    CLI["CLI / Entrypoint\n(app/main.py)"]:::cli
    subgraph "Optimization Engine\n(app/optimization/)"
        direction TB
        Registry["Algorithm Registry\n(algorithm_enum.py)"]:::engine
        Backtracking["Backtracking Solver\n(backtracking.py)"]:::engine
        subgraph "Local Search Framework"
            direction TB
            LSEntry["Local Search\n(local_search.py)"]:::engine
            InstanceLS["Instance Loader\n(instance.py)"]:::engine
            Neighborhood["Neighborhood Selector\n(neighborhood.py)"]:::engine
            Objective["Objective Evaluator\n(objective.py)"]:::engine
            subgraph "Meta-heuristics"
                HC["Hill Climbing\n(hill_climbing.py)"]:::engine
                SA["Simulated Annealing\n(simulated_annealing.py)"]:::engine
                TS["Taboo Search\n(taboo.py)"]:::engine
            end
        end
        Exceptions["Exceptions\n(exceptions.py)"]:::engine
        SolutionE["Solution Representation\n(solution.py)"]:::engine
    end

    subgraph "Problem Modules\n(app/problems/)"
        direction TB
        Box["Box Filling Problem Module\n(app/problems/box_filling/)"]:::problem
        BInstance["Instance Loader\n(instance.py)"]:::problem
        Rectangle["Rectangle Model\n(rectangle.py)"]:::problem
        PNeighborhood["Problem Neighborhoods\n(geometric_neighborhood.py)"]:::problem
        PObjective["Problem Objectives\n(objectives.py)"]:::problem
        BoxSolution["Problem Solution\n(solution.py)"]:::problem
        Utils["Utilities\n(utils.py)"]:::problem
    end

    FileSystem["Filesystem / Input Data"]:::data
    Console["Console / Output"]:::data
    Tests["Test Suite\n(tests/unit/)"]:::test

    CLI --> Registry
    Registry --> Backtracking
    Registry --> LSEntry
    Backtracking --> Box
    LSEntry --> Box
    Box --> BInstance
    Box --> Rectangle
    Box --> PNeighborhood
    Box --> PObjective
    Box --> BoxSolution
    Box --> Utils
    BoxSolution --> SolutionE
    Exceptions -.-> Backtracking
    Exceptions -.-> LSEntry
    SolutionE --> Console
    FileSystem --> BInstance
    CLI --> FileSystem
    Tests -.-> Registry
    Tests -.-> Backtracking
    Tests -.-> LSEntry
    Tests -.-> Box

    click CLI "https://github.com/flo338/optimization-algos/blob/main/app/main.py"
    click Registry "https://github.com/flo338/optimization-algos/blob/main/app/optimization/algorithm_enum.py"
    click Backtracking "https://github.com/flo338/optimization-algos/blob/main/app/optimization/backtracking/backtracking.py"
    click Exceptions "https://github.com/flo338/optimization-algos/blob/main/app/optimization/exceptions.py"
    click SolutionE "https://github.com/flo338/optimization-algos/blob/main/app/optimization/solution.py"
    click LSEntry "https://github.com/flo338/optimization-algos/blob/main/app/optimization/local_search/local_search.py"
    click InstanceLS "https://github.com/flo338/optimization-algos/blob/main/app/optimization/local_search/instance.py"
    click Neighborhood "https://github.com/flo338/optimization-algos/blob/main/app/optimization/local_search/neighborhood.py"
    click Objective "https://github.com/flo338/optimization-algos/blob/main/app/optimization/local_search/objective.py"
    click HC "https://github.com/flo338/optimization-algos/blob/main/app/optimization/local_search/meta_heuristics/hill_climbing.py"
    click SA "https://github.com/flo338/optimization-algos/blob/main/app/optimization/local_search/meta_heuristics/simulated_annealing.py"
    click TS "https://github.com/flo338/optimization-algos/blob/main/app/optimization/local_search/meta_heuristics/taboo.py"
    click Box "https://github.com/flo338/optimization-algos/tree/main/app/problems/"
    click BInstance "https://github.com/flo338/optimization-algos/blob/main/app/problems/box_filling/instance.py"
    click Rectangle "https://github.com/flo338/optimization-algos/blob/main/app/problems/box_filling/rectangle.py"
    click PNeighborhood "https://github.com/flo338/optimization-algos/blob/main/app/problems/box_filling/local_search/neighborhoods/geometric_neighborhood.py"
    click PObjective "https://github.com/flo338/optimization-algos/blob/main/app/problems/box_filling/local_search/objectives.py"
    click BoxSolution "https://github.com/flo338/optimization-algos/blob/main/app/problems/box_filling/solution.py"
    click Utils "https://github.com/flo338/optimization-algos/blob/main/app/problems/box_filling/utils.py"
    click Tests "https://github.com/flo338/optimization-algos/tree/main/tests/unit/"

    classDef cli fill:#f9f,stroke:#333,stroke-width:1px
    classDef engine fill:#bbf,stroke:#333
    classDef problem fill:#bfb,stroke:#333
    classDef data fill:#ffb,stroke:#333,stroke-width:1px
    classDef test fill:none,stroke:#999,stroke-dasharray:5 5
```
