Skip to content

Commit

Permalink
Minor documentation changes
Browse files Browse the repository at this point in the history
  • Loading branch information
mkg33 committed Jun 19, 2021
1 parent adcbec5 commit bf32833
Show file tree
Hide file tree
Showing 6 changed files with 40 additions and 37 deletions.
2 changes: 1 addition & 1 deletion docs/src/basics/NonlinearFunctions.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ The SciML ecosystem provides an extensive interface for declaring extra function
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.
`NonlinearFunction` types, which can be passed to the problems.

## Function Type Definitions

Expand Down
12 changes: 6 additions & 6 deletions docs/src/basics/NonlinearProblem.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ and an initial guess ``u₀`` of where `f(u,p)=0`. `f` should be specified as `f
(or in-place as `f(du,u,p)`), and `u₀` should be an AbstractArray (or number)
whose geometry matches the desired geometry of `u`. Note that we are not limited
to numbers or vectors for `u₀`; one is allowed to provide `u₀` as arbitrary
matrices / higher dimension tensors as well.
matrices / higher-dimension tensors as well.

## Problem Type

Expand All @@ -24,11 +24,11 @@ NonlinearProblem(f::NonlinearFunction,u0,p=NullParameters();kwargs...)
NonlinearProblem{isinplace}(f,u0,p=NullParameters();kwargs...)
```

`isinplace` optionally sets whether the function is inplace or not. This is
`isinplace` optionally sets whether the function is in-place or not. This is
determined automatically, but not inferred.

Parameters are optional, and if not given then a `NullParameters()` singleton
will be used which will throw nice errors if you try to index non-existent
Parameters are optional, and if not given, then a `NullParameters()` singleton
will be used, which will throw nice errors if you try to index non-existent
parameters. Any extra keyword arguments are passed on to the solvers. For example,
if you set a `callback` in the problem, then that `callback` will be added in
every solve call.
Expand All @@ -40,5 +40,5 @@ page.

* `f`: The function in the ODE.
* `u0`: The initial guess for the steady state.
* `p`: The parameters for the problem. Defaults to `NullParameters`
* `kwargs`: The keyword arguments passed onto the solves.
* `p`: The parameters for the problem. Defaults to `NullParameters`.
* `kwargs`: The keyword arguments passed on to the solvers.
17 changes: 10 additions & 7 deletions docs/src/index.md
Original file line number Diff line number Diff line change
@@ -1,18 +1,21 @@
# NonlinearSolve.jl: High-Performance Unified Nonlinear Solvers

NonlinaerSolve.jl is a unified interface for the nonlinear solving packages of
Julia. It includes its own high-performance nonlinear solves which include the
Julia. It includes its own high-performance nonlinear solvers which include the
ability to swap out to fast direct and iterative linear solvers, along with the
ability to use sparse automatic differentiation for Jacobian construction and
Jacobian-vector products. It interfaces with other packages of the Julia ecosystem
to make it easy to test alternative solver packages and pass small types to
control algorithm swapping. It interfaces with the
control algorithm swapping. It also interfaces with the
[ModelingToolkit.jl](https://mtk.sciml.ai/dev/) world of symbolic modeling to
allow for automatically generating high performance code.
allow for automatically generating high-performance code.

Performance is key: the current methods are made to be highly performant on
scalar and statically sized small problems, with options for large-scale systems.
If you run into any performance issues, please file an issue.
If you run into any performance issues, please file an issue. Note that this
package is distinct from [SciMLNLSolve.jl](https://github.com/SciML/SciMLNLSolve.jl).
Consult the [NonlinearSystemSolvers](@ref nonlinearsystemsolvers) page for
information on how to import solvers from different packages.

## Installation

Expand All @@ -29,10 +32,10 @@ Pkg.add("NonlinearSolve")
[SciML ColPrac: Contributor's Guide on Collaborative Practices for Community Packages](https://github.com/SciML/ColPrac/blob/master/README.md)
for guidance on PRs, issues, and other matters relating to contributing to ModelingToolkit.
- There are a few community forums:
- The #diffeq-bridged channel in the [Julia Slack](https://julialang.org/slack/)
- the #diffeq-bridged channel in the [Julia Slack](https://julialang.org/slack/)
- [JuliaDiffEq](https://gitter.im/JuliaDiffEq/Lobby) on Gitter
- On the Julia Discourse forums (look for the [modelingtoolkit tag](https://discourse.julialang.org/tag/modelingtoolkit)
- See also [SciML Community page](https://sciml.ai/community/)
- on the Julia Discourse forums (look for the [modelingtoolkit tag](https://discourse.julialang.org/tag/modelingtoolkit)
- see also [SciML Community page](https://sciml.ai/community/)

## Roadmap

Expand Down
2 changes: 1 addition & 1 deletion docs/src/solvers/BracketingSolvers.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,5 +16,5 @@ less stable than `Bisection`.

### NonlinearSolve.jl

- `Falsi` : A non-allocating regula falsi method
- `Falsi`: A non-allocating regula falsi method
- `Bisection`: A common bisection method
40 changes: 20 additions & 20 deletions docs/src/solvers/NonlinearSystemSolvers.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Nonlinear System Solvers
# [Nonlinear System Solvers]((@id nonlinearsystemsolvers))

`solve(prob::NonlinearProblem,alg;kwargs)`

Expand All @@ -13,11 +13,11 @@ This page is solely focused on the methods for nonlinear systems.
static arrays and thus really well-optimized for small systems, while for large
systems it can make use of sparsity patterns for sparse automatic differentiation
and sparse linear solving of very large systems. That said, as a classic Newton
method, it's stability region can be smaller than other methods. `NLSolveJL`'s
method, its stability region can be smaller than other methods. `NLSolveJL`'s
`:trust_region` method can be a good choice for high stability, along with
`CMINPACK`.

For a system which is very non-stiff (i.e. the condition number of the Jacobian
For a system which is very non-stiff (i.e., the condition number of the Jacobian
is small, or the eigenvalues of the Jacobian are within a few orders of magnitude),
then `NLSolveJL`'s `:anderson` can be a good choice.

Expand All @@ -34,7 +34,7 @@ These are the core solvers.

### SciMLNLSolve.jl

This is a wrapper package to import solvers from other packages into this interface.
This is a wrapper package for importing solvers from other packages into this interface.
Note that these solvers do not come by default, and thus one needs to install
the package before using these solvers:

Expand Down Expand Up @@ -64,13 +64,13 @@ NLSolveJL(;

Choices for methods in `NLSolveJL`:

- `:fixedpoint`: fixed point iteration
- `:anderson`: Anderson accelerated fixed point iteration
- `:fixedpoint`: Fixed-point iteration
- `:anderson`: Anderson-accelerated fixed-point iteration
- `:newton`: Classical Newton method with an optional line search
- `:trust_region`: Trust region Newton method. The default
- `:trust_region`: Trust region Newton method (the default choice)

For more information on these arguments, consult the
[NLsolve.jl documentation](https://github.com/JuliaNLSolvers/NLsolve.jl)
[NLsolve.jl documentation](https://github.com/JuliaNLSolvers/NLsolve.jl).

### Sundials.jl

Expand All @@ -96,22 +96,22 @@ KINSOL(;

The choices for the linear solver are:

- `:Dense` - A dense linear solver.
- `:Band` - A solver specialized for banded Jacobians. If used, you must set the
- `:Dense`: A dense linear solver
- `:Band`: A solver specialized for banded Jacobians. If used, you must set the
position of the upper and lower non-zero diagonals via `jac_upper` and
`jac_lower`.
- `:LapackDense` - A version of the dense linear solver that uses the Julia-provided
- `:LapackDense`: A version of the dense linear solver that uses the Julia-provided
OpenBLAS-linked LAPACK for multithreaded operations. This will be faster than
`:Dense` on larger systems but has noticable overhead on smaller (<100 ODE) systems.
- `:LapackBand` - A version of the banded linear solver that uses the Julia-provided
`:Dense` on larger systems but has noticeable overhead on smaller (<100 ODE) systems.
- `:LapackBand`: A version of the banded linear solver that uses the Julia-provided
OpenBLAS-linked LAPACK for multithreaded operations. This will be faster than
`:Band` on larger systems but has noticable overhead on smaller (<100 ODE) systems.
- `:Diagonal` - This method is specialized for diagonal Jacobians.
- `:GMRES` - A GMRES method. Recommended first choice Krylov method
- `:BCG` - A Biconjugate gradient method.
- `:PCG` - A preconditioned conjugate gradient method. Only for symmetric
`:Band` on larger systems but has noticeable overhead on smaller (<100 ODE) systems.
- `:Diagonal`: This method is specialized for diagonal Jacobians.
- `:GMRES`: A GMRES method. Recommended first choice Krylov method.
- `:BCG`: A biconjugate gradient method
- `:PCG`: A preconditioned conjugate gradient method. Only for symmetric
linear systems.
- `:TFQMR` - A TFQMR method.
- `:KLU` - A sparse factorization method. Requires that the user specifies a
- `:TFQMR`: A TFQMR method.
- `:KLU`: A sparse factorization method. Requires that the user specify a
Jacobian. The Jacobian must be set as a sparse matrix in the `ODEProblem`
type.
4 changes: 2 additions & 2 deletions docs/src/tutorials/nonlinear.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,12 +16,12 @@ solver = solve(probN, NewtonRaphson(), tol = 1e-9)

where `u0` is the initial condition for the rootfind. Native NonlinearSolve.jl
solvers use the given type of `u0` to determine the type used within the solver
and the return. Note that the parameters `p` can be any type, but most be an
and the return. Note that the parameters `p` can be any type, but most are an
AbstractArray for automatic differentiation.

## Using Bracketing Methods

For scalar rootfinding problems, bracketing methods exist. In this case one passes
For scalar rootfinding problems, bracketing methods exist. In this case, one passes
a bracket instead of an initial condition, for example:

```julia
Expand Down

0 comments on commit bf32833

Please sign in to comment.