gurobi-modelanalyzer 3.0.0

Model analysis tools for explaining ill-conditioning, analyzing solutions, and scaling problems.

Gurobi Model Analyzer

Gurobi Model Analyzer is an open-source python package that provides detailed analysis of model solutions and model characteristics. It consists of a results_analyzer module that calculates explanations of ill-conditioned basis matrices, a solcheck module that analyzes a given solution, and a scaling module that scales optimization models to improve numerical conditioning prior to solving.

Documentation

The latest user manual is available on readthedocs.

Contact us

For questions related to using Gurobi Model Analyzer, please use Gurobi's Forum.

For reporting bugs, issues, and feature requests please open an issue.

If you encounter issues with Gurobi or gurobipy please contact Gurobi Support.

Installation

Dependencies

• Python >= 3.10
• numpy >= 1.21.5 (although earlier versions compatible with python 3.7 will probably work).
• questionary for the (optional) interactive version

Pip installation

The easiest way to install gurobi-modelanalyzer is using pip in a virtual environment:

(.venv) pip install gurobi-modelanalyzer

This will also install the numpy and gurobipy dependencies. One of the advanced functions makes use of matplotlib; if you haven't already installed that and plan to use this function (matrix_bitmap), you can either install the matplotlib package directly, or install it with the gurobi-modelanalyzer package via "pip install gurobi-modelanalyzer matplotlib".

Please note that gurobipy is commercial software and requires a license. When installed via pip or conda, gurobipy ships with a free license for testing and can only solve models of limited size.

Example usage

Using the explainer functions

import gurobipy as gp
import gurobi_modelanalyzer as gma

model = gp.read("myillconditionedmodel.mps")
model.optimize()
gma.kappa_explain(model)

# row-based explanation (default)
gma.kappa_explain(model, expltype="ROWS")

# column-based explanation
gma.kappa_explain(model, expltype="COLS")

# custom output file name
gma.kappa_explain(model, filename="myname.lp")

# angle-based explanation (only looks for pairs of rows or columns
# that cause ill-conditioning.
gma.angle_explain(model)

Use help(gma.kappa_explain) or help(gma.angle_explain) for information on more advanced usage.

Using the solution checker

Testing a suboptimal solution

import gurobipy as gp
import gurobi_modelanalyzer as gma

m = gp.read("examples/data/afiro.mps")

sol = {m.getVarByName("X01"): 78, m.getVarByName("X22"): 495}
sc = gma.SolCheck(m)

sc.test_sol(sol)
print(f"Solution Status: {sc.Status}")
sc.optimize()
for v in sol.keys():
    print(f"{v.VarName}: Fixed value: {sol[v]}, Computed value: {v.X}")

Testing an infeasible solution

m = gp.read("examples/data/misc07.mps")

sol = {m.getVarByName("COL260"): 2400.5}
sc = gma.sol_check(m)

sc.test_sol(sol)

print(f"Solution Status: {sc.Status}")
sc.inf_repair()
for c in m.getConstrs():
    if abs(c._Violation) > 0.0001:
        print(f"{c.ConstrName}: RHS: {c.RHS}, Violation: {c._Violation}")

Using the model scaling module

Scale a poorly conditioned model to improve numerical stability before solving:

import gurobipy as gp
import gurobi_modelanalyzer as gma

m = gp.read("mymodel.mps")
m_scaled = gma.scale_model(m, method="equilibration")

m_scaled.optimize()

# Retrieve the solution in the original (unscaled) variable space
for var in m_scaled.getVarsUnscaled():
    print(f"{var.VarName}: {var.Xunsc:.6e}")

# Check constraint and bound violations in the original space
m_scaled.computeUnscVio()
print(f"Max constraint violation: {m_scaled.MaxUnscConstrVio:.2e}")
print(f"Max bound violation:      {m_scaled.MaxUnscBoundVio:.2e}")

Save the scaling factors to a file and reuse them in a later run:

m_scaled.write_scaling("mymodel.scl")

# Later: reload and reproduce the exact same scaling
m2 = gp.read("mymodel.mps")
gma.read_scaling_file("mymodel.scl", m2)
m2_scaled = gma.scale_model(m2, method="equilibration", init_scaling=2)

The package also provides the gurobi_cls command-line tool, which scales and solves a model in one step (analogous to Gurobi's gurobi_cl):

gurobi_cls --method equilibration TimeLimit=120 mymodel.mps

For more details see the Model Scaling documentation.

Getting a Gurobi License

Alternatively to the bundled limited license, there are licenses that can handle models of all sizes.

As a student or staff member of an academic institution, you qualify for a free, full-product license. For more information, see:

• https://www.gurobi.com/academia/academic-program-and-licenses/

For a commercial evaluation, you can request an evaluation license.

Other useful resources to get started:

• https://www.gurobi.com/documentation/
• https://support.gurobi.com/hc/en-us/community/topics/

Development

We value any level of experience in using Gurobi Model Analyzer and would like to encourage you to contribute directly to this project. Please see the Contributing Guide for more information.

Running the tests

Install the package and execute the unit tests from the project root:

python -m pip install .
python -m unittest discover -v

This runs all tests under the tests/ directory.

Submitting a Pull Request

Before opening a Pull Request, have a look at the full Contributing page to make sure your code complies with our guidelines.