docs: update documentation

Author: avik-pal

.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

.github/workflows/Downgrade.yml

@@ -14,15 +14,42 @@ jobs:
   test:
     runs-on: ubuntu-latest
     strategy:
+      fail-fast: false
       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

Project.toml

@@ -68,9 +68,9 @@ BenchmarkTools = "1.4"
 CUDA = "5.5"
 CommonSolve = "0.2.4"
 ConcreteStructs = "0.2.3"
-DiffEqBase = "6.158.3"
-DifferentiationInterface = "0.6.1"
-Enzyme = "0.13.2"
+DiffEqBase = "6.155.3"
+DifferentiationInterface = "0.6.16"
+Enzyme = "0.13.11"
 ExplicitImports = "1.5"
 FastClosures = "0.3.2"
 FastLevenbergMarquardt = "0.1"
@@ -108,7 +108,7 @@ SciMLOperators = "0.3.10"
 SimpleNonlinearSolve = "2"
 SparseArrays = "1.10"
 SparseConnectivityTracer = "0.6.5"
-SparseMatrixColorings = "0.4.2"
+SparseMatrixColorings = "0.4.5"
 SpeedMapping = "0.3"
 StableRNGs = "1"
 StaticArrays = "1.9"

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"
-DifferentiationInterface = "0.6.1"
+BracketingNonlinearSolve = "1"
+DifferentiationInterface = "0.6.16"
 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"

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,

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",

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)
 ```

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

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
 ```

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
 ```

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
+```

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.

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]
 ```