Merge pull request #380 from ArnoStrouwen/fixtuts

ChrisRackauckas · web-flow · commit c9c667e626bf · 2022-10-09T08:50:48.000-04:00
example and strict docs
diff --git a/docs/Project.toml b/docs/Project.toml
@@ -7,15 +7,22 @@ ForwardDiff = "f6369f11-7733-5829-9624-2563aa707210"
 Ipopt = "b6b21f68-93f8-5de0-b562-5493be1d77c9"
 Ipopt_jll = "9cc047cb-c261-5740-88fc-0cf96f7bdcc7"
 IterTools = "c8e1da08-722c-5040-9ed9-7db0dc04731e"
+Juniper = "2ddba703-00a4-53a7-87a5-e8b9971dde84"
 ModelingToolkit = "961ee093-0014-501f-94e3-6117800e7a78"
+NLopt = "76087f3c-5699-56af-9a33-bf431cd00edd"
 Optimization = "7f7a1694-90dd-40f0-9382-eb1efda571ba"
 OptimizationBBO = "3e6eede4-6085-4f62-9a71-46d9bc1eb92b"
 OptimizationCMAEvolutionStrategy = "bd407f91-200f-4536-9381-e4ba712f53f8"
 OptimizationEvolutionary = "cb963754-43f6-435e-8d4b-99009ff27753"
+OptimizationGCMAES = "6f0a0517-dbc2-4a7a-8a20-99ae7f27e911"
 OptimizationMOI = "fd9f6733-72f4-499f-8506-86b2bdd0dea1"
+OptimizationMetaheuristics = "3aafef2f-86ae-4776-b337-85a36adf0b55"
+OptimizationMultistartOptimization = "e4316d97-8bbb-4fd3-a7d8-3851d2a72823"
 OptimizationNLopt = "4e6fcdb7-1186-4e1f-a706-475e75c168bb"
+OptimizationNOMAD = "2cab0595-8222-4775-b714-9828e6a9e01b"
 OptimizationOptimJL = "36348300-93cb-4f02-beb5-3c3902f8871e"
 OptimizationOptimisers = "42dfb2eb-d2b4-4451-abcd-913932933ac1"
+OptimizationSpeedMapping = "3d669222-0d7d-4eb9-8a9f-d8528b0d9b91"
 OrdinaryDiffEq = "1dea7af3-3e70-54e6-95c3-0bf5283fa5ed"
 ReverseDiff = "37e2e3b7-166d-5795-8a7a-e32c996b4267"
 SciMLSensitivity = "1ed8b502-d754-442c-8d5d-10ac956f44a1"
diff --git a/docs/make.jl b/docs/make.jl
@@ -5,10 +5,17 @@ include("pages.jl")
 
 makedocs(sitename = "Optimization.jl",
          authors = "Chris Rackauckas, Vaibhav Kumar Dixit et al.",
-         clean = true,
-         doctest = false,
          modules = [Optimization, Optimization.SciMLBase, FiniteDiff,
              ForwardDiff, ModelingToolkit, ReverseDiff, Tracker, Zygote],
+         clean = true, doctest = false,
+         strict = [
+             :doctest,
+             :linkcheck,
+             :parse_error,
+             :example_block,
+             # Other available options are
+             # :autodocs_block, :cross_references, :docs_block, :eval_block, :example_block, :footnote, :meta_block, :missing_docs, :setup_block
+         ],
          format = Documenter.HTML(analytics = "UA-90474609-3",
                                   assets = ["assets/favicon.ico"],
                                   canonical = "https://Optimization.sciml.ai/stable/"),
diff --git a/docs/src/API/optimization_function.md b/docs/src/API/optimization_function.md
@@ -20,11 +20,11 @@ The choices for the auto-AD fill-ins with quick descriptions are:
 The following sections describe the Auto-AD choices in detail.
 
 ```@docs
-AutoForwardDiff
-AutoFiniteDiff
-AutoReverseDiff
-AutoZygote
-AutoTracker
-AutoModelingToolkit
+Optimization.AutoForwardDiff
+Optimization.AutoFiniteDiff
+Optimization.AutoReverseDiff
+Optimization.AutoZygote
+Optimization.AutoTracker
+Optimization.AutoModelingToolkit
 ```
 
diff --git a/docs/src/optimization_packages/blackboxoptim.md b/docs/src/optimization_packages/blackboxoptim.md
@@ -48,7 +48,8 @@ The currently available algorithms are listed [here](https://github.com/robertfe
 
 The Rosenbrock function can optimized using the `BBO_adaptive_de_rand_1_bin_radiuslimited()` as follows:
 
-```julia
+```@example BBO
+using Optimization, OptimizationBBO
 rosenbrock(x, p) =  (p[1] - x[1])^2 + p[2] * (x[2] - x[1]^2)^2
 x0 = zeros(2)
 p  = [1.0, 100.0]
diff --git a/docs/src/optimization_packages/cmaevolutionstrategy.md b/docs/src/optimization_packages/cmaevolutionstrategy.md
@@ -21,7 +21,8 @@ constraint equations. However, lower and upper constraints set by `lb` and `ub`
 
 The Rosenbrock function can optimized using the `CMAEvolutionStrategyOpt()` as follows:
 
-```julia
+```@example CMAEvolutionStrategy
+using Optimization, OptimizationCMAEvolutionStrategy
 rosenbrock(x, p) =  (p[1] - x[1])^2 + p[2] * (x[2] - x[1]^2)^2
 x0 = zeros(2)
 p  = [1.0, 100.0]
diff --git a/docs/src/optimization_packages/evolutionary.md b/docs/src/optimization_packages/evolutionary.md
@@ -31,7 +31,8 @@ Algorithm specific options are defined as `kwargs`. See the respective documenta
 
 The Rosenbrock function can optimized using the `Evolutionary.CMAES()` as follows:
 
-```julia
+```@example Evolutionary
+using Optimization, OptimizationEvolutionary
 rosenbrock(x, p) =  (p[1] - x[1])^2 + p[2] * (x[2] - x[1]^2)^2
 x0 = zeros(2)
 p  = [1.0, 100.0]
diff --git a/docs/src/optimization_packages/gcmaes.md b/docs/src/optimization_packages/gcmaes.md
@@ -21,7 +21,8 @@ constraint equations. However, lower and upper constraints set by `lb` and `ub`
 
 The Rosenbrock function can optimized using the `GCMAESOpt()` without utilizing the gradient information as follows:
 
-```julia
+```@example GCMAES
+using Optimization, OptimizationGCMAES
 rosenbrock(x, p) =  (p[1] - x[1])^2 + p[2] * (x[2] - x[1]^2)^2
 x0 = zeros(2)
 p  = [1.0, 100.0]
@@ -32,11 +33,8 @@ sol = solve(prob, GCMAESOpt())
 
 We can also utilise the gradient information of the optimization problem to aid the optimization as follows:
 
-```julia
-rosenbrock(x, p) =  (p[1] - x[1])^2 + p[2] * (x[2] - x[1]^2)^2
-x0 = zeros(2)
-p  = [1.0, 100.0]
-f = OptimizationFunction(rosenbrock, Optimization.ForwardDiff)
+```@example GCMAES
+f = OptimizationFunction(rosenbrock, Optimization.AutoForwardDiff())
 prob = Optimization.OptimizationProblem(f, x0, p, lb = [-1.0,-1.0], ub = [1.0,1.0])
 sol = solve(prob, GCMAESOpt())
 ```
diff --git a/docs/src/optimization_packages/mathoptinterface.md b/docs/src/optimization_packages/mathoptinterface.md
@@ -61,16 +61,15 @@ sol = solve(prob,  Ipopt.Optimizer(); option_name = option_value, ...)
   [Juniper documentation](https://github.com/lanl-ansi/Juniper.jl) for more
   detail.
 
-```julia
-using Optimization, ForwardDiff
+```@example MOI
+using Optimization, OptimizationMOI, Juniper, Ipopt
 rosenbrock(x, p) =  (p[1] - x[1])^2 + p[2] * (x[2] - x[1]^2)^2
 x0 = zeros(2)
 _p  = [1.0, 100.0]
 
 f = OptimizationFunction(rosenbrock, Optimization.AutoForwardDiff())
 prob = Optimization.OptimizationProblem(f, x0, _p)
 
-using OptimizationMOI, Juniper, Ipopt
 opt = OptimizationMOI.MOI.OptimizerWithAttributes(
     Juniper.Optimizer,
     "nl_solver"=>OptimizationMOI.MOI.OptimizerWithAttributes(Ipopt.Optimizer, "print_level"=>0),
diff --git a/docs/src/optimization_packages/metaheuristics.md b/docs/src/optimization_packages/metaheuristics.md
@@ -48,7 +48,8 @@ constraint equations. However, lower and upper constraints set by `lb` and `ub`
 
 The Rosenbrock function can optimized using the Evolutionary Centers Algorithm `ECA()` as follows:
 
-```julia
+```@example Metaheuristics
+using Optimization, OptimizationMetaheuristics
 rosenbrock(x, p) =  (p[1] - x[1])^2 + p[2] * (x[2] - x[1]^2)^2
 x0 = zeros(2)
 p  = [1.0, 100.0]
@@ -59,12 +60,7 @@ sol = solve(prob, ECA(), maxiters=100000, maxtime=1000.0)
 
 Per default `Metaheuristics` ignores the initial values `x0` set in the `OptimizationProblem`. In order to for `Optimization` to use `x0` we have to set `use_initial=true`:
 
-```julia
-rosenbrock(x, p) =  (p[1] - x[1])^2 + p[2] * (x[2] - x[1]^2)^2
-x0 = zeros(2)
-p  = [1.0, 100.0]
-f = OptimizationFunction(rosenbrock)
-prob = Optimization.OptimizationProblem(f, x0, p, lb = [-1.0,-1.0], ub = [1.0,1.0])
+```@example Metaheuristics
 sol = solve(prob, ECA(), use_initial=true, maxiters=100000, maxtime=1000.0)
 ```
 
diff --git a/docs/src/optimization_packages/multistartoptimization.md b/docs/src/optimization_packages/multistartoptimization.md
@@ -26,9 +26,8 @@ constraint equations. However, lower and upper constraints set by `lb` and `ub`
 
 The Rosenbrock function can optimized using `MultistartOptimization.TikTak()` with 100 initial points and the local method `NLopt.LD_LBFGS()` as follows:
 
-```julia
-using OptimizationMultistartOptimization
-using OptimizationNLopt
+```@example MultiStart
+using Optimization, OptimizationMultistartOptimization, OptimizationNLopt
 rosenbrock(x, p) =  (p[1] - x[1])^2 + p[2] * (x[2] - x[1]^2)^2
 x0 = zeros(2)
 p  = [1.0, 100.0]
@@ -39,12 +38,8 @@ sol = solve(prob, MultistartOptimization.TikTak(100), NLopt.LD_LBFGS())
 
 You can use any `Optimization` optimizers you like. The global method of the `MultistartOptimization` is a positional argument and followed by the local method. This for example means we can perform a multistartoptimization with LBFGS as the optimizer using either the `NLopt.jl` or `Optim.jl` implementation as follows. Moreover, this interface allows you access and adjust all the optimizer settings as you normally would:
 
-```julia
+```@example MultiStart
 using OptimizationOptimJL
-using ForwardDiff
-rosenbrock(x, p) =  (p[1] - x[1])^2 + p[2] * (x[2] - x[1]^2)^2
-x0 = zeros(2)
-p  = [1.0, 100.0]
 f = OptimizationFunction(rosenbrock, Optimization.AutoForwardDiff())
 prob = Optimization.OptimizationProblem(f, x0, p, lb = [-1.0,-1.0], ub = [1.0,1.0])
 sol = solve(prob, MultistartOptimization.TikTak(100), LBFGS(), maxiters=5)
diff --git a/docs/src/optimization_packages/nlopt.md b/docs/src/optimization_packages/nlopt.md
@@ -90,7 +90,9 @@ Derivative-free optimizers are optimizers that can be used even in cases where n
 
 The Rosenbrock function can optimized using the `NLopt.LN_NELDERMEAD()` as follows:
 
-```julia
+```@example NLopt1
+using Optimization
+using NLopt
 rosenbrock(x, p) =  (p[1] - x[1])^2 + p[2] * (x[2] - x[1]^2)^2
 x0 = zeros(2)
 p  = [1.0, 100.0]
@@ -122,7 +124,8 @@ Gradient-based optimizers are optimizers which utilise the gradient information
 
 The Rosenbrock function can optimized using `NLopt.LD_LBFGS()` as follows:
 
-```julia
+```@example NLopt2
+using Optimization, OptimizationNLopt
 rosenbrock(x, p) =  (p[1] - x[1])^2 + p[2] * (x[2] - x[1]^2)^2
 x0 = zeros(2)
 p  = [1.0, 100.0]
@@ -160,26 +163,28 @@ constraint equations. However, lower and upper constraints set by `lb` and `ub`
 
 The Rosenbrock function can optimized using `NLopt.GN_DIRECT()` as follows:
 
-```julia
+```@example NLopt3
+using Optimization, OptimizationNLopt
 rosenbrock(x, p) =  (p[1] - x[1])^2 + p[2] * (x[2] - x[1]^2)^2
 x0 = zeros(2)
 p  = [1.0, 100.0]
 f = OptimizationFunction(rosenbrock)
 prob = Optimization.OptimizationProblem(f, x0, p, lb = [-1.0,-1.0], ub = [1.0,1.0])
-sol = solve(prob, NLopt.GN_DIRECT())
+sol = solve(prob, NLopt.GN_DIRECT(),maxtime=10.0)
 ```
 
 Algorithms such as `NLopt.G_MLSL()` or `NLopt.G_MLSL_LDS()` also require a local optimiser to be selected which via the `local_method` argument of `solve`.
 
 The Rosenbrock function can optimized using `NLopt.G_MLSL_LDS()` with `NLopt.LN_NELDERMEAD()` as the local optimizer. The local optimizer maximum iterations are set via `local_maxiters`:
 
-```julia
+```@example NLopt4
+using Optimization, OptimizationNLopt
 rosenbrock(x, p) =  (p[1] - x[1])^2 + p[2] * (x[2] - x[1]^2)^2
 x0 = zeros(2)
 p  = [1.0, 100.0]
 f = OptimizationFunction(rosenbrock, Optimization.AutoForwardDiff())
 prob = Optimization.OptimizationProblem(f, x0, p, lb = [-1.0,-1.0], ub = [1.0,1.0])
-sol = solve(prob, NLopt.G_MLSL_LDS(), local_method = NLopt.LD_LBFGS(), local_maxiters=10000)
+sol = solve(prob, NLopt.G_MLSL_LDS(), local_method = NLopt.LD_LBFGS(),maxtime=10.0, local_maxiters=10)
 ```
 
 ### With Constraint Equations
diff --git a/docs/src/optimization_packages/nomad.md b/docs/src/optimization_packages/nomad.md
@@ -23,15 +23,16 @@ NOMAD works both with and without lower and upper boxconstraints set by `lb` and
 
 The Rosenbrock function can optimized using the `NOMADOpt()` with and without boxcontraints as follows:
 
-```julia
+```@example NOMAD
+using Optimization, OptimizationNOMAD
 rosenbrock(x, p) =  (p[1] - x[1])^2 + p[2] * (x[2] - x[1]^2)^2
 x0 = zeros(2)
 p  = [1.0, 100.0]
 f = OptimizationFunction(rosenbrock)
 
-prob = OptimizationProblem(f, x0, _p)
+prob = OptimizationProblem(f, x0, p)
 sol = Optimization.solve(prob,NOMADOpt())
 
-prob = OptimizationProblem(f, x0, _p, lb = [-1.0,-1.0], ub = [1.5,1.5])
+prob = OptimizationProblem(f, x0, p, lb = [-1.0,-1.0], ub = [1.5,1.5])
 sol = Optimization.solve(prob,NOMADOpt())
 ```
diff --git a/docs/src/optimization_packages/optim.md b/docs/src/optimization_packages/optim.md
@@ -71,7 +71,8 @@ For a more extensive documentation of all the algorithms and options please cons
 
 The Rosenbrock function can optimized using the `Optim.IPNewton()` as follows:
 
-```julia
+```@example Optim1
+using Optimization, OptimizationOptimJL
 rosenbrock(x, p) =  (p[1] - x[1])^2 + p[2] * (x[2] - x[1]^2)^2
 cons= (res,x,p) -> res .= [x[1]^2 + x[2]^2]
 x0 = zeros(2)
@@ -112,7 +113,8 @@ Derivative-free optimizers are optimizers that can be used even in cases where n
 
 The Rosenbrock function can optimized using the `Optim.NelderMead()` as follows:
 
-```julia
+```@example Optim2
+using Optimization, OptimizationOptimJL
 rosenbrock(x, p) =  (1 - x[1])^2 + 100 * (x[2] - x[1]^2)^2
 x0 = zeros(2)
 p  = [1.0,100.0]
@@ -255,15 +257,16 @@ Gradient-based optimizers are optimizers which utilise the gradient information
 
 
 
-The Rosenbrock function can optimized using the `Optim.LD_LBFGS()` as follows:
+The Rosenbrock function can optimized using the `Optim.LBFGS()` as follows:
 
-```julia
+```@example Optim3
+using Optimization, OptimizationOptimJL
 rosenbrock(x, p) =  (1 - x[1])^2 + 100 * (x[2] - x[1]^2)^2
 x0 = zeros(2)
 p  = [1.0,100.0]
 optprob = OptimizationFunction(rosenbrock, Optimization.AutoForwardDiff())
 prob = Optimization.OptimizationProblem(optprob, x0, p, lb=[-1.0, -1.0], ub=[0.8, 0.8])
-sol = solve(prob, NLopt.LD_LBFGS())
+sol = solve(prob, Optim.LBFGS())
 ```
 
 ### Hessian-Based Second Order
@@ -309,11 +312,12 @@ the Hessian in order to be appropriate.
 
 The Rosenbrock function can optimized using the `Optim.Newton()` as follows:
 
-```julia
+```@example Optim4
+using Optimization, OptimizationOptimJL, ModelingToolkit
 rosenbrock(x, p) =  (1 - x[1])^2 + 100 * (x[2] - x[1]^2)^2
 x0 = zeros(2)
 p  = [1.0,100.0]
-f = OptimizationFunction(rosenbrock,ModelingToolkit.AutoModelingToolkit(),x0,p,grad=true,hess=true)
+f = OptimizationFunction(rosenbrock,Optimization.AutoModelingToolkit())
 prob = Optimization.OptimizationProblem(f,x0,p)
 sol = solve(prob,Optim.Newton())
 ```
@@ -343,7 +347,8 @@ special case when considering conditioning of the Hessian.
 
 The Rosenbrock function can optimized using the `Optim.KrylovTrustRegion()` as follows:
 
-```julia
+```@example Optim5
+using Optimization, OptimizationOptimJL
 rosenbrock(x, p) =  (1 - x[1])^2 + 100 * (x[2] - x[1]^2)^2
 cons= (res,x,p) -> res .= [x[1]^2 + x[2]^2]
 x0 = zeros(2)
@@ -370,7 +375,8 @@ constraint equations. It works both with and without lower and upper constraints
 
 The Rosenbrock function can optimized using the `Optim.ParticleSwarm()` as follows:
 
-```julia
+```@example Optim6
+using Optimization, OptimizationOptimJL
 rosenbrock(x, p) =  (p[1] - x[1])^2 + p[2] * (x[2] - x[1]^2)^2
 x0 = zeros(2)
 p  = [1.0,100.0]
@@ -398,7 +404,8 @@ constraint equations.
 
 The Rosenbrock function can optimized using the `Optim.SAMIN()` as follows:
 
-```julia
+```@example Optim7
+using Optimization, OptimizationOptimJL
 rosenbrock(x, p) =  (1 - x[1])^2 + 100 * (x[2] - x[1]^2)^2
 x0 = zeros(2)
 p  = [1.0,100.0]
diff --git a/docs/src/optimization_packages/speedmapping.md b/docs/src/optimization_packages/speedmapping.md
@@ -21,14 +21,15 @@ If no AD backend is defined via `OptimizationFunction` the gradient is calculate
 
 The Rosenbrock function can be optimized using the `SpeedMappingOpt()` with and without bound as follows:
 
-```julia
+```@example SpeedMapping
+using Optimization, OptimizationSpeedMapping
 rosenbrock(x, p) =  (p[1] - x[1])^2 + p[2] * (x[2] - x[1]^2)^2
 x0 = zeros(2)
 p  = [1.0, 100.0]
 f = OptimizationFunction(rosenbrock, Optimization.AutoForwardDiff())
-prob = OptimizationProblem(f, x0, _p)
+prob = OptimizationProblem(f, x0, p)
 sol = solve(prob,SpeedMappingOpt())
 
-prob = OptimizationProblem(f, x0, _p;lb=[0.0,0.0], ub=[1.0,1.0])
+prob = OptimizationProblem(f, x0, p;lb=[0.0,0.0], ub=[1.0,1.0])
 sol = solve(prob,SpeedMappingOpt())
 ```
diff --git a/docs/src/tutorials/constraints.md b/docs/src/tutorials/constraints.md
@@ -16,7 +16,8 @@ x_1^2 + x_2^2 \leq 0.8 \\
 ```
 
 ```@example constraints
-using Optimization, OptimizationMOI, OptimizationOptimJL, ForwardDiff, ModelingToolkit
+using Optimization, OptimizationMOI, OptimizationOptimJL, Ipopt
+using ForwardDiff, ModelingToolkit
 
 rosenbrock(x, p) = (p[1] - x[1])^2 + p[2] * (x[2] - x[1]^2)^2
 x0 = zeros(2)
diff --git a/docs/src/tutorials/intro.md b/docs/src/tutorials/intro.md
@@ -33,6 +33,8 @@ The output of the first optimization task (with the `NelderMead()` algorithm)
 is given below:
 
 ```@example intro
+optf = OptimizationFunction(rosenbrock, Optimization.AutoForwardDiff())
+prob = OptimizationProblem(optf, u0, p, lb = [-1.0,-1.0], ub = [1.0,1.0])
 sol = solve(prob,NelderMead())
 ```
 
