Merge pull request #302 from avik-pal/ap/breaking

NonlinearSolve v3 Release
SciML · Dec 8, 2023 · 4e1638a · 4e1638a · avik-pal · Dec 8, 2023
2 parents b853842 + 50cef59
commit 4e1638a
Show file tree

Hide file tree

Showing 54 changed files with 1,341 additions and 581 deletions.
diff --git a/Project.toml b/Project.toml
@@ -1,7 +1,7 @@
 name = "NonlinearSolve"
 uuid = "8913a72c-1f9b-4ce2-8d82-65094dcecaec"
 authors = ["SciML"]
-version = "2.10.0"
+version = "3.0.0"
 
 [deps]
 ADTypes = "47edcb42-4c32-4615-8424-f2b9edc5f35b"
@@ -33,12 +33,16 @@ UnPack = "3a884ed6-31ef-47d7-9d2a-63182c4928ed"
 BandedMatrices = "aae01518-5342-5314-be14-df237901396f"
 FastLevenbergMarquardt = "7a0df574-e128-4d35-8cbd-3d84502bf7ce"
 LeastSquaresOptim = "0fc2ff8b-aaa3-5acd-a817-1944a5e08891"
+MINPACK = "4854310b-de5a-5eb6-a2a5-c1dee2bd17f9"
+NLsolve = "2774e3e8-f4cf-5e23-947b-6d7e65073b56"
 Zygote = "e88e6eb3-aa80-5325-afca-941959d7151f"
 
 [extensions]
 NonlinearSolveBandedMatricesExt = "BandedMatrices"
 NonlinearSolveFastLevenbergMarquardtExt = "FastLevenbergMarquardt"
 NonlinearSolveLeastSquaresOptimExt = "LeastSquaresOptim"
+NonlinearSolveMINPACKExt = "MINPACK"
+NonlinearSolveNLsolveExt = "NLsolve"
 NonlinearSolveZygoteExt = "Zygote"
 
 [compat]
@@ -60,19 +64,21 @@ LeastSquaresOptim = "0.8"
 LineSearches = "7"
 LinearAlgebra = "<0.0.1, 1"
 LinearSolve = "2.12"
+MINPACK = "1.2"
 MaybeInplace = "0.1"
+NLsolve = "4.5"
 NaNMath = "1"
 NonlinearProblemLibrary = "0.1"
 Pkg = "1"
 PrecompileTools = "1"
 Printf = "<0.0.1, 1"
-Random = "1"
+Random = "<0.0.1, 1"
 RecursiveArrayTools = "2"
 Reexport = "0.2, 1"
 SafeTestsets = "0.1"
 SciMLBase = "2.9"
 SciMLOperators = "0.3"
-SimpleNonlinearSolve = "0.1.23"
+SimpleNonlinearSolve = "1"
 SparseArrays = "<0.0.1, 1"
 SparseDiffTools = "2.14"
 StableRNGs = "1"
@@ -94,17 +100,19 @@ ForwardDiff = "f6369f11-7733-5829-9624-2563aa707210"
 LeastSquaresOptim = "0fc2ff8b-aaa3-5acd-a817-1944a5e08891"
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
 LinearSolve = "7ed4a6bd-45f5-4d41-b270-4a48e9bafcae"
+MINPACK = "4854310b-de5a-5eb6-a2a5-c1dee2bd17f9"
+NLsolve = "2774e3e8-f4cf-5e23-947b-6d7e65073b56"
 NaNMath = "77ba4419-2d1f-58cd-9bb1-8ffee604a2e3"
 NonlinearProblemLibrary = "b7050fa9-e91f-4b37-bcee-a89a063da141"
 Pkg = "44cfe95a-1eb2-52ea-b672-e2afdf69b78f"
 Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
 SafeTestsets = "1bc83da4-3b8d-516f-aca4-4fe02f6d838f"
-StableRNGs = "860ef19b-820b-49d6-a774-d7a799459cd3"
 SparseDiffTools = "47a9eef4-7e08-11e9-0b38-333d64bd3804"
+StableRNGs = "860ef19b-820b-49d6-a774-d7a799459cd3"
 StaticArrays = "90137ffa-7385-5640-81b9-e52037218182"
 Symbolics = "0c5d862f-8b57-4792-8d23-62f2024744c7"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 Zygote = "e88e6eb3-aa80-5325-afca-941959d7151f"
 
 [targets]
-test = ["Aqua", "Enzyme", "BenchmarkTools", "SafeTestsets", "Pkg", "Test", "ForwardDiff", "StaticArrays", "Symbolics", "LinearSolve", "Random", "LinearAlgebra", "Zygote", "SparseDiffTools", "NonlinearProblemLibrary", "LeastSquaresOptim", "FastLevenbergMarquardt", "NaNMath", "BandedMatrices", "DiffEqBase", "StableRNGs"]
+test = ["Aqua", "Enzyme", "BenchmarkTools", "SafeTestsets", "Pkg", "Test", "ForwardDiff", "StaticArrays", "Symbolics", "LinearSolve", "Random", "LinearAlgebra", "Zygote", "SparseDiffTools", "NonlinearProblemLibrary", "LeastSquaresOptim", "FastLevenbergMarquardt", "NaNMath", "BandedMatrices", "DiffEqBase", "StableRNGs", "MINPACK", "NLsolve"]
diff --git a/docs/Project.toml b/docs/Project.toml
@@ -8,9 +8,9 @@ IncompleteLU = "40713840-3770-5561-ab4c-a76e7d0d7895"
 LinearSolve = "7ed4a6bd-45f5-4d41-b270-4a48e9bafcae"
 ModelingToolkit = "961ee093-0014-501f-94e3-6117800e7a78"
 NonlinearSolve = "8913a72c-1f9b-4ce2-8d82-65094dcecaec"
-NonlinearSolveMINPACK = "c100e077-885d-495a-a2ea-599e143bf69d"
+OrdinaryDiffEq = "1dea7af3-3e70-54e6-95c3-0bf5283fa5ed"
+Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
 SciMLBase = "0bca4576-84f4-4d90-8ffe-ffa030f20462"
-SciMLNLSolve = "e9a6253c-8580-4d32-9898-8661bb511710"
 SimpleNonlinearSolve = "727e6d20-b764-4bd8-a329-72de5adea6c7"
 StaticArrays = "90137ffa-7385-5640-81b9-e52037218182"
 SteadyStateDiffEq = "9672c7b4-1e72-59bd-8a11-6ac3964bc41f"
@@ -26,12 +26,11 @@ Documenter = "1"
 IncompleteLU = "0.2"
 LinearSolve = "2"
 ModelingToolkit = "8"
-NonlinearSolve = "1, 2"
-NonlinearSolveMINPACK = "0.1"
+NonlinearSolve = "3"
+Random = "<0.0.1, 1"
 SciMLBase = "2.4"
-SciMLNLSolve = "0.1"
-SimpleNonlinearSolve = "0.1.5, 1"
+SimpleNonlinearSolve = "1"
 StaticArrays = "1"
-SteadyStateDiffEq = "1.10, 2"
+SteadyStateDiffEq = "2"
 Sundials = "4.11"
 Symbolics = "4, 5"
diff --git a/docs/make.jl b/docs/make.jl
@@ -1,21 +1,22 @@
-using Documenter, NonlinearSolve, SimpleNonlinearSolve, Sundials, SciMLNLSolve,
-    NonlinearSolveMINPACK, SteadyStateDiffEq, SciMLBase, DiffEqBase
+using Documenter,
+    NonlinearSolve, SimpleNonlinearSolve, Sundials, SteadyStateDiffEq, SciMLBase, DiffEqBase
 
-cp("./docs/Manifest.toml", "./docs/src/assets/Manifest.toml", force = true)
-cp("./docs/Project.toml", "./docs/src/assets/Project.toml", force = true)
+cp(joinpath(@__DIR__, "Manifest.toml"), joinpath(@__DIR__, "src/assets/Manifest.toml"),
+    force = true)
+cp(joinpath(@__DIR__, "Project.toml"), joinpath(@__DIR__, "src/assets/Project.toml"),
+    force = true)
 
 include("pages.jl")
 
-makedocs(sitename = "NonlinearSolve.jl",
+makedocs(; sitename = "NonlinearSolve.jl",
     authors = "Chris Rackauckas",
     modules = [NonlinearSolve, SciMLBase, DiffEqBase, SimpleNonlinearSolve, Sundials,
-        SciMLNLSolve, NonlinearSolveMINPACK, SteadyStateDiffEq],
+        SteadyStateDiffEq],
     clean = true, doctest = false, linkcheck = true,
     linkcheck_ignore = ["https://twitter.com/ChrisRackauckas/status/1544743542094020615"],
     warnonly = [:missing_docs, :cross_references],
     format = Documenter.HTML(assets = ["assets/favicon.ico"],
         canonical = "https://docs.sciml.ai/NonlinearSolve/stable/"),
-    pages = pages)
+    pages)
 
-deploydocs(repo = "github.com/SciML/NonlinearSolve.jl.git";
-    push_preview = true)
+deploydocs(repo = "github.com/SciML/NonlinearSolve.jl.git"; push_preview = true)
diff --git a/docs/pages.jl b/docs/pages.jl
@@ -2,9 +2,9 @@
 
 pages = ["index.md",
     "Getting Started with Nonlinear Rootfinding in Julia" => "tutorials/getting_started.md",
-    "Tutorials" => Any["Code Optimization for Small Nonlinear Systems" => "tutorials/code_optimization.md",
-        "Handling Large Ill-Conditioned and Sparse Systems" => "tutorials/large_systems.md",
-        "Symbolic System Definition and Acceleration via ModelingToolkit" => "tutorials/modelingtoolkit.md",
+    "Tutorials" => Any["tutorials/code_optimization.md",
+        "tutorials/large_systems.md",
+        "tutorials/modelingtoolkit.md",
         "tutorials/small_compile.md",
         "tutorials/iterator_interface.md"],
     "Basics" => Any["basics/NonlinearProblem.md",
@@ -24,5 +24,8 @@ pages = ["index.md",
         "api/minpack.md",
         "api/nlsolve.md",
         "api/sundials.md",
-        "api/steadystatediffeq.md"],
+        "api/steadystatediffeq.md",
+        "api/leastsquaresoptim.md",
+        "api/fastlevenbergmarquardt.md"],
+    "Release Notes" => "release_notes.md",
 ]
diff --git a/docs/src/api/fastlevenbergmarquardt.md b/docs/src/api/fastlevenbergmarquardt.md
@@ -0,0 +1,17 @@
+# FastLevenbergMarquardt.jl
+
+This is a extension for importing solvers from FastLevenbergMarquardt.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
+using Pkg
+Pkg.add("FastLevenbergMarquardt")
+using FastLevenbergMarquardt, NonlinearSolve
+```
+
+## Solver API
+
+```@docs
+FastLevenbergMarquardtJL
+```
diff --git a/docs/src/api/leastsquaresoptim.md b/docs/src/api/leastsquaresoptim.md
@@ -0,0 +1,17 @@
+# LeastSquaresOptim.jl
+
+This is a extension for importing solvers from LeastSquaresOptim.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
+using Pkg
+Pkg.add("LeastSquaresOptim")
+using LeastSquaresOptim, NonlinearSolve
+```
+
+## Solver API
+
+```@docs
+LeastSquaresOptimJL
+```
diff --git a/docs/src/api/minpack.md b/docs/src/api/minpack.md
@@ -1,17 +1,15 @@
 # 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:
+This is a extension for importing solvers from MINPACK 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
 using Pkg
-Pkg.add("NonlinearSolveMINPACK")
-using NonlinearSolveMINPACK
+Pkg.add("MINPACK")
+using MINPACK, NonlinearSolve
 ```
 
-These methods can be used independently of the rest of NonlinearSolve.jl
-
 ## Solver API
 
 ```@docs

diff --git a/docs/src/api/nlsolve.md b/docs/src/api/nlsolve.md
@@ -1,17 +1,17 @@
 # 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:
+This is a extension 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
 using Pkg
-Pkg.add("SciMLNLSolve")
-using SciMLNLSolve
+Pkg.add("NLsolve")
+using NLSolve, NonlinearSolve
 ```
 
 ## Solver API
 
 ```@docs
-NLSolveJL
+NLsolveJL
 ```
diff --git a/docs/src/api/nonlinearsolve.md b/docs/src/api/nonlinearsolve.md
@@ -9,8 +9,8 @@ NewtonRaphson
 TrustRegion
 PseudoTransient
 DFSane
-GeneralBroyden
-GeneralKlement
+Broyden
+Klement
 ```
 
 ## Polyalgorithms

diff --git a/docs/src/api/simplenonlinearsolve.md b/docs/src/api/simplenonlinearsolve.md
@@ -6,7 +6,8 @@ These methods can be used independently of the rest of NonlinearSolve.jl
 
 ### Interval Methods
 
-These methods are suited for interval (scalar) root-finding problems, i.e. `IntervalNonlinearProblem`.
+These methods are suited for interval (scalar) root-finding problems,
+i.e. `IntervalNonlinearProblem`.
 
 ```@docs
 ITP
@@ -18,14 +19,15 @@ Brent
 
 ### General Methods
 
-These methods are suited for any general nonlinear root-finding problem , i.e. `NonlinearProblem`.
+These methods are suited for any general nonlinear root-finding problem, i.e.
+`NonlinearProblem`.
 
 ```@docs
 SimpleNewtonRaphson
-Broyden
+SimpleBroyden
 SimpleHalley
-Klement
+SimpleKlement
 SimpleTrustRegion
 SimpleDFSane
-LBroyden
+SimpleLimitedMemoryBroyden
 ```
diff --git a/docs/src/api/steadystatediffeq.md b/docs/src/api/steadystatediffeq.md
@@ -1,8 +1,8 @@
 # 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
+[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
@@ -17,4 +17,5 @@ These methods can be used independently of the rest of NonlinearSolve.jl
 
 ```@docs
 DynamicSS
+SSRootfind
 ```
diff --git a/docs/src/api/sundials.md b/docs/src/api/sundials.md
@@ -1,8 +1,8 @@
 # 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:
+Note that these solvers do not come by default, and thus one needs to install the package
+before using these solvers:
 
 ```julia
 using Pkg

diff --git a/docs/src/basics/FAQ.md b/docs/src/basics/FAQ.md
@@ -8,7 +8,7 @@ On the test example:
 ```@example
 using NonlinearSolve, BenchmarkTools
 
-N = 100_000;
+const N = 100_000;
 levels = 1.5 .* rand(N);
 out = zeros(N);
 myfun(x, lv) = x * sin(x) - lv
@@ -31,8 +31,62 @@ end
 @btime f2(out, levels, 1.0)
 ```
 
-MATLAB 2022a achieves 1.66s. Try this code yourself: we receive 0.06 seconds, or a 28x speedup.
-This example is still not optimized in the Julia code, and we expect an improvement in a near
-future version.
+MATLAB 2022a achieves 1.66s. Try this code yourself: we receive 0.009 seconds, or a 184x
+speedup.
 
 For more information on performance of SciML, see the [SciMLBenchmarks](https://docs.sciml.ai/SciMLBenchmarksOutput/stable/).
+
+## The solver tried to set a Dual Number in my Vector of Floats.How do I fix that?
+
+This is a common problem that occurs if the code was not written to be generic based on the
+input types. For example, consider this example taken from
+[this issue](https://github.com/SciML/NonlinearSolve.jl/issues/298)
+
+```@example dual_error_faq
+using NonlinearSolve, Random
+
+function fff_incorrect(var, p)
+    v_true = [1.0, 0.1, 2.0, 0.5]
+    xx = [1.0, 2.0, 3.0, 4.0]
+    xx[1] = var[1] - v_true[1]
+    return var - v_true
+end
+
+v_true = [1.0, 0.1, 2.0, 0.5]
+v_init = v_true .+ randn!(similar(v_true)) * 0.1
+
+prob_oop = NonlinearLeastSquaresProblem{false}(fff_incorrect, v_init)
+try
+    sol = solve(prob_oop, LevenbergMarquardt(); maxiters = 10000, abstol = 1e-8)
+catch e
+    @error e
+end
+```
+
+Essentially what happened was, NonlinearSolve checked that we can use ForwardDiff.jl to
+differentiate the function based on the input types. However, this function has
+`xx = [1.0, 2.0, 3.0, 4.0]` followed by a `xx[1] = var[1] - v_true[1]` where `var` might
+be a Dual number. This causes the error. To fix it:
+
+ 1. Specify the `autodiff` to be `AutoFiniteDiff`
+
+```@example dual_error_faq
+sol = solve(prob_oop, LevenbergMarquardt(; autodiff = AutoFiniteDiff()); maxiters = 10000,
+    abstol = 1e-8)
+```
+
+This worked but, Finite Differencing is not the recommended approach in any scenario.
+Instead, rewrite the function to use
+[PreallocationTools.jl](https://github.com/SciML/PreallocationTools.jl) or write it as
+
+```@example dual_error_faq
+function fff_correct(var, p)
+    v_true = [1.0, 0.1, 2.0, 0.5]
+    xx = eltype(var)[1.0, 2.0, 3.0, 4.0]
+    xx[1] = var[1] - v_true[1]
+    return xx - v_true
+end
+
+prob_oop = NonlinearLeastSquaresProblem{false}(fff_correct, v_init)
+sol = solve(prob_oop, LevenbergMarquardt(); maxiters = 10000, abstol = 1e-8)
+```
diff --git a/docs/src/basics/NonlinearFunctions.md b/docs/src/basics/NonlinearFunctions.md
@@ -1,10 +1,10 @@
 # [NonlinearFunctions and Jacobian Types](@id nonlinearfunctions)
 
 The SciML ecosystem provides an extensive interface for declaring extra functions
-associated with the differential equation's data. In traditional libraries, there
-is usually only one option: the Jacobian. However, we allow for a large array
-of pre-computed functions to speed up the calculations. This is offered via the
-`NonlinearFunction` types, which can be passed to the problems.
+associated with the differential equation's data. In traditional libraries, there is usually
+only one option: the Jacobian. However, we allow for a large array of pre-computed functions
+to speed up the calculations. This is offered via the `NonlinearFunction` types, which can
+be passed to the problems.
 
 ## Function Type Definitions