Julia interface to Sundials, including a nonlinear solver (KINSOL), ODE's (CVODE and ARKODE), and DAE's (IDA).
Permalink
Failed to load latest commit information.
deps Update build to sundials-3.1.1.6 binaries Jul 12, 2018
src update to new callbacks Aug 17, 2018
test add 2D linear ARKODE test Jul 25, 2018
.gitignore update .gitignore for new build setup Jan 11, 2018
.travis.yml v1.0 Aug 11, 2018
LICENSE Add license. Mar 12, 2013
README.md Update DL_LOAD_PATH in Readme Feb 28, 2018
REQUIRE v1.0 Aug 11, 2018
appveyor.yml v1.0 Aug 11, 2018

README.md

Sundials.jl

Join the chat at https://gitter.im/JuliaDiffEq/Lobby Travis AppVoyer Coveralls Sundials

Introduction

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

  • CVODES - for integration and sensitivity analysis of ODEs. CVODES treats stiff and nonstiff ODE systems of the form y' = f(t,y,p), y(t0) = y0(p), where p is a set of parameters.
  • ARKODE - for integration of non-stiff, stiff, and mixed mode ODEs via its explicit, implicit, and IMEX Runge-Kutta methods on ODEs of the form My' = f(t,y,p), y(t0) = y0(p) for a set of parameters p.
  • IDAS - for integration and sensitivity analysis of DAEs. IDAS treats DAE systems of the form F(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 form 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.

Installation

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.

Common Interface API

This package is part of the JuliaDiffEq common interface. This is documented in the DifferentialEquaitons.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 SplitODEProblems to solve ODEs in IMEX form.

KINSOL High Level API

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,
                stored_upper = jac_upper + jac_lower)

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.

Direct API

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 Arrays) instead of Sundials objects (like N_Vectors). 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:

  • Macros like DENSE_ELEM are not available.
  • Nothing is exported from the module. You need to put Sundials. in front of everything.
  • The parallel versions of Sundials which require different N_Vector types have not been wrapped.

Citing

If you use this library, please cite both Sundials and the JuliaDiffEq project.

  • Rackauckas, C. & Nie, Q., (2017). DifferentialEquations.jl – A Performant and Feature-Rich Ecosystem for Solving Differential Equations in Julia. Journal of Open Research Software. 5(1), p.15. DOI: http://doi.org/10.5334/jors.151

  • A. C. Hindmarsh, P. N. Brown, K. E. Grant, S. L. Lee, R. Serban, D. E. Shumaker, and C. S. Woodward, “SUNDIALS: Suite of Nonlinear and Differential/Algebraic Equation Solvers,” ACM Transactions on Mathematical Software, 31(3), pp. 363-396, 2005. Also available as LLNL technical report UCRL-JP-200037.