From bf328335cc98a696ea60b689d0b0c08e253dc71c Mon Sep 17 00:00:00 2001 From: mkg33 Date: Sat, 19 Jun 2021 15:01:44 +0200 Subject: [PATCH] Minor documentation changes --- docs/src/basics/NonlinearFunctions.md | 2 +- docs/src/basics/NonlinearProblem.md | 12 +++---- docs/src/index.md | 17 +++++---- docs/src/solvers/BracketingSolvers.md | 2 +- docs/src/solvers/NonlinearSystemSolvers.md | 40 +++++++++++----------- docs/src/tutorials/nonlinear.md | 4 +-- 6 files changed, 40 insertions(+), 37 deletions(-) diff --git a/docs/src/basics/NonlinearFunctions.md b/docs/src/basics/NonlinearFunctions.md index 8b2150015..7b57ac988 100644 --- a/docs/src/basics/NonlinearFunctions.md +++ b/docs/src/basics/NonlinearFunctions.md @@ -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 diff --git a/docs/src/basics/NonlinearProblem.md b/docs/src/basics/NonlinearProblem.md index 5b6b8e72c..cdd20adc6 100644 --- a/docs/src/basics/NonlinearProblem.md +++ b/docs/src/basics/NonlinearProblem.md @@ -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 @@ -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. @@ -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. diff --git a/docs/src/index.md b/docs/src/index.md index b38e1ae53..8392246bc 100644 --- a/docs/src/index.md +++ b/docs/src/index.md @@ -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 @@ -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 diff --git a/docs/src/solvers/BracketingSolvers.md b/docs/src/solvers/BracketingSolvers.md index 293ddc28b..f83650029 100644 --- a/docs/src/solvers/BracketingSolvers.md +++ b/docs/src/solvers/BracketingSolvers.md @@ -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 diff --git a/docs/src/solvers/NonlinearSystemSolvers.md b/docs/src/solvers/NonlinearSystemSolvers.md index 17669625b..5f59dd013 100644 --- a/docs/src/solvers/NonlinearSystemSolvers.md +++ b/docs/src/solvers/NonlinearSystemSolvers.md @@ -1,4 +1,4 @@ -# Nonlinear System Solvers +# [Nonlinear System Solvers]((@id nonlinearsystemsolvers)) `solve(prob::NonlinearProblem,alg;kwargs)` @@ -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. @@ -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: @@ -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 @@ -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. diff --git a/docs/src/tutorials/nonlinear.md b/docs/src/tutorials/nonlinear.md index 3974ecfc1..73007f441 100644 --- a/docs/src/tutorials/nonlinear.md +++ b/docs/src/tutorials/nonlinear.md @@ -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