[docs] restructure conic optimization tutorials

docs/make.jl

@@ -362,11 +362,11 @@ const _PAGES = [
         ],
         "Conic programs" => [
             "tutorials/conic/introduction.md",
-            "tutorials/conic/start_values.md",
             "tutorials/conic/tips_and_tricks.md",
-            "tutorials/conic/simple_examples.md",
             "tutorials/conic/dualization.md",
             "tutorials/conic/arbitrary_precision.md",
+            "tutorials/conic/start_values.md",
+            "tutorials/conic/simple_examples.md",
             "tutorials/conic/logistic_regression.md",
             "tutorials/conic/experiment_design.md",
             "tutorials/conic/min_ellipse.md",

docs/src/tutorials/conic/arbitrary_precision.jl

@@ -8,6 +8,8 @@
 # The purpose of this tutorial is to explain how to use a solver which supports
 # arithmetic using a number type other than `Float64`.
 
+# ## Required packages
+
 # This tutorial uses the following packages:
 
 using JuMP

docs/src/tutorials/conic/dualization.jl

@@ -6,8 +6,9 @@
 # # Dualization
 
 # The purpose of this tutorial is to explain how to use [Dualization.jl](@ref) to
-# improve the performance of some conic optimization models. There are two
-# important takeaways:
+# improve the performance of some conic optimization models.
+
+# There are two important takeaways:
 #
 #  1. JuMP reformulates problems to meet the input requirements of the
 #     solver, potentially increasing the problem size by adding slack variables
@@ -18,7 +19,9 @@
 # [Dualization.jl](@ref) is a package which fixes these problems, allowing you
 # to solve the dual instead of the primal with a one-line change to your code.
 
-# This tutorial uses the following packages
+# ## Required packages
+
+# This tutorial uses the following packages:
 
 using JuMP
 import Dualization

docs/src/tutorials/conic/ellipse_approx.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
 
-# # Ellipsoid approximation
+# # Example: ellipsoid approximation
 
 # This tutorial considers the problem of computing _extremal ellipsoids_:
 # finding ellipsoids that best approximate a given set. As an extension, we show
@@ -14,6 +14,17 @@
 
 # For a related example, see also the [Minimal ellipses](@ref) tutorial.
 
+# ## Required packages
+
+# This tutorial uses the following packages:
+
+using JuMP
+import LinearAlgebra
+import Plots
+import Random
+import SCS
+import Test
+
 # ## Problem formulation
 
 # Suppose that we are given a set ``\mathcal{S}`` consisting of ``m`` points in
@@ -40,17 +51,6 @@
 # ```
 # where ``D = Z_*`` and ``c = Z_*^{-1} z_*``.
 
-# ## Required packages
-
-# This tutorial uses the following packages:
-
-using JuMP
-import LinearAlgebra
-import Plots
-import Random
-import SCS
-import Test
-
 # ## Data
 
 # We first need to generate some points to work with.

docs/src/tutorials/conic/experiment_design.jl

@@ -18,28 +18,23 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE  #src
 # SOFTWARE.                                                                      #src
 
-# # Experiment design
+# # Example: experiment design
 
 # **This tutorial was originally contributed by Arpit Bhatia and Chris Coey.**
 
 # This tutorial covers experiment design examples (D-optimal, A-optimal, and
 # E-optimal) from section 7.5 of [Boyd2004](@cite).
 
-# The tutorial uses the following packages
+# ## Required packages
+
+# This tutorial uses the following packages:
+
 using JuMP
 import SCS
 import LinearAlgebra
+import MathOptInterface as MOI
 import Random
 
-# !!! info
-#     This tutorial uses sets from [MathOptInterface](@ref moi_documentation).
-#     By default, JuMP exports the `MOI` symbol as an alias for the
-#     MathOptInterface.jl package. We recommend making this more explicit in
-#     your code by adding the following lines:
-#     ```julia
-#     import MathOptInterface as MOI
-#     ```
-
 # We set a seed so the random numbers are repeatable:
 Random.seed!(1234)
 

docs/src/tutorials/conic/logistic_regression.jl

@@ -24,15 +24,23 @@
 
 # **This tutorial was originally contributed by François Pacaud.**
 
-# This tutorial shows how to solve a logistic regression problem
-# with JuMP. Logistic regression is a well known method in machine learning,
-# useful when we want to classify binary variables with the help of
-# a given set of features. To this goal,
-# we find the optimal combination of features maximizing
-# the (log)-likelihood onto a training set. From a modern optimization glance,
-# the resulting problem is convex and differentiable. On a modern optimization
-# glance, it is even conic representable.
-#
+# This tutorial shows how to solve a logistic regression problem with JuMP.
+# Logistic regression is a well known method in machine learning, useful when we
+# want to classify binary variables with the help of a given set of features. To
+# this goal, we find the optimal combination of features maximizing the
+# (log)-likelihood onto a training set.
+
+# ## Required packages
+
+# This tutorial uses the following packages:
+
+using JuMP
+import MathOptInterface as MOI
+import Random
+import SCS
+
+Random.seed!(2713);
+
 # ## Formulating the logistic regression problem
 #
 # Suppose we have a set of training data-point $i = 1, \cdots, n$, where
@@ -122,22 +130,6 @@
 # Thus, if $n \gg 1$, we get a large number of variables and constraints.
 
 # ## Fitting logistic regression with a conic solver
-#
-# It is now time to pass to the implementation. We choose SCS as a conic solver.
-using JuMP
-import Random
-import SCS
-
-# !!! info
-#     This tutorial uses sets from [MathOptInterface](@ref moi_documentation).
-#     By default, JuMP exports the `MOI` symbol as an alias for the
-#     MathOptInterface.jl package. We recommend making this more explicit in
-#     your code by adding the following lines:
-#     ```julia
-#     import MathOptInterface as MOI
-#     ```
-
-Random.seed!(2713);
 
 # We start by implementing a function to generate a fake dataset, and where
 # we could tune the correlation between the feature variables. The function

docs/src/tutorials/conic/min_ellipse.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
 
-# # Minimal ellipses
+# # Example: minimal ellipses
 
 # This example comes from section 8.4.1 of the book *Convex Optimization* by
 # [Boyd and Vandenberghe (2004)](https://web.stanford.edu/~boyd/cvxbook/).

docs/src/tutorials/conic/quantum_discrimination.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
 
-# # Quantum state discrimination
+# # Example: quantum state discrimination
 
 # This tutorial solves the problem of [quantum state discrimination](https://en.wikipedia.org/wiki/Quantum_state_discrimination).
 
@@ -13,7 +13,7 @@
 
 # ## Required packages
 
-# This tutorial makes use of the following packages:
+# This tutorial uses the following packages:
 
 using JuMP
 import LinearAlgebra

docs/src/tutorials/conic/simple_examples.jl

@@ -5,10 +5,12 @@
 
 # # Simple semidefinite programming examples
 
-# This tutorial is a collection of examples of small conic programs from the field of
-# [semidefinite programming](https://en.wikipedia.org/wiki/Semidefinite_programming) (SDP).
-#
-# This tutorial makes use of the following packages:
+# The purpose of this tutorial is to provide a collection of examples of small
+# conic programs from the field of [semidefinite programming](https://en.wikipedia.org/wiki/Semidefinite_programming) (SDP).
+
+# ## Required packages
+
+# This tutorial uses the following packages:
 
 using JuMP
 import LinearAlgebra

docs/src/tutorials/conic/start_values.jl

@@ -9,23 +9,24 @@
 # solution. This can improve performance, particularly if you are repeatedly
 # solving a sequence of related problems.
 
+# The purpose of this tutorial is to demonstrate how to write a function that
+# sets the primal and dual starts as the optimal solution stored in a model. It
+# is intended to be a starting point for which you can modify if you want to do
+# something similar in your own code.
+
 # !!! tip
 #     See [`set_start_values`](@ref) for a generic implementation of this
 #     function that was added to JuMP after this tutorial was written.
 
-# In this tutorial, we demonstrate how to write a function that sets the primal
-# and dual starts as the optimal solution stored in a model. It is intended to
-# be a starting point for which you can modify if you want to do something
-# similar in your own code.
-
-# !!! warning
-#     This tutorial does not set start values for nonlinear models.
+# ## Required packages
 
 # This tutorial uses the following packages:
 
 using JuMP
 import SCS
 
+# ## A basic function
+
 # The main component of this tutorial is the following function. The most
 # important observation is that we cache all of the solution values first, and
 # then we modify the model second. (Alternating between querying a value and
@@ -60,6 +61,8 @@ function set_optimal_start_values(model::Model)
     return
 end
 
+# ## Testing the function
+
 # To test our function, we use the following linear program:
 
 model = Model(SCS.Optimizer)
@@ -81,8 +84,11 @@ optimize!(model)
 # Now the optimization terminates after 0 iterations because our starting point
 # is already optimal.
 
-# Note that some solvers do not support setting some parts of the starting
-# solution, for example, they may support only `set_start_value` for variables.
+# ## Caveats
+
+# Some solvers do not support setting some parts of the starting solution, for
+# example, they may support only `set_start_value` for variables.
+
 # If you encounter an `UnsupportedSupported` attribute error for
 # [`MOI.VariablePrimalStart`](@ref), [`MOI.ConstraintPrimalStart`](@ref), or
 # [`MOI.ConstraintDualStart`](@ref), comment out the corresponding part of the

docs/src/tutorials/conic/tips_and_tricks.jl

@@ -18,36 +18,30 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE  #src
 # SOFTWARE.                                                                      #src
 
-# # [Tips and Tricks](@id conic_tips_and_tricks)
+# # [Modeling with cones](@id conic_tips_and_tricks)
 
 # **This tutorial was originally contributed by Arpit Bhatia.**
 
-# This tutorial is aimed at providing a simplistic introduction to conic
-# programming using JuMP.
+# The purpose of this tutorial is to show how you can model various common
+# problems using conic optimization.
 
-# It uses the following packages:
+# !!! tip
+#     A good resource for learning more about functions which can be modeled
+#     using cones is the [MOSEK Modeling Cookbook](https://docs.mosek.com/modeling-cookbook/index.html).
+
+# ## Required packages
+
+# This tutorial uses the following packages:
 
 using JuMP
-import SCS
 import LinearAlgebra
-
-# !!! info
-#     This tutorial uses sets from [MathOptInterface](@ref moi_documentation).
-#     By default, JuMP exports the `MOI` symbol as an alias for the
-#     MathOptInterface.jl package. We recommend making this more explicit in
-#     your code by adding the following lines:
-#     ```julia
-#     import MathOptInterface as MOI
-#     ```
+import MathOptInterface as MOI
+import SCS
 
 import Random      # hide
 Random.seed!(1234) # hide
 nothing            # hide
 
-# !!! tip
-#     A good resource for learning more about functions which can be modeled
-#     using cones is the [MOSEK Modeling Cookbook](https://docs.mosek.com/modeling-cookbook/index.html).
-
 # ## Background theory
 
 # A subset $C$ of a vector space $V$ is a cone if $\forall x \in C$ and positive