Totsu is a structural modeling and diagnostic toolkit for mathematical optimization.
Most optimization libraries focus on computing optimal solutions. Totsu focuses on understanding why models behave the way they do.
It provides tools to measure structural tension, visualize combinatorial behavior, and explore negotiable trade-offs inside mathematical models.
Requires Pyomo + any LP/MILP solver available to Pyomo (HiGHS, CBC, or GLPK).
Check solver availability:
python -c "from pyomo.environ import SolverFactory; print('highs', SolverFactory('highs').available(False)); print('cbc', SolverFactory('cbc').available(False)); print('glpk', SolverFactory('glpk').available(False))"If you already have a working Pyomo + solver environment, you can run Totsu from source without extra setup.
# Clone this repository
git clone git@github.com:ggsato/totsu.git
cd totsu
# Use auto solver detection (highs -> cbc -> glpk)
python -m totsu.examples.demo.transportation_elastic_quickstart --solver autoWhat you should see:
- The base model is infeasible
- Elastic analysis reports the minimal relaxations needed to make it feasible
- This answers the practical request: "Infeasible — what should we change to restore feasibility?"
Next, try it on your own model:
python -m totsu.examples.demo.transportation_elastic_quickstart --helpOptional / Advanced — Gotcha: Penalty too small can make violations "cheap"
- What happens: if penalty is too small, the model may prefer violating constraints (e.g., demand effectively unmet / pushed to zero) instead of operating normally.
- Why: the objective trades off business cost and violation penalty; a small penalty makes violation a cheap choice.
- Fix:
- set penalties large enough for your model scale,
- start with
violation_onlyto inspect violation amounts, - then move to
original_plus_violationfor cost-aware repair.
For the public API path, see docs/TRY_YOUR_MODEL.md.
Totsu is not just a solver wrapper.
It is a toolkit for:
- Measuring infeasibility
- Diagnosing structural bottlenecks
- Visualizing MILP behavior
- Exploring trade-offs beyond a single optimal solution
Optimization is not only about deciding. It is also about measuring.
The Elastic Tool transforms infeasible or tightly constrained models into measurable systems. Terminology: violation vs margin (and why Elastic uses aux variables internally) -> docs/elastic/ELASTIC_TOOL_GENERIC.md
Instead of stopping at infeasible, it answers:
flowchart LR
A["Original Model<br/>Hard Constraints"] --> B["Elastic Transformation"]
B --> C["Violation Variables Added"]
B --> D["Penalty Terms Added"]
C --> E["Always-Feasible Model"]
D --> E
E --> F["Minimal Structural Repair"]
- Which constraints absorb the structural stress?
- How much relaxation is required?
- What is the minimum structural adjustment needed?
- If relaxation is allowed, what is the most rational repair plan?
Elastic analysis supports two key modes:
Minimizes total constraint violation.
This answers:
“How far is the model from feasibility?”
It measures structural deficit without considering the original objective.
Minimizes:
(original objective) + (penalty × violation)
This answers:
“If limited relaxation is allowed, what is the most rational adjustment?”
This mode does not just measure infeasibility —
it proposes a structurally minimal and economically consistent repair.
Original model:
LP HAS NO PRIMAL FEASIBLE SOLUTION
Elastic (violation_only):
Total violation cost: 750
Supply constraints relaxed: +75 units
Elastic (original_plus_violation):
Relax 73 units at S3
Relax 2 units at S2
Note: in original_plus_violation mode, set violation penalties high enough
relative to normal objective coefficients. If penalties are too small, the model
can prefer violating demand/supply instead of performing real operations.
Interpretation:
The model requires 75 additional units of supply.
Given transportation costs, the economically optimal repair is
to expand Supplier S3 primarily.
Elastic analysis does not only diagnose infeasibility.
It suggests how structure should adapt.
Optimization is not only about finding optimal answers.
It is also about understanding how systems bend before they break.
MILP models often suffer from combinatorial explosion.
Totsu does not treat integer constraints as merely rules to enforce.
Instead, it treats them as indicators of structural rigidity.
Totsu provides tools to:
- Measure how close LP relaxation solutions are to integrality
- Visualize fractional variable distributions
- Anticipate branch-and-bound difficulty before solving fully
- Inspect where structural hardness emerges
The goal is not only to solve MILPs faster — but to measure how much structural “hardening” integer constraints introduce.
Integer variables are not just decisions. They are boundaries.
Totsu visualizes the distance to those boundaries.
Many real-world systems contain both stable structure and legitimate exceptions.
Dual Stacking explores a two-layer structural approach:
- A stable layer captures dominant, persistent structure.
- A negotiable layer captures conditional, context-dependent behavior.
The purpose is not to improve predictive accuracy.
The purpose is to separate:
- what is structurally fixed
- from what is structurally flexible
Rather than collapsing everything into a single model, Dual Stacking preserves meaningful variation.
It aims to distinguish:
- core structure
- from structured exceptions
- without treating rare but valid cases as mere noise.
This direction builds on Elastic diagnosis and structural analysis, and remains under experimental development.
flowchart TD
A["Users / Examples"] --> B["Elastic Tool"]
A --> C["MILP Visualization"]
A --> D["Dual Stacking (Experimental)"]
B --> E["Core Utilities"]
C --> E
D --> E
E --> F["SimplexSolver"]
E --> G["Tableau"]
E --> H["Sensitivity & Structural Analysis"]
F --> I["Solver Layer"]
G --> I
Totsu evolves in stages:
Measure structural tensions by allowing controlled relaxations.
Understand combinatorial explosion and model design quality.
Move from single optimal solutions toward structured trade-off landscapes.
Totsu is designed to be tried with minimal friction.
Clone and run the examples directly from source (recommended for quick evaluation).
If you don't have Pyomo/solvers yet, this is a minimal starting point.
conda install -c conda-forge pyomo glpkIf you want to run tests and notebooks:
conda install -c conda-forge numpy pytest plotly dash dash-bootstrap-components jupyterlab
pytestFor Jupyter Notebook support:
conda install jupyterlabUse Totsu when you want to understand model structure, not only compute a solution.
- Your model becomes infeasible, and you want to know which constraints are causing it (Elastic Tool)
- A MILP “works” but is slow / unstable / hard to explain, and you want to see why (MILP Visualization)
- You need interpretable trade-offs and “negotiable constraints” rather than a single answer (Dual Stacking: experimental)
- You only need a fast optimal solution and already trust your formulation (use standard solvers directly)
- You don’t need diagnostics, explanation, or alternative trade-offs
Start here (Elastic feasibility repair):
python -m totsu.examples.demo.transportation_elastic_quickstart --solver autoOther examples live under:
totsu/examples/
Optimization is not only about computing answers. It is about making structure visible.
Totsu provides tools for structural measurement.
Detailed solver internals such as:
- SimplexSolver
- TableauVisualizer
- SensitivityAnalysis
are documented under:
totsu/utils/README.md
Totsu is licensed under the MIT License, ensuring it remains accessible and open for all.