ARKode Installation Procedure

The installation of any SUNDIALS package is accomplished by installing the SUNDIALS suite as a whole, according to the instructions that follow. The same procedure applies whether or not the downloaded file contains one or all solvers in SUNDIALS.

The SUNDIALS suite (or individual solvers) are distributed as compressed archives (.tar.gz). The name of the distribution archive is of the form SOLVER-X.Y.Z.tar.gz, where SOLVER is one of: sundials, cvode, cvodes, arkode, ida, idas, or kinsol, and X.Y.Z represents the version number (of the SUNDIALS suite or of the individual solver). To begin the installation, first uncompress and expand the sources, by issuing

% tar -zxf SOLVER-X.Y.Z.tar.gz

This will extract source files under a directory SOLVER-X.Y.Z.

Starting with version 2.6.0 of SUNDIALS, CMake is the only supported method of installation. The explanations of the installation procedure begins with a few common observations:

Further details on the CMake-based installation procedures, instructions for manual compilation, and a roadmap of the resulting installed libraries and exported header files, are provided in the following subsections:

CMake-based installation

CMake-based installation provides a platform-independent build system. CMake can generate Unix and Linux Makefiles, as well as KDevelop, Visual Studio, and (Apple) XCode project files from the same configuration file. In addition, CMake also provides a GUI front end and which allows an interactive build and installation process.

The SUNDIALS build process requires CMake version 3.0.2 or higher and a working C compiler. On Unix-like operating systems, it also requires Make (and curses, including its development libraries, for the GUI front end to CMake, ccmake or cmake-gui), while on Windows it requires Visual Studio. While many Linux distributions offer CMake, the version included may be out of date. Many new CMake features have been added recently, and you should download the latest version from http://www.cmake.org. Build instructions for CMake (only necessary for Unix-like systems) can be found on the CMake website. Once CMake is installed, Linux/Unix users will be able to use ccmake or cmake-gui (depending on the version of CMake), while Windows users will be able to use CMakeSetup.

As previously noted, when using CMake to configure, build and install SUNDIALS, it is always required to use a separate build directory. While in-source builds are possible, they are explicitly prohibited by the SUNDIALS CMake scripts (one of the reasons being that, unlike autotools, CMake does not provide a make distclean procedure and it is therefore difficult to clean-up the source tree after an in-source build). By ensuring a separate build directory, it is an easy task for the user to clean-up all traces of the build by simply removing the build directory. CMake does generate a make clean which will remove files generated by the compiler and linker.

Configuring, building, and installing on Unix-like systems

The default CMake configuration will build all included solvers and associated examples and will build static and shared libraries. The INSTDIR defaults to /usr/local and can be changed by setting the CMAKE_INSTALL_PREFIX variable. Support for FORTRAN and all other options are disabled.

CMake can be used from the command line with the cmake command, or from a curses-based GUI by using the ccmake command, or from a wxWidgets or QT based GUI by using the cmake-gui command. Examples for using both text and graphical methods will be presented. For the examples shown it is assumed that there is a top level SUNDIALS directory with appropriate source, build and install directories:

$ mkdir (...)/INSTDIR
$ mkdir (...)/BUILDDIR
$ cd (...)/BUILDDIR

Building with the GUI

Using CMake with the ccmake GUI follows the general process:

  • Select and modify values, run configure (c key)
  • New values are denoted with an asterisk
  • To set a variable, move the cursor to the variable and press enter
    • If it is a boolean (ON/OFF) it will toggle the value
    • If it is string or file, it will allow editing of the string
    • For file and directories, the <tab> key can be used to complete
  • Repeat until all values are set as desired and the generate option is available (g key)
  • Some variables (advanced variables) are not visible right away
  • To see advanced variables, toggle to advanced mode (t key)
  • To search for a variable press / key, and to repeat the search, press the n key

Using CMake with the cmake-gui GUI follows a similar process:

  • Select and modify values, click Configure
  • The first time you click Configure, make sure to pick the appropriate generator (the following will ssume generation of Unix Makfiles).
  • New values are highlighted in red
  • To set a variable, click on or move the cursor to the variable and press enter
    • If it is a boolean (ON/OFF) it will check/uncheck the box
    • If it is string or file, it will allow editing of the string. Additionally, an ellipsis button will appear ... on the far right of the entry. Clicking this button will bring up the file or directory selection dialog.
    • For files and directories, the <tab> key can be used to complete
  • Repeat until all values are set as desired and click the Generate button
  • Some variables (advanced variables) are not visible right away
  • To see advanced variables, click the advanced button

To build the default configuration using the curses GUI, from the BUILDDIR enter the ccmake command and point to the SOLVERDIR:

$ ccmake (...)/SOLVERDIR

Similarly, to build the default configuration using the wxWidgets GUI, from the BUILDDIR enter the cmake-gui command and point to the SOLVERDIR:

$ cmake-gui (...)/SOLVERDIR

The default curses configuration screen is shown in the following figure.

_images/ccmakedefault.png

Default configuration screen. Note: Initial screen is empty. To get this default configuration, press ‘c’ repeatedly (accepting default values denoted with asterisk) until the ‘g’ option is available.

The default INSTDIR for both SUNDIALS and corresponding examples can be changed by setting the CMAKE_INSTALL_PREFIX and the EXAMPLES_INSTALL_PATH as shown in the following figure.

_images/ccmakeprefix.png

Changing the INSTDIR for SUNDIALS and corresponding EXAMPLES.

Pressing the g key or clicking generate will generate makefiles including all dependencies and all rules to build SUNDIALS on this system. Back at the command prompt, you can now run:

$ make

or for a faster parallel build (e.g. using 4 threads), you can run

$ make -j 4

To install SUNDIALS in the installation directory specified in the configuration, simply run:

$ make install

Building from the command line

Using CMake from the command line is simply a matter of specifying CMake variable settings with the cmake command. The following will build the default configuration:

$ cmake -DCMAKE_INSTALL_PREFIX=/home/myname/sundials/instdir \
>  -DEXAMPLES_INSTALL_PATH=/home/myname/sundials/instdir/examples \
>  ../srcdir
$ make
$ make install

Configuration options (Unix/Linux)

A complete list of all available options for a CMake-based SUNDIALS configuration is provide below. Note that the default values shown are for a typical configuration on a Linux system and are provided as illustration only.

BLAS_ENABLE

Enable BLAS support

Default: OFF

Note

Setting this option to ON will trigger additional CMake options. See additional information on building with BLAS enabled in Working with external Libraries.

BLAS_LIBRARIES

BLAS library

Default: /usr/lib/libblas.so

Note

CMake will search for libraries in your LD_LIBRARY_PATH prior to searching default system paths.

BUILD_ARKODE

Build the ARKODE library

Default: ON

BUILD_CVODE

Build the CVODE library

Default: ON

BUILD_CVODES

Build the CVODES library

Default: ON

BUILD_IDA

Build the IDA library

Default: ON

BUILD_IDAS

Build the IDAS library

Default: ON

BUILD_KINSOL

Build the KINSOL library

Default: ON

BUILD_SHARED_LIBS

Build shared libraries

Default: ON

BUILD_STATIC_LIBS

Build static libraries

Default: ON

CMAKE_BUILD_TYPE

Choose the type of build, options are: None (CMAKE_C_FLAGS used), Debug, Release, RelWithDebInfo, and MinSizeRel

Default:

Note

Specifying a build type will trigger the corresponding build type specific compiler flag options below which will be appended to the flags set by CMAKE_<language>_FLAGS.

CMAKE_C_COMPILER

C compiler

Default: /usr/bin/cc

CMAKE_C_FLAGS

Flags for C compiler

Default:

CMAKE_C_FLAGS_DEBUG

Flags used by the C compiler during debug builds

Default: -g

CMAKE_C_FLAGS_MINSIZEREL

Flags used by the C compiler during release minsize builds

Default: -Os -DNDEBUG

CMAKE_C_FLAGS_RELEASE

Flags used by the C compiler during release builds

Default: -O3 -DNDEBUG

CMAKE_CXX_COMPILER

C++ compiler

Default: /usr/bin/c++

Note

A C++ compiler (and all related options) are only are triggered if C++ examples are enabled (EXAMPLES_ENABLE_CXX is ON). All SUNDIALS solvers can be used from C++ applications by default without setting any additional configuration options.

CMAKE_CXX_FLAGS

Flags for C++ compiler

Default:

CMAKE_CXX_FLAGS_DEBUG

Flags used by the C++ compiler during debug builds

Default: -g

CMAKE_CXX_FLAGS_MINSIZEREL

Flags used by the C++ compiler during release minsize builds

Default: -Os -DNDEBUG

CMAKE_CXX_FLAGS_RELEASE

Flags used by the C++ compiler during release builds

Default: -O3 -DNDEBUG

CMAKE_Fortran_COMPILER

Fortran compiler

Default: /usr/bin/gfortran

Note

Fortran support (and all related options) are triggered only if either Fortran-C support is (FCMIX_ENABLE is ON) or BLAS/LAPACK support is enabled (BLAS_ENABLE or LAPACK_ENABLE is ON).

CMAKE_Fortran_FLAGS

Flags for Fortran compiler

Default:

CMAKE_Fortran_FLAGS_DEBUG

Flags used by the Fortran compiler during debug builds

Default: -g

CMAKE_Fortran_FLAGS_MINSIZEREL

Flags used by the Fortran compiler during release minsize builds

Default: -Os

CMAKE_Fortran_FLAGS_RELEASE

Flags used by the Fortran compiler during release builds

Default: -O3

CMAKE_INSTALL_PREFIX

Install path prefix, prepended onto install directories

Default: /usr/local

Note

The user must have write access to the location specified through this option. Exported SUNDIALS header files and libraries will be installed under subdirectories include and lib of CMAKE_INSTALL_PREFIX, respectively.

CXX_ENABLE

Flag to enable C++ ARKode examples (if examples are enabled)

Default: OFF

CUDA_ENABLE

Build the SUNDIALS CUDA vector module.

Default: OFF

EXAMPLES_ENABLE_C

Build the SUNDIALS C examples

Default: ON

EXAMPLES_ENABLE_CUDA

Build the SUNDIALS CUDA examples

Default: OFF

Note

You need to enable CUDA support to build these examples.

EXAMPLES_ENABLE_CXX

Build the SUNDIALS C++ examples

Default: OFF

EXAMPLES_ENABLE_F77

Build the SUNDIALS Fortran77 examples

Default: ON (if FCMIX_ENABLE is ON)

EXAMPLES_ENABLE_F90

Build the SUNDIALS Fortran90 examples

Default: OFF

EXAMPLES_INSTALL

Install example files

Default: ON

Note

This option is triggered when any of the SUNDIALS example programs are enabled (EXAMPLES_ENABLE_<language> is ON). If the user requires installation of example programs then the sources and sample output files for all SUNDIALS modules that are currently enabled will be exported to the directory specified by EXAMPLES_INSTALL_PATH. A CMake configuration script will also be automatically generated and exported to the same directory. Additionally, if the configuration is done under a Unix-like system, makefiles for the compilation of the example programs (using the installed SUNDIALS libraries) will be automatically generated and exported to the directory specified by EXAMPLES_INSTALL_PATH.

EXAMPLES_INSTALL_PATH

Output directory for installing example files

Default: /usr/local/examples

Note

The actual default value for this option will be an examples subdirectory created under CMAKE_INSTALL_PREFIX.

FCMIX_ENABLE

Enable Fortran-C support

Default: OFF

F90_ENABLE

Flag to enable Fortran 90 ARKode examples (if examples are enabled)

Default: OFF

HYPRE_ENABLE

Flag to enable hypre support

Default: OFF

Note

See additional information on building with hypre enabled in Working with external Libraries.

HYPRE_INCLUDE_DIR

Path to hypre header files

Default: none

HYPRE_LIBRARY

Path to hypre installed library files

Default: none

KLU_ENABLE

Enable KLU support

Default: OFF

Note

See additional information on building with KLU enabled in Working with external Libraries.

KLU_INCLUDE_DIR

Path to SuiteSparse header files

Default: none

KLU_LIBRARY_DIR

Path to SuiteSparse installed library files

Default: none

LAPACK_ENABLE

Enable LAPACK support

Default: OFF

Note

Setting this option to ON will trigger additional CMake options. See additional information on building with LAPACK enabled in Working with external Libraries.

LAPACK_LIBRARIES

LAPACK (and BLAS) libraries

Default: /usr/lib/liblapack.so;/usr/lib/libblas.so

Note

CMake will search for libraries in your LD_LIBRARY_PATH prior to searching default system paths.

MPI_ENABLE

Enable MPI support (build the parallel nvector).

Default: OFF

Note

Setting this option to ON will trigger several additional options related to MPI.

MPI_C_COMPILER

mpicc program

Default:

MPI_CXX_COMPILER

mpicxx program

Default:

Note

This option is triggered only if MPI is enabled (MPI_ENABLE is ON) and C++ examples are enabled (EXAMPLES_ENABLE_CXX is ON). All SUNDIALS solvers can be used from C++ MPI applications by default without setting any additional configuration options other than MPI_ENABLE.

MPI_Fortran_COMPILER

mpif77 or mpif90 program

Default:

Note

This option is triggered only if MPI is enabled (MPI_ENABLE is ON) and Fortran-C support is enabled (EXAMPLES_ENABLE_F77 or EXAMPLES_ENABLE_F90 are ON).

MPIEXEC_EXECUTABLE

Specify the executable for running MPI programs

Default: mpirun

Note

This option is triggered only if MPI is enabled (MPI_ENABLE is ON).

OPENMP_ENABLE

Enable OpenMP support (build the OpenMP NVector)

Default: OFF

PETSC_ENABLE

Enable PETSc support

Default: OFF

Note

See additional information on building with PETSc enabled in Working with external Libraries.

PETSC_INCLUDE_DIR

Path to PETSc header files

Default: none

PETSC_LIBRARY_DIR

Path to PETSc installed library files

Default: none

PTHREAD_ENABLE

Enable Pthreads support (build the Pthreads NVector)

Default: OFF

RAJA_ENABLE

Enable RAJA support (build the RAJA NVector).

Default: OFF

Note

You need to enable CUDA in order to build the RAJA vector module.

SUNDIALS_F77_FUNC_CASE

Specify the case to use in the Fortran name-mangling scheme, options are: lower or upper

Default:

Note: The build system will attempt to infer the Fortran name-mangling scheme using the Fortran compiler. This option should only be used if a Fortran compiler is not available or to override the inferred or default (lower) scheme if one can not be determined. If used, SUNDIALS_F77_FUNC_UNDERSCORES must also be set.

index:

SUNDIALS_F77_FUNC_UNDERSCORES <SUNDIALS_F77_FUNC_UNDERSCORES (CMake option)> Specify the number of underscores to append in the Fortran name-mangling scheme, options are: none, one, or two

Default:

Note: The build system will attempt to infer the Fortran name-mangling scheme using the Fortran compiler. This option should only be used if a Fortran compiler is not available or to override the inferred or default (one) scheme if one can not be determined. If used, SUNDIALS_F77_FUNC_CASE must also be set.

SUNDIALS_INDEX_TYPE (advanced)

Integer type used for SUNDIALS indices. The size must match the size provided for the SUNDIALS_INDEX_SIZE option.

Default:

Note: In past SUNDIALS versions, a user could set this option to INT64_T to use 64-bit integers, or INT32_T to use 32-bit integers. Starting in SUNDIALS 3.2.0, these special values are deprecated. For SUNDIALS 3.2.0 and up, a user will only need to use the SUNDIALS_INDEX_SIZE option in most cases.

SUNDIALS_INDEX_SIZE

Integer size (in bits) used for indices in SUNDIALS, options are: 32 or 64

Default: 64

Note: The build system tries to find an integer type of appropriate size. Candidate 64-bit integer types are (in order of preference): int64_t, __int64, long long, and long. Candidate 32-bit integers are (in order of preference): int32_t, int, and long. The advanced option, SUNDIALS_INDEX_TYPE can be used to provide a type not listed here.

SUNDIALS_PRECISION

Precision used in SUNDIALS, options are: double, single or extended

Default: double

SUPERLUMT_ENABLE

Enable SuperLU_MT support

Default: OFF

Note

See additional information on building with SuperLU_MT enabled in Working with external Libraries.

SUPERLUMT_INCLUDE_DIR

Path to SuperLU_MT header files (under a typical SuperLU_MT install, this is typically the SuperLU_MT SRC directory)

Default: none

SUPERLUMT_LIBRARY_DIR

Path to SuperLU_MT installed library files

Default: none

SUPERLUMT_THREAD_TYPE

Must be set to Pthread or OpenMP, depending on how SuperLU_MT was compiled.

Default: Pthread

USE_GENERIC_MATH

Use generic (stdc) math libraries

Default: ON

xSDK Configuration Options

SUNDIALS supports CMake configuration options defined by the Extreme-scale Scientific Software Development Kit (xSDK) community policies (see https://xsdk.info for more information). xSDK CMake options are unused by default but may be activated by setting USE_XSDK_DEFAULTS to ON.

Note

When xSDK options are active, they will overwrite the corresponding SUNDIALS option and may have different default values (see details below). As such the equivalent SUNDIALS options should not be used when configuring with xSDK options. In the GUI front end to CMake (ccmake or cmake-gui), setting USE_XSDK_DEFAULTS to ON will hide the corresponding SUNDIALS options as advanced CMake variables. During configuration, messages are output detailing which xSDK flags are active and the equivalent SUNDIALS options that are replaced. Below is a complete list xSDK options and the corresponding SUNDIALS options if applicable.

TPL_BLAS_LIBRARIES

BLAS library

Default: /usr/lib/libblas.so

SUNDIALS equivalent: BLAS_LIBRARIES

Note

CMake will search for libraries in your LD_LIBRARY_PATH prior to searching default system paths.

TPL_ENABLE_BLAS

Enable BLAS support

Default: OFF

SUNDIALS equivalent: BLAS_ENABLE

TPL_ENABLE_HYPRE

Enable hypre support

Default: OFF

SUNDIALS equivalent: HYPRE_ENABLE

TPL_ENABLE_KLU

Enable KLU support

Default: OFF

SUNDIALS equivalent: KLU_ENABLE

TPL_ENABLE_PETSC

Enable PETSc support

Default: OFF

SUNDIALS equivalent: PETSC_ENABLE

TPL_ENABLE_LAPACK

Enable LAPACK support

Default: OFF

SUNDIALS equivalent: LAPACK_ENABLE

TPL_ENABLE_SUPERLUMT

Enable SuperLU_MT support

Default: OFF

SUNDIALS equivalent: SUPERLUMT_ENABLE

TPL_HYPRE_INCLUDE_DIRS

Path to hypre header files

SUNDIALS equivalent: HYPRE_INCLUDE_DIR

TPL_HYPRE_LIBRARIES

hypre library

SUNDIALS equivalent: N/A

TPL_KLU_INCLUDE_DIRS

Path to KLU header files

SUNDIALS equivalent: KLU_INCLUDE_DIR

TPL_KLU_LIBRARIES

KLU library

SUNDIALS equivalent: N/A

TPL_LAPACK_LIBRARIES

LAPACK (and BLAS) libraries

Default: /usr/lib/liblapack.so;/usr/lib/libblas.so

SUNDIALS equivalent: LAPACK_LIBRARIES

Note

CMake will search for libraries in your LD_LIBRARY_PATH prior to searching default system paths.

TPL_PETSC_INCLUDE_DIRS

Path to PETSc header files

SUNDIALS equivalent: PETSC_INCLUDE_DIR

TPL_PETSC_LIBRARIES

PETSc library

SUNDIALS equivalent: N/A

TPL_SUPERLUMT_INCLUDE_DIRS

Path to SuperLU_MT header files

SUNDIALS equivalent: SUPERLUMT_INCLUDE_DIR

TPL_SUPERLUMT_LIBRARIES

SuperLU_MT library

SUNDIALS equivalent: N/A

TPL_SUPERLUMT_THREAD_TYPE

SuperLU_MT library thread type

SUNDIALS equivalent: SUPERLUMT_THREAD_TYPE

USE_XSDK_DEFAULTS

Enable xSDK default configuration settings

Default: OFF

SUNDIALS equivalent: N/A

Note

Enabling xSDK defaults also sets CMAKE_BUILD_TYPE to Debug

XSDK_ENABLE_FORTRAN

Enable SUNDIALS Fortran interface

Default: OFF

SUNDIALS equivalent: FCMIX_ENABLE

XSDK_INDEX_SIZE

Integer size (bits) used for indices in SUNDIALS, options are: 32 or 64

Default: 32

SUNDIALS equivalent: SUNDIALS_INDEX_SIZE

XSDK_PRECISION

Precision used in SUNDIALS, options are: double, single, or quad

Default: double

SUNDIALS equivalent: SUNDIALS_PRECISION

Configuration examples

The following examples will help demonstrate usage of the CMake configure options.

To configure SUNDIALS using the default C and Fortran compilers, and default mpicc and mpif77 parallel compilers, enable compilation of examples, and install libraries, headers, and example sources under subdirectories of /home/myname/sundials/, use:

% cmake \
> -DCMAKE_INSTALL_PREFIX=/home/myname/sundials/instdir \
> -DEXAMPLES_INSTALL_PATH=/home/myname/sundials/instdir/examples \
> -DMPI_ENABLE=ON \
> -DFCMIX_ENABLE=ON \
> /home/myname/sundials/srcdir

% make install

To disable installation of the examples, use:

% cmake \
> -DCMAKE_INSTALL_PREFIX=/home/myname/sundials/instdir \
> -DEXAMPLES_INSTALL_PATH=/home/myname/sundials/instdir/examples \
> -DMPI_ENABLE=ON \
> -DFCMIX_ENABLE=ON \
> -DEXAMPLES_INSTALL=OFF \
> /home/myname/sundials/srcdir

% make install

Working with external Libraries

The SUNDIALS suite contains many options to enable implementation flexibility when developing solutions. The following are some notes addressing specific configurations when using the supported third party libraries.

Building with BLAS

SUNDIALS does not utilize BLAS directly but it may be needed by other external libraries that SUNDIALS can be build with (e.g. LAPACK, PETSc, SuperLU_MT, etc.). To enable BLAS, set the BLAS_ENABLE option to ON. If the directory containing the BLAS library is in the LD_LIBRARY_PATH environment variable, CMake will set the BLAS_LIBRARIES variable accordingly, otherwise CMake will attempt to find the BLAS library in standard system locations. To explicitly tell CMake what libraries to use, the BLAS_LIBRARIES variable can be set to the desired library. Example:

% cmake \
> -DCMAKE_INSTALL_PREFIX=/home/myname/sundials/instdir \
> -DEXAMPLES_INSTALL_PATH=/home/myname/sundials/instdir/examples \
> -DBLAS_ENABLE=ON \
> -DBLAS_LIBRARIES=/myblaspath/lib/libblas.so \
> -DSUPERLUMT_ENABLE=ON \
> -DSUPERLUMT_INCLUDE_DIR=/mysuperlumtpath/SRC
> -DSUPERLUMT_LIBRARY_DIR=/mysuperlumtpath/lib
> /home/myname/sundials/srcdir

% make install

Note

When allowing CMake to automatically locate the LAPACK library, CMake may also locate the corresponding BLAS library.

If a working Fortran compiler is not available to infer the Fortran name-mangling scheme, the options SUNDIALS_F77_FUNC_CASE and SUNDIALS_F77_FUNC_UNDERSCORES must be set in order to bypass the check for a Fortran compiler and define the name-mangling scheme. The defaults for these options in earlier versions of SUNDIALS were lower and one, respectively.

Building with LAPACK

To enable LAPACK, set the LAPACK_ENABLE option to ON. If the directory containing the LAPACK library is in the LD_LIBRARY_PATH environment variable, CMake will set the LAPACK_LIBRARIES variable accordingly, otherwise CMake will attempt to find the LAPACK library in standard system locations. To explicitly tell CMake what library to use, the LAPACK_LIBRARIES variable can be set to the desired libraries.

Note

When setting the LAPACK location explicitly the location of the corresponding BLAS library will also need to be set. Example:

% cmake \
> -DCMAKE_INSTALL_PREFIX=/home/myname/sundials/instdir \
> -DEXAMPLES_INSTALL_PATH=/home/myname/sundials/instdir/examples \
> -DBLAS_ENABLE=ON \
> -DBLAS_LIBRARIES=/mylapackpath/lib/libblas.so \
> -DLAPACK_ENABLE=ON \
> -DLAPACK_LIBRARIES=/mylapackpath/lib/liblapack.so \
> /home/myname/sundials/srcdir

% make install

Note

When allowing CMake to automatically locate the LAPACK library, CMake may also locate the corresponding BLAS library.

If a working Fortran compiler is not available to infer the Fortran name-mangling scheme, the options SUNDIALS_F77_FUNC_CASE and SUNDIALS_F77_FUNC_UNDERSCORES must be set in order to bypass the check for a Fortran compiler and define the name-mangling scheme. The defaults for these options in earlier versions of SUNDIALS were lower and one, respectively.

Building with KLU

The KLU libraries are part of SuiteSparse, a suite of sparse matrix software, available from the Texas A&M University website: http://faculty.cse.tamu.edu/davis/suitesparse.html .

SUNDIALS has been tested with SuiteSparse version 4.5.3. To enable KLU, set KLU_ENABLE to ON, set KLU_INCLUDE_DIR to the include path of the KLU installation and set KLU_LIBRARY_DIR to the lib path of the KLU installation. The CMake configure will result in populating the following variables: AMD_LIBRARY, AMD_LIBRARY_DIR, BTF_LIBRARY, BTF_LIBRARY_DIR, COLAMD_LIBRARY, COLAMD_LIBRARY_DIR, and KLU_LIBRARY.

Building with SuperLU_MT

The SuperLU_MT libraries are available for download from the Lawrence Berkeley National Laboratory website: http://crd-legacy.lbl.gov/$sim$xiaoye/SuperLU/#superlu_mt .

SUNDIALS has been tested with SuperLU_MT version 3.1. To enable SuperLU_MT, set SUPERLUMT_ENABLE to ON, set SUPERLUMT_INCLUDE_DIR to the SRC path of the SuperLU_MT installation, and set the variable SUPERLUMT_LIBRARY_DIR to the lib path of the SuperLU_MT installation. At the same time, the variable SUPERLUMT_THREAD_TYPE must be set to either Pthread or OpenMP.

Do not mix thread types when building SUNDIALS solvers. If threading is enabled for SUNDIALS by having either OPENMP_ENABLE or PTHREAD_ENABLE set to ON then SuperLU_MT should be set to use the same threading type.

Building with PETSc

The PETSc libraries are available for download from the Argonne National Laboratory website: http://www.mcs.anl.gov/petsc .

SUNDIALS has been tested with PETSc version 3.7.2. To enable PETSc, set PETSC_ENABLE to ON, set PETSC_INCLUDE_DIR to the include path of the PETSc installation, and set the variable PETSC_LIBRARY_DIR to the lib path of the PETSc installation.

Building with hypre

The hypre libraries are available for download from the Lawrence Livermore National Laboratory website: http://computation.llnl.gov/projects/hypre. SUNDIALS has been tested with hypre version 2.11.1. To enable hypre, set HYPRE_ENABLE to ON, set HYPRE_INCLUDE_DIR to the include path of the hypre installation, and set the variable HYPRE_LIBRARY_DIR to the lib path of the hypre installation.

Building with CUDA

SUNDIALS CUDA modules and examples have been tested with version 8.0 of the CUDA toolkit. To build them, you need to install the Toolkit and compatible NVIDIA drivers. Both are available for download from the NVIDIA website: https://developer.nvidia.com/cuda-downloads. To enable CUDA, set CUDA_ENABLE to ON. If CUDA is installed in a nonstandard location, you may be prompted to set the variable CUDA_TOOLKIT_ROOT_DIR with your CUDA Toolkit installation path. To enable CUDA examples, set EXAMPLES_ENABLE_CUDA to ON.

Building with RAJA

RAJA is a performance portability layer developed by Lawrence Livermore National Laboratory and can be obtained from {tt https://github.com/LLNL/RAJA. SUNDIALS RAJA modules and examples have been tested with RAJA version 0.3. Building SUNDIALS RAJA modules requires a CUDA-enabled RAJA installation. To enable RAJA, set CUDA_ENABLE and RAJA_ENABLE to ON. If RAJA is installed in a nonstandard location you will be prompted to set the variable RAJA_DIR with the path to the RAJA CMake configuration file. To enable building the RAJA examples set EXAMPLES_ENABLE_CUDA to ON.

Testing the build and installation

If SUNDIALS was configured with EXAMPLES_ENABLE_<language> options to ON, then a set of regression tests can be run after building with the make command by running:

% make test

Additionally, if EXAMPLES_INSTALL was also set to ON, then a set of smoke tests can be run after installing with the make install command by running:

% make test_install

Building and Running Examples

Each of the SUNDIALS solvers is distributed with a set of examples demonstrating basic usage. To build and install the examples, set at least of the EXAMPLES_ENABLE_<language> options to ON, and set EXAMPLES_INSTALL to ON. Specify the installation path for the examples with the variable EXAMPLES_INSTALL_PATH. CMake will generate CMakeLists.txt configuration files (and Makefile files if on Linux/Unix) that reference the installed SUNDIALS headers and libraries.

Either the CMakeLists.txt file or the traditional Makefile may be used to build the examples as well as serve as a template for creating user developed solutions. To use the supplied Makefile simply run make to compile and generate the executables. To use CMake from within the installed example directory, run cmake (or ccmake or cmake-gui to use the GUI) followed by make to compile the example code. Note that if CMake is used, it will overwrite the traditional Makefile with a new CMake-generated Makefile.

The resulting output from running the examples can be compared with example output bundled in the SUNDIALS distribution.

NOTE: There will potentially be differences in the output due to machine architecture, compiler versions, use of third party libraries etc.

Configuring, building, and installing on Windows

CMake can also be used to build SUNDIALS on Windows. To build SUNDIALS for use with Visual Studio the following steps should be performed:

  1. Unzip the downloaded tar file(s) into a directory. This will be the SOLVERDIR
  2. Create a separate BUILDDIR
  3. Open a Visual Studio Command Prompt and cd to BUILDDIR
  4. Run cmake-gui ../SOLVERDIR
    1. Hit Configure
    2. Check/Uncheck solvers to be built
    3. Change CMAKE_INSTALL_PREFIX to INSTDIR
    4. Set other options as desired
    5. Hit Generate
  5. Back in the VS Command Window:
    1. Run msbuild ALL_BUILD.vcxproj
    2. Run msbuild INSTALL.vcxproj

The resulting libraries will be in the INSTDIR.

The SUNDIALS project can also now be opened in Visual Studio. Double click on the ALL_BUILD.vcxproj file to open the project. Build the whole solution to create the SUNDIALS libraries. To use the SUNDIALS libraries in your own projects, you must set the include directories for your project, add the SUNDIALS libraries to your project solution, and set the SUNDIALS libraries as dependencies for your project.

Installed libraries and exported header files

Using the CMake SUNDIALS build system, the command

$ make install

will install the libraries under LIBDIR and the public header files under INCLUDEDIR. The values for these directories are INSTDIR/lib and INSTDIR/include, respectively. The location can be changed by setting the CMake variable CMAKE_INSTALL_PREFIX. Although all installed libraries reside under LIBDIR/lib, the public header files are further organized into subdirectories under INCLUDEDIR/include.

The installed libraries and exported header files are listed for reference in the Table: SUNDIALS libraries and header files. The file extension .LIB is typically .so for shared libraries and .a for static libraries. Note that, in this table names are relative to LIBDIR for libraries and to INCLUDEDIR for header files.

A typical user program need not explicitly include any of the shared SUNDIALS header files from under the INCLUDEDIR/include/sundials directory since they are explicitly included by the appropriate solver header files (e.g., cvode_dense.h includes sundials_dense.h). However, it is both legal and safe to do so, and would be useful, for example, if the functions declared in sundials_dense.h are to be used in building a preconditioner.

Table: SUNDIALS libraries and header files

Shared Header files sundials/sundials_band.h, sundials/sundials_config.h, sundials/sundials_dense.h, sundials/sundials_direct.h, sundials/sundials_fconfig.h, sundials/sundials_fnvector.h, sundials/sundials_iterative.h, sundials/sundials_linearsolver.h, sundials/sundials_nonlinearsolver.h, sundials/sundials_matrix.h, sundials/sundials_math.h, sundials/sundials_nvector.h, sundials/sundials_types.h, sundials/sundials_version.h
NVECTOR_SERIAL Libraries libsundials_nvecserial.LIB, libsundials_fnvecserial.a
NVECTOR_SERIAL Header files nvector/nvector_serial.h
NVECTOR_PARALLEL Libraries libsundials_nvecparallel.LIB, libsundials_fnvecparallel.a
NVECTOR_PARALLEL Header files nvector/nvector_parallel.h
NVECTOR_OPENMP Libraries libsundials_nvecopenmp.LIB, libsundials_fnvecopenmp.a
NVECTOR_OPENMP Header files nvector/nvector_openmp.h
NVECTOR_PTHREADS Libraries libsundials_nvecpthreads.LIB, libsundials_fnvecpthreads.a
NVECTOR_PTHREADS Header files nvector/nvector_pthreads.h
SUNMATRIX_BAND Libraries libsundials_sunmatrixband.LIB, libsundials_fsunmatrixband.a
SUNMATRIX_BAND Header files sunmatrix/sunmatrix_band.h
SUNMATRIX_DENSE Libraries libsundials_sunmatrixdense.LIB, libsundials_fsunmatrixdense.a
SUNMATRIX_DENSE Header files sunmatrix/sunmatrix_dense.h
SUNMATRIX_SPARSE Libraries libsundials_sunmatrixsparse.LIB, libsundials_fsunmatrixsparse.a
SUNMATRIX_SPARSE Header files sunmatrix/sunmatrix_sparse.h
SUNLINSOL_BAND Libraries libsundials_sunlinsolband.LIB, libsundials_fsunlinsolband.a
SUNLINSOL_BAND Header files sunlinsol/sunlinsol_band.h
SUNLINSOL_DENSE Libraries libsundials_sunlinsoldense.LIB, libsundials_fsunlinsoldense.a
SUNLINSOL_DENSE Header files sunlinsol/sunlinsol_dense.h
SUNLINSOL_KLU Libraries libsundials_sunlinsolklu.LIB, libsundials_fsunlinsolklu.a
SUNLINSOL_KLU Header files sunlinsol/sunlinsol_klu.h
SUNLINSOL_LAPACKBAND Libraries libsundials_sunlinsollapackband.LIB, libsundials_fsunlinsollapackband.a
SUNLINSOL_LAPACKBAND Header files sunlinsol/sunlinsol_lapackband.h
SUNLINSOL_LAPACKDENSE Libraries libsundials_sunlinsollapackdense.LIB, libsundials_fsunlinsollapackdense.a
SUNLINSOL_LAPACKDENSE Header files sunlinsol/sunlinsol_lapackdense.h
SUNLINSOL_PCG Libraries libsundials_sunlinsolpcg.LIB, libsundials_fsunlinsolpcg.a
SUNLINSOL_PCG Header files sunlinsol/sunlinsol_pcg.h
SUNLINSOL_SPBCGS Libraries libsundials_sunlinsolspbcgs.LIB, libsundials_fsunlinsolspbcgs.a
SUNLINSOL_SPBCGS Header files sunlinsol/sunlinsol_spbcgs.h
SUNLINSOL_SPFGMR Libraries libsundials_sunlinsolspfgmr.LIB, libsundials_fsunlinsolspfgmr.a
SUNLINSOL_SPFGMR Header files sunlinsol/sunlinsol_spfgmr.h
SUNLINSOL_SPGMR Libraries libsundials_sunlinsolspgmr.LIB, libsundials_fsunlinsolspgmr.a
SUNLINSOL_SPGMR Header files sunlinsol/sunlinsol_spgmr.h
SUNLINSOL_SPTFQMR Libraries libsundials_sunlinsolsptfqmr.LIB, libsundials_fsunlinsolsptfqmr.a
SUNLINSOL_SPTFQMR Header files sunlinsol/sunlinsol_sptfqmr.h
SUNLINSOL_SUPERLUMT Libraries libsundials_sunlinsolsuperlumt.LIB, libsundials_fsunlinsolsuperlumt.a
SUNLINSOL_SUPERLUMT Header files sunlinsol/sunlinsol_superlumt.h
SUNNONLINSOL_NEWTON Libraries libsundials_sunnonlinsolnewton.LIB, libsundials_fsunnonlinsolnewton.a
SUNNONLINSOL_NEWTON Header files sunnonlinsol/sunnonlinsol_newton.h
SUNNONLINSOL_FIXEDPOINT Libraries libsundials_sunnonlinsolfixedpoint.LIB, libsundials_fsunnonlinsolfixedpoint.a
SUNNONLINSOL_FIXEDPOINT Header files sunnonlinsol/sunnonlinsol_fixedpoint.h
CVODE Libraries libsundials_cvode.LIB, libsundials_fcvode.a
CVODE Header files cvode/cvode.h, cvode/cvode_bandpre.h, cvode/cvode_bbdpre.h, cvode/cvode_diag.h, cvode/cvode_direct.h, cvode/cvode_impl.h, cvode/cvode_ls.h, cvode/cvode_spils.h,
CVODES Libraries libsundials_cvodes.LIB
CVODES Header files cvodes/cvodes.h, cvodes/cvodes_bandpre.h, cvodes/cvodes_bbdpre.h, cvodes/cvodes_diag.h, cvodes/cvodes_direct.h, cvodes/cvodes_impl.h, cvodes/cvodes_spils.h,
ARKODE Libraries libsundials_arkode.LIB, libsundials_farkode.a
ARKODE Header files arkode/arkode.h, arkode/arkode_arkstep.h, arkode/arkode_bandpre.h, arkode/arkode_bbdpre.h, arkode/arkode_butcher.h, arkode/arkode_butcher_dirk.h, arkode/arkode_butcher_erk.h, arkode/arkode_erkstep.h, arkode/arkode_impl.h, arkode/arkode_ls.h,
IDA Libraries libsundials_ida.LIB, libsundials_fida.a
IDA Header files ida/ida.h, ida/ida_bbdpre.h, ida/ida_direct.h, ida/ida_impl.h, ida/ida_ls.h, ida/ida_spils.h,
IDAS Libraries libsundials_idas.LIB
IDAS Header files idas/idas.h, idas/idas_bbdpre.h idas/idas_direct.h, idas/idas_impl.h, idas/idas_spils.h,
KINSOL Libraries libsundials_kinsol.LIB, libsundials_fkinsol.a
KINSOL Header files kinsol/kinsol.h, kinsol/kinsol_bbdpre.h, kinsol/kinsol_direct.h, kinsol/kinsol_impl.h, kinsol/kinsol_ls.h, kinsol/kinsol_spils.h,