Julia interface to Sundials, including a nonlinear solver (KINSOL), ODE's (CVODE and ARKODE), and DAE's (IDA) in a SciML scientific machine learning enabled manner
Sundials.jl is a Julia package that interfaces to the Sundials library (see source). Sundials (the C library and this package) provides the following:
y' = f(t,y,p), y(t0) = y0(p)
,
where p
is a set of parameters.My' = f_E(t,y,p) + f_i(t,y,p), y(t0) = y0(p)
for a set of parameters p
.y' = f(t,y,p), y(t0) = y0(p)
for a set of parameters p
.F(t,y,y',p) = 0, y(t0) = y0(p), y'(t0) = y0'(p)
F(u) = 0
Note that CVODES and IDAS contain all functions provided by CVODE and IDA (for integration
without sensitivity analysis). If you need to use the latter, you can set enable_sensitivities=false
in deps/build.jl
and (re)build the package.
Within Julia, use the package manager:
Pkg.add("Sundials")
This should download and install the Sundials libraries and register the package. On Windows precompiled binaries are used, while on Unix and OSX Sundials is built from its sources (provided the necessary tools are available). If you have Sundials already installed, make sure that Julia can find it, e.g., via
push!(Base.DL_LOAD_PATH, "/opt/local/lib")
before you install the package. Downloading and/or re-building of the library can be triggered by Pkg.build("Sundials")
if anything goes wrong.
To test the installation use
Pkg.test("Sundials")
which currently runs some of the examples in the examples
directory.
This package is part of the JuliaDiffEq common interface. This is documented in the DifferentialEquations.jl documentation. Thus the ODE tutorial applies. For example, the Lorenz attractor can be solved with CVODE_Adams
as follows:
using Sundials
function lorenz(du,u,p,t)
du[1] = 10.0(u[2]-u[1])
du[2] = u[1]*(28.0-u[3]) - u[2]
du[3] = u[1]*u[2] - (8/3)*u[3]
end
u0 = [1.0;0.0;0.0]
tspan = (0.0,100.0)
prob = ODEProblem(lorenz,u0,tspan)
sol = solve(prob,CVODE_Adams())
using Plots; plot(sol,vars=(1,2,3))
Sundials.jl exports the CVODE_BDF
, CVODE_Adams
, and ARKODE
methods for
ODEs which are documented
in the ODE Solvers page, and IDA
which is documented
in the DAE solvers page.
Additionally, the ARKODE
method can be used
on SplitODEProblem
s
to solve ODEs in IMEX form.
Along with the ODE solvers, Sundials contains the KINSOL nonlinear solver. It's called via:
kinsol(f, y0::Vector{Float64};
userdata::Any = nothing,
linear_solver=:Dense, jac_upper=0, jac_lower=0)
where f(res,y)
is an in-place function that computes the residual f(y)-res=0
,
and KINSOL attempts to find y
such that res=0
. This method is generally
quite fast and the choice linear_solver=:Band
is well-suited for problems
with a banded Jacobian (you must specify the upper and lower band sizes). However,
this is not as robust as many other techniques like trust-region methods, and
thus we recommend NLsolve.jl for
more general nonlinear solving.
This package closely follows the Sundials C API. At a slightly higher
level, many (but not all) Sundials.jl functions support passing Julia
objects (like Array
s) instead of Sundials objects (like N_Vector
s).
The Julia package Clang.jl was
used to wrap Sundials. This directly uses Sundials' headers sort-of
like SWIG. Thus the general
C documentation
is the documentation for the direct API. See the
test directory for usage examples
of the direct interface.
For the wrapping code, see src/wrap_sundials.jl. Because of Clang.jl, Sundials.jl provides almost full coverage of the Sundials library (the serial version). A few things to note:
DENSE_ELEM
are not available.Sundials.
in front of everything.N_Vector
types have not been wrapped.If you use this library, please cite both Sundials and the JuliaDiffEq project.
@article{rackauckas2017differentialequations,
title={Differentialequations. jl--a performant and feature-rich ecosystem for solving differential equations in julia},
author={Rackauckas, Christopher and Nie, Qing},
journal={Journal of Open Research Software},
volume={5},
number={1},
year={2017},
publisher={Ubiquity Press}
}
@article{gardner2022sundials,
title={Enabling new flexibility in the {SUNDIALS} suite of nonlinear and differential/algebraic equation solvers},
author={Gardner, David J and Reynolds, Daniel R and Woodward, Carol S and Balos, Cody J},
journal={ACM Transactions on Mathematical Software (TOMS)},
publisher={ACM},
year={2022},
doi={10.1145/3539801}
}
@article{hindmarsh2005sundials,
title={{SUNDIALS}: Suite of nonlinear and differential/algebraic equation solvers},
author={Hindmarsh, Alan C and Brown, Peter N and Grant, Keith E and Lee, Steven L and Serban, Radu and Shumaker, Dan E and Woodward, Carol S},
journal={ACM Transactions on Mathematical Software (TOMS)},
volume={31},
number={3},
pages={363--396},
year={2005},
publisher={ACM}
}