# paulafernalia/benders-gurobi architecture

> Architecture diagram of the GitHub repository paulafernalia/benders-gurobi, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/paulafernalia/benders-gurobi
- Repository: https://github.com/paulafernalia/benders-gurobi

## Overview

This is a **Python package / CLI tool** that implements **Benders decomposition for a generic MIP** using **Gurobi**, starting from an **LP file** (“full problem”) and **automatically separating continuous vs. binary variables**.

So the “system” isn’t a distributed runtime; it’s a **library + executable flow** with a clear algorithmic pipeline:
- Ingest an LP model
- Partition variables into master (binary/integer) vs. subproblem (continuous)
- Build corresponding Gurobi models
- Solve iteratively using **Gurobi callbacks** to add Benders cuts

From `src/benders`:

- `__main__.py`: **CLI entrypoint / runnable flow** (`make run` executes this)
- `solver.py`: likely the **Benders orchestration loop** (solve master, trigger subproblem solves, convergence criteria, cut management)
- `model_builders.py`: **model construction layer** (parses LP, splits variables, builds master/subproblem models)
- `callbacks.py`: **Gurobi callback integration** (where lazy constraints/cuts are injected, where incumbent solutions are read, etc.)

Other relevant top-level:
- `conf/logging.yml`: **logging config** (include as supporting config feeding the runtime)

##### User / Client
- provides: LP file path, solver options (time limit, mipgap, etc. if supported)

##### CLI Runner (`benders.__main__`)
- parses args/config
- initializes logging
- invokes solver

##### Benders Solver / Orchestrator (`solver.py`)
- owns the iterative algorithm state
- coordinates master/subproblem solving
- convergence checks, termination
- aggregates cuts/stats

##### Model Builders (`model_builders.py`)
- LP ingestion
- variable classification: binary/integer vs continuous
- builds:
- **Master problem** (discrete vars + θ/recourse proxy)
- **Subproblem** (continuous recourse given master assignment)
- defines mapping between master solution → subproblem RHS/constraints

##### Callback Layer (`callbacks.py`)
- hooks into Gurobi solve
- reads incumbent solution during MIP search
- triggers subproblem evaluation
- adds Benders cuts (lazy constraints / user cuts depending on implementation)

##### Gurobi Optimizer (External System)
- runs MIP (master)
- runs LP/QP (subproblem) as needed
- provides callback API + solver results

##### Artifacts / Outputs
- logs (configured by `conf/logging.yml`)
- solution object / objective value
- optional: cut pool, iteration stats

- User → `__main__.py`: “LP file + options”
- `__main__.py` → logging config: “load logging.yml”
- `__main__.py` → `solver.py`: “start solve()”
- `solver.py` → `model_builders.py`: “build master + subproblem models; mappings”
- `solver.py` → Gurobi: “optimize(master)”
- Gurobi → `callbacks.py`: “callback events (MIPSOL / NODE / etc.)”
- `callbacks.py` → subproblem model (via `model_builders` outputs): “fix master vars, solve subproblem”
- Subproblem solve → `callbacks.py`: “dual rays / duals / recourse cost”
- `callbacks.py` → Gurobi: “add Benders cut to master (lazy/user cut)”
- Gurobi → `solver.py`: “final master solution / status”
- `solver.py` → Outputs: “best solution + stats”
- Outputs → User: “report result”

Important: show **two distinct solve loops**:
- **Master MIP search** driven by Gurobi
- **Subproblem evaluations** triggered repeatedly from callback (or from an outer loop depending on implementation)

- “Master optimization (Gurobi)” with an internal hook to “Cut generation (callbacks + subproblem solves)”.

##### Architectural patterns / principles to call out

- **Separation of concerns**
- Model creation is isolated (`model_builders.py`)
- Solve orchestration is isolated (`solver.py`)
- Solver integration points are isolated (`callbacks.py`)

- **Plugin/inversion via callbacks**
- The Benders algorithm is partially executed “inside” the solver through callback events.
- Cuts are produced as a function of incumbent master solutions.

- **Pipeline from LP → partition → two models**
- This is central: the tool’s value is in automatic separation + constructing the decomposition.

- **External dependency boundary**

##### Suggested “most accurate” component breakdown for this repo

- `benders.__main__` (entrypoint)
- `conf/logging.yml` (config input)
- `benders.solver` (Benders loop + state)
- `benders.model_builders` (LP parsing + master/subproblem creation)
- `benders.callbacks` (cut generation + solver events)
- “Master model (Gurobi Model object)”
- “Subproblem model (Gurobi Model object)”
- “Gurobi Optimizer + Callback API”
- “LP file (input)”
- “Logs + solution report (output)”

## Diagram (Mermaid)

```mermaid
flowchart TD

%% =========================
%% Diagram 1: Runtime / Algorithm Architecture (Primary)
%% =========================

subgraph "Runtime / Algorithm Architecture (Benders Decomposition CLI)"
direction TB

    %% Inputs
    subgraph "Inputs"
    direction TB
        User["User / Client"]:::actor
        LP[/"LP file (full MIP model)"/]:::io
        Opts[/"Solver options\n(time limit, mipgap, etc.)"/]:::io
        LogCfg[/"logging.yml"/]:::config
    end

    %% Python package
    subgraph "Python Package: benders"
    direction TB
        Main["benders.__main__\n(CLI Runner)"]:::module
        Init["benders.__init__\n(Package exports)"]:::module
        Solver["benders.solver\n(Benders Solver / Orchestrator)"]:::module
        Builders["benders.model_builders\n(Model Builders)"]:::module
        Cbs["benders.callbacks\n(Callback Layer)"]:::module
    end

    %% External boundary
    subgraph "External System Boundary"
    direction TB
        Gurobi["Gurobi Optimizer\n+ Callback API"]:::external
        Master["Master model\n(Gurobi Model object)"]:::model
        Subp["Subproblem model\n(Gurobi Model object)"]:::model
    end

    %% Outputs
    subgraph "Artifacts / Outputs"
    direction TB
        Logs[/"Logs"/]:::io
        Report[/"Solution + objective\nIteration stats / cut pool (optional)"/]:::io
    end

    %% --- Control flow (solid) ---
    User -->|"provide_inputs"| Main
    Main -->|"load_config"| LogCfg
    Main -->|"start_solve()"| Solver
    Solver -->|"build_models()"| Builders
    Solver -->|"optimize(master)"| Gurobi

    %% Callback-driven inner loop
    Gurobi -->|"callback_events\n(MIPSOL/NODE/...)"| Cbs
    Cbs -->|"solve_subproblem()"| Gurobi
    Cbs -->|"add_cut\n(lazy/user)"| Gurobi

    %% Finalization
    Gurobi -->|"final_status\n+ best_solution"| Solver
    Solver -->|"emit_results"| Report
    Solver -->|"write_logs"| Logs
    Report -->|"report_result"| User

    %% --- Data/artifacts (dashed) ---
    User -.->|"LP_path"| LP
    LP -.->|"parse_LP"| Builders
    Opts -.->|"config"| Main

    Builders -.->|"master_model"| Master
    Builders -.->|"subproblem_model\n+ mappings"| Subp
    Master -.->|"optimize_target"| Gurobi
    Subp -.->|"recourse_eval"| Gurobi

    Gurobi -.->|"incumbent_x"| Cbs
    Cbs -.->|"dual_values\n/ dual_rays\n/ recourse_cost"| Cbs
    Cbs -.->|"benders_cuts"| Master
    Solver -.->|"solution_object\n+ stats"| Report
    Main -.->|"logger_setup"| Logs

end

%% =========================
%% Diagram 2: Dev / Packaging Workflow (Secondary)
%% =========================

subgraph "Dev / Packaging Workflow (optional)"
direction TB

    DevUser["Developer"]:::actor
    Make["Makefile\n(build/run entry)"]:::dev
    PyProj["pyproject.toml\n(project metadata)"]:::dev
    UvLock["uv.lock\n(dependency lock)"]:::dev
    PreC[".pre-commit-config.yaml\n(quality gates)"]:::dev

    DevUser -->|"make run/test/lint"| Make
    Make -->|"install/resolve"| PyProj
    PyProj -->|"lock_deps"| UvLock
    DevUser -->|"git commit"| PreC
    PreC -->|"run_hooks\n(format/lint/typecheck)"| Make
end

%% =========================
%% Click Events (from component_mapping)
%% =========================
click Main "https://github.com/paulafernalia/benders-gurobi/blob/main/src/benders/__main__.py"
click Solver "https://github.com/paulafernalia/benders-gurobi/blob/main/src/benders/solver.py"
click Builders "https://github.com/paulafernalia/benders-gurobi/blob/main/src/benders/model_builders.py"
click Cbs "https://github.com/paulafernalia/benders-gurobi/blob/main/src/benders/callbacks.py"
click Init "https://github.com/paulafernalia/benders-gurobi/blob/main/src/benders/__init__.py"
click LogCfg "https://github.com/paulafernalia/benders-gurobi/blob/main/conf/logging.yml"
click Make "https://github.com/paulafernalia/benders-gurobi/tree/main/Makefile"
click PyProj "https://github.com/paulafernalia/benders-gurobi/blob/main/pyproject.toml"
click UvLock "https://github.com/paulafernalia/benders-gurobi/blob/main/uv.lock"
click PreC "https://github.com/paulafernalia/benders-gurobi/blob/main/.pre-commit-config.yaml"

%% =========================
%% Styles
%% =========================
classDef module fill:#d7ebff,stroke:#1f5fbf,stroke-width:1.5px,color:#0b2a55
classDef external fill:#e6e6e6,stroke:#4a4a4a,stroke-width:2.5px,color:#1e1e1e
classDef io fill:#dff7e8,stroke:#1f7a3a,stroke-width:1.5px,color:#0f3b1d
classDef config fill:#e8f8df,stroke:#2f7d32,stroke-width:1.5px,color:#163b17
classDef model fill:#fff1c9,stroke:#b7791f,stroke-width:1.5px,color:#4a2c0a
classDef actor fill:#f5e1ff,stroke:#7b2cbf,stroke-width:1.5px,color:#3d0d66
classDef dev fill:#ffe3d6,stroke:#c2410c,stroke-width:1.5px,color:#5a1c06
```
