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.

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 LAPACK support is enabled (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 modules.

Default: OFF

CUDA_ARCH

Specifies the CUDA architecture to compile for.

Default: sm_30

ENABLE_XBRAID

Enable or disable the ARKStep + XBraid interface.

Default: OFF

Note

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

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: ON (if F77_INTERFACE_ENABLE is ON)

EXAMPLES_ENABLE_F2003

Build the SUNDIALS Fortran2003 examples

Default: ON (if F2003_INTERFACE_ENABLE is ON)

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.

F77_INTERFACE_ENABLE

Enable Fortran77-C interface

Default: OFF

F2003_INTERFACE_ENABLE

Enable Fortran2003 interface

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. This will build the parallel nvector and the MPI-aware version of the ManyVector library.

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_DIR

Path to PETSc installation

Default: none

PETSC_LIBRARIES (advanced option)

Semi-colon separated list of PETSc link libraries. Unless provided by the user, this is autopopulated based on the PETSc installation found in PETSC_DIR.

Default: none

PETSC_INCLUDES (advanced option)

Semi-colon separated list of PETSc include directroies. Unless provided by the user, this is autopopulated based on the PETSc installation found in PETSC_DIR.

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_BUILD_WITH_MONITORING

Build SUNDIALS with capabilties for fine-grained monitoring of solver progress and statistics. This is primarily useful for debugging.

Default: OFF

Note: Building with monitoring may result in minor performance degradation even if monitoring is not utilized.

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.

SUNDIALS_F77_FUNC_UNDERSCORES

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

SUPERLUDIST_ENABLE

Enable SuperLU_DIST support

Default: OFF

Note

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

SUPERLUDIST_INCLUDE_DIR

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

Default: none

SUPERLUDIST_LIBRARY_DIR

Path to SuperLU_DIST installed library files

Default: none

SUPERLUDIST_LIBRARIES

Semi-colon separated list of libraries needed for SuperLU_DIST

Default: none

SUPERLUDIST_OpenMP

Enable SUNDIALS support for SuperLU_DIST built with OpenMP

Default: none

Note: SuperLU_DIST must be built with OpenMP support for this option to function. Additionally the environment variable OMP_NUM_THREADS must be set to the desired number of threads.

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

XBRAID_DIR <XBRAID_DIR (CMake option)

The root directory of the XBraid installation.

Default: OFF

XBRAID_INCLUDES

Semi-colon separated list of XBraid include directories. Unless provided by the user, this is autopopulated based on the XBraid installation found in XBRAID_DIR.

Default: none

XBRAID_LIBRARIES

Semi-colon separated list of XBraid link libraries. Unless provided by the user, this is autopopulated based on the XBraid installation found in XBRAID_DIR.

Default: none

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_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_SUPERLUDIST

Enable SuperLU_DIST support

Default: OFF

SUNDIALS equivalent: SUPERLUDIST_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_DIR

Path to PETSc installtion

SUNDIALS equivalent: PETSC_DIR

TPL_SUPERLUDIST_INCLUDE_DIRS

Path to SuperLU_DIST header files

SUNDIALS equivalent: SUPERLUDIST_INCLUDE_DIR

TPL_SUPERLUDIST_LIBRARIES

Semi-colon separated list of libraries needed for SuperLU_DIST including the SuperLU_DIST library itself

SUNDIALS equivalent: SUPERLUDIST_LIBRARIES

TPL_SUPERLUDIST_OpenMP

Enable SUNDIALS support for SuperLU_DIST built with OpenMP

SUNDIALS equivalent: SUPERLUDIST_OpenMP

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 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 required for LAPACK.

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

% make install

Note

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 5.7.2. 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_DIST

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

SUNDIALS has been tested with SuperLU_DIST version 6.1.1. To enable SuperLU_DIST, set SUPERLUDIST_ENABLE to ON, set SUPERLUDIST_INCLUDE_DIR to the SRC path of the SuperLU_DIST installation, and set the variable SUPERLUMT_LIBRARY_DIR to the lib path of the SuperLU_DIST installation. At the same time, the variable SUPERLUDIST_LIBRARIES must be set to a semi-colon separated list of other libraries SuperLU_DIST depends on. For example, if SuperLU_DIST was built with LAPACK, then include the LAPACK library in this list. If SuperLU_DIST was built with OpenMP support, then you may set SUPERLUDIST_OpenMP to ON utilize the OpenMP functionality of SuperLU_DIST.

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_LIBRARIES must be set to a semi-colon separated list of other libraries SuperLU_MT depends on. For example, if SuperLU_MT was build with an external blas library, then include the full path to the blas library in this list. Additionally, 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.10.0 - 3.13.4. To enable PETSc, set PETSC_ENABLE to ON, and set PETSC_DIR to the path of the PETSc installation. Alternatively, a user can provide a list of inlcude paths in PETSC_INCLUDES and a list of complete paths to the PETSc libraries in PETSC_LIBRARIES.

Building with hypre

The hypre libraries are available for download from the Lawrence Livermore National Laboratory website: http://computing.llnl.gov/projects/hypre. SUNDIALS has been tested with hypre version 2.19.0. 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.

Note: SUNDIALS must be configured so that SUNDIALS_INDEX_SIZE (or equivalently, XSDK_INDEX_SIZE) equals the precision of HYPRE_BigInt in the corresponding hypre installation.

Building with CUDA

SUNDIALS CUDA modules and examples have been tested with version 10 and 11 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.12.1. 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.

Building with XBraid

The XBraid library is available for download from the XBraid GitHub: https://github.com/XBraid/xbraid. SUNDIALS has been tested with XBraid version 3.0.0. To enable XBraid, set ENABLE_XBRAID to ON, set XBRAID_DIR to the root install location of XBraid or the location of the clone of the XBraid repository.

Note: At this time the XBraid types braid_Int and braid_Real are hard-coded to int and double respectively. As such SUNDIALS must be configured with SUNDIALS_INDEX_SIZE set to 32 and SUNDIALS_PRECISION set to double. Additionally, SUNDIALS must be configured with ENABLE_MPI set 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.

SUNDIALS shared libraries and header files
Shared Headers sundials/sundials_band.h
sundials/sundials_config.h
sundials/sundials_cuda_policies.hpp
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
sundials/sundials_xbraid.h
NVECTOR Modules
SERIAL Libraries libsundials_nvecserial.LIB
libsundials_fnvecserial.a
Headers nvector/nvector_serial.h
PARALLEL Libraries libsundials_nvecparallel.LIB
libsundials_fnvecparallel.a
Headers nvector/nvector_parallel.h
OPENMP Libraries libsundials_nvecopenmp.LIB
libsundials_fnvecopenmp.a
Headers nvector/nvector_openmp.h
PTHREADS Libraries libsundials_nvecpthreads.LIB
libsundials_fnvecpthreads.a
Headers nvector/nvector_pthreads.h
PARHYP Libraries libsundials_nvecparhyp.LIB
Headers nvector/nvector_parhyp.h
PETSC Libraries libsundials_nvecpetsc.LIB
Headers nvector/nvector_petsc.h
CUDA Libraries libsundials_nveccuda.LIB
Headers nvector/nvector_cuda.h
RAJA Libraries libsundials_nvecraja.LIB
Headers nvector/nvector_raja.h
MANYVECTOR Libraries libsundials_nvecmanyvector.LIB
Headers nvector/nvector_manyvector.h
MPIMANYVECTOR Libraries libsundials_nvecmpimanyvector.LIB
Headers nvector/nvector_mpimanyvector.h
MPIPLUSX Libraries libsundials_nvecmpiplusx.LIB
Headers nvector/nvector_mpiplusx.h
SUNMATRIX Modules
BAND Libraries libsundials_sunmatrixband.LIB
libsundials_fsunmatrixband.a
Headers sunmatrix/sunmatrix_band.h
DENSE Libraries libsundials_sunmatrixdense.LIB
libsundials_fsunmatrixdense.a
Headers sunmatrix/sunmatrix_dense.h
SPARSE Libraries libsundials_sunmatrixsparse.LIB
libsundials_fsunmatrixsparse.a
Headers sunmatrix/sunmatrix_sparse.h
SLUNRLOC Libraries libsundials_sunmatrixslunrloc.LIB
Headers sunmatrix/sunmatrix_slunrloc.h
CUSPARSE Libraries libsundials_sunmatrixcusparse.LIB
Headers sunmatrix/sunmatrix_cusparse.h
SUNLINSOL Modules
BAND Libraries libsundials_sunlinsolband.LIB
libsundials_fsunlinsolband.a
Headers sunlinsol/sunlinsol_band.h
DENSE Libraries libsundials_sunlinsoldense.LIB
libsundials_fsunlinsoldense.a
Headers sunlinsol/sunlinsol_dense.h
KLU Libraries libsundials_sunlinsolklu.LIB
libsundials_fsunlinsolklu.a
Headers sunlinsol/sunlinsol_klu.h
LAPACKBAND Libraries libsundials_sunlinsollapackband.LIB
libsundials_fsunlinsollapackband.a
Headers sunlinsol/sunlinsol_lapackband.h
LAPACKDENSE Libraries libsundials_sunlinsollapackdense.LIB
libsundials_fsunlinsollapackdense.a
Headers sunlinsol/sunlinsol_lapackdense.h
PCG Libraries libsundials_sunlinsolpcg.LIB
libsundials_fsunlinsolpcg.a
Headers sunlinsol/sunlinsol_pcg.h
SPBCGS Libraries libsundials_sunlinsolspbcgs.LIB
libsundials_fsunlinsolspbcgs.a
Headers sunlinsol/sunlinsol_spbcgs.h
SPFGMR Libraries libsundials_sunlinsolspfgmr.LIB
libsundials_fsunlinsolspfgmr.a
Headers sunlinsol/sunlinsol_spfgmr.h
SPGMR Libraries libsundials_sunlinsolspgmr.LIB
libsundials_fsunlinsolspgmr.a
Headers sunlinsol/sunlinsol_spgmr.h
SPTFQMR Libraries libsundials_sunlinsolsptfqmr.LIB
libsundials_fsunlinsolsptfqmr.a
Headers sunlinsol/sunlinsol_sptfqmr.h
SUPERLUMT Libraries libsundials_sunlinsolsuperlumt.LIB
libsundials_fsunlinsolsuperlumt.a
Headers sunlinsol/sunlinsol_superlumt.h
SUPERLUDIST Libraries libsundials_sunlinsolsuperludist.LIB
Headers sunlinsol/sunlinsol_superludist.h
CUSOLVERSP_BATCHQR Libraries libsundials_sunlinsolcusolversp.LIB
Headers sunlinsol/sunlinsol_cusolversp_batchqr.h
SUNNONLINSOL Modules
NEWTON Libraries libsundials_sunnonlinsolnewton.LIB
libsundials_fsunnonlinsolnewton.a
Headers sunnonlinsol/sunnonlinsol_newton.h
FIXEDPOINT Libraries libsundials_sunnonlinsolfixedpoint.LIB
libsundials_fsunnonlinsolfixedpoint.a
Headers sunnonlinsol/sunnonlinsol_fixedpoint.h
PETSCSNES Libraries libsundials_sunnonlinsolpetscsnes.LIB
Headers sunnonlinsol/sunnonlinsol_petscsnes.h
SUNDIALS Packages
CVODE Libraries libsundials_cvode.LIB
libsundials_fcvode.a
Headers 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
Headers 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
libsundials_xbraid.LIB
Headers 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
arkode/arkode_xbraid.h
IDA Libraries libsundials_ida.LIB
libsundials_fida.a
Headers 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
Headers 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
Headers kinsol/kinsol.h
kinsol/kinsol_bbdpre.h
kinsol/kinsol_direct.h
kinsol/kinsol_impl.h
kinsol/kinsol_ls.h
kinsol/kinsol_spils.h