format markdown

Author: ArnoStrouwen

.JuliaFormatter.toml

@@ -1 +1,2 @@
 style = "sciml"
+format_markdown = true

.gitignore

@@ -1,3 +1,4 @@
 .DS_Store
 /Manifest.toml
 /dev/
+/docs/build/

README.md

@@ -6,7 +6,7 @@
 [![codecov](https://codecov.io/gh/SciML/Optimization.jl/branch/master/graph/badge.svg)](https://codecov.io/gh/SciML/Optimization.jl)
 [![Build Status](https://github.com/SciML/Optimization.jl/workflows/CI/badge.svg)](https://github.com/SciML/Optimization.jl/actions?query=workflow%3ACI)
 
-[![ColPrac: Contributor's Guide on Collaborative Practices for Community Packages](https://img.shields.io/badge/ColPrac-Contributor's%20Guide-blueviolet)](https://github.com/SciML/ColPrac)
+[![ColPrac: Contributor's Guide on Collaborative Practices for Community Packages](https://img.shields.io/badge/ColPrac-Contributor%27s%20Guide-blueviolet)](https://github.com/SciML/ColPrac)
 [![SciML Code Style](https://img.shields.io/static/v1?label=code%20style&message=SciML&color=9558b2&labelColor=389826)](https://github.com/SciML/SciMLStyle)
 
 Optimization.jl is a package with a scope that is beyond your normal global optimization
@@ -23,25 +23,27 @@ Assuming that you already have Julia correctly installed, it suffices to import
 Optimization.jl in the standard way:
 
 ```julia
-import Pkg; Pkg.add("Optimization")
+using Pkg
+Pkg.add("Optimization")
 ```
+
 The packages relevant to the core functionality of Optimization.jl will be imported
 accordingly and, in most cases, you do not have to worry about the manual
 installation of dependencies. Below is the list of packages that need to be
 installed explicitly if you intend to use the specific optimization algorithms
 offered by them:
 
-- OptimizationBBO for [BlackBoxOptim.jl](https://github.com/robertfeldt/BlackBoxOptim.jl)
-- OptimizationEvolutionary for [Evolutionary.jl](https://github.com/wildart/Evolutionary.jl) (see also [this documentation](https://wildart.github.io/Evolutionary.jl/dev/))
-- OptimizationGCMAES for [GCMAES.jl](https://github.com/AStupidBear/GCMAES.jl)
-- OptimizationMOI for [MathOptInterface.jl](https://github.com/jump-dev/MathOptInterface.jl) (usage of algorithm via MathOptInterface API; see also the API [documentation](https://jump.dev/MathOptInterface.jl/stable/))
-- OptimizationMetaheuristics for [Metaheuristics.jl](https://github.com/jmejia8/Metaheuristics.jl) (see also [this documentation](https://jmejia8.github.io/Metaheuristics.jl/stable/))
-- OptimizationMultistartOptimization for [MultistartOptimization.jl](https://github.com/tpapp/MultistartOptimization.jl) (see also [this documentation](https://juliahub.com/docs/MultistartOptimization/cVZvi/0.1.0/))
-- OptimizationNLopt for [NLopt.jl](https://github.com/JuliaOpt/NLopt.jl) (usage via the NLopt API; see also the available [algorithms](https://nlopt.readthedocs.io/en/latest/NLopt_Algorithms/))
-- OptimizationNOMAD for [NOMAD.jl](https://github.com/bbopt/NOMAD.jl) (see also [this documentation](https://bbopt.github.io/NOMAD.jl/stable/))
-- OptimizationNonconvex for [Nonconvex.jl](https://github.com/JuliaNonconvex/Nonconvex.jl) (see also [this documentation](https://julianonconvex.github.io/Nonconvex.jl/stable/))
-- OptimizationQuadDIRECT for [QuadDIRECT.jl](https://github.com/timholy/QuadDIRECT.jl)
-- OptimizationSpeedMapping for [SpeedMapping.jl](https://github.com/NicolasL-S/SpeedMapping.jl) (see also [this documentation](https://nicolasl-s.github.io/SpeedMapping.jl/stable/))
+  - OptimizationBBO for [BlackBoxOptim.jl](https://github.com/robertfeldt/BlackBoxOptim.jl)
+  - OptimizationEvolutionary for [Evolutionary.jl](https://github.com/wildart/Evolutionary.jl) (see also [this documentation](https://wildart.github.io/Evolutionary.jl/dev/))
+  - OptimizationGCMAES for [GCMAES.jl](https://github.com/AStupidBear/GCMAES.jl)
+  - OptimizationMOI for [MathOptInterface.jl](https://github.com/jump-dev/MathOptInterface.jl) (usage of algorithm via MathOptInterface API; see also the API [documentation](https://jump.dev/MathOptInterface.jl/stable/))
+  - OptimizationMetaheuristics for [Metaheuristics.jl](https://github.com/jmejia8/Metaheuristics.jl) (see also [this documentation](https://jmejia8.github.io/Metaheuristics.jl/stable/))
+  - OptimizationMultistartOptimization for [MultistartOptimization.jl](https://github.com/tpapp/MultistartOptimization.jl) (see also [this documentation](https://juliahub.com/docs/MultistartOptimization/cVZvi/0.1.0/))
+  - OptimizationNLopt for [NLopt.jl](https://github.com/JuliaOpt/NLopt.jl) (usage via the NLopt API; see also the available [algorithms](https://nlopt.readthedocs.io/en/latest/NLopt_Algorithms/))
+  - OptimizationNOMAD for [NOMAD.jl](https://github.com/bbopt/NOMAD.jl) (see also [this documentation](https://bbopt.github.io/NOMAD.jl/stable/))
+  - OptimizationNonconvex for [Nonconvex.jl](https://github.com/JuliaNonconvex/Nonconvex.jl) (see also [this documentation](https://julianonconvex.github.io/Nonconvex.jl/stable/))
+  - OptimizationQuadDIRECT for [QuadDIRECT.jl](https://github.com/timholy/QuadDIRECT.jl)
+  - OptimizationSpeedMapping for [SpeedMapping.jl](https://github.com/NicolasL-S/SpeedMapping.jl) (see also [this documentation](https://nicolasl-s.github.io/SpeedMapping.jl/stable/))
 
 ## Tutorials and Documentation
 
@@ -54,36 +56,34 @@ the documentation, which contains the unreleased features.
 
 ```julia
 using Optimization
-rosenbrock(x,p) =  (p[1] - x[1])^2 + p[2] * (x[2] - x[1]^2)^2
+rosenbrock(x, p) = (p[1] - x[1])^2 + p[2] * (x[2] - x[1]^2)^2
 x0 = zeros(2)
-p  = [1.0,100.0]
+p = [1.0, 100.0]
 
-prob = OptimizationProblem(rosenbrock,x0,p)
+prob = OptimizationProblem(rosenbrock, x0, p)
 
 using OptimizationOptimJL
-sol = solve(prob,NelderMead())
-
+sol = solve(prob, NelderMead())
 
 using OptimizationBBO
-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())
+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 Optimization.jl. However, BlackBoxOptim.jl
 is not and must already be installed (see the list above).
 
 *Warning:* The output of the second optimization task (`BBO_adaptive_de_rand_1_bin_radiuslimited()`) is
-currently misleading in the sense that it returns `Status: failure
-(reached maximum number of iterations)`. However, convergence is actually
+currently misleading in the sense that it returns `Status: failure (reached maximum number of iterations)`. However, convergence is actually
 reached and the confusing message stems from the reliance on the Optim.jl output
- struct (where the situation of reaching the maximum number of iterations is
+struct (where the situation of reaching the maximum number of iterations is
 rightly regarded as a failure). The improved output struct will soon be
 implemented.
 
 The output of the first optimization task (with the `NelderMead()` algorithm)
 is given below:
 
-```julia
+```
 * Status: success
 
 * Candidate solution
@@ -100,17 +100,19 @@ is given below:
    Iterations:    60
    f(x) calls:    118
 ```
+
 We can also explore other methods in a similar way:
 
 ```julia
 using ForwardDiff
 f = OptimizationFunction(rosenbrock, Optimization.AutoForwardDiff())
 prob = OptimizationProblem(f, x0, p)
-sol = solve(prob,BFGS())
+sol = solve(prob, BFGS())
 ```
+
 For instance, the above optimization task produces the following output:
 
-```julia
+```
 * Status: success
 
 * Candidate solution
@@ -134,9 +136,10 @@ For instance, the above optimization task produces the following output:
 ```
 
 ```julia
-prob = OptimizationProblem(f, x0, p, lb = [-1.0,-1.0], ub = [1.0,1.0])
+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 Optimization.jl provides an intuitive
 way of specifying optimization tasks and offers a relatively
 easy access to a wide range of optimization algorithms.

docs/src/API/FAQ.md

@@ -3,7 +3,7 @@
 ## The Solver Seems to Violate Constraints During the Optimization, Causing `DomainError`s, What Can I Do About That?
 
 During the optimization, optimizers use slack variables to relax the solution to the constraints. Because of this,
-there is no guarantee that for an arbitrary optimizer the steps will all satisfy the constraints during the 
+there is no guarantee that for an arbitrary optimizer the steps will all satisfy the constraints during the
 optimization. In many cases, this can cause one's objective function code throw a `DomainError` if it is evaluated
 outside of its acceptable zone. For example, `log(-1)` gives:
 
@@ -16,15 +16,15 @@ log will only return a complex result if called with a complex argument. Try log
 To handle this, one should not assume that the variables will always satisfy the constraints on each step. There
 are three general ways to handle this better:
 
-1. Use [NaNMath.jl](https://github.com/JuliaMath/NaNMath.jl)
-2. Process variables before domain-restricted calls
-3. Use a domain transformation
+ 1. Use [NaNMath.jl](https://github.com/JuliaMath/NaNMath.jl)
+ 2. Process variables before domain-restricted calls
+ 3. Use a domain transformation
 
 NaNMath.jl gives alternative implementations of standard math functions like `log` and `sqrt` in forms that do not
 throw `DomainError`s but rather return `NaN`s. The optimizers will be able to handle the NaNs gracefully and recover,
 allowing for many of these cases to be solved without further modification. Note that this is done [internally in
 JuMP.jl, and thus if a case is working with JuMP and not Optimization.jl
-](https://discourse.julialang.org/t/optimizationmoi-ipopt-violating-inequality-constraint/92608/) this may be the 
+](https://discourse.julialang.org/t/optimizationmoi-ipopt-violating-inequality-constraint/92608/) this may be the
 reason for the difference.
 
 Alternatively, one can pre-process the values directly. For example, `log(abs(x))` is guaranteed to work. If one does
@@ -68,7 +68,7 @@ example, the ModelingToolkit integration with Optimization.jl will do many simpl
 is called. One of them is tearing on the constraints. To understand the tearing process, assume that we had
 nonlinear constraints of the form:
 
-```julia
+```
     0 ~ u1 - sin(u5) * h,
     0 ~ u2 - cos(u1),
     0 ~ u3 - hypot(u1, u2),
@@ -86,7 +86,7 @@ u3 = f3(u1, u2)
 u4 = f4(u2, u3)
 ```
 
-and thus if the objective function was the function of these 5 variables and 4 constraints, ModelingToolkit.jl will 
+and thus if the objective function was the function of these 5 variables and 4 constraints, ModelingToolkit.jl will
 transform it into system of 1 variable with no constraints, allowing unconstrained optimization on a smaller system.
 This will both be faster and numerically easier.
 

docs/src/API/modelingtoolkit.md

@@ -1,19 +1,19 @@
-# ModelingToolkit Integration
-
-Optimization.jl is heavily integrated with the ModelingToolkit.jl
-symbolic system for symbolic-numeric optimizations. It provides a
-front-end for automating the construction, parallelization, and
-optimization of code. Optimizers can better interface with the extra
-symbolic information provided by the system.
-
-There are two ways that the user interacts with ModelingToolkit.jl.
-One can use `OptimizationFunction` with `AutoModelingToolkit` for
-automatically transforming numerical codes into symbolic codes. See
-the [OptimizationFunction documentation](@id optfunction) for more
-details.
-
-Secondly, one can generate `OptimizationProblem`s for use in
-Optimization.jl from purely a symbolic front-end. This is the form
-users will encounter when using ModelingToolkit.jl directly, and it is
-also the form supplied by domain-specific languages. For more information,
-see the [OptimizationSystem documentation](https://docs.sciml.ai/ModelingToolkit/stable/systems/OptimizationSystem/).
+# ModelingToolkit Integration
+
+Optimization.jl is heavily integrated with the ModelingToolkit.jl
+symbolic system for symbolic-numeric optimizations. It provides a
+front-end for automating the construction, parallelization, and
+optimization of code. Optimizers can better interface with the extra
+symbolic information provided by the system.
+
+There are two ways that the user interacts with ModelingToolkit.jl.
+One can use `OptimizationFunction` with `AutoModelingToolkit` for
+automatically transforming numerical codes into symbolic codes. See
+the [OptimizationFunction documentation](@id optfunction) for more
+details.
+
+Secondly, one can generate `OptimizationProblem`s for use in
+Optimization.jl from purely a symbolic front-end. This is the form
+users will encounter when using ModelingToolkit.jl directly, and it is
+also the form supplied by domain-specific languages. For more information,
+see the [OptimizationSystem documentation](https://docs.sciml.ai/ModelingToolkit/stable/systems/OptimizationSystem/).

docs/src/API/optimization_function.md

@@ -8,12 +8,12 @@ SciMLBase.OptimizationFunction
 
 The choices for the auto-AD fill-ins with quick descriptions are:
 
-- `AutoForwardDiff()`: The fastest choice for small optimizations
-- `AutoReverseDiff(compile=false)`: A fast choice for large scalar optimizations
-- `AutoTracker()`: Like ReverseDiff but GPU-compatible
-- `AutoZygote()`: The fastest choice for non-mutating array-based (BLAS) functions
-- `AutoFiniteDiff()`: Finite differencing, not optimal but always applicable
-- `AutoModelingToolkit()`: The fastest choice for large scalar optimizations
+  - `AutoForwardDiff()`: The fastest choice for small optimizations
+  - `AutoReverseDiff(compile=false)`: A fast choice for large scalar optimizations
+  - `AutoTracker()`: Like ReverseDiff but GPU-compatible
+  - `AutoZygote()`: The fastest choice for non-mutating array-based (BLAS) functions
+  - `AutoFiniteDiff()`: Finite differencing, not optimal but always applicable
+  - `AutoModelingToolkit()`: The fastest choice for large scalar optimizations
 
 ## Automatic Differentiation Choice API
 
@@ -27,4 +27,3 @@ Optimization.AutoZygote
 Optimization.AutoTracker
 Optimization.AutoModelingToolkit
 ```
-