Repository files navigation

Sundials.jl is a Julia package that interfaces to theSundialslibrary (seesource).Sundials (the C library and this package) provides thefollowing:

• CVODES - for integration and sensitivity analysis of ODEs.CVODES treats stiff and nonstiff ODE systems of the formy' = f(t,y,p), y(t0) = y0(p),wherep is a set of parameters.
• ARKStep - for integration of non-stiff, stiff, and mixed modeODEs via split, linearly-implicit form, implicit, and IMEX Runge-Kuttamethods on ODEs of the formMy' = f_E(t,y,p) + f_i(t,y,p), y(t0) = y0(p)for a set of parametersp.
• ERKStep - for integration of non-stiff, stiff, and mixed modeODEs via split, linearly-implicit form, implicit, and IMEX Runge-Kuttamethods on ODEs of the formy' = f(t,y,p), y(t0) = y0(p)for a set of parametersp.
• IDAS - for integration and sensitivity analysis of DAEs.IDAS treats DAE systems of the formF(t,y,y',p) = 0, y(t0) = y0(p), y'(t0) = y0'(p)
• KINSOL - for solution of nonlinear algebraic systems.KINSOL treats nonlinear systems of the formF(u) = 0

Note thatCVODES andIDAS contain all functions provided byCVODE andIDA (for integrationwithout sensitivity analysis). If you need to use the latter, you can setenable_sensitivities=falseindeps/build.jl and (re)build the package.

Within Julia, use the package manager:

using PkgPkg.add("Sundials")

To test the installation use

using PkgPkg.test("Sundials")

This package is part of the JuliaDiffEq common interface. This is documented inthe DifferentialEquations.jl documentation. Thusthe ODE tutorial applies. For example, the Lorenz attractor can be solved withCVODE_Adams as follows:

using Sundialsfunctionlorenz(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]endu0= [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 theCVODE_BDF,CVODE_Adams, andARKODE methods forODEs which are documentedin the ODE Solvers page, andIDA which is documentedin the DAE solvers page.Additionally, theARKODE method can be usedonSplitODEProblemsto 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)

wheref(res,y) is an in-place function that computes the residualf(y)-res=0,and KINSOL attempts to findy such thatres=0. This method is generallyquite fast and the choicelinear_solver=:Band is well-suited for problemswith 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, andthus we recommendNLsolve.jl formore general nonlinear solving.

This package closely follows the Sundials C API. At a slightly higherlevel, many (but not all) Sundials.jl functions support passing Juliaobjects (likeArrays) instead of Sundials objects (likeN_Vectors).The Julia packageClang.jl wasused to wrap Sundials. This directly uses Sundials' headers sort-oflike SWIG. Thus the generalC documentationis the documentation for the direct API. See thetest directory for usage examplesof the direct interface.

For the wrappingcode, seesrc/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:

• Macros likeDENSE_ELEM are not available.
• Nothing is exported from the module. You need to putSundials.in front of everything.
• The parallel versions of Sundials which require differentN_Vectortypes 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}}