Skip to content

Commit 2c008ee

Browse files
odowodow
authored
Update README (#447)
1 parent af5848d commit 2c008ee

File tree

1 file changed

+110
-83
lines changed

1 file changed

+110
-83
lines changed

‎README.md‎

Lines changed: 110 additions & 83 deletions
Original file line numberDiff line numberDiff line change
@@ -1,39 +1,82 @@
1-
# Pajarito
1+
# Pajarito.jl
22

3-
Pajarito is a **mixed-integer convex programming** (MICP) solver package written in [Julia](http://julialang.org/).
4-
MICP problems are convex except for restrictions that some variables take binary or integer values.
3+
Pajarito is a **mixed-integer convex programming** (MICP) solver package written
4+
in [Julia](http://julialang.org/).
55

6-
Pajarito solves MICP problems in conic form, by constructing sequential polyhedral outer approximations of the conic feasible set.
7-
The underlying algorithm has theoretical finite-time convergence under reasonable assumptions.
8-
Pajarito accesses state-of-the-art MILP solvers and continuous conic solvers through MathOptInterface.
6+
MICP problems are convex except for restrictions that some variables take binary
7+
or integer values.
98

10-
For algorithms that use a derivative-based nonlinear programming (NLP) solver (e.g. Ipopt) instead of a conic solver, use [Pavito](https://github.com/jump-dev/Pavito.jl).
11-
Pavito is a convex mixed-integer nonlinear programming (convex MINLP) solver.
12-
As Pavito relies on gradient cuts, it can fail near points of nondifferentiability.
13-
Pajarito may be more robust than Pavito on nonsmooth problems.
9+
Pajarito solves MICP problems in conic form, by constructing sequential
10+
polyhedral outer approximations of the conic feasible set.
1411

15-
## Installation and usage
12+
The underlying algorithm has theoretical finite-time convergence under
13+
reasonable assumptions.
1614

17-
Pajarito can be installed through the Julia package manager:
15+
Pajarito accesses state-of-the-art MILP solvers and continuous conic solvers
16+
through [MathOptInterface](https://github.com/jump-dev/MathOptInterface.jl).
17+
18+
## Pavito
19+
20+
For algorithms that use a derivative-based nonlinear programming (NLP) solver
21+
(for example, Ipopt) instead of a conic solver, use [Pavito](https://github.com/jump-dev/Pavito.jl).
22+
23+
Pavito is a convex mixed-integer nonlinear programming (convex MINLP) solver.
24+
Because Pavito relies on gradient cuts, it can fail near points of
25+
non-differentiability. Pajarito may be more robust than Pavito on non-smooth
26+
problems.
27+
28+
## License
29+
30+
`Pajarito.jl` is licensed under the [MPL 2.0 license](https://github.com/jump-dev/Pajarito.jl/blob/master/LICENSE.md).
31+
32+
## Installation
33+
34+
Install Pajarito using `Pkg.add`:
1835
```julia
1936
import Pkg
2037
Pkg.add("Pajarito")
2138
```
2239

23-
There are several convenient ways to model MICPs in Julia and access Pajarito.
24-
[JuMP](https://github.com/jump-dev/JuMP.jl) and [Convex.jl](https://github.com/jump-dev/Convex.jl) are algebraic modeling interfaces, while [MathOptInterface](https://github.com/jump-dev/MathOptInterface.jl) is a lower-level interface.
25-
2640
## MIP and continuous solvers
2741

28-
The algorithm implemented by Pajarito itself is relatively simple, and most of the hard work is performed by the MIP outer approximation (OA) solver and the continuous conic solver.
29-
**The performance of Pajarito depends on these two types of solvers.**
42+
The algorithm implemented by Pajarito itself is relatively simple, and most of
43+
the hard work is performed by the MIP outer approximation (OA) solver and the
44+
continuous conic solver.
45+
46+
Therefore, in addition to installing Pajarito, you must also install a
47+
mixed-integer linear programming solver and a continuous conic solver.
48+
49+
**The performance of Pajarito depends on these two types of solvers.**
50+
51+
The OA solver (typically a mixed-integer linear solver) is specified by the
52+
`oa_solver` option. You must first load the Julia package that provides this
53+
solver, for example, `using Gurobi`. The continuous conic solver is specified by
54+
the `conic_solver` option.
3055

31-
The OA solver (typically a mixed-integer linear solver) is specified by the `oa_solver` option.
32-
You must first load the Julia package that provides this solver, e.g. `using Gurobi`.
33-
The continuous conic solver is specified by the `conic_solver` option.
3456
See JuMP's [list of supported solvers](https://jump.dev/JuMP.jl/stable/installation/#Supported-solvers).
3557

36-
## Solver options
58+
## Use with JuMP
59+
60+
To use Pajarito with JuMP, use:
61+
```julia
62+
using JuMP, Pajarito, HiGHS, Hypatia
63+
model = Model(
64+
optimizer_with_attributes(
65+
Pajarito.Optimizer,
66+
"oa_solver" => optimizer_with_attributes(
67+
HiGHS.Optimizer,
68+
MOI.Silent() => true,
69+
"mip_feasibility_tolerance" => 1e-8,
70+
"mip_rel_gap" => 1e-6,
71+
),
72+
"conic_solver" =>
73+
optimizer_with_attributes(Hypatia.Optimizer, MOI.Silent() => true),
74+
)
75+
)
76+
set_attribute(model, "time_limit", 60)
77+
```
78+
79+
## Options
3780

3881
We list Pajarito's options below.
3982

@@ -43,85 +86,69 @@ We list Pajarito's options below.
4386
- `tol_abs_gap::Float64` is the absolute optimality gap tolerance
4487
- `time_limit::Float64` sets the time limit (in seconds)
4588
- `iteration_limit::Int` sets the iteration limit (for the iterative method)
46-
- `use_iterative_method::Union{Nothing,Bool}` toggles the iterative algorithm; if `nothing' is specified, Pajarito defaults to the OA-solver-driven (single tree) algorithm if lazy callbacks are supported by the OA solver
47-
- `use_extended_form::Bool` toggles the use of extended formulations (e.g. for the second-order cone)
89+
- `use_iterative_method::Union{Nothing,Bool}` toggles the iterative algorithm;
90+
if `nothing` is specified, Pajarito defaults to the OA-solver-driven (single
91+
tree) algorithm if lazy callbacks are supported by the OA solver
92+
- `use_extended_form::Bool` toggles the use of extended formulations for the
93+
second-order cone
4894
- `solve_relaxation::Bool` toggles solution of the continuous conic relaxation
4995
- `solve_subproblems::Bool` toggles solution of the continuous conic subproblems
5096
- `use_init_fixed_oa::Bool` toggles initial fixed OA cuts
5197
- `oa_solver::Union{Nothing,MOI.OptimizerWithAttributes}` is the OA solver
5298
- `conic_solver::Union{Nothing,MOI.OptimizerWithAttributes}` is the conic solver
5399

54100
**Pajarito may require tuning of parameters to improve convergence.**
101+
55102
For example, it often helps to tighten the OA solver's integrality tolerance.
56103
OA solver and conic solver options must be specified directly to those solvers.
57104

58-
Note: if `solve_subproblems` is true, Pajarito usually returns a solution constructed from one of the conic solver's feasible solutions; since the conic solver is not subject to the same feasibility tolerances as the OA solver, Pajarito's solution will not necessarily satisfy `tol_feas`.
59-
60-
## JuMP example
61-
62-
```julia
63-
using JuMP, Pajarito, HiGHS, Hypatia
105+
Note: if `solve_subproblems` is true, Pajarito usually returns a solution
106+
constructed from one of the conic solver's feasible solutions; since the conic
107+
solver is not subject to the same feasibility tolerances as the OA solver,
108+
Pajarito's solution will not necessarily satisfy `tol_feas`.
64109

65-
# setup solvers
66-
oa_solver = optimizer_with_attributes(HiGHS.Optimizer,
67-
MOI.Silent() => true,
68-
"mip_feasibility_tolerance" => 1e-8,
69-
"mip_rel_gap" => 1e-6,
70-
)
71-
conic_solver = optimizer_with_attributes(Hypatia.Optimizer,
72-
MOI.Silent() => true,
73-
)
74-
opt = optimizer_with_attributes(Pajarito.Optimizer,
75-
"time_limit" => 60,
76-
"oa_solver" => oa_solver,
77-
"conic_solver" => conic_solver,
78-
)
110+
## Cone interface
79111

80-
# setup model
81-
model = Model(opt)
82-
@variable(model, x, Int)
83-
@variable(model, y)
84-
@variable(model, z, Int)
85-
@constraint(model, z <= 2.5)
86-
@objective(model, Min, x + 2y)
87-
@constraint(model, [z, x, y] in SecondOrderCone())
88-
89-
# solve
90-
optimize!(model)
91-
@show termination_status(model) # MOI.OPTIMAL
92-
@show primal_status(model) # MOI.FEASIBLE_POINT
93-
@show objective_value(model) # -1 - 2 * sqrt(3)
94-
@show value(x) # -1
95-
@show value(y) # -sqrt(3)
96-
@show value(z) # 2
97-
```
112+
Pajarito has a generic cone interface (see the [cones folder](src/Cones/)) that
113+
allows the user to add support for new convex cones.
98114

99-
## Cone interface
115+
To illustrate, in the experimental package [PajaritoExtras](https://github.com/chriscoey/PajaritoExtras.jl)
116+
we have extended Pajarito by adding support for several cones recognized by
117+
[Hypatia.jl](https://github.com/chriscoey/Hypatia.jl) (a continuous conic solver
118+
with its own generic cone interface).
100119

101-
Pajarito has a generic cone interface (see the [cones folder](src/Cones/)) that allows the user to add support for new convex cones.
102-
To illustrate, in the experimental package [PajaritoExtras](https://github.com/chriscoey/PajaritoExtras.jl) we have extended Pajarito by adding support for several cones recognized by [Hypatia.jl](https://github.com/chriscoey/Hypatia.jl) (a continuous conic solver with its own generic cone interface).
103-
The examples folder of PajaritoExtras also contains many applied mixed-integer convex problems that are solved using Pajarito.
120+
The examples folder of PajaritoExtras also contains many applied mixed-integer
121+
convex problems that are solved using Pajarito.
104122

105123
## Bug reports and support
106124

107-
Please report any issues via the Github [issue tracker](https://github.com/jump-dev/Pajarito.jl/issues).
108-
All types of issues are welcome and encouraged; this includes bug reports, documentation typos, feature requests, etc.
109-
The [Optimization (Mathematical)](https://discourse.julialang.org/c/domain/opt) category on Discourse is appropriate for general discussion.
125+
Please report any issues via the GitHub
126+
[issue tracker](https://github.com/jump-dev/Pajarito.jl/issues).
127+
128+
All types of issues are welcome and encouraged; this includes bug reports,
129+
documentation typos, and feature requests. The [Optimization (Mathematical)](https://discourse.julialang.org/c/domain/opt)
130+
category on Discourse is appropriate for general discussion.
110131

111132
## References
112133

113-
If you find Pajarito useful in your work, we kindly request that you cite the following paper ([arXiv preprint](http://arxiv.org/abs/1808.05290)), which is recommended reading for advanced users:
114-
115-
@article{CoeyLubinVielma2020,
116-
title={Outer approximation with conic certificates for mixed-integer convex problems},
117-
author={Coey, Chris and Lubin, Miles and Vielma, Juan Pablo},
118-
journal={Mathematical Programming Computation},
119-
volume={12},
120-
number={2},
121-
pages={249--293},
122-
year={2020},
123-
publisher={Springer}
124-
}
125-
126-
Note this paper describes a legacy MathProgBase version of Pajarito, which is available on the [`mathprogbase` branch](https://github.com/jump-dev/Pajarito.jl/tree/mathprogbase) of this repository.
127-
Starting with version 0.8.0, Pajarito only supports MathOptInterface.
134+
If you find Pajarito useful in your work, we kindly request that you cite the
135+
following paper ([arXiv preprint](http://arxiv.org/abs/1808.05290)), which is
136+
recommended reading for advanced users:
137+
138+
```
139+
@article{CoeyLubinVielma2020,
140+
title={Outer approximation with conic certificates for mixed-integer convex problems},
141+
author={Coey, Chris and Lubin, Miles and Vielma, Juan Pablo},
142+
journal={Mathematical Programming Computation},
143+
volume={12},
144+
number={2},
145+
pages={249--293},
146+
year={2020},
147+
publisher={Springer}
148+
}
149+
```
150+
151+
Note this paper describes a legacy MathProgBase version of Pajarito, which is
152+
available on the [`mathprogbase` branch](https://github.com/jump-dev/Pajarito.jl/tree/mathprogbase)
153+
of this repository. Starting with version v0.8.0, Pajarito supports
154+
MathOptInterface instead of MathProgBase.

0 commit comments

Comments
 (0)