diff --git a/docs/make.jl b/docs/make.jl index 54ea801b60b..a86b18224f8 100644 --- a/docs/make.jl +++ b/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", diff --git a/docs/src/tutorials/conic/arbitrary_precision.jl b/docs/src/tutorials/conic/arbitrary_precision.jl index 2323d25bbb5..834383d3793 100644 --- a/docs/src/tutorials/conic/arbitrary_precision.jl +++ b/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 diff --git a/docs/src/tutorials/conic/dualization.jl b/docs/src/tutorials/conic/dualization.jl index 8a2fc18fde2..798ffcddf9d 100644 --- a/docs/src/tutorials/conic/dualization.jl +++ b/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 diff --git a/docs/src/tutorials/conic/ellipse_approx.jl b/docs/src/tutorials/conic/ellipse_approx.jl index 2b08720ca47..997317cb7ea 100644 --- a/docs/src/tutorials/conic/ellipse_approx.jl +++ b/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. diff --git a/docs/src/tutorials/conic/experiment_design.jl b/docs/src/tutorials/conic/experiment_design.jl index 75680c92dbd..7bf8c4356bc 100644 --- a/docs/src/tutorials/conic/experiment_design.jl +++ b/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) diff --git a/docs/src/tutorials/conic/logistic_regression.jl b/docs/src/tutorials/conic/logistic_regression.jl index 890bde86267..26a81958d2d 100644 --- a/docs/src/tutorials/conic/logistic_regression.jl +++ b/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 diff --git a/docs/src/tutorials/conic/min_ellipse.jl b/docs/src/tutorials/conic/min_ellipse.jl index d6a6f4e74fb..9cf1859c115 100644 --- a/docs/src/tutorials/conic/min_ellipse.jl +++ b/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/). diff --git a/docs/src/tutorials/conic/quantum_discrimination.jl b/docs/src/tutorials/conic/quantum_discrimination.jl index 252fd95d7f8..02ccba1e999 100644 --- a/docs/src/tutorials/conic/quantum_discrimination.jl +++ b/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 diff --git a/docs/src/tutorials/conic/simple_examples.jl b/docs/src/tutorials/conic/simple_examples.jl index 4d5951f15ce..9e2b383bcb3 100644 --- a/docs/src/tutorials/conic/simple_examples.jl +++ b/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 diff --git a/docs/src/tutorials/conic/start_values.jl b/docs/src/tutorials/conic/start_values.jl index 0ebc7d62f4c..e2b2975d979 100644 --- a/docs/src/tutorials/conic/start_values.jl +++ b/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 diff --git a/docs/src/tutorials/conic/tips_and_tricks.jl b/docs/src/tutorials/conic/tips_and_tricks.jl index 9de21fb0463..e5159f8ef26 100644 --- a/docs/src/tutorials/conic/tips_and_tricks.jl +++ b/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