Skip to content

Commit

Permalink
README and documentation changes
Browse files Browse the repository at this point in the history
  • Loading branch information
@DimitriAlston
DimitriAlston authored Nov 6, 2023
2 parents 90d449c + 213d32c commit 75b09a9
Show file tree
Hide file tree
Showing 47 changed files with 891 additions and 723 deletions.
2 changes: 1 addition & 1 deletion .gitignore
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,4 +3,4 @@
*.jl.mem
*.mem
*.cov
docs/build/
docs/build/
2 changes: 1 addition & 1 deletion NEWS.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,7 @@
## [v0.7.0](https://github.com/PSORLab/EAGO.jl/releases/tag/v0.7.0) (March 28, 2022)

- Added envelopes of activation functions: `xabsx`, `logcosh`
- Added `estimator_extrema`, `estimator_under`, and `estimator_over` functions for McCormick relaxations.
- Added variations of `estimator_extrema`, `estimator_under`, and `estimator_over` functions to EAGO for bilinear relaxations.
- Moved various functions and related structures to new files.
- Added `RelaxCache` structure to hold relaxed problem information.
- Updated forward and reverse propagation.
Expand Down
120 changes: 63 additions & 57 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,31 +4,42 @@

EAGO is an open-source development environment for **robust and global optimization** in Julia.

| **Documentation** | **Linux/OS/Windows** | **Persistent DOI** |
|:-----------------------------------------------------------------:|:-----------------------------------------------------------------------------------------------:|:-----------------------------------------------------------------------------------------------:|
| [![](https://img.shields.io/badge/docs-stable-blue.svg)](https://PSORLab.github.io/EAGO.jl/stable) [![](https://img.shields.io/badge/docs-latest-blue.svg)](https://PSORLab.github.io/EAGO.jl/dev) | [![Build Status](https://github.com/PSORLab/EAGO.jl/workflows/CI/badge.svg?branch=master)](https://github.com/PSORLab/EAGO.jl/actions?query=workflow%3ACI) | [![DOI](https://zenodo.org/badge/108954118.svg)](https://zenodo.org/badge/latestdoi/108954118) |
| **PSOR Lab** | **Build Status** |
|:------------:|:-----------------------------------------------------------------------------------------------:|
| [![](https://img.shields.io/badge/Developed_by-PSOR_Lab-342674)](https://psor.uconn.edu/) | [![Build Status](https://github.com/PSORLab/EAGO.jl/workflows/CI/badge.svg?branch=master)](https://github.com/PSORLab/EAGO.jl/actions?query=workflow%3ACI) [![codecov](https://codecov.io/gh/PSORLab/EAGO.jl/branch/master/graph/badge.svg)](https://codecov.io/gh/PSORLab/EAGO.jl)|

| **Coverage** | **Chat** |
|:------------:|:------------:|
| [![codecov](https://codecov.io/gh/PSORLab/EAGO.jl/branch/master/graph/badge.svg)](https://codecov.io/gh/PSORLab/EAGO.jl) | [![Join the chat at https://gitter.im/EAGODevelopment](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/EAGODevelopment/Lobby?utm_source=share-link&utm_medium=link&utm_campaign=share-link)
| **Documentation** | **Persistent DOI** |
|:-----------------------------------------------------------------:|:-----------------------------------------------------------------------------------------------:|
| [![](https://img.shields.io/badge/docs-stable-blue.svg)](https://PSORLab.github.io/EAGO.jl/stable) [![](https://img.shields.io/badge/docs-latest-blue.svg)](https://PSORLab.github.io/EAGO.jl/dev) | [![DOI](https://zenodo.org/badge/108954118.svg)](https://zenodo.org/badge/latestdoi/108954118) |

| **Chat** |
|:------------:|
| [![Join the chat at https://gitter.im/EAGODevelopment](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/EAGODevelopment/Lobby?utm_source=share-link&utm_medium=link&utm_campaign=share-link)

## EAGO's Optimizer Capabilities

EAGO is a deterministic global optimizer designed to address a wide variety of optimization problems, emphasizing nonlinear programs (NLPs), by propagating McCormick relaxations along the factorable structure of each expression in the NLP. Most operators supported by modern automatic differentiation (AD) packages (e.g., `+`, `sin`, `cosh`) are supported by EAGO and a number utilities for sanitizing native Julia code and generating relaxations on a wide variety of user-defined functions have been included. Currently, EAGO supports problems that have a priori variable bounds defined and have differentiable constraints. That is, problems should be specified in the generic form below:

<p align="center">
<img src="https://github.com/PSORLab/EAGO.jl/blob/master/images/OptForm.svg" width="30%" height="30%">
$$
\begin{align*}
f^{\*} = & \min_{\mathbf y \in Y \subset \mathbb R^{n_{y}}} f(\mathbf y) \\
{\rm s.t.} \\;\\; & \mathbf h(\mathbf y) = \mathbf 0 \\
& \mathbf g(\mathbf y) \leq \mathbf 0 \\
& Y = [\mathbf y^{\mathbf L}, \mathbf y^{\mathbf U}] \in \mathbb{IR}^{n} \\
& \qquad \mathbf y^{\mathbf L}, \mathbf y^{\mathbf U} \in \mathbb R^{n}
\end{align*}
$$

## EAGO's Relaxations

For each nonlinear term, EAGO makes use of factorable representations to construct bounds and relaxations. In the case of `f(x) = x(x-5)sin(x)`, a list is generated and rules for constructing McCormick relaxations are used to formulate relaxations in the original decision space, *X* [[1](#references)]:
For each nonlinear term, EAGO makes use of factorable representations to construct bounds and relaxations. In the case of $f(x) = x (x - 5) \sin(x)$, a list is generated and rules for constructing McCormick relaxations are used to formulate relaxations in the original decision space, $X$ [[1](#references)]:

- *v*<sub>1</sub> = *x*
- *v*<sub>2</sub> = *v*<sub>1</sub> - 5
- *v*<sub>3</sub> = sin(*v*<sub>1</sub>)
- *v*<sub>4</sub> = *v*<sub>1</sub>*v*<sub>2</sub>
- *v*<sub>5</sub> = *v*<sub>4</sub>*v*<sub>3</sub>
- f(x) = *v*<sub>5</sub>
- $v_{1} = x$
- $v_{2} = v_{1} - 5$
- $v_{3} = \sin(v_{1})$
- $v_{4} = v_{1} v_{2}$
- $v_{5} = v_{4} v_{3}$
- $f(x) = v_{5}$

<p align="center">
<img src="https://github.com/PSORLab/EAGO.jl/blob/master/docs/src/mccormick/Figure_1.png" width="60%" height="60%">
Expand All @@ -39,8 +50,20 @@ Either these original relaxations, differentiable McCormick relaxations [[2](#re

EAGO makes use of the JuMP algebraic modeling language to improve the user's experience in setting up optimization models. Consider the familiar "process" problem instance [[5](#references)]:

<p align="center">
<img src="https://github.com/PSORLab/EAGO.jl/blob/master/images/ProcessFormulation.svg" width="60%" height="60%">
$$
\begin{align*}
& \max_{\mathbf x \in X} 0.063 x_{4} x_{7} - 5.04 x_{1} - 0.035 x_{2} - 10 x_{3} - 3.36 x_{2} \\
{\rm s.t.} \\;\\; & x_{1} (1.12 + 0.13167 x_{8} - 0.00667 x_{8}^{2}) + x_{4} = 0 \\
& -0.001 x_{4} x_{9} x_{6} / (98 - x_{6}) + x_{3} = 0 \\
& -(1.098 x_{8} - 0.038 x_{8}^{2}) - 0.325 x_{6} + x_{7} = 0 \\
& -(x_{2} + x_{5}) / x_{1} + x_{8} = 0 \\
& -x_{1} + 1.22 x_{4} - x_{5} = 0 \\
& x_{9} + 0.222 x_{10} - 35.82 = 0 \\
& -3.0 x_{7} + x_{10} + 133.0 = 0 \\
& X = [10, 2000] \times [0, 16000] \times [0, 120] \times [0, 5000] \\
& \qquad \times [0, 2000] \times [85, 93] \times [90,9 5] \times [3, 12] \times [1.2, 4] \times [145, 162]
\end{align*}
$$


This model can be formulated using JuMP code as:
Expand All @@ -56,38 +79,22 @@ xU = [2000.0; 16000.0; 120.0; 5000.0; 2000.0; 93.0; 95.0; 12.0; 4.0; 162.0]
@variable(m, xL[i] <= x[i=1:10] <= xU[i])

# Define nonlinear constraints
@NLconstraint(m, e1, -x[1]*(1.12+0.13167*x[8]-0.00667* (x[8])^2)+x[4] == 0.0)
@NLconstraint(m, e3, -0.001*x[4]*x[9]*x[6]/(98-x[6])+x[3] == 0.0)
@NLconstraint(m, e4, -(1.098*x[8]-0.038* (x[8])^2)-0.325*x[6]+x[7] == 57.425)
@NLconstraint(m, e5, -(x[2]+x[5])/x[1]+x[8] == 0.0)
@NLconstraint(m, e1, -x[1]*(1.12 + 0.13167*x[8] - 0.00667*(x[8])^2) + x[4] == 0.0)
@NLconstraint(m, e3, -0.001*x[4]*x[9]*x[6]/(98.0 - x[6]) + x[3] == 0.0)
@NLconstraint(m, e4, -(1.098*x[8] - 0.038*(x[8])^2) - 0.325*x[6] + x[7] == 57.425)
@NLconstraint(m, e5, -(x[2] + x[5])/x[1] + x[8] == 0.0)

# Define linear constraints
@constraint(m, e2, -x[1]+1.22*x[4]-x[5] == 0.0)
@constraint(m, e6, x[9]+0.222*x[10] == 35.82)
@constraint(m, e7, -3*x[7]+x[10] == -133.0)
@constraint(m, e2, -x[1] + 1.22*x[4] - x[5] == 0.0)
@constraint(m, e6, x[9] + 0.222*x[10] == 35.82)
@constraint(m, e7, -3.0*x[7] + x[10] == -133.0)

# Define nonlinear objective
@NLobjective(m, Max, 0.063*x[4]*x[7] - 5.04*x[1] - 0.035*x[2] - 10*x[3] - 3.36*x[5])

# Solve the optimization problem
JuMP.optimize!(m)
```
<!--
$
\begin{align}
\max_{x \in X}{0.063x_4x_7 - 5.04x_1 - 0.035x_2 - 10x_3 - 3.36x_2} & \\
s.t. \; x_1(1.12 + 0.13167x_8-0.00667x_8^2) + x_4 &= 0 \\
-0.001x_4x_9x_6/(98-x_6)+x_3 &= 0 \\
-(1.098x_8 - 0.038x_8^2) - 0.325x_6 + x_7 &= 0 \\
-(x_2 + x_5)/x_1 + x_8 &= 0 \\
-x_1 + 1.22x_4 - x_5 &= 0 \\
x_9 + 0.222x_{10} - 35.82 &= 0 \\
-3.0x_7 + x_{10} + 133.0 &= 0
\end{align}
$
where $X= [10, 2000] \times[0, 16000] \times[0, 120] \times[0, 5000]$
$\qquad \times[0, 2000] \times[85, 93] \times [90,95] \times [3,12] \times [1.2, 4] \times [145, 162]$
-->

Special handling has been included for linear/quadratic functions defined using the `@constraint` macro in JuMP and these can generally be expected to perform better than specifying quadratic or linear terms with the `@NLconstraint` macro.

Expand Down Expand Up @@ -115,12 +122,11 @@ The EAGO package has numerous features: a solver accessible from JuMP/MathOptInt
- Models, nodes, expressions, constraints, and operators are now compatible with MOI.
- Added logic and comparison operators to `EAGO.OperatorRegistry`.

For a full list of EAGO release news, click [here](https://psorlab.github.io/EAGO.jl/stable/news/).
For a full list of EAGO release news, click [here](https://github.com/PSORLab/EAGO.jl/blob/master/NEWS.md).

## Installing EAGO

EAGO is a registered Julia package and it can be installed using the Julia package manager.
From the Julia REPL, type `]` to enter the Package manager (Pkg) mode and run the following command:
EAGO is a registered Julia package and it can be installed using the Julia package manager. From the Julia REPL, type `]` to enter the Package manager (Pkg) mode and run the following command:

```jldoctest
pkg> add EAGO
Expand All @@ -132,8 +138,7 @@ Currently, EAGO is compatible with version 1.12 of JuMP. This allows a replicati
pkg> add JuMP
```

EAGO v0.8.1 is the current tagged version and requires Julia 1.6+ for full functionality (however Julia 1.0+ versions support partial functionality). Use with version 1.8 is recommended as the majority of in-house testing has occurred using this version of Julia. The user is directed to the [High-Performance Configuration](https://psorlab.github.io/EAGO.jl/optimizer/high_performance/) for instructions on how to install a high performance version of EAGO (rather than the basic entirely open-source version).
If any issues are encountered when loading EAGO (or when using it), please submit an issue using the GitHub [issue tracker](https://github.com/PSORLab/EAGO.jl/issues).
EAGO v0.8.1 is the current tagged version and requires Julia 1.6+ for full functionality (however Julia 1.0+ versions support partial functionality). Use with version 1.8 is recommended as the majority of in-house testing has occurred using this version of Julia. The user is directed to the [High-Performance Configuration](https://psorlab.github.io/EAGO.jl/optimizer/high_performance/) for instructions on how to install a high performance version of EAGO (rather than the basic entirely open-source version). If any issues are encountered when loading EAGO (or when using it), please submit an issue using the GitHub [issue tracker](https://github.com/PSORLab/EAGO.jl/issues).

## Bug Reporting, Support, and Feature Requests

Expand All @@ -155,15 +160,17 @@ Please report bugs or feature requests by opening an issue using the GitHub [iss
## Citing EAGO

Please cite the following paper when using EAGO. In plain text form this is:

```
M. E. Wilhelm & M. D. Stuber (2022) EAGO.jl: easy advanced global optimization in Julia,
Optimization Methods and Software, 37:2, 425-450, DOI: 10.1080/10556788.2020.1786566
Wilhelm, M.E. and Stuber, M.D. EAGO.jl: easy advanced global optimization in Julia.
Optimization Methods and Software. 37(2): 425-450 (2022). DOI: 10.1080/10556788.2020.1786566
```

A BibTeX entry is given below and a corresponding .bib file is given in citation.bib.

```bibtex
@article{doi:10.1080/10556788.2020.1786566,
author = {M. E. Wilhelm and M. D. Stuber},
author = {Wilhelm, M.E. and Stuber, M.D.},
title = {EAGO.jl: easy advanced global optimization in Julia},
journal = {Optimization Methods and Software},
volume = {37},
Expand All @@ -179,15 +186,14 @@ eprint = {https://doi.org/10.1080/10556788.2020.1786566}

## Related Packages

- [ValidatedNumerics.jl](https://github.com/JuliaIntervals/ValidatedNumerics.jl): A Julia library for validated interval calculations, including basic interval extensions, constraint programming, and interval contractors
- [MAiNGO](http://swmath.org/software/27878): An open-source mixed-integer nonlinear programming package in C++ that utilizes MC++ for relaxations.
- [MC++](https://omega-icl.github.io/mcpp/): A mature McCormick relaxation package in C++ that also includes McCormick-Taylor, Chebyshev
Polyhedral and Ellipsoidal arithmetics.
- [ValidatedNumerics.jl](https://github.com/JuliaIntervals/ValidatedNumerics.jl): A Julia library for validated interval calculations, including basic interval extensions, constraint programming, and interval contractors
- [MAiNGO](https://avt-svt.pages.rwth-aachen.de/public/maingo/): An open-source mixed-integer nonlinear programming package in C++ that utilizes MC++ for relaxations
- [MC++](https://github.com/coin-or/MCpp): A mature McCormick relaxation package in C++ that also includes McCormick-Taylor, Chebyshev Polyhedral, and Ellipsoidal arithmetics

## References

1. A. Mitsos, B. Chachuat, and P. I. Barton. **McCormick-based relaxations of algorithms.** *SIAM Journal on Optimization*, 20(2):573–601, 2009.
2. K.A. Khan, HAJ Watson, P.I. Barton. **Differentiable McCormick relaxations.** *Journal of Global Optimization*, 67(4):687-729 (2017).
3. Stuber, M.D., Scott, J.K., Barton, P.I.: **Convex and concave relaxations of implicit functions.** *Optim. Methods Softw.* 30(3), 424–460 (2015)
4. A., Wechsung JK Scott, HAJ Watson, and PI Barton. **Reverse propagation of McCormick relaxations.** *Journal of Global Optimization* 63(1):1-36 (2015).
5. Bracken, Jerome and McCormick, Garth P. **Selected Applications of Nonlinear Programming**, John Wiley and Sons, New York, 1968.
1. Mitsos, A., Chachuat, B., and Barton, P.I. **McCormick-based relaxations of algorithms.** *SIAM Journal on Optimization*. 20(2): 573–601 (2009).
2. Khan, K.A., Watson, H.A.J., and Barton, P.I. **Differentiable McCormick relaxations.** *Journal of Global Optimization*. 67(4): 687-729 (2017).
3. Stuber, M.D., Scott, J.K., and Barton, P.I.: **Convex and concave relaxations of implicit functions.** *Optimization Methods and Software* 30(3): 424–460 (2015).
4. Wechsung, A., Scott, J.K., Watson, H.A.J., and Barton, P.I. **Reverse propagation of McCormick relaxations.** *Journal of Global Optimization* 63(1): 1-36 (2015).
5. Bracken, J., and McCormick, G.P. *Selected Applications of Nonlinear Programming.* John Wiley and Sons, New York (1968).
31 changes: 4 additions & 27 deletions citation.bib
View file
Original file line number Diff line number Diff line change
@@ -1,12 +1,5 @@







@article{doi:10.1080/10556788.2020.1786566,
author = {M. E. Wilhelm and M. D. Stuber},
author = {Wilhelm, M.E. and Stuber, M.D.},
title = {EAGO.jl: easy advanced global optimization in Julia},
journal = {Optimization Methods and Software},
volume = {37},
Expand All @@ -15,22 +8,6 @@ @article{doi:10.1080/10556788.2020.1786566
year = {2022},
publisher = {Taylor & Francis},
doi = {10.1080/10556788.2020.1786566},

URL = {
https://doi.org/10.1080/10556788.2020.1786566
},
eprint = {
https://doi.org/10.1080/10556788.2020.1786566
}

}


URL = {https://doi.org/10.1080/10556788.2020.1786566},
eprint = {https://doi.org/10.1080/10556788.2020.1786566}
}
2 changes: 1 addition & 1 deletion docs/Project.toml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,5 +9,5 @@ McCormick = "53c679d3-6890-5091-8386-c291e8c8aaa1"
StaticArrays = "90137ffa-7385-5640-81b9-e52037218182"

[compat]
Documenter = "0.27.9, 0.28"
JuMP = "1.12"
Documenter = "~1"
Loading

0 comments on commit 75b09a9

Please sign in to comment.