Skip to content

Commit

Permalink
Update README.md for JuMP documentation (#229)
Browse files Browse the repository at this point in the history
  • Loading branch information
@odow
odow authored May 18, 2023
1 parent ac6078e commit dc01653
Showing 1 changed file with 39 additions and 21 deletions.
60 changes: 39 additions & 21 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
# Alpine, A global solver for non-convex MINLPs <span style="color:black"></span>
# Alpine, a global solver for non-convex MINLPs

STATUS: [![CI](https://github.com/lanl-ansi/Alpine.jl/actions/workflows/ci.yml/badge.svg)](https://github.com/lanl-ansi/Alpine.jl/actions/workflows/ci.yml)
[![CI](https://github.com/lanl-ansi/Alpine.jl/actions/workflows/ci.yml/badge.svg)](https://github.com/lanl-ansi/Alpine.jl/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/lanl-ansi/Alpine.jl/branch/master/badge.svg)](https://codecov.io/gh/lanl-ansi/Alpine.jl)
[![Documentation](https://github.com/lanl-ansi/Alpine.jl/actions/workflows/documentation.yml/badge.svg)](https://lanl-ansi.github.io/Alpine.jl/latest/)
[![version](https://juliahub.com/docs/Alpine/version.svg)](https://juliahub.com/ui/Packages/Alpine/TRSJF)

"ALPINE: glob(AL) o(P)timization for mixed-(I)nteger programs with (N)onlinear (E)quations", is a novel global optimization solver that uses an adaptive, piecewise convexification scheme and constraint programming methods to solve non-convex Mixed-Integer Non-Linear Programs (MINLPs) efficiently. MINLPs are typically "hard" optimization problems which appear in numerous applications (see [MINLPLib.jl](https://github.com/lanl-ansi/MINLPLib.jl)).
ALPINE (glob(AL) o(P)timization for mixed-(I)nteger programs with (N)onlinear (E)quations), is a novel global optimization solver that uses an adaptive, piecewise convexification scheme and constraint programming methods to solve non-convex Mixed-Integer Non-Linear Programs (MINLPs) efficiently. MINLPs are typically "hard" optimization problems which appear in numerous applications (see [MINLPLib.jl](https://github.com/lanl-ansi/MINLPLib.jl)).

Alpine is entirely built upon [JuMP](https://github.com/jump-dev/JuMP.jl) and [MathOptInterface](https://github.com/jump-dev/MathOptInterface.jl) in Julia, which provides incredible flexibility for usage and further development.

Expand All @@ -15,30 +15,45 @@ Alpine globally solves a given MINLP by:

* Performing sequential optimization-based bound tightening (OBBT) and an iterative MIP-based adaptive partitioning scheme via piecewise polyhedral relaxations with a guarantee of global convergence

**Allowable nonlinearities**: Alpine can currently handle MINLPs with polynomials in constraints and/or in the objective. Currently, there is no support for exponential cones and Positive Semi-Definite (PSD) cones in MINLPs. Alpine is also a good fit for subsets of the MINLP family, e.g., Mixed-Integer Quadratically Constrainted Quadradic Programs (MIQCQPs), Non-Linear Programs (NLPs), etc.
## Installation

<!--
**Illustration of Alpine's dynamic partitioning and outer-approximation on simple functions** ([Source](https://arxiv.org/abs/1707.02514))
<p align="center"> <img src="https://github.com/lanl-ansi/Alpine.jl/blob/master/Dynamic_partitions_github.png" width="580" class="centerImage"> </p>
-->
For more details, check out this [video](https://www.youtube.com/watch?v=mwkhiEIS5JA) on Alpine.jl at the [2nd Annual JuMP-dev Workshop](http://www.juliaopt.org/meetings/bordeaux2018/), held at the Institut de Mathématiques de Bordeaux, June 2018.
Install Alpine using the Julia package manager:

<!-- [<img src="https://github.com/lanl-ansi/Alpine.jl/blob/master/alpine_slide.png" width="600" height="350">](https://www.youtube.com/watch?v=mwkhiEIS5JA) -->
```julia
import Pkg
Pkg.add("Alpine")
```

## Use with JuMP

Use Alpine with JuMP as follows:

```julia
using JuMP, Alpine, Ipopt, HiGHS
ipopt = optimizer_with_attributes(Ipopt.Optimizer, "print_level" => 0)
highs = optimizer_with_attributes(HiGHS.Optimizer, "output_flag" => false)
model = Model(
optimizer_with_attributes(
Juniper.Optimizer,
"nlp_solver" => ipopt,
"mip_solver" => highs,
),
)
```

## Installation and Usage
## Documentation

Alpine can be installed through the Julia package manager:
For more details, see the [online documentation](https://lanl-ansi.github.io/Alpine.jl/latest/).

`julia> Pkg.add("Alpine")`
## Support problem types

Developers: Any further development of Alpine can be conducted on a new branch or a forked repo.
Alpine can currently handle MINLPs with polynomials in constraints and/or in the objective. Currently, there is no support for exponential cones and Positive Semi-Definite (PSD) cones in MINLPs. Alpine is also a good fit for subsets of the MINLP family, e.g., Mixed-Integer Quadratically Constrained Quadratic Programs (MIQCQPs), Non-Linear Programs (NLPs), etc.

Check the "test/examples" folder on how to use this package.
For more details, check out this [video](https://www.youtube.com/watch?v=mwkhiEIS5JA) on Alpine.jl at [JuMP-dev 2018](http://www.juliaopt.org/meetings/bordeaux2018/).

## Underlying solvers

Though the MIP-based bounding algorithm implemented in Alpine is quite involved, most of the computational bottleneck arises in the underlying MIP solvers. Since every iteration of Alpine solves an MIP sub-problem, which is typically a convex MILP/MIQCQP, Alpine's run time heavily depends on the run-time of these solvers. For the best performance of Alpine, we recommend using the commercial solver [Gurobi](https://www.gurobi.com), which is avaible [free](https://www.gurobi.com/academia/academic-program-and-licenses/) for academic purposes. However, due to the flexibility offered by [JuMP](https://github.com/jump-dev/JuMP.jl), the following MIP and NLP solvers are supported in Alpine:
Though the MIP-based bounding algorithm implemented in Alpine is quite involved, most of the computational bottleneck arises in the underlying MIP solvers. Since every iteration of Alpine solves an MIP sub-problem, which is typically a convex MILP/MIQCQP, Alpine's run time heavily depends on the run-time of these solvers. For the best performance of Alpine, we recommend using the commercial solver [Gurobi](https://www.gurobi.com), which is available [free](https://www.gurobi.com/academia/academic-program-and-licenses/) for academic purposes. However, due to the flexibility offered by [JuMP](https://github.com/jump-dev/JuMP.jl), the following MIP and NLP solvers are supported in Alpine:


| Solver | Julia Package |
Expand All @@ -53,15 +68,17 @@ Though the MIP-based bounding algorithm implemented in Alpine is quite involved,
| [HiGHS](https://highs.dev/) | [HiGHS.jl](https://github.com/jump-dev/HiGHS.jl)

## Bug reports and support
Please report any issues via the Github **[issue tracker]**. All types of issues are welcome and encouraged; this includes bug reports, documentation typos, feature requests, etc.

[issue tracker]: https://github.com/lanl-ansi/Alpine.jl/issues
Please report any issues via the GitHub [issue tracker](https://github.com/lanl-ansi/Alpine.jl/issues).
All types of issues are welcome and encouraged; this includes bug reports, documentation typos, feature requests, etc.

## Challenging Problems

We are seeking out hard benchmark instances for MINLPs. Please get in touch either by opening an issue or [privately](https://harshangrjn.github.io/#contact) if you would like to share any hard instances.

## Citing Alpine
If you find Alpine useful in your work, we kindly request that you cite the following papers ([pdf](http://harshangrjn.github.io/pdf/JOGO_2018.pdf), [pdf](http://harshangrjn.github.io/pdf/CP_2016.pdf))

If you find Alpine useful in your work, we kindly request that you cite the following papers ([PDF](http://harshangrjn.github.io/pdf/JOGO_2018.pdf), [PDF](http://harshangrjn.github.io/pdf/CP_2016.pdf))
```bibtex
@article{alpine_JOGO2019,
title = {An adaptive, multivariate partitioning algorithm for global optimization of nonconvex programs},
Expand All @@ -82,6 +99,7 @@ If you find Alpine useful in your work, we kindly request that you cite the foll
doi = {10.1007/978-3-319-44953-1_24},
}
```

If you find the underlying piecewise polyhedral formulations implemented in Alpine useful in your work, we kindly request that you cite the following papers ([link-1](https://doi.org/10.1016/j.orl.2020.12.002), [link-2](http://www.optimization-online.org/DB_HTML/2022/07/8974.html)):
```bibtex
@article{alpine_ORL2021,
Expand All @@ -101,4 +119,4 @@ If you find the underlying piecewise polyhedral formulations implemented in Alpi
eprinttype={Optimization Online},
date={2022}
}
```
```

0 comments on commit dc01653

Please sign in to comment.