Merge pull request #345 from avik-pal/ap/rework_internals

What is a Nonlinear Solver? And How to easily build Newer Ones

Author: ChrisRackauckas

.github/workflows/CI.yml

@@ -13,7 +13,7 @@ concurrency:
   cancel-in-progress: ${{ startsWith(github.ref, 'refs/pull/') }}
 jobs:
   test:
-    runs-on: ubuntu-latest
+    runs-on: ${{ matrix.os }}
     strategy:
       fail-fast: false
       matrix:
@@ -24,8 +24,11 @@ jobs:
           - Wrappers
           - Miscellaneous
         version:
-          - '1'
-          - '~1.10.0-0'
+          - '1.10'
+        os:
+          - ubuntu-latest
+          - macos-latest
+          - windows-latest
     steps:
       - uses: actions/checkout@v4
       - uses: julia-actions/setup-julia@v1

.github/workflows/Documentation.yml

@@ -20,6 +20,7 @@ jobs:
         run: julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
       - name: Build and deploy
         env:
+          JULIA_DEBUG: "Documenter"
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # For authentication with GitHub Actions token
           DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }} # For authentication with SSH deploy key
         run: julia --project=docs/ --code-coverage=user docs/make.jl

Project.toml

@@ -1,14 +1,13 @@
 name = "NonlinearSolve"
 uuid = "8913a72c-1f9b-4ce2-8d82-65094dcecaec"
 authors = ["SciML"]
-version = "3.4.0"
+version = "3.5.0"
 
 [deps]
 ADTypes = "47edcb42-4c32-4615-8424-f2b9edc5f35b"
 ArrayInterface = "4fba245c-0d91-5ea0-9b3e-6abc04ee57a9"
 ConcreteStructs = "2569d6c7-a4a2-43d3-a901-331e8e4be471"
 DiffEqBase = "2b5f629d-d688-5b77-993f-72d75c75574e"
-EnumX = "4e289a0a-7415-4d19-859d-a7e5c4648b56"
 FastBroadcast = "7034ab61-46d4-4ed7-9d0f-46aef9175898"
 FastClosures = "9aa1b823-49e4-5ca5-8b0f-3971ec8bab6a"
 FiniteDiff = "6a86dc24-6348-571c-b903-95158fe2bd41"
@@ -19,16 +18,16 @@ LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
 LinearSolve = "7ed4a6bd-45f5-4d41-b270-4a48e9bafcae"
 MaybeInplace = "bb5d69b7-63fc-4a16-80bd-7e42200c7bdb"
 PrecompileTools = "aea7be01-6a6a-4083-8856-8a6e6704d82a"
+Preferences = "21216c6a-2e73-6563-6e65-726566657250"
 Printf = "de0858da-6303-5e67-8744-51eddeeeb8d7"
 RecursiveArrayTools = "731186ca-8d62-57ce-b412-fbd966d074cd"
 Reexport = "189a3867-3050-52da-a836-e630ba90ab69"
 SciMLBase = "0bca4576-84f4-4d90-8ffe-ffa030f20462"
-SciMLOperators = "c0aeaf25-5076-4817-a8d5-81caf7dfa961"
 SimpleNonlinearSolve = "727e6d20-b764-4bd8-a329-72de5adea6c7"
 SparseArrays = "2f01184e-e22b-5df5-ae63-d93ebab69eaf"
 SparseDiffTools = "47a9eef4-7e08-11e9-0b38-333d64bd3804"
-StaticArrays = "90137ffa-7385-5640-81b9-e52037218182"
-UnPack = "3a884ed6-31ef-47d7-9d2a-63182c4928ed"
+StaticArraysCore = "1e83bf80-4336-4d27-bf5d-d5a4f845583c"
+TimerOutputs = "a759f4b9-e2f1-59dc-863e-4aeb61b1ea8f"
 
 [weakdeps]
 BandedMatrices = "aae01518-5342-5314-be14-df237901396f"
@@ -55,14 +54,13 @@ NonlinearSolveSymbolicsExt = "Symbolics"
 NonlinearSolveZygoteExt = "Zygote"
 
 [compat]
-ADTypes = "0.2.5"
+ADTypes = "0.2.6"
 Aqua = "0.8"
 ArrayInterface = "7.7"
 BandedMatrices = "1.4"
 BenchmarkTools = "1.4"
-ConcreteStructs = "0.2"
-DiffEqBase = "6.144"
-EnumX = "1"
+ConcreteStructs = "0.2.3"
+DiffEqBase = "6.146.0"
 Enzyme = "0.11.11"
 FastBroadcast = "0.2.8"
 FastClosures = "0.3"
@@ -73,36 +71,37 @@ ForwardDiff = "0.10.36"
 LazyArrays = "1.8.2"
 LeastSquaresOptim = "0.8.5"
 LineSearches = "7.2"
-LinearAlgebra = "<0.0.1, 1"
+LinearAlgebra = "1.10"
 LinearSolve = "2.21"
 MINPACK = "1.2"
 MaybeInplace = "0.1.1"
 NLsolve = "4.5"
 NaNMath = "1"
 NonlinearProblemLibrary = "0.1.2"
 OrdinaryDiffEq = "6.63"
-Pkg = "1"
+Pkg = "1.10"
 PrecompileTools = "1.2"
+Preferences = "1.4"
 Printf = "1.10"
 Random = "1.91"
-RecursiveArrayTools = "3.2"
+RecursiveArrayTools = "3.4"
 Reexport = "1.2"
 SIAMFANLEquations = "1.0.1"
 SafeTestsets = "0.1"
-SciMLBase = "2.11"
-SciMLOperators = "0.3.7"
-SimpleNonlinearSolve = "1.0.2"
+SciMLBase = "2.19.0"
+SimpleNonlinearSolve = "1.2"
 SparseArrays = "1.10"
 SparseDiffTools = "2.14"
 SpeedMapping = "0.3"
 StableRNGs = "1"
 StaticArrays = "1.7"
+StaticArraysCore = "1.4"
 Sundials = "4.23.1"
 Symbolics = "5.13"
-Test = "1"
-UnPack = "1.0"
+Test = "1.10"
+TimerOutputs = "0.5.23"
 Zygote = "0.6.67"
-julia = "1.9"
+julia = "1.10"
 
 [extras]
 Aqua = "4c88cf16-eb10-579e-8560-4a9242c79595"

docs/LocalPreferences.toml

@@ -0,0 +1,2 @@
+[NonlinearSolve]
+enable_timer_outputs = true

docs/Project.toml

@@ -4,7 +4,9 @@ ArrayInterface = "4fba245c-0d91-5ea0-9b3e-6abc04ee57a9"
 BenchmarkTools = "6e4b80f9-dd63-53aa-95a3-0cdb28fa8baf"
 DiffEqBase = "2b5f629d-d688-5b77-993f-72d75c75574e"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+DocumenterCitations = "daee34ce-89f3-4625-b898-19384cb65244"
 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"
@@ -25,6 +27,7 @@ ArrayInterface = "6, 7"
 BenchmarkTools = "1"
 DiffEqBase = "6.136"
 Documenter = "1"
+DocumenterCitations = "1"
 IncompleteLU = "0.2"
 LinearSolve = "2"
 ModelingToolkit = "8"

docs/make.jl

@@ -1,5 +1,6 @@
-using Documenter,
-    NonlinearSolve, SimpleNonlinearSolve, Sundials, SteadyStateDiffEq, SciMLBase, DiffEqBase
+using Documenter, DocumenterCitations
+using NonlinearSolve,
+    SimpleNonlinearSolve, Sundials, SteadyStateDiffEq, SciMLBase, DiffEqBase
 
 cp(joinpath(@__DIR__, "Manifest.toml"), joinpath(@__DIR__, "src/assets/Manifest.toml"),
     force = true)
@@ -8,14 +9,16 @@ cp(joinpath(@__DIR__, "Project.toml"), joinpath(@__DIR__, "src/assets/Project.to
 
 include("pages.jl")
 
+bib = CitationBibliography(joinpath(@__DIR__, "src", "refs.bib"))
+
 makedocs(; sitename = "NonlinearSolve.jl",
     authors = "Chris Rackauckas",
     modules = [NonlinearSolve, SimpleNonlinearSolve, SteadyStateDiffEq, Sundials,
         DiffEqBase, SciMLBase],
     clean = true, doctest = false, linkcheck = true,
     linkcheck_ignore = ["https://twitter.com/ChrisRackauckas/status/1544743542094020615"],
-    checkdocs = :export,
-    format = Documenter.HTML(assets = ["assets/favicon.ico"],
+    checkdocs = :exports, warnonly = [:missing_docs], plugins = [bib],
+    format = Documenter.HTML(assets = ["assets/favicon.ico", "assets/citations.css"],
         canonical = "https://docs.sciml.ai/NonlinearSolve/stable/"),
     pages)
 

docs/pages.jl

@@ -1,37 +1,46 @@
 # 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",
         "tutorials/large_systems.md",
         "tutorials/modelingtoolkit.md",
         "tutorials/small_compile.md",
         "tutorials/iterator_interface.md",
         "tutorials/optimizing_parameterized_ode.md"],
-    "Basics" => Any["basics/NonlinearProblem.md",
-        "basics/NonlinearFunctions.md",
+    "Basics" => Any["basics/nonlinear_problem.md",
+        "basics/nonlinear_functions.md",
         "basics/solve.md",
-        "basics/NonlinearSolution.md",
-        "basics/TerminationCondition.md",
-        "basics/Logging.md",
-        "basics/SparsityDetection.md",
-        "basics/FAQ.md"],
-    "Solver Summaries and Recommendations" => Any["solvers/NonlinearSystemSolvers.md",
-        "solvers/BracketingSolvers.md",
-        "solvers/SteadyStateSolvers.md",
-        "solvers/NonlinearLeastSquaresSolvers.md",
-        "solvers/FixedPointSolvers.md",
-        "solvers/LineSearch.md"],
-    "Detailed Solver APIs" => Any["api/nonlinearsolve.md",
-        "api/simplenonlinearsolve.md",
+        "basics/nonlinear_solution.md",
+        "basics/termination_condition.md",
+        "basics/diagnostics_api.md",
+        "basics/sparsity_detection.md",
+        "basics/faq.md"],
+    "Solver Summaries and Recommendations" => Any["solvers/nonlinear_system_solvers.md",
+        "solvers/bracketing_solvers.md",
+        "solvers/steady_state_solvers.md",
+        "solvers/nonlinear_least_squares_solvers.md",
+        "solvers/fixed_point_solvers.md"],
+    "Native Functionalities" => Any["native/solvers.md",
+        "native/simplenonlinearsolve.md",
+        "native/steadystatediffeq.md",
+        "native/descent.md",
+        "native/globalization.md",
+        "native/diagnostics.md"],
+    "Wrapped Solver APIs" => Any["api/fastlevenbergmarquardt.md",
+        "api/fixedpointacceleration.md",
+        "api/leastsquaresoptim.md",
         "api/minpack.md",
         "api/nlsolve.md",
-        "api/sundials.md",
-        "api/steadystatediffeq.md",
-        "api/leastsquaresoptim.md",
-        "api/fastlevenbergmarquardt.md",
+        "api/siamfanlequations.md",
         "api/speedmapping.md",
-        "api/fixedpointacceleration.md",
-        "api/siamfanlequations.md"],
+        "api/sundials.md"],
+    "Development Documentation" => ["devdocs/internal_interfaces.md",
+        "devdocs/linear_solve.md",
+        "devdocs/jacobian.md",
+        "devdocs/operators.md",
+        "devdocs/algorithm_helpers.md"],
     "Release Notes" => "release_notes.md",
+    "References" => "references.md",
 ]

docs/src/api/nonlinearsolve.md

@@ -0,0 +1,23 @@
+.citation dl {
+  display: grid;
+  grid-template-columns: max-content auto;
+}
+.citation dt {
+  grid-column-start: 1;
+}
+.citation dd {
+  grid-column-start: 2;
+  margin-bottom: 0.75em;
+}
+.citation ul {
+  padding: 0 0 2.25em 0;
+  margin: 0;
+  list-style: none;
+}
+.citation ul li {
+  text-indent: -2.25em;
+  margin: 0.33em 0.5em 0.5em 2.25em;
+}
+.citation ol li {
+  padding-left: 0.75em;
+}