Skip to content

Commit c86413c

Browse files
committed
Update documentation
1 parent ad93e39 commit c86413c

25 files changed

+691
-452
lines changed

Project.toml

+1-1
Original file line numberDiff line numberDiff line change
@@ -66,7 +66,7 @@ NonlinearProblemLibrary = "0.1"
6666
Pkg = "1"
6767
PrecompileTools = "1"
6868
Printf = "<0.0.1, 1"
69-
Random = "1"
69+
Random = "<0.0.1, 1"
7070
RecursiveArrayTools = "2"
7171
Reexport = "0.2, 1"
7272
SafeTestsets = "0.1"

docs/Project.toml

+4-2
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ LinearSolve = "7ed4a6bd-45f5-4d41-b270-4a48e9bafcae"
99
ModelingToolkit = "961ee093-0014-501f-94e3-6117800e7a78"
1010
NonlinearSolve = "8913a72c-1f9b-4ce2-8d82-65094dcecaec"
1111
NonlinearSolveMINPACK = "c100e077-885d-495a-a2ea-599e143bf69d"
12+
Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
1213
SciMLBase = "0bca4576-84f4-4d90-8ffe-ffa030f20462"
1314
SciMLNLSolve = "e9a6253c-8580-4d32-9898-8661bb511710"
1415
SimpleNonlinearSolve = "727e6d20-b764-4bd8-a329-72de5adea6c7"
@@ -26,12 +27,13 @@ Documenter = "1"
2627
IncompleteLU = "0.2"
2728
LinearSolve = "2"
2829
ModelingToolkit = "8"
29-
NonlinearSolve = "1, 2"
30+
NonlinearSolve = "3"
3031
NonlinearSolveMINPACK = "0.1"
32+
Random = "<0.0.1, 1"
3133
SciMLBase = "2.4"
3234
SciMLNLSolve = "0.1"
3335
SimpleNonlinearSolve = "1"
3436
StaticArrays = "1"
35-
SteadyStateDiffEq = "1.10, 2"
37+
SteadyStateDiffEq = "2"
3638
Sundials = "4.11"
3739
Symbolics = "4, 5"
+19
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# FastLevenbergMarquardt.jl
2+
3+
This is a wrapper package for importing solvers from FastLevenbergMarquardt.jl into the
4+
SciML interface. Note that these solvers do not come by default, and thus one needs to
5+
install the package before using these solvers:
6+
7+
```julia
8+
using Pkg
9+
Pkg.add("FastLevenbergMarquardt")
10+
using FastLevenbergMarquardt
11+
```
12+
13+
These methods can be used independently of the rest of NonlinearSolve.jl
14+
15+
## Solver API
16+
17+
```@docs
18+
FastLevenbergMarquardtJL
19+
```

docs/src/api/leastsquaresoptim.md

+19
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# LeastSquaresOptim.jl
2+
3+
This is a wrapper package for importing solvers from LeastSquaresOptim.jl into the SciML
4+
interface. Note that these solvers do not come by default, and thus one needs to install
5+
the package before using these solvers:
6+
7+
```julia
8+
using Pkg
9+
Pkg.add("LeastSquaresOptim")
10+
using LeastSquaresOptim
11+
```
12+
13+
These methods can be used independently of the rest of NonlinearSolve.jl
14+
15+
## Solver API
16+
17+
```@docs
18+
LeastSquaresOptimJL
19+
```

docs/src/api/minpack.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
# MINPACK.jl
22

33
This is a wrapper package for importing solvers from Sundials into the SciML interface.
4-
Note that these solvers do not come by default, and thus one needs to install
5-
the package before using these solvers:
4+
Note that these solvers do not come by default, and thus one needs to install the package
5+
before using these solvers:
66

77
```julia
88
using Pkg

docs/src/api/nlsolve.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
# NLsolve.jl
22

33
This is a wrapper package for importing solvers from NLsolve.jl into the SciML interface.
4-
Note that these solvers do not come by default, and thus one needs to install
5-
the package before using these solvers:
4+
Note that these solvers do not come by default, and thus one needs to install the package
5+
before using these solvers:
66

77
```julia
88
using Pkg

docs/src/api/simplenonlinearsolve.md

+7-5
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,8 @@ These methods can be used independently of the rest of NonlinearSolve.jl
66

77
### Interval Methods
88

9-
These methods are suited for interval (scalar) root-finding problems, i.e. `IntervalNonlinearProblem`.
9+
These methods are suited for interval (scalar) root-finding problems,
10+
i.e. `IntervalNonlinearProblem`.
1011

1112
```@docs
1213
ITP
@@ -18,14 +19,15 @@ Brent
1819

1920
### General Methods
2021

21-
These methods are suited for any general nonlinear root-finding problem, i.e. `NonlinearProblem`.
22+
These methods are suited for any general nonlinear root-finding problem, i.e.
23+
`NonlinearProblem`.
2224

2325
```@docs
2426
SimpleNewtonRaphson
25-
Broyden
27+
SimpleBroyden
2628
SimpleHalley
27-
Klement
29+
SimpleKlement
2830
SimpleTrustRegion
2931
SimpleDFSane
30-
LBroyden
32+
SimpleLimitedMemoryBroyden
3133
```

docs/src/api/steadystatediffeq.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
# SteadyStateDiffEq.jl
22

33
This is a wrapper package for using ODE solvers from
4-
[DifferentialEquations.jl](https://docs.sciml.ai/DiffEqDocs/stable/) into the SciML interface.
5-
Note that these solvers do not come by default, and thus one needs to install
4+
[DifferentialEquations.jl](https://docs.sciml.ai/DiffEqDocs/stable/) into the SciML
5+
interface. Note that these solvers do not come by default, and thus one needs to install
66
the package before using these solvers:
77

88
```julia

docs/src/api/sundials.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
# Sundials.jl
22

33
This is a wrapper package for importing solvers from Sundials into the SciML interface.
4-
Note that these solvers do not come by default, and thus one needs to install
5-
the package before using these solvers:
4+
Note that these solvers do not come by default, and thus one needs to install the package
5+
before using these solvers:
66

77
```julia
88
using Pkg

docs/src/basics/FAQ.md

+58-4
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ On the test example:
88
```@example
99
using NonlinearSolve, BenchmarkTools
1010
11-
N = 100_000;
11+
const N = 100_000;
1212
levels = 1.5 .* rand(N);
1313
out = zeros(N);
1414
myfun(x, lv) = x * sin(x) - lv
@@ -31,8 +31,62 @@ end
3131
@btime f2(out, levels, 1.0)
3232
```
3333

34-
MATLAB 2022a achieves 1.66s. Try this code yourself: we receive 0.06 seconds, or a 28x speedup.
35-
This example is still not optimized in the Julia code, and we expect an improvement in a near
36-
future version.
34+
MATLAB 2022a achieves 1.66s. Try this code yourself: we receive 0.009 seconds, or a 184x
35+
speedup.
3736

3837
For more information on performance of SciML, see the [SciMLBenchmarks](https://docs.sciml.ai/SciMLBenchmarksOutput/stable/).
38+
39+
## The solver tried to set a Dual Number in my Vector of Floats.How do I fix that?
40+
41+
This is a common problem that occurs if the code was not written to be generic based on the
42+
input types. For example, consider this example taken from
43+
[this issue](https://github.com/SciML/NonlinearSolve.jl/issues/298)
44+
45+
```@example dual_error_faq
46+
using NonlinearSolve, Random
47+
48+
function fff_incorrect(var, p)
49+
v_true = [1.0, 0.1, 2.0, 0.5]
50+
xx = [1.0, 2.0, 3.0, 4.0]
51+
xx[1] = var[1] - v_true[1]
52+
return var - v_true
53+
end
54+
55+
v_true = [1.0, 0.1, 2.0, 0.5]
56+
v_init = v_true .+ randn!(similar(v_true)) * 0.1
57+
58+
prob_oop = NonlinearLeastSquaresProblem{false}(fff_incorrect, v_init)
59+
try
60+
sol = solve(prob_oop, LevenbergMarquardt(); maxiters = 10000, abstol = 1e-8)
61+
catch e
62+
@error e
63+
end
64+
```
65+
66+
Essentially what happened was, NonlinearSolve checked that we can use ForwardDiff.jl to
67+
differentiate the function based on the input types. However, this function has
68+
`xx = [1.0, 2.0, 3.0, 4.0]` followed by a `xx[1] = var[1] - v_true[1]` where `var` might
69+
be a Dual number. This causes the error. To fix it:
70+
71+
1. Specify the `autodiff` to be `AutoFiniteDiff`
72+
73+
```@example dual_error_faq
74+
sol = solve(prob_oop, LevenbergMarquardt(; autodiff = AutoFiniteDiff()); maxiters = 10000,
75+
abstol = 1e-8)
76+
```
77+
78+
This worked but, Finite Differencing is not the recommended approach in any scenario.
79+
Instead, rewrite the function to use
80+
[PreallocationTools.jl](https://github.com/SciML/PreallocationTools.jl) or write it as
81+
82+
```@example dual_error_faq
83+
function fff_correct(var, p)
84+
v_true = [1.0, 0.1, 2.0, 0.5]
85+
xx = eltype(var)[1.0, 2.0, 3.0, 4.0]
86+
xx[1] = var[1] - v_true[1]
87+
return xx - v_true
88+
end
89+
90+
prob_oop = NonlinearLeastSquaresProblem{false}(fff_correct, v_init)
91+
sol = solve(prob_oop, LevenbergMarquardt(); maxiters = 10000, abstol = 1e-8)
92+
```

docs/src/basics/NonlinearFunctions.md

+4-4
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
11
# [NonlinearFunctions and Jacobian Types](@id nonlinearfunctions)
22

33
The SciML ecosystem provides an extensive interface for declaring extra functions
4-
associated with the differential equation's data. In traditional libraries, there
5-
is usually only one option: the Jacobian. However, we allow for a large array
6-
of pre-computed functions to speed up the calculations. This is offered via the
7-
`NonlinearFunction` types, which can be passed to the problems.
4+
associated with the differential equation's data. In traditional libraries, there is usually
5+
only one option: the Jacobian. However, we allow for a large array of pre-computed functions
6+
to speed up the calculations. This is offered via the `NonlinearFunction` types, which can
7+
be passed to the problems.
88

99
## Function Type Definitions
1010

docs/src/basics/NonlinearProblem.md

+11-6
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,17 @@
11
# [Nonlinear Problems](@id problems)
22

3-
## The Three Types of Nonlinear Problems
3+
## The Four Types of Nonlinear Problems
44

5-
NonlinearSolve.jl tackles three related types of nonlinear systems:
5+
NonlinearSolve.jl tackles four related types of nonlinear systems:
66

7-
1. Interval rootfinding problems. I.e., find the ``t \in [t_0, t_f]`` such that ``f(t) = 0``.
7+
1. Interval rootfinding problems. I.e., find the ``t \in [t_0, t_f]`` such that
8+
``f(t) = 0``.
89
2. Systems of nonlinear equations, i.e., find the ``u`` such that ``f(u) = 0``.
910
3. Steady state problems, i.e., find the ``u`` such that ``u' = f(u,t)`` has reached steady state,
1011
i.e., ``0 = f(u, ∞)``.
12+
4. The nonlinear least squares problem, which is an under/over-constrained nonlinear system
13+
which might not be satisfiable, i.e. there may be no `u` such that `f(u) = 0`, and thus
14+
we find the `u` which minimizes `||f(u)||` in the least squares sense.
1115

1216
The first is for solving scalar rootfinding problems, i.e., finding a single number, and
1317
requires that a bracketing interval is known. For a bracketing interval, one must have that
@@ -16,9 +20,9 @@ interval.
1620

1721
!!! note
1822

19-
Interval rootfinding problems allow for `f` to return an array, in which case the interval
20-
rootfinding problem is interpreted as finding the first `t` such that any of the components
21-
of the array hit zero.
23+
Interval rootfinding problems allow for `f` to return an array, in which case the
24+
interval rootfinding problem is interpreted as finding the first `t` such that any of
25+
the components of the array hit zero.
2226

2327
The second type of nonlinear system can be multidimensional, and thus no ordering nor
2428
boundaries are assumed to be known. For a system of nonlinear equations, `f` can return
@@ -43,4 +47,5 @@ ODE `u' = f(u,t)`.
4347
SciMLBase.IntervalNonlinearProblem
4448
SciMLBase.NonlinearProblem
4549
SciMLBase.SteadyStateProblem
50+
SciMLBase.NonlinearLeastSquaresProblem
4651
```

docs/src/basics/solve.md

+17-17
Original file line numberDiff line numberDiff line change
@@ -6,28 +6,28 @@ solve(prob::SciMLBase.NonlinearProblem, args...; kwargs...)
66

77
## General Controls
88

9-
- `alias_u0::Bool`: Whether to alias the initial condition or use a copy.
10-
Defaults to `false`.
11-
- `internal_norm::Function`: The norm used by the solver. Default depends on algorithm
12-
choice.
9+
- `alias_u0::Bool`: Whether to alias the initial condition or use a copy.
10+
Defaults to `false`.
11+
- `internal_norm::Function`: The norm used by the solver. Default depends on algorithm
12+
choice.
1313

1414
## Iteration Controls
1515

16-
- `maxiters::Int`: The maximum number of iterations to perform. Defaults to `1000`.
17-
- `abstol::Number`: The absolute tolerance.
18-
- `reltol::Number`: The relative tolerance.
19-
- `termination_condition`: Termination Condition from DiffEqBase. Defaults to
20-
`AbsSafeBestTerminationMode()` for `NonlinearSolve.jl` and `AbsTerminateMode()` for
21-
`SimpleNonlinearSolve.jl`.
16+
- `maxiters::Int`: The maximum number of iterations to perform. Defaults to `1000`.
17+
- `abstol::Number`: The absolute tolerance.
18+
- `reltol::Number`: The relative tolerance.
19+
- `termination_condition`: Termination Condition from DiffEqBase. Defaults to
20+
`AbsSafeBestTerminationMode()` for `NonlinearSolve.jl` and `AbsTerminateMode()` for
21+
`SimpleNonlinearSolve.jl`.
2222

2323
## Tracing Controls
2424

2525
These are exclusively available for native `NonlinearSolve.jl` solvers.
2626

27-
- `show_trace`: Must be `Val(true)` or `Val(false)`. This controls whether the trace is
28-
displayed to the console. (Defaults to `Val(false)`)
29-
- `trace_level`: Needs to be one of Trace Objects: [`TraceMinimal`](@ref),
30-
[`TraceWithJacobianConditionNumber`](@ref), or [`TraceAll`](@ref). This controls the
31-
level of detail of the trace. (Defaults to `TraceMinimal()`)
32-
- `store_trace`: Must be `Val(true)` or `Val(false)`. This controls whether the trace is
33-
stored in the solution object. (Defaults to `Val(false)`)
27+
- `show_trace`: Must be `Val(true)` or `Val(false)`. This controls whether the trace is
28+
displayed to the console. (Defaults to `Val(false)`)
29+
- `trace_level`: Needs to be one of Trace Objects: [`TraceMinimal`](@ref),
30+
[`TraceWithJacobianConditionNumber`](@ref), or [`TraceAll`](@ref). This controls the
31+
level of detail of the trace. (Defaults to `TraceMinimal()`)
32+
- `store_trace`: Must be `Val(true)` or `Val(false)`. This controls whether the trace is
33+
stored in the solution object. (Defaults to `Val(false)`)

docs/src/index.md

+25-26
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,19 @@
11
# NonlinearSolve.jl: High-Performance Unified Nonlinear Solvers
22

3-
NonlinearSolve.jl is a unified interface for the nonlinear solving packages of
4-
Julia. The package includes its own high-performance nonlinear solvers which include the
5-
ability to swap out to fast direct and iterative linear solvers, along with the
6-
ability to use sparse automatic differentiation for Jacobian construction and
7-
Jacobian-vector products. NonlinearSolve.jl interfaces with other packages of the Julia ecosystem
8-
to make it easy to test alternative solver packages and pass small types to
9-
control algorithm swapping. It also interfaces with the
10-
[ModelingToolkit.jl](https://docs.sciml.ai/ModelingToolkit/stable/) world of symbolic
11-
modeling to allow for automatically generating high-performance code.
12-
13-
Performance is key: the current methods are made to be highly performant on
14-
scalar and statically sized small problems, with options for large-scale systems.
15-
If you run into any performance issues, please file an issue.
16-
Consult the [NonlinearSystemSolvers](@ref nonlinearsystemsolvers) page for
17-
information on how to import solvers from different packages.
3+
NonlinearSolve.jl is a unified interface for the nonlinear solving packages of Julia. The
4+
package includes its own high-performance nonlinear solvers which include the ability to
5+
swap out to fast direct and iterative linear solvers, along with the ability to use sparse
6+
automatic differentiation for Jacobian construction and Jacobian-vector products.
7+
NonlinearSolve.jl interfaces with other packages of the Julia ecosystem to make it easy to
8+
test alternative solver packages and pass small types to control algorithm swapping. It also
9+
interfaces with the [ModelingToolkit.jl](https://docs.sciml.ai/ModelingToolkit/stable/)
10+
world of symbolic modeling to allow for automatically generating high-performance code.
11+
12+
Performance is key: the current methods are made to be highly performant on scalar and
13+
statically sized small problems, with options for large-scale systems. If you run into any
14+
performance issues, please file an issue. Consult the
15+
[NonlinearSystemSolvers](@ref nonlinearsystemsolvers) page for information on how to import
16+
solvers from different packages.
1817

1918
## Installation
2019

@@ -27,17 +26,17 @@ Pkg.add("NonlinearSolve")
2726

2827
## Contributing
2928

30-
- Please refer to the
31-
[SciML ColPrac: Contributor's Guide on Collaborative Practices for Community Packages](https://github.com/SciML/ColPrac/blob/master/README.md)
32-
for guidance on PRs, issues, and other matters relating to contributing to SciML.
33-
34-
- See the [SciML Style Guide](https://github.com/SciML/SciMLStyle) for common coding practices and other style decisions.
35-
- There are a few community forums:
36-
37-
- The #diffeq-bridged and #sciml-bridged channels in the [Julia Slack](https://julialang.org/slack/)
38-
- The #diffeq-bridged and #sciml-bridged channels in the [Julia Zulip](https://julialang.zulipchat.com/#narrow/stream/279055-sciml-bridged)
39-
- On the [Julia Discourse forums](https://discourse.julialang.org)
40-
- See also [SciML Community page](https://sciml.ai/community/)
29+
- Please refer to the
30+
[SciML ColPrac: Contributor's Guide on Collaborative Practices for Community Packages](https://github.com/SciML/ColPrac/blob/master/README.md)
31+
for guidance on PRs, issues, and other matters relating to contributing to SciML.
32+
33+
- See the [SciML Style Guide](https://github.com/SciML/SciMLStyle) for common coding practices and other style decisions.
34+
- There are a few community forums:
35+
36+
+ The #diffeq-bridged and #sciml-bridged channels in the [Julia Slack](https://julialang.org/slack/)
37+
+ The #diffeq-bridged and #sciml-bridged channels in the [Julia Zulip](https://julialang.zulipchat.com/#narrow/stream/279055-sciml-bridged)
38+
+ On the [Julia Discourse forums](https://discourse.julialang.org)
39+
+ See also [SciML Community page](https://sciml.ai/community/)
4140

4241
## Reproducibility
4342

0 commit comments

Comments
 (0)