INSTALL GUIDE

INSTALL_GUIDE

User Manual:

Open the PDF directly: View PDF .
Page Count: 22

Download
Open PDF In Browser	View PDF

Installation Guide for sundials v3.2.1
Eddy Banks, Aaron M. Collier, David J. Gardner, Alan C. Hindmarsh,
Radu Serban, and Carol S. Woodward
Center for Applied Scientific Computing
Lawrence Livermore National Laboratory
October 11, 2018

UCRL-SM-208116

DISCLAIMER
This document was prepared as an account of work sponsored by an agency of the United States
government. Neither the United States government nor Lawrence Livermore National Security, LLC,
nor any of their employees makes any warranty, expressed or implied, or assumes any legal liability or
responsibility for the accuracy, completeness, or usefulness of any information, apparatus, product, or
process disclosed, or represents that its use would not infringe privately owned rights. Reference herein
to any specific commercial product, process, or service by trade name, trademark, manufacturer, or
otherwise does not necessarily constitute or imply its endorsement, recommendation, or favoring by
the United States government or Lawrence Livermore National Security, LLC. The views and opinions
of authors expressed herein do not necessarily state or reflect those of the United States government
or Lawrence Livermore National Security, LLC, and shall not be used for advertising or product
endorsement purposes.

This work was performed under the auspices of the U.S. Department of Energy by Lawrence Livermore
National Laboratory under Contract DE-AC52-07NA27344.

Approved for public release; further dissemination unlimited

Contents
1 SUNDIALS Package Installation Procedure
1.1 CMake-based installation . . . . . . . . . . . . . . . . .
1.1.1 Configuring, building, and installing on Unix-like
1.1.2 Configuration options (Unix/Linux) . . . . . . .
1.1.3 Configuration examples . . . . . . . . . . . . . .
1.1.4 Working with external Libraries . . . . . . . . .
1.1.5 Testing the build and installation . . . . . . . . .
1.2 Building and Running Examples . . . . . . . . . . . . .
1.3 Configuring, building, and installing on Windows . . . .
1.4 Installed libraries and exported header files . . . . . . .

. . . . .
systems
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .

.
.
.
.
.
.
.
.
.

1
2
2
4
10
11
13
13
14
14

Chapter 1

SUNDIALS Package 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 xzf 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:
• The remainder of this chapter will follow these conventions:
solverdir is the directory solver-x.y.z created above; i.e., the directory containing the sundials sources.
builddir is the (temporary) directory under which sundials is built.
instdir is the directory under which the sundials exported header files and libraries will be
installed. Typically, header files are exported under a directory instdir/include while
libraries are installed under instdir/CMAKE INSTALL LIBDIR, with instdir and
CMAKE INSTALL LIBDIR specified at configuration time.
• For sundials CMake-based installation, in-source builds are prohibited; in other words, the
build directory builddir can not be the same as solverdir and such an attempt will lead to
an error. This prevents “polluting” the source tree and allows efficient builds for different
configurations and/or options.
• The installation directory instdir can not be the same as the source directory solverdir.
• By default, only the libraries and header files are exported to the installation directory instdir.
If enabled by the user (with the appropriate toggle for CMake), the examples distributed with
sundials will be built together with the solver libraries but the installation step will result
in exporting (by default in a subdirectory of the installation directory) the example sources
and sample outputs together with automatically generated configuration files that reference the
installed sundials headers and libraries. As such, these configuration files for the sundials examples can be used as “templates” for your own problems. CMake installs CMakeLists.txt files
1

and also (as an option available only under Unix/Linux) Makefile files. Note this installation
approach also allows the option of building the sundials examples without having to install
them. (This can be used as a sanity check for the freshly built libraries.)
• Even if generation of shared libraries is enabled, only static libraries are created for the FCMIX
modules. (Because of the use of fixed names for the Fortran user-provided subroutines, FCMIX
shared libraries would result in “undefined symbol” errors at link time.)

1.1

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.1.3 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), while on Windows it requires Visual Studio. CMake is continually adding new features, and the latest version can be downloaded 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, 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.

1.1.1

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 installdir 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. Examples for using both 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 (...)sundials/instdir
% mkdir (...)sundials/builddir
% cd (...)sundials/builddir
Building with the GUI
Using CMake with the GUI follows this 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
2

– For file and directories, the 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
To build the default configuration using the GUI, from the builddir enter the ccmake command
and point to the solverdir:
% ccmake ../solverdir
The default configuration screen is shown in Figure 1.1.

Figure 1.1: 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 figure 1.2.
Pressing the (g key) 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
To install sundials in the installation directory specified in the configuration, simply run:
% make install
3

Figure 1.2: Changing the instdir for sundials and corresponding examples
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 \
../solverdir
make
make install

1.1.2

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 1.1.4.
BLAS LIBRARIES - BLAS library
Default: /usr/lib/libblas.so
4

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 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 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
5

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 enabled (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
CMAKE INSTALL LIBDIR of CMAKE INSTALL PREFIX, respectively.
CMAKE INSTALL LIBDIR - Library installation directory
Default:
Note: This is the directory within CMAKE INSTALL PREFIX that the sundials libraries will be
installed under. The default is automatically set based on the operating system using the
GNUInstallDirs CMake module.
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 RAJA - Build the sundials raja examples
Default: OFF
Note: You need to enable cuda and raja support to build these examples.
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
6

EXAMPLES INSTALL - Install example files
Default: ON
Note: This option is triggered when any of the sundials example programs are enabled
(EXAMPLES ENABLE 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
HYPRE ENABLE - Enable hypre support
Default: OFF
Note: See additional information on building with hypre enabled in 1.1.4.
HYPRE INCLUDE DIR - Path to hypre header files
HYPRE LIBRARY DIR - Path to hypre installed library files
KLU ENABLE - Enable KLU support
Default: OFF
Note: See additional information on building with KLU enabled in 1.1.4.
KLU INCLUDE DIR - Path to SuiteSparse header files
KLU LIBRARY DIR - Path to SuiteSparse installed library files
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 1.1.4.
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.
7

MPI Fortran COMPILER - mpif77 or mpif90 program
Default:
Note: This option is triggered only if MPI is enabled (MPI ENABLE is ON), Fortran-C support is
enabled (FCMIX ENABLE is ON), and Fortran77 or Fortran90 examples are 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 1.1.4.
PETSC INCLUDE DIR - Path to PETSc header files
PETSC LIBRARY DIR - Path to PETSc installed library files
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 - advanced option - 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.
SUNDIALS F77 FUNC UNDERSCORES - advanced 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.
8

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 1.1.4.
SUPERLUMT INCLUDE DIR - Path to SuperLU MT header files (typically SRC directory)
SUPERLUMT LIBRARY DIR - Path to SuperLU MT installed library files
SUPERLUMT THREAD TYPE - Must be set to Pthread or OpenMP
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.
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), 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
9

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

1.1.3

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:
10

%
>
>
>
>
>
%
%
%

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/solverdir
make install

To disable installation of the examples, use:
%
>
>
>
>
>
>
%
%
%

1.1.4

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. When building sundials as a shared library external libraries any used with
sundials must also be build as a shared library or as a static library compiled with the -fPIC flag.

Building with BLAS
sundials does not utilize BLAS directly but it may be needed by other external libraries that sundials can be built 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/solverdir
make install

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. 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/solverdir
make install

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/∼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.
12

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 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 RAJA to ON.

1.1.5

Testing the build and installation

If sundials was configured with EXAMPLES ENABLE 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

1.2

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 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 to use the GUI) followed by make to compile the example code.
13

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.

1.3

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
(a) Hit Configure
(b) Check/Uncheck solvers to be built
(c) Change CMAKE INSTALL PREFIX to instdir
(d) Set other options as desired
(e) Hit Generate
5. Back in the VS Command Window:
(a) Run msbuild ALL BUILD.vcxproj
(b) 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.

1.4

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/CMAKE INSTALL LIBDIR and instdir/include, respectively. The location can be
changed by setting the CMake variable CMAKE INSTALL PREFIX. Although all installed libraries reside
under libdir/CMAKE INSTALL LIBDIR, the public header files are further organized into subdirectories
under includedir/include.
The installed libraries and exported header files are listed for reference in Table 1.1. The file
extension .lib is typically .so for shared libraries and .a for static libraries. Note that, in the Tables,
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.
14

shared

nvector serial
nvector parallel
nvector openmp
nvector pthreads
nvector parhyp
nvector petsc
nvector cuda

nvector raja

sunmatrix band

sunmatrix dense

sunmatrix sparse

Table 1.1: sundials libraries and header files
Libraries
n/a
Header files sundials/sundials config.h
sundials/sundials fconfig.h
sundials/sundials types.h
sundials/sundials math.h
sundials/sundials nvector.h sundials/sundials fnvector.h
sundials/sundials iterative.h sundials/sundials direct.h
sundials/sundials dense.h
sundials/sundials band.h
sundials/sundials matrix.h
sundials/sundials version.h
sundials/sundials linearsolver.hsundials/sundials mpi types.h
Libraries
libsundials nvecserial.lib
libsundials fnvecserial.a
Header files nvector/nvector serial.h
Libraries
libsundials nvecparallel.lib
libsundials fnvecparallel.a
Header files nvector/nvector parallel.h
Libraries
libsundials nvecopenmp.lib
libsundials fnvecopenmp.a
Header files nvector/nvector openmp.h
Libraries
libsundials nvecpthreads.lib libsundials fnvecpthreads.a
Header files nvector/nvector pthreads.h
Libraries
libsundials nvecparhyp.lib
Header files nvector/nvector parhyp.h
Libraries
libsundials nvecpetsc.lib
Header files nvector/nvector petsc.h
Libraries
libsundials nveccuda.lib
Libraries
libsundials nvecmpicuda.lib
Header files nvector/nvector cuda.h
nvector/nvector mpicuda.h
nvector/cuda/ThreadPartitioning.hpp
nvector/cuda/Vector.hpp
nvector/cuda/VectorKernels.cuh
Libraries
libsundials nveccudaraja.lib
Libraries
libsundials nveccudampiraja.lib
Header files nvector/nvector raja.h
nvector/nvector mpiraja.h
nvector/raja/Vector.hpp
Libraries
libsundials sunmatrixband.lib
libsundials fsunmatrixband.a
Header files sunmatrix/sunmatrix band.h
Libraries
libsundials sunmatrixdense.lib
libsundials fsunmatrixdense.a
Header files sunmatrix/sunmatrix dense.h
Libraries
libsundials sunmatrixsparse.lib
continued on next page

continued from last page

sunlinsol band

Header files
Libraries

sunlinsol dense

Header files
Libraries

sunlinsol klu

Header files
Libraries

sunlinsol lapackband

Header files
Libraries

sunlinsol lapackdense

Header files
Libraries

sunlinsol pcg

Header files
Libraries

sunlinsol spbcgs

Header files
Libraries

sunlinsol spfgmr

Header files
Libraries

sunlinsol spgmr

Header files
Libraries

sunlinsol sptfqmr

Header files
Libraries

sunlinsol superlumt

Header files
Libraries

cvode

Header files
Libraries
Header files

cvodes

Libraries
Header files

libsundials fsunmatrixsparse.a
sunmatrix/sunmatrix sparse.h
libsundials sunlinsolband.lib
libsundials fsunlinsolband.a
sunlinsol/sunlinsol band.h
libsundials sunlinsoldense.lib
libsundials fsunlinsoldense.a
sunlinsol/sunlinsol dense.h
libsundials sunlinsolklu.lib
libsundials fsunlinsolklu.a
sunlinsol/sunlinsol klu.h
libsundials sunlinsollapackband.lib
libsundials fsunlinsollapackband.a
sunlinsol/sunlinsol lapackband.h
libsundials sunlinsollapackdense.lib
libsundials fsunlinsollapackdense.a
sunlinsol/sunlinsol lapackdense.h
libsundials sunlinsolpcg.lib
libsundials fsunlinsolpcg.a
sunlinsol/sunlinsol pcg.h
libsundials sunlinsolspbcgs.lib
libsundials fsunlinsolspbcgs.a
sunlinsol/sunlinsol spbcgs.h
libsundials sunlinsolspfgmr.lib
libsundials fsunlinsolspfgmr.a
sunlinsol/sunlinsol spfgmr.h
libsundials sunlinsolspgmr.lib
libsundials fsunlinsolspgmr.a
sunlinsol/sunlinsol spgmr.h
libsundials sunlinsolsptfqmr.lib
libsundials fsunlinsolsptfqmr.a
sunlinsol/sunlinsol sptfqmr.h
libsundials sunlinsolsuperlumt.lib
libsundials fsunlinsolsuperlumt.a
sunlinsol/sunlinsol superlumt.h
libsundials cvode.lib
libsundials fcvode.a
cvode/cvode.h
cvode/cvode impl.h
cvode/cvode direct.h
cvode/cvode spils.h
cvode/cvode bandpre.h
cvode/cvode bbdpre.h
libsundials cvodes.lib
cvodes/cvodes.h
cvodes/cvodes impl.h
continued on next page

continued from last page

arkode

Libraries
Header files

ida

Libraries
Header files

idas

Libraries
Header files

kinsol

Libraries
Header files

cvodes/cvodes direct.h
cvodes/cvodes bandpre.h
libsundials arkode.lib
arkode/arkode.h
arkode/arkode direct.h
arkode/arkode bandpre.h
libsundials ida.lib
ida/ida.h
ida/ida direct.h
ida/ida bbdpre.h
libsundials idas.lib
idas/idas.h
idas/idas direct.h
idas/idas bbdpre.h
libsundials kinsol.lib
kinsol/kinsol.h
kinsol/kinsol direct.h
kinsol/kinsol bbdpre.h

cvodes/cvodes spils.h
cvodes/cvodes bbdpre.h
libsundials farkode.a
arkode/arkode impl.h
arkode/arkode spils.h
arkode/arkode bbdpre.h
libsundials fida.a
ida/ida impl.h
ida/ida spils.h

idas/idas impl.h
idas/idas spils.h
libsundials fkinsol.a
kinsol/kinsol impl.h
kinsol/kinsol spils.h

Source Exif Data:

File Type                       : PDF
File Type Extension             : pdf
MIME Type                       : application/pdf
PDF Version                     : 1.5
Linearized                      : No
Page Count                      : 22
Page Mode                       : UseOutlines
Author                          : 
Title                           : 
Subject                         : 
Creator                         : LaTeX with hyperref package
Producer                        : pdfTeX-1.40.19
Create Date                     : 2018:10:11 12:22:10-07:00
Modify Date                     : 2018:10:11 12:22:10-07:00
Trapped                         : False
PTEX Fullbanner                 : This is pdfTeX, Version 3.14159265-2.6-1.40.19 (TeX Live 2018) kpathsea version 6.3.0

EXIF Metadata provided by EXIF.tools

INSTALL GUIDE

INSTALL_GUIDE

Navigation menu

Versions of this User Manual:

Views

Navigation