Describe the feature you'd like to see
Add a model.diagnostics module/accessor that provides insights into model structure, quality, and performance characteristics. This module would be experimental — the API may change between releases as we learn what's most useful. Users will be warned accordingly.
Motivation
Users often build large models and have limited visibility into why solves are slow or produce unexpected results. A diagnostics module gives them tools to inspect and understand their models without needing deep solver expertise.
Ideas and use cases
Below is a non-exhaustive list of possible diagnostics. Not all need to be implemented at once — the module can grow over time.
Pre-solve (no solve needed, pure matrix/model analysis)
| Diagnostic |
Use case |
| Scaling report — coefficient range ratios per row/column, flagging problematic ratios |
Identify numerical issues that slow down solvers or cause inaccurate results |
| Big-M detection — find constraints where binary variables appear with very large coefficients |
Spot big-M formulations that weaken LP relaxation and slow branch-and-bound |
| RHS/coefficient mismatch — flag constraints where RHS is on a very different scale than coefficients |
Catch common modeling mistakes that hurt solver performance |
| Model summary/profile — variable/constraint counts by type, sparsity, density of constraint matrix |
Quick overview to sanity-check model size and structure |
| Coefficient histogram/distribution — distribution of coefficient magnitudes across the model |
Understand overall scaling characteristics at a glance |
| Duplicate/near-duplicate constraint detection — find rows of A that are identical or nearly identical |
Catch redundant constraints that bloat the model |
| Empty/trivial constraint detection — constraints with no variables or that are trivially satisfied |
Catch modeling bugs early |
| Variable bound analysis — variables with very wide or very tight bounds, or missing bounds |
Spot variables that may need tighter bounds for performance |
Post-solve (requires a solve)
| Diagnostic |
Use case |
| Constraint activity — classify constraints as tight, slack, or violated; report slack values |
Understand which constraints are binding and which are redundant in the solution |
| Variables at bounds — which variables are at their lower/upper bound |
Identify bottlenecks in the solution |
| LP relaxation quality — solve LP relaxation, report integrality gap and fractionality per integer variable |
Assess MIP formulation strength and identify variables with weak relaxation |
| Dual value analysis — distribution and extreme values of dual variables |
Understand shadow prices and constraint sensitivity |
Solver-dependent (requires specific solver backends)
| Diagnostic |
Use case |
IIS analysis (already exists via compute_infeasibilities) |
Diagnose infeasible models |
| Basis condition number |
Assess numerical stability of the current basis |
Design considerations
- Experimental API — this module should clearly warn users (e.g. via a
FutureWarning on first use or in docs) that the API is not yet stable and may change
- Accessor pattern — similar to
model.matrices, accessed via model.diagnostics
- Lazy computation — diagnostics should be computed on demand, not on model creation
- Solver-agnostic where possible — most diagnostics should work on the model's xarray data structures without requiring a specific solver
- Return xarray objects — results should use xarray DataArrays/Datasets to stay consistent with linopy's data model and preserve labeled dimensions. This makes it easy to cross-reference diagnostics with the original variables and constraints
- Non-invasive — diagnostics should never modify the model (LP relaxation analysis should restore state via
unrelax())
What this is NOT
- Not an automatic reformulation tool — diagnostics identify issues, the user decides how to fix them
- Not a replacement for solver-specific analysis tools — but a solver-agnostic starting point
- Not a stable API commitment (initially) — we should be free to iterate on what's useful
Describe the feature you'd like to see
Add a
model.diagnosticsmodule/accessor that provides insights into model structure, quality, and performance characteristics. This module would be experimental — the API may change between releases as we learn what's most useful. Users will be warned accordingly.Motivation
Users often build large models and have limited visibility into why solves are slow or produce unexpected results. A diagnostics module gives them tools to inspect and understand their models without needing deep solver expertise.
Ideas and use cases
Below is a non-exhaustive list of possible diagnostics. Not all need to be implemented at once — the module can grow over time.
Pre-solve (no solve needed, pure matrix/model analysis)
Post-solve (requires a solve)
Solver-dependent (requires specific solver backends)
compute_infeasibilities)Design considerations
FutureWarningon first use or in docs) that the API is not yet stable and may changemodel.matrices, accessed viamodel.diagnosticsunrelax())What this is NOT