docs: update documentation

avik-pal · avik-pal · commit f3a7cccbcca3 · 2024-10-22T18:34:33.000-04:00
diff --git a/.github/workflows/Documentation.yml b/.github/workflows/Documentation.yml
@@ -15,7 +15,7 @@ jobs:
       - uses: actions/checkout@v4
       - uses: julia-actions/setup-julia@latest
         with:
-          version: '1'
+          version: '1.10'
       - name: Install dependencies
         run: |
           import Pkg
diff --git a/.github/workflows/Downgrade.yml b/.github/workflows/Downgrade.yml
@@ -15,14 +15,40 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        version: ["1.10"]
+        version:
+          - "1.10"
+        group:
+          - Core
+          - Downstream
+          - Misc
+          - Wrappers
     steps:
       - uses: actions/checkout@v4
       - uses: julia-actions/setup-julia@v2
         with:
           version: ${{ matrix.version }}
       - uses: julia-actions/julia-downgrade-compat@v1
+      - name: "Install Dependencies and Run Tests"
+        run: |
+          import Pkg
+          Pkg.Registry.update()
+          # Install packages present in subdirectories
+          dev_pks = Pkg.PackageSpec[]
+          for path in ("lib/SciMLJacobianOperators", "lib/BracketingNonlinearSolve", "lib/NonlinearSolveBase", "lib/SimpleNonlinearSolve")
+              push!(dev_pks, Pkg.PackageSpec(; path))
+          end
+          Pkg.develop(dev_pks)
+          Pkg.instantiate()
+          Pkg.test(; coverage=true)
+        shell: julia --color=yes --code-coverage=user --depwarn=yes --project=. {0}
+        env:
+          GROUP: ${{ matrix.group }}
+      - uses: julia-actions/julia-processcoverage@v1
         with:
-          skip: Pkg,TOML
-      - uses: julia-actions/julia-buildpkg@v1
-      - uses: julia-actions/julia-runtest@v1
+          directories: src,ext,lib/SciMLJacobianOperators/src
+      - uses: codecov/codecov-action@v4
+        with:
+          file: lcov.info
+          token: ${{ secrets.CODECOV_TOKEN }}
+          verbose: true
+          fail_ci_if_error: true
diff --git a/docs/Project.toml b/docs/Project.toml
@@ -3,6 +3,7 @@ ADTypes = "47edcb42-4c32-4615-8424-f2b9edc5f35b"
 AlgebraicMultigrid = "2169fc97-5a83-5252-b627-83903c6c433c"
 ArrayInterface = "4fba245c-0d91-5ea0-9b3e-6abc04ee57a9"
 BenchmarkTools = "6e4b80f9-dd63-53aa-95a3-0cdb28fa8baf"
+BracketingNonlinearSolve = "70df07ce-3d50-431d-a3e7-ca6ddb60ac1e"
 DiffEqBase = "2b5f629d-d688-5b77-993f-72d75c75574e"
 DifferentiationInterface = "a0c0ee7d-e4b9-4e03-894e-1c5f64a51d63"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
@@ -11,8 +12,8 @@ DocumenterInterLinks = "d12716ef-a0f6-4df4-a9f1-a5a34e75c656"
 IncompleteLU = "40713840-3770-5561-ab4c-a76e7d0d7895"
 InteractiveUtils = "b77e0a4c-d291-57a0-90e8-8db25a27a240"
 LinearSolve = "7ed4a6bd-45f5-4d41-b270-4a48e9bafcae"
-ModelingToolkit = "961ee093-0014-501f-94e3-6117800e7a78"
 NonlinearSolve = "8913a72c-1f9b-4ce2-8d82-65094dcecaec"
+NonlinearSolveBase = "be0214bd-f91f-a760-ac4e-3421ce2b2da0"
 OrdinaryDiffEqTsit5 = "b1df2697-797e-41e3-8120-5422d3b24e4a"
 Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"
 Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
@@ -29,16 +30,16 @@ ADTypes = "1.9.0"
 AlgebraicMultigrid = "0.5, 0.6"
 ArrayInterface = "6, 7"
 BenchmarkTools = "1"
-DiffEqBase = "6.136"
+BracketingNonlinearSolve = "1"
 DifferentiationInterface = "0.6.1"
 Documenter = "1"
 DocumenterCitations = "1"
 DocumenterInterLinks = "1.0.0"
 IncompleteLU = "0.2"
 InteractiveUtils = "<0.0.1, 1"
 LinearSolve = "2"
-ModelingToolkit = "9"
 NonlinearSolve = "4"
+NonlinearSolveBase = "1"
 OrdinaryDiffEqTsit5 = "1.1.0"
 Plots = "1"
 Random = "1.10"
diff --git a/docs/make.jl b/docs/make.jl
@@ -1,7 +1,8 @@
 using Documenter, DocumenterCitations, DocumenterInterLinks
 using NonlinearSolve, SimpleNonlinearSolve, Sundials, SteadyStateDiffEq, SciMLBase,
-      DiffEqBase
+      BracketingNonlinearSolve, NonlinearSolveBase
 using SciMLJacobianOperators
+import DiffEqBase
 
 cp(joinpath(@__DIR__, "Manifest.toml"),
     joinpath(@__DIR__, "src/assets/Manifest.toml"), force = true)
@@ -20,8 +21,9 @@ interlinks = InterLinks(
 makedocs(;
     sitename = "NonlinearSolve.jl",
     authors = "Chris Rackauckas",
-    modules = [NonlinearSolve, SimpleNonlinearSolve, SteadyStateDiffEq,
-        Sundials, DiffEqBase, SciMLBase, SciMLJacobianOperators],
+    modules = [NonlinearSolve, SimpleNonlinearSolve, SteadyStateDiffEq, DiffEqBase,
+        Sundials, NonlinearSolveBase, SciMLBase, SciMLJacobianOperators,
+        BracketingNonlinearSolve],
     clean = true,
     doctest = false,
     linkcheck = true,
diff --git a/docs/pages.jl b/docs/pages.jl
@@ -1,6 +1,7 @@
 # Put in a separate page so it can be used by SciMLDocs.jl
 
-pages = ["index.md",
+pages = [
+    "index.md",
     "Getting Started with Nonlinear Rootfinding in Julia" => "tutorials/getting_started.md",
     "Tutorials" => Any[
         "tutorials/code_optimization.md",
@@ -31,6 +32,7 @@ pages = ["index.md",
     "Native Functionalities" => Any[
         "native/solvers.md",
         "native/simplenonlinearsolve.md",
+        "native/bracketingnonlinearsolve.md",
         "native/steadystatediffeq.md",
         "native/descent.md",
         "native/globalization.md",
diff --git a/docs/src/basics/diagnostics_api.md b/docs/src/basics/diagnostics_api.md
@@ -27,20 +27,16 @@ Note that you will have to restart Julia to disable the timer outputs once enabl
 ## Example Usage
 
 ```@example diagnostics_example
-using ModelingToolkit, NonlinearSolve
+using NonlinearSolve
 
-@variables x y z
-@parameters σ ρ β
+function nlfunc(resid, u0, p)
+    resid[1] = u0[1] * u0[1] - p
+    resid[2] = u0[2] * u0[2] - p
+    resid[3] = u0[3] * u0[3] - p
+    nothing
+end
 
-# Define a nonlinear system
-eqs = [0 ~ σ * (y - x), 0 ~ x * (ρ - z) - y, 0 ~ x * y - β * z]
-@mtkbuild ns = NonlinearSystem(eqs, [x, y, z], [σ, ρ, β])
-
-u0 = [x => 1.0, y => 0.0, z => 0.0]
-
-ps = [σ => 10.0 ρ => 26.0 β => 8 / 3]
-
-prob = NonlinearProblem(ns, u0, ps)
+prob = NonlinearProblem(nlfunc, [1.0, 3.0, 5.0], 2.0)
 
 solve(prob)
 ```
diff --git a/docs/src/basics/solve.md b/docs/src/basics/solve.md
@@ -1,7 +1,7 @@
 # [Common Solver Options (Solve Keyword Arguments)](@id solver_options)
 
 ```@docs
-solve(prob::SciMLBase.NonlinearProblem, args...; kwargs...)
+solve(::NonlinearProblem, args...; kwargs...)
 ```
 
 ## General Controls
diff --git a/docs/src/basics/termination_condition.md b/docs/src/basics/termination_condition.md
@@ -23,17 +23,23 @@ terminated = cache(du, u, uprev)
 ### Absolute Tolerance
 
 ```@docs
-AbsTerminationMode
-AbsNormTerminationMode
-AbsNormSafeTerminationMode
-AbsNormSafeBestTerminationMode
+NonlinearSolveBase.AbsTerminationMode
+NonlinearSolveBase.AbsNormTerminationMode
+NonlinearSolveBase.AbsNormSafeTerminationMode
+NonlinearSolveBase.AbsNormSafeBestTerminationMode
 ```
 
 ### Relative Tolerance
 
 ```@docs
-RelTerminationMode
-RelNormTerminationMode
-RelNormSafeTerminationMode
-RelNormSafeBestTerminationMode
+NonlinearSolveBase.RelTerminationMode
+NonlinearSolveBase.RelNormTerminationMode
+NonlinearSolveBase.RelNormSafeTerminationMode
+NonlinearSolveBase.RelNormSafeBestTerminationMode
+```
+
+### Both Tolerances
+
+```@docs
+NonlinearSolveBase.NormTerminationMode
 ```
diff --git a/docs/src/devdocs/algorithm_helpers.md b/docs/src/devdocs/algorithm_helpers.md
@@ -60,9 +60,6 @@ NonlinearSolve.GenericTrustRegionScheme
 ## Miscellaneous
 
 ```@docs
-SimpleNonlinearSolve.__nextfloat_tdir
-SimpleNonlinearSolve.__prevfloat_tdir
-SimpleNonlinearSolve.__max_tdir
 NonlinearSolve.callback_into_cache!
 NonlinearSolve.concrete_jac
 ```
diff --git a/docs/src/native/bracketingnonlinearsolve.md b/docs/src/native/bracketingnonlinearsolve.md
@@ -0,0 +1,21 @@
+# BracketingNonlinearSolve.jl
+
+These methods can be used independently of the rest of NonlinearSolve.jl
+
+```@index
+Pages = ["bracketingnonlinearsolve.md"]
+```
+
+## Interval Methods
+
+These methods are suited for interval (scalar) root-finding problems,
+i.e. [`IntervalNonlinearProblem`](@ref).
+
+```@docs
+ITP
+Alefeld
+Bisection
+Falsi
+Ridder
+Brent
+```
diff --git a/docs/src/native/simplenonlinearsolve.md b/docs/src/native/simplenonlinearsolve.md
@@ -6,20 +6,6 @@ These methods can be used independently of the rest of NonlinearSolve.jl
 Pages = ["simplenonlinearsolve.md"]
 ```
 
-## Interval Methods
-
-These methods are suited for interval (scalar) root-finding problems,
-i.e. `IntervalNonlinearProblem`.
-
-```@docs
-ITP
-Alefeld
-Bisection
-Falsi
-Ridder
-Brent
-```
-
 ## General Methods
 
 These methods are suited for any general nonlinear root-finding problem, i.e.
@@ -54,6 +40,6 @@ Squares problems.
 [^1]: Needs [`StaticArrays.jl`](https://github.com/JuliaArrays/StaticArrays.jl) to be
     installed and loaded for the non-allocating version.
 [^2]: This method is non-allocating if the termination condition is set to either `nothing`
-    (default) or [`AbsNormTerminationMode`](@ref).
+    (default) or [`NonlinearSolveBase.AbsNormTerminationMode`](@ref).
 [^3]: Only the defaults are guaranteed to work inside kernels. We try to provide warnings
     if the used version is not non-allocating.
diff --git a/docs/src/tutorials/modelingtoolkit.md b/docs/src/tutorials/modelingtoolkit.md
@@ -5,7 +5,7 @@ modeling system for the Julia SciML ecosystem. It adds a high-level interactive
 for the numerical solvers which can make it easy to symbolically modify and generate
 equations to be solved. The basic form of using ModelingToolkit looks as follows:
 
-```@example mtk
+```julia
 using ModelingToolkit, NonlinearSolve
 
 @variables x y z
@@ -30,20 +30,20 @@ sol = solve(prob, NewtonRaphson())
 As a symbolic system, ModelingToolkit can be used to represent the equations and derive new
 forms. For example, let's look at the equations:
 
-```@example mtk
+```julia
 equations(ns)
 ```
 
 We can ask it what the Jacobian of our system is via `calculate_jacobian`:
 
-```@example mtk
+```julia
 calculate_jacobian(ns)
 ```
 
 We can tell MTK to generate a computable form of this analytical Jacobian via `jac = true`
 to help the solver use efficient forms:
 
-```@example mtk
+```julia
 prob = NonlinearProblem(ns, u0, ps, jac = true)
 sol = solve(prob, NewtonRaphson())
 ```
@@ -54,7 +54,7 @@ One of the major reasons for using ModelingToolkit is to allow structural simpli
 the systems. It's very easy to write down a mathematical model that, in theory, could be
 solved more simply. Let's take a look at a quick system:
 
-```@example mtk
+```julia
 @variables u1 u2 u3 u4 u5
 eqs = [0 ~ u1 - sin(u5), 0 ~ u2 - cos(u1), 0 ~ u3 - hypot(u1, u2),
     0 ~ u4 - hypot(u2, u3), 0 ~ u5 - hypot(u4, u1)]
@@ -63,47 +63,47 @@ eqs = [0 ~ u1 - sin(u5), 0 ~ u2 - cos(u1), 0 ~ u3 - hypot(u1, u2),
 
 If we run structural simplification, we receive the following form:
 
-```@example mtk
+```julia
 sys = structural_simplify(sys)
 ```
 
-```@example mtk
+```julia
 equations(sys)
 ```
 
 How did it do this? Let's look at the `observed` to see the relationships that it found:
 
-```@example mtk
+```julia
 observed(sys)
 ```
 
 Using ModelingToolkit, we can build and solve the simplified system:
 
-```@example mtk
+```julia
 u0 = [u5 .=> 1.0]
 prob = NonlinearProblem(sys, u0)
 sol = solve(prob, NewtonRaphson())
 ```
 
 We can then use symbolic indexing to retrieve any variable:
 
-```@example mtk
+```julia
 sol[u1]
 ```
 
-```@example mtk
+```julia
 sol[u2]
 ```
 
-```@example mtk
+```julia
 sol[u3]
 ```
 
-```@example mtk
+```julia
 sol[u4]
 ```
 
-```@example mtk
+```julia
 sol[u5]
 ```
 
diff --git a/lib/BracketingNonlinearSolve/README.md b/lib/BracketingNonlinearSolve/README.md
@@ -0,0 +1,23 @@
+# BracketingNonlinearSolve.jl
+
+Fast implementations of interval root finding algorithms in Julia that satisfy the SciML
+common interface. BracketingNonlinearSolve.jl focuses on low-dependency implementations of
+very fast methods for very small and simple problems. For the full set of solvers, see
+[NonlinearSolve.jl](https://github.com/SciML/NonlinearSolve.jl), of which
+BracketingNonlinearSolve.jl is just one solver set.
+
+For information on using the package,
+[see the stable documentation](https://docs.sciml.ai/NonlinearSolve/stable/). Use the
+[in-development documentation](https://docs.sciml.ai/NonlinearSolve/dev/) for the version of
+the documentation which contains the unreleased features.
+
+## High Level Examples
+
+```julia
+using BracketingNonlinearSolve
+
+f(u, p) = u .* u .- 2.0
+u0 = (1.0, 2.0) # brackets
+probB = IntervalNonlinearProblem(f, u0)
+sol = solve(probB, ITP())
+```
diff --git a/lib/NonlinearSolveBase/src/public.jl b/lib/NonlinearSolveBase/src/public.jl
@@ -81,7 +81,7 @@ for norm_type in (:RelNorm, :AbsNorm), safety in (:Safe, :SafeBest)
     supertype_name = Symbol(:Abstract, safety, :NonlinearTerminationMode)
 
     doctring = safety == :Safe ?
-               "Essentially [`$(norm_type)NormTerminationMode`](@ref) + terminate if there \
+               "Essentially [`$(norm_type)TerminationMode`](@ref) + terminate if there \
                 has been no improvement for the last `patience_steps` + terminate if the \
                 solution blows up (diverges)." :
                "Essentially [`$(norm_type)SafeTerminationMode`](@ref), but caches the best\
diff --git a/lib/SimpleNonlinearSolve/README.md b/lib/SimpleNonlinearSolve/README.md
