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.*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.

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!(Sys.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 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).
See
src/Sundials.jl
for examples of how the higher-level interfacing works.

The Julia package Clang.jl was used to wrap Sundials. This directly uses Sundials' headers sort-of like SWIG. This is great work by Isaiah--it didn't take me much work to package a pretty complete interface to Sundials. For the wrapping code, see src/wrap_sundials.jl.

Because of Clang.jl, Sundials.jl provides good coverage of the Sundials library (the serial version).

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(t,u,du)
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`

and `CVODE_Adams`

methods for ODEs which are documented in the ODE Solvers page, and `IDA`

which is documented in the DAE solvers page.

Three functions `kinsol`

, `cvode`

, and `idasol`

are provided as high-level,
very simple functions. *Note that the latter two functions were previously
called ode and ida.* Here is an example for

`cvode`

:```
using Sundials
function f(t, y, ydot)
ydot[1] = -0.04*y[1] + 1.0e4*y[2]*y[3]
ydot[3] = 3.0e7*y[2]*y[2]
ydot[2] = -ydot[1] - ydot[3]
end
t = [0.0; 4 * logspace(-1., 7., 9)]
res = Sundials.cvode(f, [1.0, 0.0, 0.0], t)
```

For `cvode`

, there is an optional positional argument `integrator`

to choose
between the two provided integration options: `:BDF`

for a Backwards Differentiation
Formula method and `:Adams`

for an Adams-Moulton method. There are two supported
keyword arguments, `reltol`

, and `abstol`

, for `cvode`

and `idasol`

. For more
details, please see the docstrings.

See the examples directory.

Three-Body Problem is a notebook with a more thoroughly explained example.

Please note that this is a developer preview. There could be bugs, and everything is subject to change. Of note are:

- The API that matches the Sundials C API should be stable.
- The simplified API is not stable.
- There is no documentation for this package. Please see the general C documentation for Sundials. The API should be identical.
- Macros like
`DENSE_ELEM`

are not available. - Nothing is (yet) exported from the module. You need to put
`Sundials.`

in front of everything. - Parts of the Sundials API that access C structures are difficult. One can use the StrPack package to read or write to these structures, but nothing is built into this package. See this CVODE example.
- The parallel versions of Sundials have been wrapped, but I doubt that they are usable from Julia. They need to be integrated with MPI.jl
- More work could be done to provide a better interface to
`N_Vector`

s.

03/12/2013

about 24 hours ago

236 commits