[docs] restructure nonlinear optimization tutorials (#3823)

jump-dev · Sep 11, 2024 · dc4f2a8 · dc4f2a8
1 parent ceb8e54
commit dc4f2a8
Show file tree

Hide file tree

Showing 14 changed files with 71 additions and 42 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -26,6 +26,8 @@
 #
 # For a more advanced example, see [Nested optimization problems](@ref).
 
+# ## Required packages
+
 # This tutorial uses the following packages:
 
 using JuMP