How paulafernalia/benders-gurobi works
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)”