Merge pull request #110 from SciML/docs

ChrisRackauckas · web-flow · commit 8fa597523550 · 2022-12-04T14:15:39.000+01:00
Add steady state docs and MINPACK
diff --git a/docs/Project.toml b/docs/Project.toml
@@ -2,10 +2,20 @@
 BenchmarkTools = "6e4b80f9-dd63-53aa-95a3-0cdb28fa8baf"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 NonlinearSolve = "8913a72c-1f9b-4ce2-8d82-65094dcecaec"
+NonlinearSolveMINPACK = "c100e077-885d-495a-a2ea-599e143bf69d"
+SciMLNLSolve = "e9a6253c-8580-4d32-9898-8661bb511710"
+SimpleNonlinearSolve = "727e6d20-b764-4bd8-a329-72de5adea6c7"
 StaticArrays = "90137ffa-7385-5640-81b9-e52037218182"
+SteadyStateDiffEq = "9672c7b4-1e72-59bd-8a11-6ac3964bc41f"
+Sundials = "c3572dad-4567-51f8-b174-8c6c989267f4"
 
 [compat]
 BenchmarkTools = "1"
 Documenter = "0.27"
 NonlinearSolve = "1"
+NonlinearSolveMINPACK = "0.1"
+SciMLNLSolve = "0.1"
+SimpleNonlinearSolve = "0.1"
 StaticArrays = "1"
+SteadyStateDiffEq = "1.10"
+Sundials = "4.11"
diff --git a/docs/make.jl b/docs/make.jl
@@ -1,4 +1,5 @@
-using Documenter, NonlinearSolve
+using Documenter, NonlinearSolve, SimpleNonlinearSolve, Sundials, SciMLNLSolve,
+      NonlinearSolveMINPACK, SteadyStateDiffEq
 
 cp("./docs/Manifest.toml", "./docs/src/assets/Manifest.toml", force = true)
 cp("./docs/Project.toml", "./docs/src/assets/Project.toml", force = true)
@@ -7,7 +8,8 @@ include("pages.jl")
 
 makedocs(sitename = "NonlinearSolve.jl",
          authors = "Chris Rackauckas",
-         modules = [NonlinearSolve, NonlinearSolve.SciMLBase],
+         modules = [NonlinearSolve, NonlinearSolve.SciMLBase, SimpleNonlinearSolve,
+             Sundials, SciMLNLSolve, NonlinearSolveMINPACK, SteadyStateDiffEq],
          clean = true, doctest = false,
          strict = [
              :doctest,
diff --git a/docs/pages.jl b/docs/pages.jl
@@ -5,7 +5,15 @@ pages = ["index.md",
                        "tutorials/iterator_interface.md"],
     "Basics" => Any["basics/NonlinearProblem.md",
                     "basics/NonlinearFunctions.md",
+                    "basics/NonlinearSolution.md",
                     "basics/FAQ.md"],
-    "Solvers" => Any["solvers/NonlinearSystemSolvers.md",
-                     "solvers/BracketingSolvers.md"],
+    "Solver Summaries and Recommendations" => Any["solvers/NonlinearSystemSolvers.md",
+                                                  "solvers/BracketingSolvers.md",
+                                                  "solvers/SteadyStateSolvers.md"],
+    "Detailed Solver APIs" => Any["api/nonlinearsolve.md",
+                                  "api/simplenonlinearsolve.md",
+                                  "api/minpack.md",
+                                  "api/nlsolve.md",
+                                  "api/sundials.md",
+                                  "api/steadystatediffeq.md"],
 ]
diff --git a/docs/src/api/minpack.md b/docs/src/api/minpack.md
@@ -0,0 +1,18 @@
+# MINPACK.jl
+
+This is a wrapper package for importing solvers from Sundials into the SciML interface.
+Note that these solvers do not come by default, and thus one needs to install
+the package before using these solvers:
+
+```julia
+]add NonlinearSolveMINPACK
+using NonlinearSolveMINPACK
+```
+
+These methods can be used independently of the rest of NonlinearSolve.jl
+
+## Solver API
+
+```@docs
+CMINPACK
+```
diff --git a/docs/src/api/nlsolve.md b/docs/src/api/nlsolve.md
@@ -0,0 +1,16 @@
+# NLsolve.jl
+
+This is a wrapper package for importing solvers from NLsolve.jl into the SciML interface.
+Note that these solvers do not come by default, and thus one needs to install
+the package before using these solvers:
+
+```julia
+]add SciMLNLSolve
+using SciMLNLSolve
+```
+
+## Solver API
+
+```@docs
+NLsolveJL
+```
diff --git a/docs/src/api/nonlinearsolve.md b/docs/src/api/nonlinearsolve.md
@@ -0,0 +1,9 @@
+# NonlinearSolve.jl Native Solvers
+
+These are the native solvers of NonlinearSolve.jl.
+
+## Solver API
+
+```@docs
+NewtonRaphson
+```
diff --git a/docs/src/api/simplenonlinearsolve.md b/docs/src/api/simplenonlinearsolve.md
@@ -0,0 +1,11 @@
+# SimpleNonlinearSolve.jl
+
+These methods can be used independently of the rest of NonlinearSolve.jl
+
+## Solver API
+
+```@docs
+Bisection
+Falsi
+SimpleNewtonRaphson
+```
diff --git a/docs/src/api/steadystatediffeq.md b/docs/src/api/steadystatediffeq.md
@@ -0,0 +1,19 @@
+# SteadyStateDiffEq.jl
+
+This is a wrapper package for using ODE solvers from
+[DifferentialEquations.jl](https://docs.sciml.ai/DiffEqDocs/stable/) into the SciML interface.
+Note that these solvers do not come by default, and thus one needs to install
+the package before using these solvers:
+
+```julia
+]add SteadyStateDiffEq
+using SteadyStateDiffEq
+```
+
+These methods can be used independently of the rest of NonlinearSolve.jl
+
+## Solver API
+
+```@docs
+DynamicSS
+```
diff --git a/docs/src/api/sundials.md b/docs/src/api/sundials.md
@@ -0,0 +1,18 @@
+## Sundials.jl
+
+This is a wrapper package for importing solvers from Sundials into the SciML interface.
+Note that these solvers do not come by default, and thus one needs to install
+the package before using these solvers:
+
+```julia
+]add Sundials
+using Sundials
+```
+
+These methods can be used independently of the rest of NonlinearSolve.jl
+
+## Solver API
+
+```@docs
+KINSOL
+```
diff --git a/docs/src/basics/FAQ.md b/docs/src/basics/FAQ.md
@@ -35,4 +35,4 @@ MATLAB 2022a achieves 1.66s. Try this code yourself: we receive 0.06 seconds, or
 This example is still not optimized in the Julia code and we expect an improvement in a near
 future version.
 
-For more information on performance of SciML, see the [SciMLBenchmarks](https://docs.sciml.ai/SciMLBenchmarksOutput/stable/)
+For more information on performance of SciML, see the [SciMLBenchmarks](https://docs.sciml.ai/SciMLBenchmarksOutput/stable/).
diff --git a/docs/src/basics/NonlinearProblem.md b/docs/src/basics/NonlinearProblem.md
@@ -1,32 +1,46 @@
 # Nonlinear Problems
 
-## The Two Types of Nonlinear Problems
+## The Three Types of Nonlinear Problems
 
 NonlinearSolve.jl tackles two related types of nonlinear systems:
 
 1. Interval rootfinding problems. I.e., find the ``t in [t_0, t_f]`` such that `f(t) = 0`.
 2. Systems of nonlinear equations, i.e. find the `u` such that `f(u) = 0`.
+3. Steady state problems, i.e. find the `u` such that `u' = f(u,t)` has reached steady state,
+   i.e. `0 = f(u, ∞)`.
 
-The former is for solving scalar rootfinding problems, i.e. finding a single number, and
+The first is for solving scalar rootfinding problems, i.e. finding a single number, and
 requires that a bracketing interval is known. For a bracketing interval, one must have that
 the sign of `f(t_0)` is opposite the sign of `f(t_f)`, thus guaranteeing a root in the
 interval.
 
-The latter type of nonlinear system can be multidimensional and thus no ordering nor
-boundaries are assumed to be known. For a system of nonlinear equations, `f` can return
-an array and the solver seeks to find the value of `u` for which all outputs of `f` are
-simultaniously zero.
-
 !!! note
 
     Interval rootfinding problems allow for `f` to return an array, in which case the interval
     rootfinding problem is interpreted as finding the first `t` such that any of the components
     of the array hit zero.
 
+The second type of nonlinear system can be multidimensional and thus no ordering nor
+boundaries are assumed to be known. For a system of nonlinear equations, `f` can return
+an array and the solver seeks to find the value of `u` for which all outputs of `f` are
+simultaniously zero.
+
+The last type if equivalent to a nonlinear system but with the extra interpretion of
+having a potentially preferred unique root. That is, when there are multiple `u` such
+that `f(u) = 0`, the `NonlinearProblem` does not have a preferred solution, while for the
+`SteadyStateProblem` the preferred solution is the `u(∞)` that would arise from solving the
+ODE `u' = f(u,t)`.
+
+!!! warn
+
+    Most solvers for `SteadyStateProblem` do not guarentee the preferred solution and
+    instead will solve for some `u` in the set of solutions. The documentation of the
+    nonlinear solvers will note if they return the preferred solution.
 
 ## Problem Construction Details
 
 ```@docs
 SciMLBase.IntervalNonlinearProblem
 SciMLBase.NonlinearProblem
+SciMLBase.SteadyStateProblem
 ```
diff --git a/docs/src/basics/NonlinearSolution.md b/docs/src/basics/NonlinearSolution.md
@@ -0,0 +1,5 @@
+# Nonlinear Solutions
+
+```@docs
+SciMLBase.NonlinearSolution
+```
diff --git a/docs/src/index.md b/docs/src/index.md
@@ -7,8 +7,8 @@ ability to use sparse automatic differentiation for Jacobian construction and
 Jacobian-vector products. It interfaces with other packages of the Julia ecosystem
 to make it easy to test alternative solver packages and pass small types to
 control algorithm swapping. It also interfaces with the
-[ModelingToolkit.jl](https://docs.sciml.ai/ModelingToolkit/stable/) world of symbolic modeling to
-allow for automatically generating high-performance code.
+[ModelingToolkit.jl](https://docs.sciml.ai/ModelingToolkit/stable/) world of symbolic
+modeling to allow for automatically generating high-performance code.
 
 Performance is key: the current methods are made to be highly performant on
 scalar and statically sized small problems, with options for large-scale systems.
@@ -39,14 +39,8 @@ Pkg.add("NonlinearSolve")
     - On the [Julia Discourse forums](https://discourse.julialang.org)
     - See also [SciML Community page](https://sciml.ai/community/)
 
-## Roadmap
-
-The current algorithms should support automatic differentiation, though improved
-adjoint overloads are planned to be added in the current update (which will make
-use of the `f(u,p)` form). Future updates will include standard methods for
-larger scale nonlinear solving like Newton-Krylov methods.
-
 ## Reproducibility
+
 ```@raw html
 <details><summary>The documentation of this SciML package was built using these direct dependencies,</summary>
 ```
diff --git a/docs/src/solvers/BracketingSolvers.md b/docs/src/solvers/BracketingSolvers.md
@@ -5,8 +5,6 @@
 Solves for ``f(t)=0`` in the problem defined by `prob` using the algorithm
 `alg`. If no algorithm is given, a default algorithm will be chosen.
 
-This page is solely focused on the bracketing methods for scalar nonlinear equations.
-
 ## Recommended Methods
 
 `Falsi()` can have a faster convergence and is discretely differentiable, but is
diff --git a/docs/src/solvers/NonlinearSystemSolvers.md b/docs/src/solvers/NonlinearSystemSolvers.md
diff --git a/docs/src/solvers/SteadyStateSolvers.md b/docs/src/solvers/SteadyStateSolvers.md
diff --git a/src/raphson.jl b/src/raphson.jl
