From dc4f2a8ebb83d1bc21fac6fdaf3dc9da6eea299a Mon Sep 17 00:00:00 2001 From: Oscar Dowson Date: Wed, 11 Sep 2024 19:54:47 +1200 Subject: [PATCH] [docs] restructure nonlinear optimization tutorials (#3823) --- docs/make.jl | 8 +++--- docs/src/changelog.md | 2 +- docs/src/tutorials/nonlinear/classifiers.jl | 4 +-- .../tutorials/nonlinear/complementarity.jl | 7 +++-- docs/src/tutorials/nonlinear/introduction.md | 10 +++---- .../tutorials/nonlinear/nested_problems.jl | 18 ++++++++----- docs/src/tutorials/nonlinear/operator_ad.jl | 4 +++ docs/src/tutorials/nonlinear/portfolio.jl | 4 +-- .../tutorials/nonlinear/querying_hessians.jl | 2 ++ .../src/tutorials/nonlinear/rocket_control.jl | 4 ++- .../tutorials/nonlinear/simple_examples.jl | 7 +++-- .../space_shuttle_reentry_trajectory.jl | 27 ++++++++++++------- .../tutorials/nonlinear/tips_and_tricks.jl | 14 +++++++--- .../nonlinear/user_defined_hessians.jl | 2 ++ 14 files changed, 71 insertions(+), 42 deletions(-) diff --git a/docs/make.jl b/docs/make.jl index a86b18224f8..7c1b9b7907b 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -349,16 +349,16 @@ const _PAGES = [ "Nonlinear programs" => [ "tutorials/nonlinear/introduction.md", "tutorials/nonlinear/simple_examples.md", - "tutorials/nonlinear/portfolio.md", - "tutorials/nonlinear/rocket_control.md", - "tutorials/nonlinear/space_shuttle_reentry_trajectory.md", "tutorials/nonlinear/tips_and_tricks.md", + "tutorials/nonlinear/operator_ad.md", "tutorials/nonlinear/user_defined_hessians.md", "tutorials/nonlinear/nested_problems.md", "tutorials/nonlinear/querying_hessians.md", "tutorials/nonlinear/complementarity.md", "tutorials/nonlinear/classifiers.md", - "tutorials/nonlinear/operator_ad.md", + "tutorials/nonlinear/portfolio.md", + "tutorials/nonlinear/rocket_control.md", + "tutorials/nonlinear/space_shuttle_reentry_trajectory.md", ], "Conic programs" => [ "tutorials/conic/introduction.md", diff --git a/docs/src/changelog.md b/docs/src/changelog.md index 6d859e2d49c..3ae3fb06fbc 100644 --- a/docs/src/changelog.md +++ b/docs/src/changelog.md @@ -261,7 +261,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - `Percival.jl` (#3567) - Added new tutorials: - [Approximating nonlinear functions](@ref) (#3563) - - [Classifiers](@ref) (#3569) + - [Example: classification problems](@ref) (#3569) - Improved documentation for: - [`Semicontinuous`](@ref) and [`Semiinteger`](@ref) variables (#3562) - [`SOS1`](@ref) and [`SOS2`](@ref) (#3565) diff --git a/docs/src/tutorials/nonlinear/classifiers.jl b/docs/src/tutorials/nonlinear/classifiers.jl index 351742b74c6..c0761adc4fc 100644 --- a/docs/src/tutorials/nonlinear/classifiers.jl +++ b/docs/src/tutorials/nonlinear/classifiers.jl @@ -3,7 +3,7 @@ # v.2.0. If a copy of the MPL was not distributed with this file, You can #src # obtain one at https://mozilla.org/MPL/2.0/. #src -# # Classifiers +# # Example: classification problems # The purpose of this tutorial is to show how JuMP can be used to formulate # classification problems. @@ -17,7 +17,7 @@ # ## Required packages -# This tutorial uses the following packages +# This tutorial uses the following packages: using JuMP import DelimitedFiles diff --git a/docs/src/tutorials/nonlinear/complementarity.jl b/docs/src/tutorials/nonlinear/complementarity.jl index 43fb65807c9..1b712819fa1 100644 --- a/docs/src/tutorials/nonlinear/complementarity.jl +++ b/docs/src/tutorials/nonlinear/complementarity.jl @@ -3,9 +3,12 @@ # v.2.0. If a copy of the MPL was not distributed with this file, You can #src # obtain one at https://mozilla.org/MPL/2.0/. #src -# # Mixed complementarity problems +# # Example: mixed complementarity problems -# This tutorial is a collection of mixed complementarity programs. +# The purpose of this tutorial is to provide a collection of mixed +# complementarity programs. + +# ## Required packages # This tutorial uses the following packages: diff --git a/docs/src/tutorials/nonlinear/introduction.md b/docs/src/tutorials/nonlinear/introduction.md index 21772704cb9..4a5530140a2 100644 --- a/docs/src/tutorials/nonlinear/introduction.md +++ b/docs/src/tutorials/nonlinear/introduction.md @@ -37,13 +37,9 @@ will help you know where to look for certain things. then formulate it in mathematics, and then solve it in JuMP. This usually involves some sort of visualization of the solution. Start here if you are new to JuMP. - * [Rocket Control](@ref) - * [Optimal control for a Space Shuttle reentry trajectory](@ref) - * [Portfolio optimization](@ref) - * The [Tips and tricks](@ref nonlinear_tips_and_tricks) tutorial contains a - number of helpful reformulations and tricks you can use when modeling - nonlinear programs. Look here if you are stuck trying to formulate a problem - as a nonlinear program. + * [Example: nonlinear optimal control of a rocket](@ref) + * [Example: optimal control for a Space Shuttle reentry trajectory](@ref) + * [Example: portfolio optimization](@ref) * The [Computing Hessians](@ref) is an advanced tutorial which explains how to compute the Hessian of the Lagrangian of a nonlinear program. This is useful only in particular cases. diff --git a/docs/src/tutorials/nonlinear/nested_problems.jl b/docs/src/tutorials/nonlinear/nested_problems.jl index 27b069469e9..b9a437d7d7c 100644 --- a/docs/src/tutorials/nonlinear/nested_problems.jl +++ b/docs/src/tutorials/nonlinear/nested_problems.jl @@ -20,27 +20,31 @@ # # Nested optimization problems -# In this tutorial we explain how to write a *nested* optimization problem, -# where an *upper* problem uses the results from the optimization of a *lower* -# subproblem. +# The purpose of this tutorial is to show how to solve a *nested* optimization +# problem, where an *upper* problem uses the results from the optimization of a +# *lower* subproblem. # # To model the problem, we define a user-defined operator to handle the # decomposition of the lower problem inside the upper one. Finally, we show how # to improve the performance by using a cache that avoids resolving the lower # problem. # -# For a simpler example of writing a user-defined operator, -# see the [User-defined Hessians](@ref) tutorial. +# For a simpler example of writing a user-defined operator, see the +# [User-defined Hessians](@ref) tutorial. # !!! info -# The JuMP extension [BilevelJuMP.jl](../../packages/BilevelJuMP.md) can also be used to model and -# solve bilevel optimization problems. +# The JuMP extension [BilevelJuMP.jl](../../packages/BilevelJuMP.md) can +# also be used to model and solve bilevel optimization problems. + +# ## Required packages # This tutorial uses the following packages: using JuMP import Ipopt +# ## Formulation + # In the rest of this tutorial, our goal is to solve the bilevel # optimization problem: diff --git a/docs/src/tutorials/nonlinear/operator_ad.jl b/docs/src/tutorials/nonlinear/operator_ad.jl index 47c5dd398ec..e1d08275497 100644 --- a/docs/src/tutorials/nonlinear/operator_ad.jl +++ b/docs/src/tutorials/nonlinear/operator_ad.jl @@ -29,6 +29,8 @@ # operator is necessary, consider using the default of `@operator(model, op_f, N, f)` # instead of passing explicit [Gradients and Hessians](@ref). +# ## Required packages + # This tutorial uses the following packages: using JuMP @@ -37,6 +39,8 @@ import ForwardDiff import Ipopt import Test +# ## Primal function + # As a simple example, we consider the Rosenbrock function: f(x::T...) where {T} = (1 - x[1])^2 + 100 * (x[2] - x[1]^2)^2 diff --git a/docs/src/tutorials/nonlinear/portfolio.jl b/docs/src/tutorials/nonlinear/portfolio.jl index 420c13bacf0..4e2786ae850 100644 --- a/docs/src/tutorials/nonlinear/portfolio.jl +++ b/docs/src/tutorials/nonlinear/portfolio.jl @@ -18,7 +18,7 @@ # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE #src # SOFTWARE. #src -# # Portfolio optimization +# # Example: portfolio optimization # **This tutorial was originally contributed by Arpit Bhatia.** @@ -31,7 +31,7 @@ # ## Required packages -# This tutorial uses the following packages +# This tutorial uses the following packages: using JuMP import DataFrames diff --git a/docs/src/tutorials/nonlinear/querying_hessians.jl b/docs/src/tutorials/nonlinear/querying_hessians.jl index 37c97da2d01..c0a98aa1b7e 100644 --- a/docs/src/tutorials/nonlinear/querying_hessians.jl +++ b/docs/src/tutorials/nonlinear/querying_hessians.jl @@ -49,6 +49,8 @@ # ``\mu`` is a vector of weights corresponding to the Lagrangian dual of the # constraints. +# ## Required packages + # This tutorial uses the following packages: using JuMP diff --git a/docs/src/tutorials/nonlinear/rocket_control.jl b/docs/src/tutorials/nonlinear/rocket_control.jl index 478e8319c87..b1f460235c4 100644 --- a/docs/src/tutorials/nonlinear/rocket_control.jl +++ b/docs/src/tutorials/nonlinear/rocket_control.jl @@ -3,7 +3,7 @@ # This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 #src # International License. URL: http://creativecommons.org/licenses/by-sa/4.0. #src -# # Rocket Control +# # Example: nonlinear optimal control of a rocket # **This tutorial was originally contributed by Iain Dunning.** @@ -16,6 +16,8 @@ # The JuMP extension [InfiniteOpt.jl](../../packages/InfiniteOpt.md) can also be # used to model and solve optimal control problems. +# ## Required packages + # This tutorial uses the following packages: using JuMP diff --git a/docs/src/tutorials/nonlinear/simple_examples.jl b/docs/src/tutorials/nonlinear/simple_examples.jl index 1eade4f5462..76361455700 100644 --- a/docs/src/tutorials/nonlinear/simple_examples.jl +++ b/docs/src/tutorials/nonlinear/simple_examples.jl @@ -5,8 +5,11 @@ # # Simple examples -# This tutorial is a collection of examples of small nonlinear programs. It uses -# the following packages: +# This tutorial is a collection of examples of small nonlinear programs. + +# ## Required packages + +# This tutorial uses the following packages: using JuMP import Ipopt diff --git a/docs/src/tutorials/nonlinear/space_shuttle_reentry_trajectory.jl b/docs/src/tutorials/nonlinear/space_shuttle_reentry_trajectory.jl index 4e35e55d165..2e6adde4679 100644 --- a/docs/src/tutorials/nonlinear/space_shuttle_reentry_trajectory.jl +++ b/docs/src/tutorials/nonlinear/space_shuttle_reentry_trajectory.jl @@ -20,22 +20,33 @@ # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE #src # SOFTWARE. #src -# # Optimal control for a Space Shuttle reentry trajectory +# # Example: optimal control for a Space Shuttle reentry trajectory # **This tutorial was originally contributed by Henrique Ferrolho.** # This tutorial demonstrates how to compute a reentry trajectory for the -# [Space Shuttle](https://en.wikipedia.org/wiki/Space_Shuttle), -# by formulating and solving a nonlinear programming problem. -# The problem was drawn from Chapter 6 of [Betts2010](@cite). +# [Space Shuttle](https://en.wikipedia.org/wiki/Space_Shuttle), by formulating +# and solving a nonlinear programming problem. The problem was drawn from +# Chapter 6 of [Betts2010](@cite). # !!! info # The JuMP extension [InfiniteOpt.jl](../../packages/InfiniteOpt.md) can also be # used to model and solve optimal control problems. # !!! tip -# This tutorial is a more-complicated version of the [Rocket Control](@ref) example. -# If you are new to solving nonlinear programs in JuMP, you may want to start there instead. +# This tutorial is a more-complicated version of the [Example: nonlinear optimal control of a rocket](@ref) +# tutorial. If you are new to solving nonlinear programs in JuMP, you may +# want to start there instead. + +# ## Required packages + +# This tutorial uses the following packages: + +using JuMP +import Interpolations +import Ipopt + +# ## Formulation # The motion of the vehicle is defined by the following set of DAEs: # @@ -123,10 +134,6 @@ # having position and velocity errors with orders of magnitude $10^4$ ft and # $10^2$ ft/sec, respectively. -using JuMP -import Interpolations -import Ipopt - ## Global variables const w = 203000.0 # weight (lb) const gā‚€ = 32.174 # acceleration (ft/sec^2) diff --git a/docs/src/tutorials/nonlinear/tips_and_tricks.jl b/docs/src/tutorials/nonlinear/tips_and_tricks.jl index a51f5e6108a..e59aaf9bd72 100644 --- a/docs/src/tutorials/nonlinear/tips_and_tricks.jl +++ b/docs/src/tutorials/nonlinear/tips_and_tricks.jl @@ -3,16 +3,20 @@ # v.2.0. If a copy of the MPL was not distributed with this file, You can #src # obtain one at https://mozilla.org/MPL/2.0/. #src -# # [Tips and tricks](@id nonlinear_tips_and_tricks) +# # User-defined operators with vector outputs -# This example collates some tips and tricks you can use when formulating -# nonlinear programs. It uses the following packages: +# The purpose of this tutorial is to demonstrate how to write a user-defined +# operator with a vector-valued output. + +# ## Required packages + +# This tutorial uses the following packages: using JuMP import Ipopt import Test -# ## User-defined operators with vector outputs +# ## Motivation # A common situation is to have a user-defined operator like the following that # returns multiple outputs (we define `function_calls` to keep track of how @@ -58,6 +62,8 @@ Test.@test value.(x) ā‰ˆ [1.0, 1.0] atol = 1e-4 println("Naive approach: function calls = $(function_calls)") naive_approach = function_calls #src +# ## Memoization + # An alternative approach is to use _memoization_, which uses a cache to store # the result of function evaluations. We can write a memoization function as # follows: diff --git a/docs/src/tutorials/nonlinear/user_defined_hessians.jl b/docs/src/tutorials/nonlinear/user_defined_hessians.jl index f2e272229d8..dc2339468c0 100644 --- a/docs/src/tutorials/nonlinear/user_defined_hessians.jl +++ b/docs/src/tutorials/nonlinear/user_defined_hessians.jl @@ -26,6 +26,8 @@ # # For a more advanced example, see [Nested optimization problems](@ref). +# ## Required packages + # This tutorial uses the following packages: using JuMP