Skip to content

Commit 29dbfda

Browse files
joaquimgjoaquimg
authored
Add docs (#12)
* Add docs * format * fix names
1 parent dbc49be commit 29dbfda

File tree

11 files changed

+609
-4
lines changed

11 files changed

+609
-4
lines changed

‎docs/Project.toml

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
[deps]
2+
Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
3+
ModelAnalyzer = "d1179b25-476b-425c-b826-c7787f0fff83"

‎docs/make.jl

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
using Documenter, ModelAnalyzer
2+
3+
makedocs(; sitename = "ModelAnalyzer.jl documentation")
4+
5+
deploydocs(;
6+
repo = "github.com/jump-dev/ModelAnalyzer.jl.git",
7+
push_preview = true,
8+
)

‎docs/src/analyzer.md

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
2+
# ModelAnalyzer main API
3+
4+
All the analysis modules in `ModelAnalyzer` follow the same main API.
5+
The main function to perform an analysis is:
6+
7+
```@docs
8+
ModelAnalyzer.analyze
9+
```
10+
11+
Once the analysis is performed, the resulting data structure can be summarized
12+
using:
13+
14+
```@docs
15+
ModelAnalyzer.summarize
16+
```
17+
18+
Alternatively, you can also query the types of issues found in the analysis
19+
and summarize them individually. The following functions are useful for this:
20+
21+
```@docs
22+
ModelAnalyzer.list_of_issue_types
23+
ModelAnalyzer.list_of_issues
24+
```

‎docs/src/feasibility.md

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
2+
# Feasibility Analysis
3+
4+
This module provides functionality to perform feasibility analysis on a JuMP model.
5+
This module follows the main API and is activated by the struct:
6+
7+
```@docs
8+
ModelAnalyzer.Feasibility.Analyzer
9+
```
10+
11+
The analysis will return issues of the abstract type:
12+
13+
```@docs
14+
ModelAnalyzer.Feasibility.AbstractFeasibilityIssue
15+
```
16+
Specifically, the possible issues are:
17+
18+
```@docs
19+
ModelAnalyzer.Feasibility.PrimalViolation
20+
ModelAnalyzer.Feasibility.DualViolation
21+
ModelAnalyzer.Feasibility.ComplemetarityViolation
22+
ModelAnalyzer.Feasibility.DualObjectiveMismatch
23+
ModelAnalyzer.Feasibility.PrimalObjectiveMismatch
24+
ModelAnalyzer.Feasibility.PrimalDualMismatch
25+
ModelAnalyzer.Feasibility.PrimalDualSolverMismatch
26+
```
27+
28+
These issues are saved in the data structure that is returned from the
29+
`ModelAnalyzer.analyze` function:
30+
31+
```@docs
32+
ModelAnalyzer.Feasibility.Data
33+
```

‎docs/src/index.md

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
```@meta
2+
CurrentModule = ModelAnalyzer
3+
DocTestSetup = quote
4+
using ModelAnalyzer
5+
end
6+
```
7+
8+
# ModelAnalyzer.jl
9+
10+
This package provides tools for analyzing (and debugging) [JuMP](https://github.com/jump-dev/JuMP.jl) models.
11+
12+
Three main functionalities are provided:
13+
14+
1. **Numerical Analysis**: Check for numerical issues in the model, such as large and small coefficients,
15+
empty constraints, non-convex quadratic functions.
16+
17+
2. **Feasibility Analysis**: Given an optimized model, or a candidate solution, check if the solutions is
18+
feasible and optimal (when possible). This includes checking the feasibility of the primal model and
19+
also the dual model (if available). Complementary slackness conditions are also checked (if applicable).
20+
21+
3. **Infeasibility Analysis**: Given an unsolved of solved model, three steps are made to check for
22+
infeasibility:
23+
- Check bounds, integers and binaries consistency is also checked at this point.
24+
- Propagate bounds in constraints individually, to check if each constraint is infeasible
25+
given the current variable bounds. This is only done if bounds are ok.
26+
- Run an IIS (Irreducible Inconsistent Subsystem / irreducible infeasible sets)
27+
resolver algorithm to find a minimal infeasible subset of constraints.
28+
This is only done if no issues are found in the previous two steps.
29+
30+
## Installation
31+
32+
You can install the package using the Julia package manager. In the Julia REPL, run:
33+
34+
```julia
35+
using Pkg
36+
Pkg.add("https://github.com/jump-dev/ModelAnalyzer.jl")
37+
```
38+
39+
## Usage
40+
41+
### Basic usage
42+
43+
Here is a simple example of how to use the package:
44+
45+
```julia
46+
using JuMP
47+
using ModelAnalyzer
48+
using HiGHS # or any other supported solver
49+
# Create a simple JuMP model
50+
model = Model(HiGHS.Optimizer)
51+
@variable(model, x >= 0)
52+
@variable(model, y >= 0)
53+
@constraint(model, c1, 2x + 3y == 5)
54+
@constraint(model, c2, x + 2y <= 3)
55+
@objective(model, Min, x + y)
56+
# Optimize the model
57+
optimize!(model)
58+
59+
# either
60+
61+
# Perform a numerical analysis of the model
62+
data = ModelAnalyzer.analyze(ModelAnalyzer.Numerical.Analyzer(), model)
63+
# print report
64+
ModelAnalyzer.summarize(data)
65+
66+
# or
67+
68+
# Check for solution feasibility and optimality
69+
data = ModelAnalyzer.analyze(ModelAnalyzer.Feasibility.Analyzer(), model)
70+
# print report
71+
ModelAnalyzer.summarize(data)
72+
73+
# or
74+
75+
# Infeasibility analysis (if the model was infeasible)
76+
data = ModelAnalyzer.analyze(
77+
ModelAnalyzer.Infeasibility.Analyzer(),
78+
model,
79+
optimizer = HiGHS.Optimizer,
80+
)
81+
# print report
82+
ModelAnalyzer.summarize(data)
83+
```
84+
85+
The `ModelAnalyzer.analyze(...)` function can always take the keyword arguments:
86+
* `verbose = false` to condense the print output.
87+
* `max_issues = n` to limit the maximum number of issues to report for each type.
88+
89+
For certain analysis modes, the `summarize` function can take additional arguments.
90+
91+
### Advanced usage
92+
93+
After any `ModelAnalyzer.analyze(...)` call is performed, the resulting data structure
94+
can be summarized using `ModelAnalyzer.summarize(data)` as show above,
95+
or it can be further inspected programmatically.
96+
97+
```julia
98+
# given a `data` object obtained from `ModelAnalyzer.analyze(...)`
99+
100+
# query the types os issues found in the analysis
101+
list = ModelAnalyzer.list_of_issue_types(data)
102+
103+
# information about the types of issues found can be printed out
104+
ModelAnalyzer.summarize(data, list[1])
105+
106+
# for each issue type, you can get the actual issues found in the analysis
107+
issues = ModelAnalyzer.list_of_issues(data, list[1])
108+
109+
# the list of issues of the given type can be summarized with:
110+
ModelAnalyzer.summarize(data, issues)
111+
112+
# infdividual issues can also be summarized
113+
ModelAnalyzer.summarize(data, issues[1])
114+
```

‎docs/src/infeasibility.md

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
2+
# Infeasibility Analysis
3+
4+
This module provides functionality to perform infeasibility analysis on a JuMP model.
5+
This module follows the main API and is activated by the struct:
6+
7+
```@docs
8+
ModelAnalyzer.Infeasibility.Analyzer
9+
```
10+
11+
The analysis will return issues of the abstract type:
12+
13+
```@docs
14+
ModelAnalyzer.Infeasibility.AbstractInfeasibilitylIssue
15+
```
16+
17+
Specifically, the possible issues are:
18+
19+
```@docs
20+
ModelAnalyzer.Infeasibility.InfeasibleBounds
21+
ModelAnalyzer.Infeasibility.InfeasibleIntegrality
22+
ModelAnalyzer.Infeasibility.InfeasibleConstraintRange
23+
ModelAnalyzer.Infeasibility.IrreducibleInfeasibleSubset
24+
```
25+
26+
These issues are saved in the data structure that is returned from the
27+
`ModelAnalyzer.analyze` function:
28+
29+
```@docs
30+
ModelAnalyzer.Infeasibility.Data
31+
```

‎docs/src/numerical.md

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
2+
# Numerical Analysis
3+
4+
This module provides functionality to perform numerical analysis on a JuMP model.
5+
This module follows the main API and is activated by the struct:
6+
7+
```@docs
8+
ModelAnalyzer.Numerical.Analyzer
9+
```
10+
11+
The analysis will return issues of the abstract type:
12+
13+
```@docs
14+
ModelAnalyzer.Numerical.AbstractNumericalIssue
15+
```
16+
17+
Specifically the possible issues are:
18+
19+
```@docs
20+
ModelAnalyzer.Numerical.VariableNotInConstraints
21+
ModelAnalyzer.Numerical.EmptyConstraint
22+
ModelAnalyzer.Numerical.VariableBoundAsConstraint
23+
ModelAnalyzer.Numerical.DenseConstraint
24+
ModelAnalyzer.Numerical.SmallMatrixCoefficient
25+
ModelAnalyzer.Numerical.LargeMatrixCoefficient
26+
ModelAnalyzer.Numerical.SmallBoundCoefficient
27+
ModelAnalyzer.Numerical.LargeBoundCoefficient
28+
ModelAnalyzer.Numerical.SmallRHSCoefficient
29+
ModelAnalyzer.Numerical.LargeRHSCoefficient
30+
ModelAnalyzer.Numerical.SmallObjectiveCoefficient
31+
ModelAnalyzer.Numerical.LargeObjectiveCoefficient
32+
ModelAnalyzer.Numerical.SmallObjectiveQuadraticCoefficient
33+
ModelAnalyzer.Numerical.LargeObjectiveQuadraticCoefficient
34+
ModelAnalyzer.Numerical.NonconvexQuadraticConstraint
35+
ModelAnalyzer.Numerical.SmallMatrixQuadraticCoefficient
36+
ModelAnalyzer.Numerical.LargeMatrixQuadraticCoefficient
37+
```
38+
39+
These issues are saved in the data structure that is returned from the `ModelAnalyzer.analyze` function:
40+
41+
```@docs
42+
ModelAnalyzer.Numerical.Data
43+
```

‎src/ModelAnalyzer.jl

Lines changed: 53 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,59 @@ abstract type AbstractData end
1111

1212
abstract type AbstractAnalyzer end
1313

14+
"""
15+
analyze(analyzer::AbstractAnalyzer, model::JuMP.Model; kwargs...)
16+
17+
Analyze a JuMP model using the specified analyzer.
18+
Depending on the analyzer, this keyword arguments might vary.
19+
This function will return an instance of `AbstractData` which contains the
20+
results of the analysis that can be further summarized or queried for issues.
21+
22+
See [`summarize`](@ref), [`list_of_issues`](@ref), and
23+
[`list_of_issue_types`](@ref).
24+
"""
25+
function analyze end
26+
27+
"""
28+
summarize([io::IO,] AbstractData; verbose = true, max_issues = typemax(Int), kwargs...)
29+
30+
Print a summary of the analysis results contained in `AbstractData` to the
31+
specified IO stream. If no IO stream is provided, it defaults to `stdout`.
32+
The `verbose` flag controls whether to print detailed information about each
33+
issue (if `true`) or a concise summary (if `false`). The `max_issues` argument
34+
controls the maximum number of issues to display in the summary. If there are
35+
more issues than `max_issues`, only the first `max_issues` will be displayed.
36+
37+
summarize([io::IO,] ::Type{T}; verbose = true) where {T<:AbstractIssue}
38+
39+
This variant allows summarizing information of a specific type `T` (which must
40+
be a subtype of `AbstractIssue`). In the verbose case it will provide a text
41+
explaning the issue. In the non-verbose case it will provide just the issue
42+
name.
43+
44+
summarize([io::IO,] issue::AbstractIssue; verbose = true)
45+
46+
This variant allows summarizing a single issue instance of type `AbstractIssue`.
47+
"""
48+
function summarize end
49+
50+
"""
51+
list_of_issue_types(data::AbstractData)
52+
53+
Return a vector of `DataType` containing the types of issues found in the
54+
analysis results contained in `data`.
55+
"""
56+
function list_of_issue_types end
57+
58+
"""
59+
list_of_issues(data::AbstractData, issue_type::Type{T}) where {T<:AbstractIssue}
60+
61+
Return a vector of instances of `T` (which must be a subtype of `AbstractIssue`)
62+
found in the analysis results contained in `data`. This allows you to retrieve
63+
all instances of a specific issue type from the analysis results.
64+
"""
65+
function list_of_issues end
66+
1467
function summarize(io::IO, ::Type{T}; verbose = true) where {T<:AbstractIssue}
1568
if verbose
1669
return _verbose_summarize(io, T)
@@ -49,10 +102,6 @@ function summarize(data::AbstractData; kwargs...)
49102
return summarize(stdout, data; kwargs...)
50103
end
51104

52-
function analyze end
53-
function list_of_issues end
54-
function list_of_issue_types end
55-
56105
function _verbose_summarize end
57106
function _summarize end
58107

0 commit comments

Comments
 (0)