update docs for subpackages

Author: ChrisRackauckas

docs/src/optimization_packages/optim.md

@@ -1,4 +1,4 @@
-# Optim.jl
+# [Optim.jl](@id optim)
 [`Optim`](https://github.com/JuliaNLSolvers/Optim.jl) is Julia package implementing various algorithm to perform univariate and multivariate optimization.
 
 ## Installation: GalacticOptimJL.jl

docs/src/tutorials/intro.md

@@ -6,43 +6,58 @@ from BlackBoxOptim.jl on the Rosenbrock equation. The simplest copy-pasteable
 code to get started is the following:
 
 ```julia
- using GalacticOptim, Optim
- rosenbrock(x,p) =  (p[1] - x[1])^2 + p[2] * (x[2] - x[1]^2)^2
- x0 = zeros(2)
- p  = [1.0,100.0]
+using GalacticOptim
+rosenbrock(x,p) =  (p[1] - x[1])^2 + p[2] * (x[2] - x[1]^2)^2
+x0 = zeros(2)
+p  = [1.0,100.0]
 
- prob = OptimizationProblem(rosenbrock,x0,p)
- sol = solve(prob,NelderMead())
+prob = OptimizationProblem(rosenbrock,x0,p)
 
+using GalacticOptimJL
+sol = solve(prob,NelderMead())
 
- using BlackBoxOptim
- prob = OptimizationProblem(rosenbrock, x0, p, lb = [-1.0,-1.0], ub = [1.0,1.0])
- sol = solve(prob,BBO_adaptive_de_rand_1_bin_radiuslimited())
+
+using GalacticBBO
+prob = OptimizationProblem(rosenbrock, x0, p, lb = [-1.0,-1.0], ub = [1.0,1.0])
+sol = solve(prob,BBO_adaptive_de_rand_1_bin_radiuslimited())
 ```
 
-Note that Optim.jl is a core dependency of GalaticOptim.jl. However, BlackBoxOptim.jl
-is not and must already be installed (see the list above).
+Notice that GalacticOptim.jl is the core glue package that holds all of the common
+pieces, but to solve the equations we need to use a solver package. Here, GalcticOptimJL
+is for [Optim.jl](https://github.com/JuliaNLSolvers/Optim.jl) and GalacticBBO is for
+[BlackBoxOptim.jl](https://github.com/robertfeldt/BlackBoxOptim.jl).
 
 The output of the first optimization task (with the `NelderMead()` algorithm)
 is given below:
 
 ```julia
-* Status: success
+sol = solve(prob,NelderMead())
+u: 2-element Vector{Float64}:
+ 0.9999634355313174
+ 0.9999315506115275
+```
 
-* Candidate solution
-   Final objective value:     3.525527e-09
+The solution from the original solver can always be obtained via `original`:
 
-* Found with
-   Algorithm:     Nelder-Mead
+```julia
+julia> sol.original
+ * Status: success
 
-* Convergence measures
-   √(Σ(yᵢ-ȳ)²)/n ≤ 1.0e-08
+ * Candidate solution
+    Final objective value:     3.525527e-09
 
-* Work counters
-   Seconds run:   0  (vs limit Inf)
-   Iterations:    60
-   f(x) calls:    118
+ * Found with
+    Algorithm:     Nelder-Mead
+
+ * Convergence measures
+    √(Σ(yᵢ-ȳ)²)/n ≤ 1.0e-08
+
+ * Work counters
+    Seconds run:   0  (vs limit Inf)
+    Iterations:    60
+    f(x) calls:    117
 ```
+
 We can also explore other methods in a similar way:
 
 ```julia
@@ -80,6 +95,7 @@ For instance, the above optimization task produces the following output:
  prob = OptimizationProblem(f, x0, p, lb = [-1.0,-1.0], ub = [1.0,1.0])
  sol = solve(prob, Fminbox(GradientDescent()))
 ```
+
 The examples clearly demonstrate that GalacticOptim.jl provides an intuitive
 way of specifying optimization tasks and offers a relatively
 easy access to a wide range of optimization algorithms.

docs/src/tutorials/minibatch.md

@@ -1,7 +1,12 @@
 # Minibatch examples
 
+!!! note
+
+    This example uses the GalacticOptimJL.jl package. See the [Optim.jl page](@ref optim)
+    for details on the installation and usage.
+
 ```julia
-using DiffEqFlux, GalacticOptim, OrdinaryDiffEq
+using DiffEqFlux, GalacticOptim, GalacticOptimJL, OrdinaryDiffEq
 
 function newtons_cooling(du, u, p, t)
     temp = u[1]

docs/src/tutorials/rosenbrock.md

@@ -1,5 +1,12 @@
 # Rosenbrock function examples
 
+!!! note
+
+    This example uses many different solvers of GalacticOptim.jl. Each solver
+    subpackage needs to be installed separate. For example, for the details on 
+    the installation and usage of GalacticOptimJL.jl package, see the 
+    [Optim.jl page](@ref optim).
+
 ```julia
 using GalacticOptim, Optim, ForwardDiff, Zygote, Test, Random
 
@@ -10,6 +17,11 @@ _p  = [1.0, 100.0]
 f = OptimizationFunction(rosenbrock, GalacticOptim.AutoForwardDiff())
 l1 = rosenbrock(x0, _p)
 prob = OptimizationProblem(f, x0, _p)
+
+## Optim.jl Solvers
+
+using GalacticOptimJL
+
 sol = solve(prob, SimulatedAnnealing())
 @test 10*sol.minimum < l1
 
@@ -18,12 +30,6 @@ prob = OptimizationProblem(f, x0, _p, lb=[-1.0, -1.0], ub=[0.8, 0.8])
 sol = solve(prob, SAMIN())
 @test 10*sol.minimum < l1
 
-using CMAEvolutionStrategy
-sol = solve(prob, CMAEvolutionStrategyOpt())
-@test 10*sol.minimum < l1
-
-rosenbrock(x, p=nothing) =  (1 - x[1])^2 + 100 * (x[2] - x[1]^2)^2
-
 l1 = rosenbrock(x0)
 prob = OptimizationProblem(rosenbrock, x0)
 sol = solve(prob, NelderMead())
@@ -86,7 +92,17 @@ prob = OptimizationProblem(optprob, x0, lb=[-1.0, -1.0], ub=[0.8, 0.8])
 @test_broken @test_nowarn sol = solve(prob, SAMIN())
 @test 10*sol.minimum < l1
 
-using NLopt
+## CMAEvolutionStrategy.jl solvers
+
+using GalacticCMAEvolutionStrategy
+sol = solve(prob, CMAEvolutionStrategyOpt())
+@test 10*sol.minimum < l1
+
+rosenbrock(x, p=nothing) =  (1 - x[1])^2 + 100 * (x[2] - x[1]^2)^2
+
+## NLopt.jl solvers
+
+using GalacticNLopt
 prob = OptimizationProblem(optprob, x0)
 sol = solve(prob, Opt(:LN_BOBYQA, 2))
 @test 10*sol.minimum < l1
@@ -101,19 +117,15 @@ sol = solve(prob, Opt(:LD_LBFGS, 2))
 sol = solve(prob, Opt(:G_MLSL_LDS, 2), nstart=2, local_method = Opt(:LD_LBFGS, 2), maxiters=10000)
 @test 10*sol.minimum < l1
 
-# using MultistartOptimization
-# sol = solve(prob, MultistartOptimization.TikTak(100), local_method = NLopt.LD_LBFGS)
-# @test 10*sol.minimum < l1
+## Evolutionary.jl Solvers
 
-# using QuadDIRECT
-# sol = solve(prob, QuadDirect(); splits = ([-0.5, 0.0, 0.5],[-0.5, 0.0, 0.5]))
-# @test 10*sol.minimum < l1
-
-using Evolutionary
+using GalacticEvolutionary
 sol = solve(prob, CMAES(μ =40 , λ = 100),abstol=1e-15)
 @test 10*sol.minimum < l1
 
-using BlackBoxOptim
+## BlackBoxOptim.jl Solvers
+
+using GalacticBBO
 prob = GalacticOptim.OptimizationProblem(optprob, x0, lb=[-1.0, -1.0], ub=[0.8, 0.8])
 sol = solve(prob, BBO())
 @test 10*sol.minimum < l1

docs/src/tutorials/symbolic.md

@@ -1,7 +1,12 @@
 # Symbolic Problem Building with ModelingToolkit
 
+!!! note
+
+    This example uses the GalacticOptimJL.jl package. See the [Optim.jl page](@ref optim)
+    for details on the installation and usage.
+
 ```julia
-using ModelingToolkit, GalacticOptim
+using ModelingToolkit, GalacticOptim, GalacticOptimJL
 
 @variables x y
 @parameters a b