diff --git a/README.md b/README.md index 38ce3052..2620358d 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,11 @@ -# Alpine, A global solver for non-convex MINLPs +# 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. @@ -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 - -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: - +```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 | @@ -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}, @@ -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, @@ -101,4 +119,4 @@ If you find the underlying piecewise polyhedral formulations implemented in Alpi eprinttype={Optimization Online}, date={2022} } -``` \ No newline at end of file +```