From cc5e58c72392635b8dc4f2fa657a526b9b8fe185 Mon Sep 17 00:00:00 2001 From: David Gardner Date: Sat, 18 Jan 2025 09:19:50 -0800 Subject: [PATCH] Docs: cleanup install guide (#637) * Separate sections for installing with Spack and CMake * Co-locate Linux, Windows, and HPC install instructions in CMake section * Remove `ccmake` steps to focus on simpler `cmake` steps * Create subsections for related CMake options * Combine TPL sections with related TPL options * Add cross-references to corresponding TPL modules * Add configuration examples for all TPLs * Combine addons section with CMake option * Create subsections for table of headers and libraries * Add CMake targets to tables * Add missing headers and libraries * Remove deprecated headers * Remove duplicate text --------- Co-authored-by: Steven Roberts --- doc/cvode/guide/source/Usage/index.rst | 2 +- doc/shared/FAQ.rst | 12 +- doc/shared/nvectors/NVector_Kokkos.rst | 2 +- doc/shared/sundials/Install.rst | 4704 +++++++++++------ doc/shared/sundials/Types.rst | 4 +- doc/shared/sunlinsol/SUNLinSol_Ginkgo.rst | 2 +- doc/shared/sunlinsol/SUNLinSol_KLU.rst | 2 +- .../sunlinsol/SUNLinSol_KokkosDense.rst | 2 +- doc/shared/sunlinsol/SUNLinSol_LapackBand.rst | 2 +- .../sunlinsol/SUNLinSol_LapackDense.rst | 2 +- .../sunlinsol/SUNLinSol_SuperLUDIST.rst | 2 +- doc/shared/sunlinsol/SUNLinSol_SuperLUMT.rst | 2 +- doc/shared/sunmatrix/SUNMatrix_Ginkgo.rst | 2 +- .../sunmatrix/SUNMatrix_KokkosDense.rst | 2 +- .../sunnonlinsol/SUNNonlinSol_PetscSNES.rst | 2 +- 15 files changed, 3155 insertions(+), 1589 deletions(-) diff --git a/doc/cvode/guide/source/Usage/index.rst b/doc/cvode/guide/source/Usage/index.rst index 85704745a9..78ab24f720 100644 --- a/doc/cvode/guide/source/Usage/index.rst +++ b/doc/cvode/guide/source/Usage/index.rst @@ -1140,7 +1140,7 @@ Main solver optional input functions **Notes:** SUNDIALS must be compiled appropriately for specialized kernels to be available. The CMake option ``SUNDIALS_BUILD_PACKAGE_FUSED_KERNELS`` must be set to - ``ON`` when SUNDIALS is compiled. See the entry for this option in :numref:`Installation.CMake.options` for more information. + ``ON`` when SUNDIALS is compiled. See the entry for this option in :numref:`Installation.Options` for more information. Currently, the fused kernels are only supported when using CVODE with the :ref:`NVECTOR_CUDA ` and :ref:`NVECTOR_HIP ` implementations of the ``N_Vector``. .. _CVODE.Usage.CC.optional_input.optin_ls: diff --git a/doc/shared/FAQ.rst b/doc/shared/FAQ.rst index 09b824fb68..1191a07ae2 100644 --- a/doc/shared/FAQ.rst +++ b/doc/shared/FAQ.rst @@ -46,16 +46,18 @@ Installation .. collapse:: How do I install SUNDIALS on Windows systems? - One way of obtaining Windows libraries for the SUNDIALS solvers is to use cygwin - `cygwin `_, in which case the installation procedure is the same - as for any other Linux system. + One way of obtaining Windows libraries for the SUNDIALS solvers is to use + `cygwin `__, in which case the installation + procedure is the same as for any other Linux/Unix system (see the + :ref:`Installation.CMake.Unix` installation section). - Otherwise, refer to :ref:`Installation.CMake.Windows`. + Otherwise, refer to the :ref:`Installation.CMake.Windows` installation + section. .. collapse:: Everything installed fine! How do I link the SUNDIALS libraries to my own application? - Refer to :ref:`Installation.Results`. + Refer to :ref:`Installation.UsingSUNDIALS`. CVODE(S) / IDA(S) / ARKODE diff --git a/doc/shared/nvectors/NVector_Kokkos.rst b/doc/shared/nvectors/NVector_Kokkos.rst index 1879a7c130..28f4b37f61 100644 --- a/doc/shared/nvectors/NVector_Kokkos.rst +++ b/doc/shared/nvectors/NVector_Kokkos.rst @@ -24,7 +24,7 @@ variety of backends including serial, OpenMP, CUDA, HIP, and SYCL. Since Kokkos a modern C++ library, the module is also written in modern C++ (it requires C++14) as a header only library. To utilize this ``N_Vector`` users will need to include ``nvector/nvector_kokkos.hpp``. More instructions on building SUNDIALS -with Kokkos enabled are given in :numref:`Installation.CMake.ExternalLibraries`. +with Kokkos enabled are given in :numref:`Installation.Options.Kokkos`. For instructions on building and using Kokkos, refer to the `Kokkos `_ documentation. diff --git a/doc/shared/sundials/Install.rst b/doc/shared/sundials/Install.rst index a478507be1..77b2109dc3 100644 --- a/doc/shared/sundials/Install.rst +++ b/doc/shared/sundials/Install.rst @@ -14,2293 +14,3857 @@ .. _Installation: -Acquiring SUNDIALS -================== +Installing SUNDIALS +=================== -There are two supported ways for building and installing SUNDIALS from -source. One option is to use the `Spack HPC package manager `_: +In this chapter we discuss two ways for building and installing SUNDIALS from +source. The first is with the `Spack `__ HPC package manager +and the second is with `CMake `__. -.. code-block:: bash +.. _Installation.Spack: - spack install sundials +Installing with Spack +--------------------- -The second supported option for building and installing SUNDIALS is with CMake. -Before proceeding with CMake, the source code must be downloaded. This can be done -by cloning the `SUNDIALS GitHub repository `_ -(run ``git clone https://github.com/LLNL/sundials``), or by downloading the -SUNDIALS release compressed archives (``.tar.gz``) from the SUNDIALS -`website `_. +Spack is a package management tool that provides a simple spec syntax to +configure and install software on a wide variety of platforms and environments. +See the `Getting Started +`__ section in the +Spack documentation for more information on installing Spack. -The compressed archives allow for downloading of individual SUNDIALS packages. -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). After downloading the relevant archives, uncompress and expand the sources, -by running +Once Spack is setup on your system, the default SUNDIALS configuration can be +install with the command .. code-block:: bash - % 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 begin 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/lib``, with ``INSTDIR`` 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``. + spack install sundials -#. 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 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.) +Additional options can be enabled through various Spack package variants. For +information on the available variants visit the `SUNDIALS Spack package +`__ web page or use the +command -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 :numref:`Installation.CMake` -and :numref:`Installation.Results`. +.. code-block:: bash + spack info sundials .. _Installation.CMake: -Building and Installing with CMake -================================== - -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.18.0 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. -CMake adds new features regularly, 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. - - -.. index:: ccmake - -.. _Installation.CMake.Unix: - -Configuring, building, and installing on Unix-like systems ----------------------------------------------------------------- +Installing with CMake +--------------------- -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 provides a platform-independent build system capable of generating Unix +and Linux Makefiles, as well as KDevelop, Visual Studio, and (Apple) XCode +project files from the same configuration file. A GUI front end is also +available allowing for an interactive build and installation process. -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: +At a minimum, building SUNDIALS requires CMake version 3.18.0 or higher and a +working C compiler. If a compatible version of CMake is not already installed on +you system, source files or pre-built binary files can be obtained from the +`CMake Download website `__. +When building with CMake, you will need to obtain the SUNDIALS source code. You +can get the source files by either cloning the `SUNDIALS GitHub repository +`__ with the command .. code-block:: bash - $ mkdir (...)/INSTDIR - $ mkdir (...)/BUILDDIR - $ cd (...)/BUILDDIR - - -.. index:: cmake-gui -.. index:: ccmake - - -Building with the GUI -^^^^^^^^^^^^^^^^^^^^^^^ - -Using CMake with the ``ccmake`` GUI follows the general process: + git clone https://github.com/LLNL/sundials -#. Select and modify values, run configure (``c`` key) - -#. New values are denoted with an asterisk +or by downloading release compressed archives (``.tar.gz`` files) from the +`SUNDIALS download website +`__. The +compressed archives allow for downloading the entire SUNDIALS suite or +individual packages. 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 +package. After downloading the relevant archives, uncompress and expand the +sources. For example, by running -#. To set a variable, move the cursor to the variable and press enter +.. code-block:: bash - * If it is a boolean (ON/OFF) it will toggle the value + tar -zxf SOLVER-x.y.z.tar.gz - * If it is string or file, it will allow editing of the string +the extracted source files will be under the ``SOLVER-x.y.z`` directory. - * For file and directories, the ```` key can be used to complete +In the installation steps below we will refer to the following directories: -#. Repeat until all values are set as desired and the generate option - is available (``g`` key) +* ``SOLVER_DIR`` is the ``sundials`` directory created when cloning from GitHub + or the ``SOLVER-x.y.z`` directory created after uncompressing the release + archive. -#. Some variables (advanced variables) are not visible right away; to - see advanced variables, toggle to advanced mode (``t`` key) +* ``BUILD_DIR`` is the (temporary) directory under which SUNDIALS is built. + In-source builds are prohibited; the build directory ``BUILD_DIR`` can **not** + be the same as ``SOLVER_DIR`` and such an attempt will lead to an error. This + prevents "polluting" the source tree, simplifies building with different + configurations and/or options, and makes it easy to clean-up all traces of the + build by simply removing the build directory. -#. To search for a variable press the ``/`` key, and to repeat the search, - press the ``n`` key +* ``INSTALL_DIR`` is the directory under which the SUNDIALS exported header + files and libraries will be installed. The installation directory + ``INSTALL_DIR`` can not be the same as the ``SOLVER_DIR`` directory. + Typically, header files are exported under a directory ``INSTALL_DIR/include`` + while libraries are typically installed under ``INSTALL_DIR/lib`` or + ``INSTALL_LIB/lib64``, with ``INSTALL_DIR`` specified at configuration time. -Using CMake with the ``cmake-gui`` GUI follows a similar process: +.. _Installation.CMake.Unix: -#. Select and modify values, click ``Configure`` +Linux/Unix systems +^^^^^^^^^^^^^^^^^^ -#. The first time you click ``Configure``, make sure to pick the - appropriate generator (the following will assume generation of Unix - Makefiles). +CMake can be used from the command line with the ``cmake`` command, or from +graphical interfaces with the ``ccmake`` or ``cmake-gui`` commands. Below we +present the installation steps using the command line interface. -#. New values are highlighted in red +Using CMake from the command line is simply a matter of generating the build +files for the desired configuration, building, and installing. For example, the +following commands will build and install the default configuration: -#. To set a variable, click on or move the cursor to the variable and press - enter +.. code-block:: bash - * If it is a boolean (``ON/OFF``) it will check/uncheck the box + cmake \ + -S SOLVER_DIR \ + -B BUILD_DIR \ + -D CMAKE_INSTALL_PREFIX=INSTALL_DIR + cd BUILD_DIR + make + make install - * 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. +The default configuration will install static and shared libraries for all +SUNDIALS packages and install the associated example codes. Additional features +can be enabled by specifying more options in the configuration step. For +example, to enable MPI add ``-D ENABLE_MPI=ON`` to the ``cmake`` command above: - * For files and directories, the ```` key can be used to - complete +.. code-block:: bash -#. Repeat until all values are set as desired and click the - ``Generate`` button + cmake \ + -S SOLVER_DIR \ + -B BUILD_DIR \ + -D CMAKE_INSTALL_PREFIX=INSTALL_DIR \ + -D ENABLE_MPI=ON -#. Some variables (advanced variables) are not visible right away; to see - advanced variables, click the ``advanced`` button +See section :numref:`Installation.Options` below for a complete list of SUNDIALS +configuration options and additional configuration examples. +.. _Installation.CMake.Windows: -To build the default configuration using the curses GUI, from the ``BUILDDIR`` -enter the ``ccmake`` command and point to the ``SOLVERDIR``: +Windows Systems +^^^^^^^^^^^^^^^ -.. code-block:: bash +CMake can also be used to build SUNDIALS on Windows. To build SUNDIALS for use +with Visual Studio the following steps should be performed: - $ ccmake (...)/SOLVERDIR +#. Create a separate ``BUILD_DIR`` -Similarly, to build the default configuration using the wxWidgets GUI, from the -``BUILDDIR`` enter the ``cmake-gui`` command and point to the ``SOLVERDIR``: +#. Open a Visual Studio Command Prompt and cd to ``BUILD_DIR`` -.. code-block:: bash +#. Run ``cmake-gui ../SOLVER_DIR`` - $ cmake-gui (...)/SOLVERDIR + a. Hit Configure -The default curses configuration screen is shown in the following figure. + b. Check/Uncheck solvers to be built -.. _ccmakedefault: + c. Change ``CMAKE_INSTALL_PREFIX`` to ``INSTALL_DIR`` -.. figure:: /figs/cmake/ccmakedefault.png - :align: center + d. Set other options as desired (see section :numref:`Installation.Options`) - 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. + e. Hit Generate -The default INSTDIR for both SUNDIALS and the corresponding examples can be changed -by setting the ``CMAKE_INSTALL_PREFIX`` and the ``EXAMPLES_INSTALL_PATH`` as -shown in the following figure. +#. Back in the VS Command Window: -.. _ccmakeprefix: + a. Run ``msbuild ALL_BUILD.vcxproj`` -.. figure:: /figs/cmake/ccmakeprefix.png - :align: center + b. Run ``msbuild INSTALL.vcxproj`` - Changing the INSTDIR for SUNDIALS and corresponding EXAMPLES. +The resulting libraries will be in the ``INSTALL_DIR``. +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. -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: +.. _Installation.CMake.HPC: -.. code-block:: bash +HPC Clusters +^^^^^^^^^^^^ - $ make +This section is a guide for installing SUNDIALS on specific HPC clusters. In +general, the procedure is the same as described previously in +:numref:`Installation.CMake.Unix` for Unix/Linux machines. The main differences +are in the modules and environment variables that are specific to different HPC +clusters. We aim to keep this section as up to date as possible, but it may lag +the latest software updates to each cluster. -or for a faster parallel build (e.g. using 4 threads), you can run +Frontier +"""""""" -.. code-block:: bash +`Frontier `__ is an Exascale supercomputer +at the Oak Ridge Leadership Computing Facility. If you are new to this system, +then we recommend that you review the `Frontier user guide +`__. - $ make -j 4 +**A Standard Installation** -To install SUNDIALS in the installation directory specified in the -configuration, simply run: +Load the modules and set the environment variables needed to build SUNDIALS. +This configuration enables both MPI and HIP support for distributed and GPU +parallelism. It uses the HIP compiler for C and C++ and the Cray Fortran +compiler. Other configurations are possible. .. code-block:: bash - $ make install - - - - + # required dependencies + module load PrgEnv-cray-amd/8.5.0 + module load craype-accel-amd-gfx90a + module load rocm/5.3.0 + module load cmake/3.23.2 -.. index:: cmake + # GPU-aware MPI + export MPICH_GPU_SUPPORT_ENABLED=1 -Building from the command line -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + # compiler environment hints + export CC=$(which hipcc) + export CXX=$(which hipcc) + export FC=$(which ftn) + export CFLAGS="-I${ROCM_PATH}/include" + export CXXFLAGS="-I${ROCM_PATH}/include -Wno-pass-failed" + export LDFLAGS="-L${ROCM_PATH}/lib -lamdhip64 ${PE_MPICH_GTL_DIR_amd_gfx90a} -lmpi_gtl_hsa" -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: +Now we can build SUNDIALS. In general, this is the same procedure described in +the previous sections. The following command builds and installs SUNDIALS with +MPI, HIP, and the Fortran interface enabled, where ```` is your +allocation account on Frontier: .. code-block:: bash - $ cmake -DCMAKE_INSTALL_PREFIX=/home/myname/sundials/instdir \ - > -DEXAMPLES_INSTALL_PATH=/home/myname/sundials/instdir/examples \ - > ../srcdir - $ make - $ make install - - -.. _Installation.CMake.Options: + cmake \ + -S SOLVER_DIR \ + -B BUILD_DIR \ + -D CMAKE_INSTALL_PREFIX=INSTALL_DIR \ + -D AMDGPU_TARGETS=gfx90a \ + -D ENABLE_HIP=ON \ + -D ENABLE_MPI=ON \ + -D BUILD_FORTRAN_MODULE_INTERFACE=ON + cd BUILD_DIR + make -j8 install + # Need an allocation to run the tests: + salloc -A -t 10 -N 1 -p batch + make test + make test_install_all +.. _Installation.Options: Configuration options --------------------- -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. - -.. cmakeoption:: BUILD_ARKODE +All available SUNDIALS CMake options are described in the sections below. The +default values for some options (e.g., compiler flags and installation paths) +are for a Linux system and are provided as illustration only. - Build the ARKODE library +.. note:: - Default: ``ON`` + When using a CMake graphical interface (`ccmake` or `cmake-gui`), multiple + configuration passes are performed before generating the build files. For + options where the default value depends on the value of another option, the + initial value is set on the first configuration pass and is not updated + automatically if the related option value is changed in subsequent + passes. For example, the default value of :cmakeop:`EXAMPLES_INSTALL_PATH` is + ``CMAKE_INSTALL_PREFIX/examples``; if the value of + :cmakeop:`CMAKE_INSTALL_PREFIX` is updated, then + :cmakeop:`EXAMPLES_INSTALL_PATH` will also need to be updated as its value + was set using the :cmakeop:`CMAKE_INSTALL_PREFIX` default. -.. cmakeoption:: BUILD_CVODE +.. _Installation.Options.BuildType: - Build the CVODE library +Build Type +^^^^^^^^^^ - Default: ``ON`` +The build type determines the level of compiler optimization, if debug +information is included, and if additional error checking code is generated. The +provided build types are: -.. cmakeoption:: BUILD_CVODES +* ``Debug`` -- no optimization flags, debugging information included, additional + error checking enabled - Build the CVODES library +* ``Release`` -- high optimization flags, no debugging information, no + additional error checks - Default: ``ON`` +* ``RelWithDebInfo`` -- high optimization flags, debugging information included, + no additional error checks -.. cmakeoption:: BUILD_IDA +* ``MinSizeRel`` -- minimize size flags, no debugging information, no additional + error checks - Build the IDA library +Each build type has a corresponding option for the set of compiler flags that +are appended to the user-specified compiler flags. See section +:numref:`Installation.Options.Compilers` for more information. - Default: ``ON`` +.. cmakeoption:: CMAKE_BUILD_TYPE -.. cmakeoption:: BUILD_IDAS + Choose the type of build for single-configuration generators (e.g., Makefiles + or Ninja). - Build the IDAS library + Default: ``RelWithDebInfo`` - Default: ``ON`` +.. cmakeoption:: CMAKE_CONFIGURATION_TYPES -.. cmakeoption:: BUILD_KINSOL + Specifies the build types for multi-config generators (e.g. Visual Studio, + Xcode, or Ninja Multi-Config) as a semicolon-separated list. - Build the KINSOL library + Default: ``Debug``, ``Release``, ``RelWithDebInfo``, and ``MinSizeRel`` - Default: ``ON`` +.. _Installation.Options.Compilers: -.. cmakeoption:: BUILD_SHARED_LIBS +Compilers and Compiler Flags +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - Build shared libraries +Building SUNDIALS requires a C compiler that supports at least a subset of the +C99 standard (specifically those features implemented by Visual Studio 2015). - Default: ``ON`` +Additional SUNDIALS features that interface with external C++ libraries or GPU +programming models require a C++ compiler (e.g., CUDA, HIP, SYCL, Ginkgo, +Trilinos, etc.). The C++ standard required depends on the particular library or +programming model used and is noted with the relevant options below. The C++ +convenience classes provided by SUNDIALS require C++14 or newer. C++ +applications that require an earlier C++ standard should use the SUNDIALS C API. -.. cmakeoption:: BUILD_STATIC_LIBS +When enabling the SUNDIALS Fortran interfaces, a Fortran compiler that supports +the Fortran 2003 or newer standard is required in order to utilize the +``ISO_C_BINDING`` module. - Build static libraries +C Compiler +"""""""""" - Default: ``ON`` +.. cmakeoption:: CMAKE_C_COMPILER -.. cmakeoption:: CMAKE_BUILD_TYPE + The full path to the C compiler - Choose the type of build, options are: - ``Debug``, ``Release``, ``RelWithDebInfo``, and ``MinSizeRel`` + Default: CMake will attempt to automatically locate a C compiler on the + system (e.g., from the ``CC`` environment variable or common installation + paths). - Default: ``RelWithDebInfo`` +.. cmakeoption:: CMAKE_C_FLAGS - .. note:: + User-specified flags for the C compiler. The value of this option should be a + string with flags separated by spaces. - 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``. + Default: Initialized by the ``CFLAGS`` environment variable. -.. cmakeoption:: CMAKE_C_COMPILER +.. cmakeoption:: CMAKE_C_FLAGS_DEBUG - C compiler + C compiler flags appended when the :cmakeop:`CMAKE_BUILD_TYPE` is ``Debug`` - Default: ``/usr/bin/cc`` + Default: ``-g`` -.. cmakeoption:: CMAKE_C_FLAGS +.. cmakeoption:: CMAKE_C_FLAGS_RELEASE - Flags for C compiler + C compiler flags appended when the :cmakeop:`CMAKE_BUILD_TYPE` is ``Release`` - Default: + Default: ``-O3 -DNDEBUG`` -.. cmakeoption:: CMAKE_C_FLAGS_DEBUG +.. cmakeoption:: CMAKE_C_FLAGS_RELWITHDEBINFO - Flags used by the C compiler during debug builds + C compiler flags appended when the :cmakeop:`CMAKE_BUILD_TYPE` is + ``RelWithDebInfo`` - Default: ``-g`` + Default: ``-O2 -g -DNDEBUG`` .. cmakeoption:: CMAKE_C_FLAGS_MINSIZEREL - Flags used by the C compiler during release minsize builds + C compiler flags appended when the :cmakeop:`CMAKE_BUILD_TYPE` is + ``MinSizeRel`` Default: ``-Os -DNDEBUG`` -.. cmakeoption:: CMAKE_C_FLAGS_RELEASE - - Flags used by the C compiler during release builds - - Default: ``-O3 -DNDEBUG`` - .. cmakeoption:: CMAKE_C_STANDARD - The C standard to build C parts of SUNDIALS with. + The C standard used when building SUNDIALS C source files. - Default: 99 + Default: ``99`` - Options: 99, 11, 17. + Options: ``99``, ``11``, or ``17`` .. cmakeoption:: CMAKE_C_EXTENSIONS Enable compiler specific C extensions. - Default: ``OFF`` - -.. cmakeoption:: CMAKE_CXX_COMPILER - - C++ compiler + Default: ``ON`` - Default: ``/usr/bin/c++`` +C++ Compiler +"""""""""""" - .. note:: +.. cmakeoption:: CMAKE_CXX_COMPILER - A C++ compiler is only required when a feature requiring C++ is enabled - (e.g., CUDA, HIP, SYCL, RAJA, etc.) or the C++ examples are enabled. + The full path to the C++ compiler - All SUNDIALS solvers can be used from C++ applications without setting - any additional configuration options. + Default: CMake will attempt to automatically locate a C++ compiler on the + system (e.g., from the ``CXX`` environment variable or common installation + paths). .. cmakeoption:: CMAKE_CXX_FLAGS - Flags for C++ compiler + User-specified flags for the C++ compiler. The value of this option should be + a string with flags separated by spaces. - Default: + Default: Initialized by the ``CXXFLAGS`` environment variable. .. cmakeoption:: CMAKE_CXX_FLAGS_DEBUG - Flags used by the C++ compiler during debug builds + C++ compiler flags appended when the :cmakeop:`CMAKE_BUILD_TYPE` is ``Debug`` Default: ``-g`` -.. cmakeoption:: CMAKE_CXX_FLAGS_MINSIZEREL +.. cmakeoption:: CMAKE_CXX_FLAGS_RELEASE - Flags used by the C++ compiler during release minsize builds + C++ compiler flags appended when the :cmakeop:`CMAKE_BUILD_TYPE` is + ``Release`` - Default: ``-Os -DNDEBUG`` + Default: ``-O3 -DNDEBUG`` -.. cmakeoption:: CMAKE_CXX_FLAGS_RELEASE +.. cmakeoption:: CMAKE_CXX_FLAGS_RELWITHDEBINFO - Flags used by the C++ compiler during release builds + C++ compiler flags appended when the :cmakeop:`CMAKE_BUILD_TYPE` is + ``RelWithDebInfo`` - Default: ``-O3 -DNDEBUG`` + Default: ``-O2 -g -DNDEBUG`` + +.. cmakeoption:: CMAKE_CXX_FLAGS_MINSIZEREL + + C++ compiler flags appended when the :cmakeop:`CMAKE_BUILD_TYPE` is + ``MinSizeRel`` + + Default: ``-Os -DNDEBUG`` .. cmakeoption:: CMAKE_CXX_STANDARD - The C++ standard to build C++ parts of SUNDIALS with. + The C++ standard used when building SUNDIALS C++ source files. - Default: 11 + Default: ``14`` - Options: 98, 11, 14, 17, 20. + Options: ``14``, ``17``, or ``20`` .. cmakeoption:: CMAKE_CXX_EXTENSIONS Enable compiler specific C++ extensions. - Default: ``OFF`` - -.. cmakeoption:: CMAKE_Fortran_COMPILER + Default: ``ON`` - Fortran compiler +Fortran Compiler +"""""""""""""""" - Default: ``/usr/bin/gfortran`` +.. cmakeoption:: CMAKE_Fortran_COMPILER - .. note:: + The full path to the Fortran compiler - Fortran support (and all related options) are triggered only if - either Fortran-C support (``BUILD_FORTRAN_MODULE_INTERFACE``) or - LAPACK (``ENABLE_LAPACK``) support is enabled. + Default: CMake will attempt to automatically locate a Fortran compiler on the + system (e.g., from the ``FC`` environment variable or common installation + paths). .. cmakeoption:: CMAKE_Fortran_FLAGS - Flags for Fortran compiler + User-specified flags for the Fortran compiler. The value of this option + should be a string with flags separated by spaces. - Default: + Default: Initialized by the ``FFLAGS`` environment variable. .. cmakeoption:: CMAKE_Fortran_FLAGS_DEBUG - Flags used by the Fortran compiler during debug builds + Fortran compiler flags appended when the :cmakeop:`CMAKE_BUILD_TYPE` is + ``Debug`` Default: ``-g`` -.. cmakeoption:: CMAKE_Fortran_FLAGS_MINSIZEREL +.. cmakeoption:: CMAKE_Fortran_FLAGS_RELEASE - Flags used by the Fortran compiler during release minsize builds + Fortran compiler flags appended when the :cmakeop:`CMAKE_BUILD_TYPE` is + ``Release`` - Default: ``-Os`` + Default: ``-O3`` -.. cmakeoption:: CMAKE_Fortran_FLAGS_RELEASE +.. cmakeoption:: CMAKE_Fortran_FLAGS_RELWITHDEBINFO - Flags used by the Fortran compiler during release builds + Fortran compiler flags appended when the :cmakeop:`CMAKE_BUILD_TYPE` is + ``RelWithDebInfo`` - Default: ``-O3`` + Default: ``-O2 -g`` -.. cmakeoption:: CMAKE_INSTALL_LIBDIR +.. cmakeoption:: CMAKE_Fortran_FLAGS_MINSIZEREL - The directory under which libraries will be installed. + C++ compiler flags appended when the :cmakeop:`CMAKE_BUILD_TYPE` is + ``MinSizeRel`` - Default: Set based on the system: ``lib``, ``lib64``, or - ``lib/`` + Default: ``-Os`` + +.. _Installation.Options.InstallLocation: + +Install Location +^^^^^^^^^^^^^^^^ + +Use the following options to set where the SUNDIALS headers, library, and CMake +configuration files will be installed. .. cmakeoption:: CMAKE_INSTALL_PREFIX - Install path prefix, prepended onto install directories + Install path prefix (``INSTALL_DIR``), 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. -.. cmakeoption:: ENABLE_CUDA + 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 :cmakeop:`CMAKE_INSTALL_LIBDIR` of + :cmakeop:`CMAKE_INSTALL_PREFIX`, respectively. - Build the SUNDIALS CUDA modules. +.. cmakeoption:: CMAKE_INSTALL_LIBDIR - Default: ``OFF`` + The directory under :cmakeop:`CMAKE_INSTALL_PREFIX` where libraries will be + installed -.. cmakeoption:: CMAKE_CUDA_ARCHITECTURES + Default: Set based on the system as ``lib``, ``lib64``, or + ``lib/`` - Specifies the CUDA architecture to compile for i.e., ``60`` for Pascal, - ``70`` Volta, ``80`` for Ampere, ``90`` for Hopper, etc. See the `GPU compute - capability tables `_ on the NVIDIA - webpage and the `GPU Compilation `_ - section of the CUDA documentation for more information. +.. cmakeoption:: SUNDIALS_INSTALL_CMAKEDIR - Default: Determined automatically by CMake. Users are encouraged to override - this value with the architecture for their system as the default varies - across compilers and compiler versions. + The directory under :cmakeop:`CMAKE_INSTALL_PREFIX` where the SUNDIALS CMake + package configuration files will be installed (see section + :numref:`Installation.CMakeConfigFile` for more information) - .. versionchanged:: 7.2.0 + Default: ``CMAKE_INSTALL_LIBDIR/cmake/sundials`` - In prior versions ``CMAKE_CUDA_ARCHITECTURES`` defaulted to ``70``. +.. _Installation.Options.LibraryTypes: -.. cmakeoption:: EXAMPLES_ENABLE_C +Shared and Static Libraries +^^^^^^^^^^^^^^^^^^^^^^^^^^^ - Build the SUNDIALS C examples +Use the following options to set which types of libraries will be installed. By +default both static and shared libraries are installed. - Default: ``ON`` +.. cmakeoption:: BUILD_SHARED_LIBS -.. cmakeoption:: EXAMPLES_ENABLE_CXX + Build shared libraries - Build the SUNDIALS C++ examples + Default: ``ON`` - Default: ``OFF`` +.. cmakeoption:: BUILD_STATIC_LIBS -.. cmakeoption:: EXAMPLES_ENABLE_CUDA + Build static libraries - Build the SUNDIALS CUDA examples + Default: ``ON`` - Default: ``OFF`` +.. _Installation.Options.IndexSize: - .. note:: You need to enable CUDA support to build these examples. +Index Size +^^^^^^^^^^ -.. cmakeoption:: EXAMPLES_ENABLE_F2003 +.. cmakeoption:: SUNDIALS_INDEX_SIZE - Build the SUNDIALS Fortran2003 examples + The integer size (in bits) used for indices in SUNDIALS (e.g., for vector and + matrix entries), options are: ``32`` or ``64`` - Default: ``ON`` (if ``BUILD_FORTRAN_MODULE_INTERFACE`` is ``ON``) + Default: ``64`` -.. cmakeoption:: EXAMPLES_INSTALL + .. note:: - Install example files + The build system tries to find an integer type of the 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, :cmakeop:`SUNDIALS_INDEX_TYPE` can be used to provide + a type not listed here. - Default: ``ON`` +.. cmakeoption:: SUNDIALS_INDEX_TYPE - .. 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``. + The integer type used for SUNDIALS indices. The type size must match the size + provided in the :cmakeop:`SUNDIALS_INDEX_SIZE` option. -.. cmakeoption:: EXAMPLES_INSTALL_PATH + Default: Automatically determined based on :cmakeop:`SUNDIALS_INDEX_SIZE` - Output directory for installing example - files + .. versionchanged:: 3.2.0 - Default: ``/usr/local/examples`` + In prior versions, this option could be set to ``INT64_T`` to use 64-bit + integers or ``INT32_T`` to use 32-bit integers. These special values are + deprecated and a user will only need to use the + :cmakeop:`SUNDIALS_INDEX_SIZE` option in most cases. - .. note:: The actual default value for this option will be an - ``examples`` subdirectory created under ``CMAKE_INSTALL_PREFIX``. +.. _Installation.Options.Precision: -.. cmakeoption:: BUILD_FORTRAN_MODULE_INTERFACE +Precision +^^^^^^^^^ - Enable Fortran 2003 interface +.. cmakeoption:: SUNDIALS_PRECISION - Default: ``OFF`` + The floating-point precision used in SUNDIALS packages and class + implementations, options are: ``single``, ``double``, or ``extended`` - .. warning:: There is a known issue with MSYS/gfortran and SUNDIALS shared libraries - that causes linking the Fortran interfaces to fail when building SUNDIALS. For - now the work around is to only build with static libraries when using MSYS with - gfortran on Windows. + Default: ``double`` -.. cmakeoption:: SUNDIALS_LOGGING_LEVEL +.. _Installation.Options.MathLibrary: - Set the maximum logging level for the SUNLogger runtime API. The higher this is set, - the more output that may be logged, and the more performance may degrade. The options are: +Math Library +^^^^^^^^^^^^ - - ``0`` -- no logging - - ``1`` -- log errors - - ``2`` -- log errors + warnings - - ``3`` -- log errors + warnings + informational output - - ``4`` -- log errors + warnings + informational output + debug output - - ``5`` -- log all of the above and even more (e.g. vector valued variables may be logged) +.. cmakeoption:: SUNDIALS_MATH_LIBRARY - Default: 2 + The standard C math library (e.g., ``libm``) to link with. + Default: ``-lm`` on Unix systems, none otherwise -.. cmakeoption:: SUNDIALS_BUILD_WITH_MONITORING +.. _Installation.Options.Packages: - Build SUNDIALS with capabilities for fine-grained monitoring of solver progress - and statistics. This is primarily useful for debugging. +SUNDIALS Packages +^^^^^^^^^^^^^^^^^ - Default: OFF +The following options can be used to enable/disable particular SUNDIALS +packages. - .. warning:: +.. cmakeoption:: BUILD_ARKODE - Building with monitoring may result in minor performance degradation even - if monitoring is not utilized. + Build the ARKODE library -.. cmakeoption:: SUNDIALS_BUILD_WITH_PROFILING + Default: ``ON`` - Build SUNDIALS with capabilities for fine-grained profiling. - This requires POSIX timers or the Windows ``profileapi.h`` timers. +.. cmakeoption:: BUILD_CVODE - Default: OFF + Build the CVODE library - .. warning:: + Default: ``ON`` - Profiling will impact performance, and should be enabled judiciously. +.. cmakeoption:: BUILD_CVODES -.. cmakeoption:: SUNDIALS_ENABLE_ERROR_CHECKS + Build the CVODES library - Build SUNDIALS with more extensive checks for unrecoverable errors. + Default: ``ON`` - Default: ``OFF`` when ``CMAKE_BUILD_TYPE=Release|RelWithDebInfo `` and ``ON`` otherwise. +.. cmakeoption:: BUILD_IDA - .. warning:: + Build the IDA library - Error checks will impact performance, but can be helpful for debugging. + Default: ``ON`` +.. cmakeoption:: BUILD_IDAS -.. cmakeoption:: SUNDIALS_ENABLE_EXTERNAL_ADDONS + Build the IDAS library - Build SUNDIALS with any external addons that you have put in ``sundials/external``. + Default: ``ON`` - Default: ``OFF`` +.. cmakeoption:: BUILD_KINSOL - .. warning:: + Build the KINSOL library - Addons are not maintained by the SUNDIALS team. Use at your own risk. + Default: ``ON`` +.. _Installation.Options.Examples: -.. cmakeoption:: ENABLE_GINKGO +Example Programs +^^^^^^^^^^^^^^^^ - Enable interfaces to the Ginkgo linear algebra library. +.. cmakeoption:: EXAMPLES_ENABLE_C - Default: ``OFF`` + Build the SUNDIALS C examples -.. cmakeoption:: Ginkgo_DIR + Default: ``ON`` - Path to the Ginkgo installation. +.. cmakeoption:: EXAMPLES_ENABLE_CXX - Default: None + Build the SUNDIALS C++ examples -.. cmakeoption:: SUNDIALS_GINKGO_BACKENDS + Default: ``OFF`` - Semi-colon separated list of Ginkgo target architectures/executors to build for. - Options currently supported are REF (the Ginkgo reference executor), OMP, CUDA, HIP, and SYCL. - - Default: "REF;OMP" +.. cmakeoption:: EXAMPLES_ENABLE_CUDA - .. versionchanged:: 7.1.0 + Build the SUNDIALS CUDA examples - The ``DPCPP`` option was changed to ``SYCL`` to align with Ginkgo's naming convention. + Default: ``ON`` when :cmakeop:`ENABLE_CUDA` is ``ON``, otherwise ``OFF`` -.. cmakeoption:: ENABLE_KOKKOS +.. cmakeoption:: EXAMPLES_ENABLE_F2003 - Enable the Kokkos based vector. + Build the SUNDIALS Fortran 2003 examples - Default: ``OFF`` + Default: ``ON`` when :cmakeop:`BUILD_FORTRAN_MODULE_INTERFACE` is ``ON``, + otherwise ``OFF`` -.. cmakeoption:: Kokkos_DIR +.. cmakeoption:: EXAMPLES_INSTALL - Path to the Kokkos installation. + Install example program source files and sample output files. See + :cmakeop:`EXAMPLES_INSTALL_PATH` for the install location. - Default: None + A ``CMakeLists.txt`` file to build the examples will be automatically + generated and installed with the source files. If building on a Unix-like + system, a ``Makefile`` for compiling the installed example programs will be + also generated and installed. -.. cmakeoption:: ENABLE_KOKKOS_KERNELS + Default: ``ON`` - Enable the Kokkos based dense matrix and linear solver. +.. cmakeoption:: EXAMPLES_INSTALL_PATH - Default: ``OFF`` + Full path to where example source and output files will be installed -.. cmakeoption:: KokkosKernels_DIR + Default: ``CMAKE_INSTALL_PREFIX/examples`` - Path to the Kokkos-Kernels installation. +.. _Installation.Options.Fortran: - Default: None +Fortran Interfaces +^^^^^^^^^^^^^^^^^^ -.. cmakeoption:: ENABLE_HIP +.. cmakeoption:: BUILD_FORTRAN_MODULE_INTERFACE - Enable HIP Support + Build the SUNDIALS Fortran 2003 interface Default: ``OFF`` -.. cmakeoption:: AMDGPU_TARGETS + .. note:: - Specify which AMDGPU processor(s) to target. + The Fortran interface are only compatible with double precision (i.e., + :cmakeop:`SUNDIALS_PRECISION` must be ``double``). - Default: None + .. warning:: -.. cmakeoption:: ENABLE_HYPRE + There is a known issue with MSYS/gfortran and SUNDIALS shared libraries + that causes linking the Fortran interfaces to fail when building + SUNDIALS. For now the work around is to only build with static libraries + when using MSYS with gfortran on Windows. - Flag to enable *hypre* support +.. _Installation.Options.ErrorChecking: - Default: ``OFF`` +Error Checking +^^^^^^^^^^^^^^ - .. note:: See additional information on building with *hypre* - enabled in :numref:`Installation.CMake.ExternalLibraries`. +For more information on error handling in SUNDIALS, see +:ref:`SUNDIALS.Errors`. -.. cmakeoption:: HYPRE_INCLUDE_DIR +.. cmakeoption:: SUNDIALS_ENABLE_ERROR_CHECKS - Path to *hypre* header files + Build SUNDIALS with more extensive checks for unrecoverable errors. - Default: none + Default: ``ON`` when :cmakeop:`CMAKE_BUILD_TYPE` is ``Debug``, otherwise + ``OFF`` -.. cmakeoption:: HYPRE_LIBRARY + .. warning:: - Path to *hypre* installed library files + Error checks will impact performance, but can be helpful for debugging. - Default: none +.. _Installation.Options.Logging: -.. cmakeoption:: ENABLE_KLU +Logging +^^^^^^^ - Enable KLU support +For more information on logging in SUNDIALS, see :ref:`SUNDIALS.Logging`. - Default: ``OFF`` +.. cmakeoption:: SUNDIALS_LOGGING_LEVEL - .. note:: See additional information on building with KLU - enabled in :numref:`Installation.CMake.ExternalLibraries`. + The maximum logging level. The options are: -.. cmakeoption:: KLU_INCLUDE_DIR + * ``0`` -- no logging + * ``1`` -- log errors + * ``2`` -- log errors + warnings + * ``3`` -- log errors + warnings + informational output + * ``4`` -- log errors + warnings + informational output + debug output + * ``5`` -- log all of the above and even more (e.g. vector valued variables may be logged) - Path to SuiteSparse header files + Default: ``2`` - Default: none + .. warning:: -.. cmakeoption:: KLU_LIBRARY_DIR + Logging will impact performance, but can be helpful for debugging or + understanding algorithm performance. The higher the logging level, the + more output that may be logged, and the more performance may degrade. - Path to SuiteSparse installed library files +.. _Installation.Options.Monitoring: - Default: none +Monitoring +^^^^^^^^^^ -.. cmakeoption:: ENABLE_LAPACK +.. cmakeoption:: SUNDIALS_BUILD_WITH_MONITORING - Enable LAPACK support + Build SUNDIALS with capabilities for fine-grained monitoring of solver + progress and statistics. This is primarily useful for debugging. Default: ``OFF`` - .. note:: Setting this option to ``ON`` will trigger additional CMake - options. See additional information on building with - LAPACK enabled in :numref:`Installation.CMake.ExternalLibraries`. + .. warning:: -.. cmakeoption:: BLAS_LIBRARIES + Building with monitoring may result in minor performance degradation even + if monitoring is not utilized. - BLAS libraries +.. _Installation.Options.Profiling: - Default: none (CMake will try to find a BLAS installation) +Profiling +^^^^^^^^^ -.. cmakeoption:: BLAS_LINKER_FLAGS +For more information on profiling in SUNDIALS, see :ref:`SUNDIALS.Profiling`. - BLAS required linker flags +.. cmakeoption:: SUNDIALS_BUILD_WITH_PROFILING - Default: none (CMake will try to determine the necessary flags) + Build SUNDIALS with capabilities for fine-grained profiling. This requires + POSIX timers, the Windows ``profileapi.h`` timers, or enabling Caliper with + :cmakeop:`ENABLE_CALIPER`. -.. cmakeoption:: LAPACK_LIBRARIES + Default: ``OFF`` - LAPACK libraries + .. warning:: - Default: none (CMake will try to find a LAPACK installation) + Profiling will impact performance, and should be enabled judiciously. -.. cmakeoption:: LAPACK_LINKER_FLAGS +.. _Installation.Options.Adiak: - LAPACK required linker flags +Building with Adiak +^^^^^^^^^^^^^^^^^^^ - Default: none (CMake will try to determine the necessary flags) +`Adiak `__ is a library for recording meta-data +about HPC simulations. Adiak is developed by Lawrence Livermore National +Laboratory and can be obtained from the `Adiak GitHub repository +`__. -.. cmakeoption:: ENABLE_MAGMA +.. cmakeoption:: ENABLE_ADIAK - Enable MAGMA support. + Enable Adiak support Default: ``OFF`` - .. note:: Setting this option to ``ON`` will trigger additional options - related to MAGMA. - -.. cmakeoption:: MAGMA_DIR - - Path to the root of a MAGMA installation. +.. cmakeoption:: adiak_DIR - Default: none + Path to the root of an Adiak installation -.. cmakeoption:: SUNDIALS_MAGMA_BACKENDS + Default: None - Which MAGMA backend to use under the SUNDIALS MAGMA interface. +.. _Installation.Options.Caliper: - Default: ``CUDA`` +Building with Caliper +^^^^^^^^^^^^^^^^^^^^^ -.. cmakeoption:: ENABLE_MPI +`Caliper `__ is a performance analysis +library providing a code instrumentation and performance measurement framework +for HPC applications. Caliper is developed by Lawrence Livermore National +Laboratory and can be obtained from the `Caliper GitHub repository +`__. - Enable MPI support. This will build the parallel nvector - and the MPI-aware version of the ManyVector library. +When profiling and Caliper are both enabled, SUNDIALS will utilize Caliper for +performance profiling. - Default: ``OFF`` +To enable Caliper support, set the :cmakeop:`ENABLE_CALIPER` to ``ON`` and set +:cmakeop:`CALIPER_DIR` to the root path of the Caliper installation. For +example, the following command will configure SUNDIALS with profiling and +Caliper support: - .. note:: Setting this option to ``ON`` will trigger several additional - options related to MPI. +.. code-block:: bash -.. cmakeoption:: MPI_C_COMPILER + cmake \ + -S SOLVER_DIR \ + -B BUILD_DIR \ + -D CMAKE_INSTALL_PREFIX=INSTALL_DIR \ + -D SUNDIALS_BUILD_WITH_PROFILING=ON \ + -D ENABLE_CALIPER=ON \ + -D CALIPER_DIR=/path/to/caliper/installation - ``mpicc`` program +.. cmakeoption:: ENABLE_CALIPER - Default: + Enable CALIPER support -.. cmakeoption:: MPI_CXX_COMPILER + Default: ``OFF`` - ``mpicxx`` program + .. note:: - Default: + Using Caliper requires setting :cmakeop:`SUNDIALS_BUILD_WITH_PROFILING` to + ``ON``. - .. note:: This option is triggered only if MPI is enabled - (``ENABLE_MPI`` 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 ``ENABLE_MPI``. +.. cmakeoption:: CALIPER_DIR -.. cmakeoption:: MPI_Fortran_COMPILER + Path to the root of a Caliper installation - ``mpif90`` program + Default: None - Default: +.. _Installation.Options.CUDA: - .. note:: This option is triggered only if MPI is enabled - (``ENABLE_MPI`` is ``ON``) and Fortran-C support is - enabled (``EXAMPLES_ENABLE_F2003`` is ``ON``). +Building with CUDA +^^^^^^^^^^^^^^^^^^ + +The NVIDIA `CUDA Toolkit `__ provides +a development environment for GPU-accelerated computing with NVIDIA GPUs. The +CUDA Toolkit and compatible NVIDIA drivers are available from the `NVIDIA +developer website `__. SUNDIALS has +been tested with the CUDA toolkit versions 10, 11, and 12. + +When CUDA support is enabled, the :ref:`CUDA NVector `, the +:ref:`cuSPARSE SUNMatrix `, and the :ref:`cuSPARSE batched +QR SUNLinearSolver ` will be built (see sections +:numref:`Installation.LibrariesAndHeaders.Vector.CUDA`, +:numref:`Installation.LibrariesAndHeaders.Matrix.cuSPARSE`, and +:numref:`Installation.LibrariesAndHeaders.LinearSolver.cuSPARSE`, respectively, +for the corresponding header files and libraries). For more information on using +SUNDIALS with GPUs, see :ref:`SUNDIALS.GPU`. + +To enable CUDA support, set :cmakeop:`ENABLE_CUDA` to ``ON``. If CUDA is +installed in a nonstandard location, you may need to set +:cmakeop:`CUDA_TOOLKIT_ROOT_DIR` to your CUDA Toolkit installation path. You +will also need to set :cmakeop:`CMAKE_CUDA_ARCHITECTURES` to the CUDA +architecture for your system. For example, the following command will configure +SUNDIALS with CUDA support for a system with an Ampere GPU: -.. cmakeoption:: MPIEXEC_EXECUTABLE +.. code-block:: bash - Specify the executable for running MPI programs + cmake \ + -S SOLVER_DIR \ + -B BUILD_DIR \ + -D CMAKE_INSTALL_PREFIX=INSTALL_DIR \ + -D ENABLE_CUDA=ON \ + -D CMAKE_CUDA_ARCHITECTURES="80" - Default: ``mpirun`` +.. cmakeoption:: ENABLE_CUDA - .. note:: This option is triggered only if MPI is enabled (``ENABLE_MPI`` is ``ON``). + Enable CUDA support -.. cmakeoption:: MPIEXEC_PREFLAGS + Default: ``OFF`` - Specifies flags that come directly after ``MPIEXEC_EXECUTABLE`` and before - ``MPIEXEC_NUMPROC_FLAG`` and ``MPIEXEC_MAX_NUMPROCS``. +.. cmakeoption:: CUDA_TOOLKIT_ROOT_DIR - Default: none + Path to the CUDA Toolkit installation - .. note:: This option is triggered only if MPI is enabled (``ENABLE_MPI`` is ``ON``). + Default: CMake will attempt to automatically locate an installed CUDA Toolkit -.. cmakeoption:: MPIEXEC_POSTFLAGS +.. cmakeoption:: CMAKE_CUDA_ARCHITECTURES - Specifies flags that come after the executable to run but before any other program arguments. + Specifies the CUDA architecture to compile for i.e., ``60`` for Pascal, + ``70`` for Volta, ``80`` for Ampere, ``90`` for Hopper, etc. See the `GPU + compute capability tables `__ on the + NVIDIA webpage and the `GPU Compilation + `__ + section of the CUDA documentation for more information. - Default: none + Default: Determined automatically by CMake. Users are encouraged to override + this value with the architecture for their system as the default varies + across compilers and compiler versions. - .. note:: This option is triggered only if MPI is enabled (``ENABLE_MPI`` is ``ON``). + .. versionchanged:: 7.2.0 -.. cmakeoption:: ENABLE_ONEMKL + In prior versions :cmakeop:`CMAKE_CUDA_ARCHITECTURES` defaulted to ``70``. - Enable oneMKL support. +.. _Installation.Options.Ginkgo: - Default: ``OFF`` +Building with Ginkgo +^^^^^^^^^^^^^^^^^^^^ -.. cmakeoption:: ONEMKL_DIR +`Ginkgo `__ is a high-performance linear +algebra library with a focus on solving sparse linear systems. It is implemented +using modern C++ (you will need at least a C++14 compliant compiler to build +it), with GPU kernels implemented in CUDA (for NVIDIA devices), HIP (for AMD +devices), and SYCL/DPC++ (for Intel devices and other supported +hardware). Ginkgo can be obtained from the `Ginkgo GitHub repository +`__. SUNDIALS is regularly tested with +the latest versions of Ginkgo, specifically up to version 1.8.0. + +When Ginkgo support is enabled, the :ref:`Ginkgo SUNMatrix ` +and the :ref:`Ginkgo SUNLinearSolver ` header files will be +installed (see sections :numref:`Installation.LibrariesAndHeaders.Matrix.Ginkgo` +and :numref:`Installation.LibrariesAndHeaders.LinearSolver.Ginkgo`, +respectively, for the corresponding header files). For more information on using +SUNDIALS with GPUs, see :ref:`SUNDIALS.GPU`. + +To enable Ginkgo support, set :cmakeop:`ENABLE_GINKGO` to ``ON`` and set +:cmakeop:`Ginkgo_DIR` to the root path of the Ginkgo installation. Additionally, +set :cmakeop:`SUNDIALS_GINKGO_BACKENDS` to a semicolon-separated list of Ginkgo +target architectures/executors. For example, the following command will +configure SUNDIALS with Ginkgo support using the reference, OpenMP, and CUDA +(targeting Ampere GPUs) backends: - Path to oneMKL installation. +.. code-block:: bash - Default: none + cmake \ + -S SOLVER_DIR \ + -B BUILD_DIR \ + -D CMAKE_INSTALL_PREFIX=INSTALL_DIR \ + -D ENABLE_GINKGO=ON \ + -D Ginkgo_DIR=/path/to/ginkgo/installation \ + -D SUNDIALS_GINKGO_BACKENDS="REF;OMP;CUDA" \ + -D ENABLE_CUDA=ON \ + -D CMAKE_CUDA_ARCHITECTURES="80" \ + -D ENABLE_OPENMP=ON -.. cmakeoption:: SUNDIALS_ONEMKL_USE_GETRF_LOOP +.. note:: - This advanced debugging option replaces the batched LU factorization with a - loop over each system in the batch and a non-batched LU factorization. + The SUNDIALS interfaces to Ginkgo are not compatible with extended precision + (i.e., when :cmakeop:`SUNDIALS_PRECISION` is set to ``extended``). - Default: OFF +.. cmakeoption:: ENABLE_GINKGO -.. cmakeoption:: SUNDIALS_ONEMKL_USE_GETRS_LOOP + Enable Ginkgo support - This advanced debugging option replaces the batched LU solve with a loop over - each system in the batch and a non-batched solve. + Default: ``OFF`` - Default: OFF +.. cmakeoption:: Ginkgo_DIR -.. cmakeoption:: ENABLE_OPENMP + Path to the Ginkgo installation - Enable OpenMP support (build the OpenMP NVector) + Default: None - Default: ``OFF`` +.. cmakeoption:: SUNDIALS_GINKGO_BACKENDS -.. cmakeoption:: ENABLE_PETSC + Semi-colon separated list of Ginkgo target architectures/executors to build + for. Options currently supported are ``REF`` (the Ginkgo reference executor), + ``OMP`` (OpenMP), ``CUDA``, ``HIP``, and ``SYCL``. - Enable PETSc support + Default: ``"REF;OMP"`` - Default: ``OFF`` + .. versionchanged:: 7.1.0 - .. note:: See additional information on building with - PETSc enabled in :numref:`Installation.CMake.ExternalLibraries`. + The ``DPCPP`` option was changed to ``SYCL`` to align with Ginkgo's naming + convention. -.. cmakeoption:: PETSC_DIR +.. _Installation.Options.HIP: - Path to PETSc installation +Building with HIP +^^^^^^^^^^^^^^^^^ + +The `Heterogeneous-compute Interface for Portability (HIP) +`__ allows developers to +create portable applications for AMD and NVIDIA GPUs. HIP can be obtained from +the `HIP GitHub repository +`__. SUNDIALS has been tested with +HIP versions between 5.0.0 to 5.4.3. + +When HIP support is enabled, the :ref:`HIP NVector ` will be built +(see section :numref:`Installation.LibrariesAndHeaders.Vector.HIP` for the +corresponding header file and library). For more information on using SUNDIALS +with GPUs, see :ref:`SUNDIALS.GPU`. + +To enable HIP support, set :cmakeop:`ENABLE_HIP` to ``ON`` and set +:cmakeop:`AMDGPU_TARGETS` to the desired target (e.g., ``gfx705``). In addition, +set :cmakeop:`CMAKE_C_COMPILER` and :cmakeop:`CMAKE_CXX_COMPILER` to a HIP +compatible compiler e.g., ``hipcc``. For example, the following command will +configure SUNDIALS with HIP support for a system with an MI250X GPU: - Default: none +.. code-block:: bash -.. cmakeoption:: PETSC_LIBRARIES + cmake \ + -S SOLVER_DIR \ + -B BUILD_DIR \ + -D CMAKE_INSTALL_PREFIX=INSTALL_DIR \ + -D CMAKE_C_COMPILER=hipcc \ + -D CMAKE_CXX_COMPILER=hipcc \ + -D ENABLE_HIP=ON \ + -D AMDGPU_TARGETS="gfx90a" - 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``. +.. cmakeoption:: ENABLE_HIP - Default: none + Enable HIP Support -.. cmakeoption:: PETSC_INCLUDES + Default: ``OFF`` - Semi-colon separated list of PETSc include directories. Unless provided by - the user, this is autopopulated based on the PETSc installation found in - ``PETSC_DIR``. +.. cmakeoption:: AMDGPU_TARGETS - Default: none + Specify which AMD GPUs to target -.. cmakeoption:: ENABLE_PTHREAD + Default: None - Enable Pthreads support (build the Pthreads NVector) +.. _Installation.Options.hypre: - Default: ``OFF`` +Building with *hypre* +^^^^^^^^^^^^^^^^^^^^^ -.. cmakeoption:: ENABLE_RAJA +`hypre `__ is a library of high performance +preconditioners and solvers featuring multigrid methods for the solution of +large, sparse linear systems of equations on massively parallel computers. The +library is developed by Lawrence Livermore National Laboratory and is available +from the `hypre GitHub repository +`__. SUNDIALS is regularly tested with the +latest versions of *hypre*, specifically up to version 2.26.0. - Enable RAJA support. +When *hypre* support is enabled, the :ref:`ParHyp NVector ` +will be built (see section +:numref:`Installation.LibrariesAndHeaders.Vector.ParHyp` for the corresponding +header file and library). - Default: OFF +To enable *hypre* support, set :cmakeop:`ENABLE_MPI` to ``ON``, set +:cmakeop:`ENABLE_HYPRE` to ``ON``, and set :cmakeop:`HYPRE_DIR` to the root path +of the *hypre* installation. For example, the following command will configure +SUNDIALS with *hypre* support: - .. note:: You need to enable CUDA or HIP in order to build the - RAJA vector module. +.. code-block:: bash -.. cmakeoption:: SUNDIALS_RAJA_BACKENDS + cmake \ + -S SOLVER_DIR \ + -B BUILD_DIR \ + -D CMAKE_INSTALL_PREFIX=INSTALL_DIR \ + -D ENABLE_MPI=ON \ + -D ENABLE_HYPRE=ON \ + -D HYPRE_DIR=/path/to/hypre/installation - If building SUNDIALS with RAJA support, this sets the RAJA backend to target. - Values supported are CUDA, HIP, or SYCL. +.. note:: - Default: CUDA + SUNDIALS must be configured so that :cmakeop:`SUNDIALS_INDEX_SIZE` is + compatible with ``HYPRE_BigInt`` in the *hypre* installation. -.. cmakeoption:: ENABLE_SUPERLUDIST +.. cmakeoption:: ENABLE_HYPRE - Enable SuperLU_DIST support + Enable *hypre* support Default: ``OFF`` - .. note:: See additional information on building with - SuperLU_DIST enabled in :numref:`Installation.CMake.ExternalLibraries`. - -.. cmakeoption:: SUPERLUDIST_DIR +.. cmakeoption:: HYPRE_DIR - Path to SuperLU_DIST installation. + Path to the *hypre* installation Default: none -.. cmakeoption:: SUPERLUDIST_OpenMP +.. _Installation.Options.KLU: - Enable SUNDIALS support for SuperLU_DIST built with OpenMP +Building with KLU +^^^^^^^^^^^^^^^^^ - Default: none +KLU is a software package for the direct solution of sparse nonsymmetric linear +systems of equations that arise in circuit simulation and is part of +`SuiteSparse `__, a suite +of sparse matrix software. The library is developed by Texas A&M University and +is available from the `SuiteSparse GitHub repository +`__. SUNDIALS is regularly +tested with the latest versions of KLU, specifically up to SuiteSparse version +7.7.0. + +When KLU support is enabled, the :ref:`KLU SUNLinearSolver ` will +be built (see section +:numref:`Installation.LibrariesAndHeaders.LinearSolver.KLU` for the +corresponding header file and library). + +To enable KLU support, set :cmakeop:`ENABLE_KLU` to ``ON``. For SuiteSparse +7.4.0 and newer, set :cmakeop:`KLU_ROOT` to the root of the SuiteSparse +installation. Alternatively, set :cmakeop:`KLU_INCLUDE_DIR` and +:cmakeop:`KLU_LIBRARY_DIR` to the path to the header and library files, +respectively, of the SuiteSparse installation. For example, the +following command will configure SUNDIALS with KLU support: - 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. +.. code-block:: bash -.. cmakeoption:: SUPERLUDIST_INCLUDE_DIRS + cmake \ + -S SOLVER_DIR \ + -B BUILD_DIR \ + -D CMAKE_INSTALL_PREFIX=INSTALL_DIR \ + -D ENABLE_KLU=ON \ + -D KLU_ROOT=/path/to/suitesparse/installation - List of include paths for SuperLU_DIST (under a typical SuperLU_DIST - install, this is typically the SuperLU_DIST ``SRC`` directory) +.. cmakeoption:: ENABLE_KLU - Default: none + Enable KLU support - .. note:: + Default: ``OFF`` - This is an advanced option. Prefer to use :cmakeop:`SUPERLUDIST_DIR`. +.. cmakeoption:: KLU_ROOT -.. cmakeoption:: SUPERLUDIST_LIBRARIES + Path to the SuiteSparse installation - Semi-colon separated list of libraries needed for SuperLU_DIST + Default: ``OFF`` - Default: none +.. cmakeoption:: KLU_INCLUDE_DIR - .. note:: + Path to SuiteSparse header files - This is an advanced option. Prefer to use :cmakeop:`SUPERLUDIST_DIR`. + Default: none -.. cmakeoption:: SUPERLUDIST_INCLUDE_DIR +.. cmakeoption:: KLU_LIBRARY_DIR - Path to SuperLU_DIST header files (under a typical SuperLU_DIST - install, this is typically the SuperLU_DIST ``SRC`` directory) + Path to SuiteSparse installed library files Default: none - .. note:: +.. _Installation.Options.Kokkos: - This is an advanced option. This option is deprecated. Use :cmakeop:`SUPERLUDIST_INCLUDE_DIRS`. +Building with Kokkos +^^^^^^^^^^^^^^^^^^^^ -.. cmakeoption:: SUPERLUDIST_LIBRARY_DIR +`Kokkos `__ is a modern C++ +(requires at least C++14) programming model for witting performance portable +code for multicore CPU and GPU-based systems including NVIDIA, AMD, and Intel +GPUs. Kokkos is developed by Sandia National Laboratory and can be obtained from +the `Kokkos GitHub repository `__. The minimum +supported version of Kokkos 3.7.00. SUNDIALS is regularly tested with the latest +versions of Kokkos, specifically up to version 4.3.01. - Path to SuperLU_DIST installed library files +When Kokkos support is enabled, the :ref:`Kokkos NVector ` +header file will be installed (see section +:numref:`Installation.LibrariesAndHeaders.Vector.Kokkos` for the corresponding +header file). For more information on using SUNDIALS with GPUs, see +:ref:`SUNDIALS.GPU`. - Default: none +To enable Kokkos support, set the :cmakeop:`ENABLE_KOKKOS` to ``ON`` and set +:cmakeop:`Kokkos_DIR` to root path of the Kokkos installation. For example, the +following command will configure SUNDIALS with Kokkos support: - .. note:: +.. code-block:: bash - This option is deprecated. Use :cmakeop:`SUPERLUDIST_DIR`. + cmake \ + -S SOLVER_DIR \ + -B BUILD_DIR \ + -D CMAKE_INSTALL_PREFIX=INSTALL_DIR \ + -D ENABLE_KOKKOS=ON \ + -D Kokkos_DIR=/path/to/kokkos/installation -.. cmakeoption:: ENABLE_SUPERLUMT +.. cmakeoption:: ENABLE_KOKKOS - Enable SuperLU_MT support + Enable Kokkos support Default: ``OFF`` - .. note:: See additional information on building with - SuperLU_MT enabled in :numref:`Installation.CMake.ExternalLibraries`. +.. cmakeoption:: Kokkos_DIR -.. cmakeoption:: SUPERLUMT_INCLUDE_DIR + Path to the Kokkos installation. - Path to SuperLU_MT header files (under a typical SuperLU_MT - install, this is typically the SuperLU_MT ``SRC`` directory) + Default: None - Default: none +.. _Installation.Options.KokkosKernels: -.. cmakeoption:: SUPERLUMT_LIBRARY_DIR +Building with KokkosKernels +^^^^^^^^^^^^^^^^^^^^^^^^^^^ - Path to SuperLU_MT installed library files +The `KokkosKernels `__ library is +built on Kokkos and provides common linear algebra computational kernels. +KokkosKernels is developed by Sandia National Laboratory and can be obtained +from the `KokkosKernels GitHub repository +`__. The minimum supported version of +KokkosKernels 3.7.00. SUNDIALS is regularly tested with the latest versions of +KokkosKernels, specifically up to version 4.3.01. + +When KokkosKernels support is enabled, the :ref:`KokkosKernels SUNMatrix +` and :ref:`KokkosKernels SUNLinearSolver ` +header files will be installed (see sections +:numref:`Installation.LibrariesAndHeaders.Matrix.KokkosKernels` and +:numref:`Installation.LibrariesAndHeaders.LinearSolver.KokkosKernels`, +respectively, for the corresponding header files). For more information on using +SUNDIALS with GPUs, see :ref:`SUNDIALS.GPU`. + +To enable KokkosKernels support, set :cmakeop:`ENABLE_KOKKOS` and +:cmakeop:`ENABLE_KOKKOS_KERNELS` to ``ON`` and set :cmakeop:`Kokkos_DIR` and +:cmakeop:`KokkosKernels_DIR` to the root paths for the Kokkos and KokkosKernels +installations, respectively. For example, the following command will configure +SUNDIALS with Kokkos and KokkosKernels support: - Default: none +.. code-block:: bash -.. cmakeoption:: SUPERLUMT_THREAD_TYPE + cmake \ + -S SOLVER_DIR \ + -B BUILD_DIR \ + -D CMAKE_INSTALL_PREFIX=INSTALL_DIR \ + -D ENABLE_KOKKOS=ON \ + -D Kokkos_DIR=/path/to/kokkos/installation \ + -D ENABLE_KOKKOS_KERNELS=ON \ + -D KokkosKernels_DIR=/path/to/kokkoskernels/installation - Must be set to Pthread or OpenMP, depending on how SuperLU_MT was compiled. +.. cmakeoption:: ENABLE_KOKKOS_KERNELS - Default: Pthread + Enable KokkosKernels support -.. cmakeoption:: ENABLE_SYCL + Default: ``OFF`` - Enable SYCL support. +.. cmakeoption:: KokkosKernels_DIR - Default: OFF + Path to the KokkosKernels installation. - .. note:: + Default: None - Building with SYCL enabled requires a compiler that supports a subset of - the of SYCL 2020 specification (specifically ``sycl/sycl.hpp`` must be - available). +.. _Installation.Options.LAPACK: - CMake does not currently support autodetection of SYCL compilers and - ``CMAKE_CXX_COMPILER`` must be set to a valid SYCL compiler. At present - the only supported SYCL compilers are the Intel oneAPI compilers i.e., - ``dpcpp`` and ``icpx``. When using ``icpx`` the ``-fsycl`` flag and any - ahead of time compilation flags must be added to ``CMAKE_CXX_FLAGS``. +Building with LAPACK +^^^^^^^^^^^^^^^^^^^^ -.. cmakeoption:: SUNDIALS_SYCL_2020_UNSUPPORTED +The `Linear Algebra PACKage (LAPACK) `__ library +interface defines functions for solving systems of linear equations. Several +LAPACK implementations are available e.g., the `Netlib reference implementation +`__, the `Intel oneAPI Math Kernel Library +`__, +or `OpenBLAS `__ (among others). SUNDIALS +is regularly tested with the latest versions of OpenBLAS, specifically up to +version 0.3.27. + +When LAPACK support is enabled, the :ref:`LAPACK banded SUNLinearSolver +` and :ref:`LAPACK dense SUNLinearSolver +` will be built (see sections +:numref:`Installation.LibrariesAndHeaders.LinearSolver.LAPACKBand` and +:numref:`Installation.LibrariesAndHeaders.LinearSolver.LAPACKDense`, +respectively, for the corresponding header files and libraries). + +To enable LAPACK support, set :cmakeop:`ENABLE_LAPACK` to ``ON``. CMake will +attempt to find BLAS and LAPACK installations on the system and set the +variables :cmakeop:`BLAS_LIBRARIES`, :cmakeop:`BLAS_LINKER_FLAGS`, +:cmakeop:`LAPACK_LIBRARIES`, and :cmakeop:`LAPACK_LINKER_FLAGS`. To explicitly +specify the LAPACK library to build with, manually set the aforementioned +variables to the desired values when configuring the build. For example, the +following command will configure SUNDIALS with LAPACK support: - This advanced option disables the use of *some* features from the SYCL 2020 - standard in SUNDIALS libraries and examples. This can be used to work around - some cases of incomplete compiler support for SYCL 2020. +.. code-block:: bash - Default: OFF + cmake \ + -S SOLVER_DIR \ + -B BUILD_DIR \ + -D CMAKE_INSTALL_PREFIX=INSTALL_DIR \ + -D ENABLE_LAPACK=ON \ + -D BLAS_LIBRARIES=/path/to/lapack/installation/lib/libblas.so \ + -D LAPACK_LIBRARIES=/path/to/lapack/installation/lib/liblapack.so -.. cmakeoption:: ENABLE_TRILINOS +.. note:: - Enable Trilinos (Tpetra) support + If a working Fortran compiler is not available to infer the name-mangling + scheme for LAPACK functions, the options :cmakeop:`SUNDIALS_LAPACK_CASE` and + :cmakeop:`SUNDIALS_LAPACK_UNDERSCORES` *must* be set 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. - Default: OFF +.. cmakeoption:: ENABLE_LAPACK + + Enable LAPACK support + + Default: ``OFF`` + +.. cmakeoption:: BLAS_LIBRARIES + + BLAS libraries + + Default: none (CMake will try to find a BLAS installation) + +.. cmakeoption:: BLAS_LINKER_FLAGS + + BLAS required linker flags + + Default: none (CMake will try to determine the necessary flags) + +.. cmakeoption:: LAPACK_LIBRARIES + + LAPACK libraries + + Default: none (CMake will try to find a LAPACK installation) + +.. cmakeoption:: LAPACK_LINKER_FLAGS + + LAPACK required linker flags + + Default: none (CMake will try to determine the necessary flags) + +.. cmakeoption:: SUNDIALS_LAPACK_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, + :cmakeop:`SUNDIALS_LAPACK_UNDERSCORES` must also be set. + +.. cmakeoption:: SUNDIALS_LAPACK_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, + :cmakeop:`SUNDIALS_LAPACK_CASE` must also be set. + +.. _Installation.Options.MAGMA: + +Building with MAGMA +^^^^^^^^^^^^^^^^^^^ + +The `Matrix Algebra on GPU and Multicore Architectures (MAGMA) +`__ project provides a dense linear algebra library +similar to LAPACK but targeting heterogeneous architectures. The library is +developed by the University of Tennessee and is available from the `MAGMA GitHub +repository `__. SUNDIALS is regularly +tested with the latest versions of MAGMA, specifically up to version 2.8.0. + +When MAGMA support is enabled, the :ref:`MAGMA dense SUNMatrix +` and :ref:`MAGMA dense SUNLinearSolver +` will be built (see sections +:numref:`Installation.LibrariesAndHeaders.Matrix.MAGMADense` and +:numref:`Installation.LibrariesAndHeaders.LinearSolver.MAGMADense`, +respectively, for the corresponding header files and libraries). For more +information on using SUNDIALS with GPUs, see :ref:`SUNDIALS.GPU`. + +To enable MAGMA support, set :cmakeop:`ENABLE_MAGMA` to ``ON``, +:cmakeop:`MAGMA_DIR` to the root path of MAGMA installation, and +:cmakeop:`SUNDIALS_MAGMA_BACKENDS` to the desired MAGMA backend to use. For +example, the following command will configure SUNDIALS with MAGMA support with +the CUDA backend (targeting Ampere GPUs): + +.. code-block:: bash + + cmake \ + -S SOLVER_DIR \ + -B BUILD_DIR \ + -D CMAKE_INSTALL_PREFIX=INSTALL_DIR \ + -D ENABLE_MAGMA=ON \ + -D MAGMA_DIR=/path/to/magma/installation \ + -D SUNDIALS_MAGMA_BACKEND="CUDA" \ + -D ENABLE_CUDA=ON \ + -D CMAKE_CUDA_ARCHITECTURES="80" + +.. cmakeoption:: ENABLE_MAGMA + + Enable MAGMA support + + Default: ``OFF`` + +.. cmakeoption:: MAGMA_DIR + + Path to the MAGMA installation + + Default: none + +.. cmakeoption:: SUNDIALS_MAGMA_BACKENDS + + Which MAGMA backend to use under the SUNDIALS MAGMA interface: ``CUDA`` or + ``HIP`` + + Default: ``CUDA`` + + .. TODO(DJG): Change this options so it is HIP or SYCL if those options are + enabled + +.. _Installation.Options.MPI: + +Building with MPI +^^^^^^^^^^^^^^^^^ + +The `Message Passing Interface (MPI) `__ is a +standard for communication on parallel computing systems. Several MPI +implementations are available e.g., `OpenMPI `__, +`MPICH `__, `MVAPICH +`__, `Cray MPICH +`__, `Intel MPI +`__, +or `IBM Spectrum MPI `__ (among +others). SUNDIALS is regularly tested with the latest versions of OpenMPI, +specifically up to version 5.0.5. + +When MPI support is enabled, the :ref:`parallel NVector `, +:ref:`MPI ManyVector NVector `, and :ref:`MPI+X NVector +` will be built (see sections +:numref:`Installation.LibrariesAndHeaders.Vector.Parallel`, +:numref:`Installation.LibrariesAndHeaders.Vector.MPIManyVector`, and +:numref:`Installation.LibrariesAndHeaders.Vector.MPIPlusX`, +respectively, for the corresponding header files and libraries). + +.. attention:: + + .. versionchanged:: 7.0.0 + + When MPI is enabled, all SUNDIALS libraries will include MPI symbols and + applications will need to include the path for MPI headers and link against + the corresponding MPI library. + +To enable MPI support, set :cmakeop:`ENABLE_MPI` to ``ON``. If CMake is unable +to locate an MPI installation, set the relevant ``MPI__COMPILER`` +options to the desired MPI compilers. For example, the following command will +configure SUNDIALS with MPI support: + +.. code-block:: bash + + cmake \ + -S SOLVER_DIR \ + -B BUILD_DIR \ + -D CMAKE_INSTALL_PREFIX=INSTALL_DIR \ + -D ENABLE_MPI=ON + +.. cmakeoption:: ENABLE_MPI + + Enable MPI support + + Default: ``OFF`` + +.. cmakeoption:: MPI_C_COMPILER + + The MPI C compiler e.g., ``mpicc`` + + Default: CMake will attempt to locate an MPI C compiler + +.. cmakeoption:: MPI_CXX_COMPILER + + The MPI C++ compiler e.g., ``mpicxx`` + + Default: CMake will attempt to locate an MPI C++ compiler + + .. note:: + + This option is only needed if MPI is enabled (:cmakeop:`ENABLE_MPI` is + ``ON``) and C++ examples are enabled (:cmakeop:`EXAMPLES_ENABLE_CXX` is + ``ON``). All SUNDIALS solvers can be used from C++ MPI applications by + without setting any additional configuration options other than + :cmakeop:`ENABLE_MPI`. + +.. cmakeoption:: MPI_Fortran_COMPILER + + The MPI Fortran compiler e.g., ``mpif90`` + + Default: CMake will attempt to locate an MPI Fortran compiler + + .. note:: + + This option is triggered only needed if MPI is enabled + (:cmakeop:`ENABLE_MPI` is ``ON``) and the Fortran interfaces are enabled + (:cmakeop:`BUILD_FORTRAN_MODULE_INTERFACE` is ``ON``). + +.. cmakeoption:: MPIEXEC_EXECUTABLE + + Specify the executable for running MPI programs e.g., ``mpiexec`` + + Default: CMake will attempt to locate the MPI executable + +.. cmakeoption:: MPIEXEC_PREFLAGS + + Specifies flags that come directly after ``MPIEXEC_EXECUTABLE`` and before + ``MPIEXEC_NUMPROC_FLAG`` and ``MPIEXEC_MAX_NUMPROCS``. + + Default: none + +.. cmakeoption:: MPIEXEC_POSTFLAGS + + Specifies flags that come after the executable to run but before any other + program arguments. + + Default: none + +.. _Installation.Options.OneMKL: + +Building with oneMKL +^^^^^^^^^^^^^^^^^^^^ + +The Intel `oneAPI Math Kernel Library (oneMKL) +`__ +includes CPU and SYCL/DPC++ interfaces for LAPACK dense linear algebra +routines. The SUNDIALS oneMKL interface targets the SYCL/DPC++ routines, to +utilize the CPU routine see section +:numref:`Installation.Options.LAPACK`. SUNDIALS has been tested with oneMKL +version 2021.4. + +When oneMKL support is enabled, the :ref:`oneMLK dense SUNMatrix +` and the :ref:`oneMKL dense SUNLinearSolver +` will be built (see sections +:numref:`Installation.LibrariesAndHeaders.Matrix.oneMKLDense` and +:numref:`Installation.LibrariesAndHeaders.LinearSolver.oneMKLDense`, +respectively, for the corresponding header files and libraries). For more +information on using SUNDIALS with GPUs, see :ref:`SUNDIALS.GPU`. + +To enable the SUNDIALS oneMKL interface set :cmakeop:`ENABLE_ONEMKL` to ``ON`` +and :cmakeop:`ONEMKL_DIR` to the root path of oneMKL installation. For example, +the following command will configure SUNDIALS with oneMKL support: + +.. code-block:: bash + + cmake \ + -S SOLVER_DIR \ + -B BUILD_DIR \ + -D CMAKE_INSTALL_PREFIX=INSTALL_DIR \ + -D ENABLE_ONEMKL=ON \ + -D ONEMKL_DIR=/path/to/onemkl/installation \ + +.. cmakeoption:: ENABLE_ONEMKL + + Enable oneMKL support + + Default: ``OFF`` + +.. cmakeoption:: ONEMKL_DIR + + Path to oneMKL installation. + + Default: none + +.. cmakeoption:: SUNDIALS_ONEMKL_USE_GETRF_LOOP + + This advanced debugging option replaces the batched LU factorization with a + loop over each system in the batch and a non-batched LU factorization. + + Default: ``OFF`` + +.. cmakeoption:: SUNDIALS_ONEMKL_USE_GETRS_LOOP + + This advanced debugging option replaces the batched LU solve with a loop over + each system in the batch and a non-batched solve. + + Default: ``OFF`` + +.. _Installation.Options.OpenMP: + +Building with OpenMP +^^^^^^^^^^^^^^^^^^^^ + +The `OpenMP `__ API defines a directive-based approach +for portable parallel programming across architectures. + +When OpenMP support is enabled, the :ref:`OpenMP NVector ` will +be built (see section :numref:`Installation.LibrariesAndHeaders.Vector.OpenMP` +for the corresponding header file and library). + +To enable OpenMP support, set the :cmakeop:`ENABLE_OPENMP` to ``ON``. For +example, the following command will configure SUNDIALS with OpenMP support: + +.. code-block:: bash + + cmake \ + -S SOLVER_DIR \ + -B BUILD_DIR \ + -D CMAKE_INSTALL_PREFIX=INSTALL_DIR \ + -D ENABLE_OPENMP=ON + +.. cmakeoption:: ENABLE_OPENMP + + Enable OpenMP support + + Default: ``OFF`` + +Building with OpenMP Device Offloading +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The `OpenMP `__ 4.0 specification added support for +offloading computations to devices (i.e., GPUs). SUNDIALS requires OpenMP 4.5 +for GPU offloading support. + +When OpenMP offloading support is enabled, the :ref:`OpenMPDEV NVector +` will be built (see section +:numref:`Installation.LibrariesAndHeaders.Vector.OpenMPDEV` for the +corresponding header file and library). + +To enable OpenMP device offloading support, set the +:cmakeop:`ENABLE_OPENMP_DEVICE` to ``ON``. For example, the following command +will configure SUNDIALS with OpenMP device offloading support: + +.. code-block:: bash + + cmake \ + -S SOLVER_DIR \ + -B BUILD_DIR \ + -D CMAKE_INSTALL_PREFIX=INSTALL_DIR \ + -D ENABLE_OPENMP_DEVICE=ON + +.. cmakeoption:: ENABLE_OPENMP_DEVICE + + Enable OpenMP device offloading support + + Default: ``OFF`` + +.. _Installation.Options.PETSc: + +Building with PETSc +^^^^^^^^^^^^^^^^^^^ + +The `Portable, Extensible Toolkit for Scientific Computation (PETSc) +`__ is a suite of data structures and routines for simulating +applications modeled by partial differential equations. The library is developed +by Argonne National Laboratory and is available from the `PETSc GitLab +repository `__. SUNDIALS requires PETSc 3.5.0 +or newer and is regularly tested with the latest versions of PETSc, specifically +up to version 3.21.4. + +When PETSc support is enabled, the :ref:`PETSc NVector ` and +:ref:`PETSc SNES SUNNonlinearSolver ` will be built (see +sections :numref:`Installation.LibrariesAndHeaders.Vector.PETSc` and +:numref:`Installation.LibrariesAndHeaders.NonlinearSolver.PETScSNES`, +respectively, for the corresponding header files and libraries). + +To enable PETSc support, set :cmakeop:`ENABLE_MPI` to ``ON``, set +:cmakeop:`ENABLE_PETSC` to ``ON``, and set :cmakeop:`PETSC_DIR` to the path of +the PETSc installation. Alternatively, a user can provide a list of include +paths in :cmakeop:`PETSC_INCLUDES` and a list of complete paths to the PETSc +libraries in :cmakeop:`PETSC_LIBRARIES`. For example, the following command will +configure SUNDIALS with PETSc support: + +.. code-block:: bash + + cmake \ + -S SOLVER_DIR \ + -B BUILD_DIR \ + -D CMAKE_INSTALL_PREFIX=INSTALL_DIR \ + -D ENABLE_MPI=ON \ + -D ENABLE_PETSC=ON \ + -D PETSC_DIR=/path/to/petsc/installation + +.. cmakeoption:: ENABLE_PETSC + + Enable PETSc support + + Default: ``OFF`` + +.. cmakeoption:: PETSC_DIR + + Path to PETSc installation + + Default: none + +.. cmakeoption:: PETSC_LIBRARIES + + Semi-colon separated list of PETSc link libraries. Unless provided by the + user, this is autopopulated based on the PETSc installation found in + :cmakeop:`PETSC_DIR`. + + Default: none + +.. cmakeoption:: PETSC_INCLUDES + + Semi-colon separated list of PETSc include directories. Unless provided by + the user, this is autopopulated based on the PETSc installation found in + :cmakeop:`PETSC_DIR`. + + Default: none + +.. _Installation.Options.PThreads: + +Building with PThreads +^^^^^^^^^^^^^^^^^^^^^^ + +POSIX Threads (PThreads) is an API for shared memory programming defined by the +Institute of Electrical and Electronics Engineers (IEEE) standard POSIX.1c. + +When PThreads support is enabled, the :ref:`PThreads NVector +` will be built (see section +:numref:`Installation.LibrariesAndHeaders.Vector.PThreads` for the corresponding +header file and library). + +To enable PThreads support, set :cmakeop:`ENABLE_PTHREAD` to ``ON``. For +example, the following command will configure SUNDIALS with PThreads support: + +.. code-block:: bash + + cmake \ + -S SOLVER_DIR \ + -B BUILD_DIR \ + -D CMAKE_INSTALL_PREFIX=INSTALL_DIR \ + -D ENABLE_PTHREAD=ON + +.. cmakeoption:: ENABLE_PTHREAD + + Enable PThreads support + + Default: ``OFF`` + +.. _Installation.Options.RAJA: + +Building with RAJA +^^^^^^^^^^^^^^^^^^ + +`RAJA `__ is a performance portability +layer developed by Lawrence Livermore National Laboratory and can be obtained +from the `RAJA GitHub repository `__. SUNDIALS is +regularly tested with the latest versions of RAJA, specifically up to version +2024.02.2. + +When RAJA support is enabled, the :ref:`RAJA NVector ` will be +built (see section :numref:`Installation.LibrariesAndHeaders.Vector.RAJA` +for the corresponding header files and libraries). + +To enable RAJA support, set :cmakeop:`ENABLE_RAJA` to ``ON``, set +:cmakeop:`RAJA_DIR` to the path of the RAJA installation, set +:cmakeop:`SUNDIALS_RAJA_BACKENDS` to the desired backend (``CUDA``, ``HIP``, or +``SYCL``), and set :cmakeop:`ENABLE_CUDA`, :cmakeop:`ENABLE_HIP`, or +:cmakeop:`ENABLE_SYCL` to ``ON`` depending on the selected backend. For +example, the following command will configure SUNDIALS with RAJA support using +the CUDA backend (targeting Ampere GPUs): + +.. code-block:: bash + + cmake \ + -S SOLVER_DIR \ + -B BUILD_DIR \ + -D CMAKE_INSTALL_PREFIX=INSTALL_DIR \ + -D ENABLE_RAJA=ON \ + -D RAJA_DIR=/path/to/raja/installation \ + -D SUNDIALS_RAJA_BACKENDS="CUDA" \ + -D ENABLE_CUDA=ON \ + -D CMAKE_CUDA_ARCHITECTURES="80" + +.. cmakeoption:: ENABLE_RAJA + + Enable RAJA support + + Default: ``OFF`` + +.. cmakeoption:: RAJA_DIR + + Path to the RAJA installation + + Default: none + +.. cmakeoption:: SUNDIALS_RAJA_BACKENDS + + If building SUNDIALS with RAJA support, this sets the RAJA backend to target. + Values supported are ``CUDA``, ``HIP``, or ``SYCL``. + + Default: ``CUDA`` + +.. _Installation.Options.SuperLU_DIST: + +Building with SuperLU_DIST +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +`SuperLU_DIST `__ is a general +purpose library for the direct solution of large, sparse, nonsymmetric systems +of linear equations in a distributed memory setting. The library is developed by +Lawrence Berkeley National Laboratory and is available from the `SuperLU_DIST +GitHub repository `__. SuperLU_DIST +version 7.0.0 or newer is required. SUNDIALS is regularly tested with the latest +versions of SuperLU_DIST, specifically up to version 8.2.1. + +When SuperLU_DIST support is enabled, the :ref:`SuperLU_DIST (SLUNRloc) +SUNMatrix ` and :ref:`SuperLU_DIST SUNLinearSolver +` will be built (see sections +:numref:`Installation.LibrariesAndHeaders.Matrix.SuperLU_DIST` and +:numref:`Installation.LibrariesAndHeaders.LinearSolver.SuperLU_DIST` for the +corresponding header files and libraries). + +To enable SuperLU_DIST support, set :cmakeop:`ENABLE_MPI` to ``ON``, set +:cmakeop:`ENABLE_SUPERLUDIST` to ``ON``, and set :cmakeop:`SUPERLUDIST_DIR` to +the path where SuperLU_DIST is installed. If SuperLU_DIST was built with OpenMP +enabled, set :cmakeop:`SUPERLUDIST_OpenMP` and :cmakeop:`ENABLE_OPENMP` to +``ON``. For example, the following command will configure SUNDIALS with +SuperLU_DIST support: + +.. code-block:: bash + + cmake \ + -S SOLVER_DIR \ + -B BUILD_DIR \ + -D CMAKE_INSTALL_PREFIX=INSTALL_DIR \ + -D ENABLE_SUPERLUDIST=ON \ + -D SUPERLUDIST_DIR=/path/to/superludist/installation + +.. cmakeoption:: ENABLE_SUPERLUDIST + + Enable SuperLU_DIST support + + Default: ``OFF`` + +.. cmakeoption:: SUPERLUDIST_DIR + + Path to SuperLU_DIST installation. + + Default: none + +.. cmakeoption:: 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. + +.. cmakeoption:: SUPERLUDIST_INCLUDE_DIRS + + List of include paths for SuperLU_DIST (under a typical SuperLU_DIST + install, this is typically the SuperLU_DIST ``SRC`` directory) + + Default: none + + .. note:: + + This is an advanced option. Prefer to use :cmakeop:`SUPERLUDIST_DIR`. + +.. cmakeoption:: SUPERLUDIST_LIBRARIES + + Semi-colon separated list of libraries needed for SuperLU_DIST + + Default: none + + .. note:: + + This is an advanced option. Prefer to use :cmakeop:`SUPERLUDIST_DIR`. + +.. cmakeoption:: 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 + + .. note:: + + This is an advanced option. This option is deprecated. Use + :cmakeop:`SUPERLUDIST_INCLUDE_DIRS`. + +.. cmakeoption:: SUPERLUDIST_LIBRARY_DIR + + Path to SuperLU_DIST installed library files + + Default: none + + .. note:: + + This option is deprecated. Use :cmakeop:`SUPERLUDIST_DIR`. + +.. _Installation.Options.SuperLU_MT: + +Building with SuperLU_MT +^^^^^^^^^^^^^^^^^^^^^^^^ + +`SuperLU_MT `__ is a general +purpose library for the direct solution of large, sparse, nonsymmetric systems +of linear equations on shared memory parallel machines. The library is developed +by Lawrence Berkeley National Laboratory and is available from the `SuperLU_MT +GitHub repository `__. SUNDIALS is +regularly tested with the latest versions of SuperLU_MT, specifically up to +version 4.0.1. + +When SuperLU_MT support is enabled, the :ref:`SuperLU_MT SUNLinearSolver +` will be built (see section +:numref:`Installation.LibrariesAndHeaders.LinearSolver.SuperLU_MT` for the +corresponding header file and library). + +To enable SuperLU_MT support, set :cmakeop:`ENABLE_SUPERLUMT` to ``ON``, set +:cmakeop:`SUPERLUMT_INCLUDE_DIR` and :cmakeop:`SUPERLUMT_LIBRARY_DIR` to the +location of the header and library files, respectively, of the SuperLU_MT +installation. Depending on the SuperLU_MT installation, it may also be necessary +to set :cmakeop:`SUPERLUMT_LIBRARIES` 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 :cmakeop:`SUPERLUMT_THREAD_TYPE` must be set to +either ``Pthread`` or ``OpenMP``. For example, the following command will +configure SUNDIALS with SuperLU_MT support using PThreads: + +.. code-block:: bash + + cmake \ + -S SOLVER_DIR \ + -B BUILD_DIR \ + -D CMAKE_INSTALL_PREFIX=INSTALL_DIR \ + -D ENABLE_SUPERLUMT=ON \ + -D SUPERLUMT_INCLUDE_DIR=/path/to/superlumt/installation/include/dir \ + -D SUPERLUMT_LIBRARY_DIR=/path/to/superlumt/installation/library/dir \ + -D SUPERLUMT_THREAD_TYPE="Pthread" + +.. warning:: + + Do not mix thread types when using SUNDIALS packages. For example, if using the + OpenMP or PThreads NVector then the SuperLU_MT installation should use the same + threading type. + +.. cmakeoption:: ENABLE_SUPERLUMT + + Enable SuperLU_MT support + + Default: ``OFF`` + +.. cmakeoption:: 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 + +.. cmakeoption:: SUPERLUMT_LIBRARY_DIR + + Path to SuperLU_MT installed library files + + Default: none + +.. cmakeoption:: SUPERLUMT_LIBRARIES + + Semi-colon separated list of libraries needed for SuperLU_MT + + Default: none + +.. cmakeoption:: SUPERLUMT_THREAD_TYPE + + Must be set to Pthread or OpenMP, depending on how SuperLU_MT was compiled. + + Default: Pthread + +.. _Installation.Options.SYCL: + +Building with SYCL +^^^^^^^^^^^^^^^^^^ + +`SYCL `__ is an abstraction layer for programming +heterogeneous parallel computing based on C++17. + +When SYCL support is enabled, the :ref:`SYCL NVector ` will +be built (see section :numref:`Installation.LibrariesAndHeaders.Vector.SYCL` +for the corresponding header file and library). + +To enable SYCL support, set the :cmakeop:`ENABLE_SYCL` to ``ON``. For example, +the following command will configure SUNDIALS with SYCL support using Intel +compilers: + +.. code-block:: bash + + cmake \ + -S SOLVER_DIR \ + -B BUILD_DIR \ + -D CMAKE_INSTALL_PREFIX=INSTALL_DIR \ + -D CMAKE_C_COMPILER=icx \ + -D CMAKE_CXX_COMPILER=icpx \ + -D CMAKE_CXX_FLAGS="-fsycl" \ + -D ENABLE_SYCL=ON + +.. cmakeoption:: ENABLE_SYCL + + Enable SYCL support + + Default: ``OFF`` + + .. note:: + + Building with SYCL enabled requires a compiler that supports a subset of + the of SYCL 2020 specification (specifically ``sycl/sycl.hpp`` must be + available). + + CMake does not currently support autodetection of SYCL compilers and + :cmakeop:`CMAKE_CXX_COMPILER` must be set to a valid SYCL compiler. At + present the only supported SYCL compilers are the Intel oneAPI compilers + i.e., ``dpcpp`` and ``icpx``. When using ``icpx`` the ``-fsycl`` flag and + any ahead of time compilation flags must be added to + :cmakeop:`CMAKE_CXX_FLAGS`. + +.. cmakeoption:: SUNDIALS_SYCL_2020_UNSUPPORTED + + This advanced option disables the use of *some* features from the SYCL 2020 + standard in SUNDIALS libraries and examples. This can be used to work around + some cases of incomplete compiler support for SYCL 2020. + + Default: ``OFF`` + +.. _Installation.Options.Trilinos: + +Building with Trilinos +^^^^^^^^^^^^^^^^^^^^^^ + +`Trilinos `__ is a collection of C++ libraries of +linear solvers, non-linear solvers, optimization solvers, etc. developed by +Sandia National Laboratory and available from the `Trilinos GitHub repository +`__. SUNDIALS is regularly tested with +the latest versions of Trilinos, specifically up to version 16.0.0. + +When Trilinos support is enabled, the :ref:`Trilinos Tpetra NVector +` will be built (see section +:numref:`Installation.LibrariesAndHeaders.Vector.Trilinos` for the corresponding +header file and library). + +To enable Trilinos support, set the :cmakeop:`ENABLE_TRILINOS` to ``ON`` and set +:cmakeop:`Trilinos_DIR` to root path of the Trilinos installation. For example, +the following command will configure SUNDIALS with Trilinos support: + +.. code-block:: bash + + cmake \ + -S SOLVER_DIR \ + -B BUILD_DIR \ + -D CMAKE_INSTALL_PREFIX=INSTALL_DIR \ + -D ENABLE_TRILONOS=ON \ + -D TRILINOS_DIR=/path/to/trilinos/installation + +.. cmakeoption:: ENABLE_TRILINOS + + Enable Trilinos support + + Default: ``OFF`` .. cmakeoption:: Trilinos_DIR - Path to the Trilinos installation. + Path to the Trilinos installation + + Default: None + +.. _Installation.Options.XBraid: + +Building with XBraid +^^^^^^^^^^^^^^^^^^^^ + +XBraid is parallel-in-time library implementing an optimal-scaling multigrid +reduction in time (MGRIT) solver. The library is developed by Lawrence Livermore +National Laboratory and is available from the `XBraid GitHub repository +`__. SUNDIALS is regularly tested with the +latest versions of XBraid, specifically up to version 3.0.0. + +To enable XBraid support, set :cmakeop:`ENABLE_MPI` to ``ON``, set +:cmakeop:`ENABLE_XBRAID` to ``ON``, set :cmakeop:`XBRAID_DIR` to the root path +of the XBraid installation. For example, the following command will configure +SUNDIALS with XBraid support: + +.. code-block:: bash + + cmake \ + -S SOLVER_DIR \ + -B BUILD_DIR \ + -D CMAKE_INSTALL_PREFIX=INSTALL_DIR \ + -D SUNDIALS_INDEX_SIZE="32" \ + -D ENABLE_MPI=ON \ + -D ENABLE_XBRAID=ON \ + -D XBRAID_DIR=/path/to/xbraid/installation + +.. 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 :cmakeop:`SUNDIALS_INDEX_SIZE` set to ``32`` and + :cmakeop:`SUNDIALS_PRECISION` set to ``double``. Additionally, SUNDIALS must + be configured with :cmakeop:`ENABLE_MPI` set to ``ON``. + +.. cmakeoption:: ENABLE_XBRAID + + Enable or disable the ARKStep + XBraid interface. + + Default: ``OFF`` + +.. cmakeoption:: XBRAID_DIR + + The root directory of the XBraid installation. + + Default: ``OFF`` + +.. cmakeoption:: 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 + :cmakeop:`XBRAID_DIR`. + + Default: none + +.. cmakeoption:: XBRAID_LIBRARIES - Default: None + Semi-colon separated list of XBraid link libraries. Unless provided by + the user, this is autopopulated based on the XBraid installation found in + :cmakeop:`XBRAID_DIR`. + + Default: none + +.. _Installation.Options.xSDK: + +Building with xSDK Defaults +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The `Extreme-scale Scientific Software Development Kit (xSDK) +`__ is a community of HPC libraries and applications +developing best practices and standards for scientific software. + +.. cmakeoption:: USE_XSDK_DEFAULTS + + Enable xSDK default configuration settings. This sets the default value for + :cmakeop:`CMAKE_BUILD_TYPE` to ``Debug``, :cmakeop:`SUNDIALS_INDEX_SIZE` to + ``32``, and :cmakeop:`SUNDIALS_PRECISION` to ``double``. + + Default: ``OFF`` + +.. _Installation.Options.Addons: + +Building with External Addons +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +SUNDIALS "addons" are community developed code additions for SUNDIALS that can +be subsumed by the SUNDIALS build system so that they have full access to all +internal SUNDIALS symbols. The intent is for SUNDIALS addons to function as if +they are part of the SUNDIALS library, while allowing them to potentially have +different licenses (although we encourage BSD-3-Clause still), code style +(although we encourage them to follow the SUNDIALS style outlined :ref:`here +`). + +.. warning:: + + SUNDIALS addons are not maintained by the SUNDIALS team and may come with + different licenses. Use them at your own risk. + +To build with SUNDIALS addons, + +1. Clone/copy the addon(s) into ``SOLVER_DIR/external/`` + +2. Copy the ``sundials-addon-example`` block in the + ``SOLVER_DIR/external/CMakeLists.txt``, paste it below the example block, and + modify the path listed for your own external addon(s). + +3. When building SUNDIALS, set the CMake option + :cmakeop:`SUNDIALS_ENABLE_EXTERNAL_ADDONS` to ``ON`` + +4. Build SUNDIALS as usual. + +.. cmakeoption:: SUNDIALS_ENABLE_EXTERNAL_ADDONS + + Build SUNDIALS with any external addons that you have put in + ``SOLVER_DIR/external``. + + Default: ``OFF`` + +.. _Installation.Testing: + +Testing the Build and Installation +---------------------------------- + +If SUNDIALS was configured with any ``EXAMPLES_ENABLE_`` options set +to ``ON``, then a set of regression tests can be run after building with the +command: + +.. code-block:: bash + + make test + +Additionally, if :cmakeop:`EXAMPLES_INSTALL` is set to ``ON``, then a set of +smoke tests can be run after installing with the command: + +.. code-block:: bash + + make test_install + +.. _Installation.BuildRunExamples: + +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 one of the +``EXAMPLES_ENABLE_`` options to ``ON``, and set +:cmakeop:`EXAMPLES_INSTALL` to ``ON``. Along side the example sources and +outputs, automatically generated ``CMakeLists.txt`` configuration files (and +``Makefile`` files if on Linux/Unix systems) are installed referencing the +*installed* SUNDIALS headers and libraries. + +Either the ``CMakeLists.txt`` file or the traditional ``Makefile`` may be used +to build the examples and serve as a template for building user developed +problems. 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. + +.. _Installation.UsingSUNDIALS: + +Using SUNDIALS In Your Project +------------------------------ + +After installing SUNDIALS, building your application with SUNDIALS involves two +steps: including the right header files and linking to the right libraries. +Depending on what features of SUNDIALS that your application uses, the header +files and libraries needed will vary. For example, if you want to use CVODE for +serial computations you need the following includes: + +.. code-block:: c + + #include + #include + +and must link to ``libsundials_cvode`` and ``libsundials_nvecserial``. If you +wanted to use CVODE with the GMRES linear solver and the CUDA NVector, you need +the following includes: + +.. code-block:: c + + #include + #include + #include + +and must link to ``libsundials_cvode``, ``libsundials_nveccuda``, and +``libsundials_sunlinsolspgmr``. + +.. attention:: + + .. versionadded:: 7.0.0 + + All applications must also link to ``libsundials_core``. For projects + using SUNDIALS CMake targets (see section + :numref:`Installation.CMakeConfigFile`), this dependency is automatically + included. + +Refer to section :numref:`Installation.LibrariesAndHeaders` below or the +documentations sections for the individual SUNDIALS packages and modules of +interest for the proper includes and libraries to link against. + +.. _Installation.CMakeConfigFile: + +CMake Projects +^^^^^^^^^^^^^^ + +For projects that use CMake, the SUNDIALS `CMake package configuration file +`__ provides +CMake targets for the consuming project. Use the CMake ``find_package`` command +to search for the configuration file, ``SUNDIALSConfig.cmake``, which is +installed alongside a package version file, ``SUNDIALSConfigVersion.cmake``, +under the ``INSTALL_DIR/SUNDIALS_INSTALL_CMAKEDIR`` directory. The SUNDIALS +CMake targets follow the same naming convention as the generated library +binaries with the ``libsundials_`` prefix replaced by ``SUNDIALS::``. For +example, the exported target for ``libsundials_cvode`` is +``SUNDIALS::cvode``. See section :numref:`Installation.LibrariesAndHeaders` for +a complete list of CMake targets. The CMake code snippit below shows how a +consuming project might leverage the SUNDIALS package configuration file to +build against SUNDIALS in their own CMake project. + +.. code-block:: cmake + + project(MyProject) + + # Set the variable SUNDIALS_DIR to the SUNDIALS instdir. + # When using the cmake CLI command, this can be done like so: + # cmake -D SUNDIALS_DIR=/path/to/sundials/installation + + # Find any SUNDIALS version... + find_package(SUNDIALS REQUIRED) + + # ... or find any version newer than some minimum... + find_package(SUNDIALS 7.1.0 REQUIRED) + + # ... or find a version in a range + find_package(SUNDIALS 7.0.0...7.1.0 REQUIRED) + + # To check if specific components are available in the SUNDIALS installation, + # use the COMPONENTS option followed by the desired target names + find_package(SUNDIALS REQUIRED COMPONENTS cvode nvecpetsc) + + add_executable(myexec main.c) + + # Link to SUNDIALS libraries through the exported targets. + # This is just an example, users should link to the targets appropriate + # for their use case. + target_link_libraries(myexec PUBLIC SUNDIALS::cvode SUNDIALS::nvecpetsc) + +.. note:: + + .. versionchanged:: 7.1.0 + + A single version provided to ``find_package`` denotes the minimum version + of SUNDIALS to look for, and any version equal or newer than what is + specified will match. In prior versions ``SUNDIALSConfig.cmake`` required + the version found to have the same major version number as the single + version provided to ``find_package``. + +To accommodate installing both static and shared libraries simultaneously, +targets are created with ``_static`` and ``_shared`` suffixes, respectively, and +the un-suffixed target is an alias to the ``_shared`` version. For example, +``SUNDIALS::cvode`` is an alias to ``SUNDIALS::cvode_shared`` in this +case. Projects that wish to use static libraries should use the ``_static`` +version of the target when both library types are installed. When only static or +shared libraries (not both) are installed the un-suffixed alias corresponds to +the library type chosen at configuration time (see section +:numref:`Installation.Options.LibraryTypes`). + +.. _Installation.LibrariesAndHeaders: + +Libraries and Header Files +-------------------------- + +As noted above, the SUNDIALS the header files and libraries are installed under +the :cmakeop:`CMAKE_INSTALL_PREFIX` path in the ``include`` and +:cmakeop:`CMAKE_INSTALL_LIBDIR` subdirectories, respectively. The public header +files are further organized into subdirectories under the ``include`` directory. +The installed public header files and libraries are listed for reference in the +sections below. Additionally, the exported CMake targets are also listed for +projects using CMake (see section :numref:`Installation.CMakeConfigFile`). The +file extension ``.LIB`` used below is typically ``.so``, ``.dll``, or ``.dylib`` +for shared libraries and ``.a`` or ``.lib`` for static libraries. + +.. warning:: + + SUNDIALS installs some header files to + ``CMAKE_INSTALL_PREFIX/include/sundials/priv``. All of the header files in + this directory are private and **should not be included in user code**. The + private headers are subject to change without any notice and relying on them + may break your code. + +.. _Installation.LibrariesAndHeaders.Core: + +SUNDIALS Core +^^^^^^^^^^^^^ + +The core library contains the shared infrastructure utilized by SUNDIALS +packages. All applications using SUNDIALS must link against the core +library. For codes using the SUNDIALS CMake targets, the core target is +automatically included as needed by other targets. + +.. table:: The SUNDIALS core library, header, and CMake target + :align: center + + +--------------+----------------------------------------------+ + | Libraries | ``libsundials_core.LIB`` | + +--------------+----------------------------------------------+ + | Headers | ``sundials/sundials_core.h`` | + +--------------+----------------------------------------------+ + | CMake target | ``SUNDIALS::core`` | + +--------------+----------------------------------------------+ + +The core header file is a convenient way to include all the header files that +make up the SUNDIALS core infrastructure. + +.. table:: Header files included by ``sundials_core.h`` + :align: center + + +--------------+----------------------------------------------+ + | Headers | ``sundials/sundials_adaptcontroller.h`` | + | +----------------------------------------------+ + | | ``sundials/sundials_config.h`` | + | +----------------------------------------------+ + | | ``sundials/sundials_context.h`` | + | +----------------------------------------------+ + | | ``sundials/sundials_errors.h`` | + | +----------------------------------------------+ + | | ``sundials/sundials_iterative.h`` | + | +----------------------------------------------+ + | | ``sundials/sundials_linearsolver.h`` | + | +----------------------------------------------+ + | | ``sundials/sundials_logger.h`` | + | +----------------------------------------------+ + | | ``sundials/sundials_math.h`` | + | +----------------------------------------------+ + | | ``sundials/sundials_matrix.h`` | + | +----------------------------------------------+ + | | ``sundials/sundials_memory.h`` | + | +----------------------------------------------+ + | | ``sundials/sundials_nonlinearsolver.h`` | + | +----------------------------------------------+ + | | ``sundials/sundials_nvector.h`` | + | +----------------------------------------------+ + | | ``sundials/sundials_profiler.h`` | + | +----------------------------------------------+ + | | ``sundials/sundials_types.h`` | + | +----------------------------------------------+ + | | ``sundials/sundials_version.h`` | + +--------------+----------------------------------------------+ + +For C++ applications, several convenience classes are provided for interacting +with SUNDIALS objects. These can be accessed by including the C++ core header +file. + +.. table:: The SUNDIALS C++ core header file + :align: center + + +--------------+----------------------------------------------+ + | Headers | ``sundials/sundials_core.hpp`` | + +--------------+----------------------------------------------+ + +Like the C core header file, the C++ core header file is a convenient way to +include all the header files for the core C++ classes. + +.. warning:: + + Features in the ``sundials::experimental`` namespace are not yet part of the + public API and are subject to change or removal without notice. + +.. table:: Header files included by ``sundials_core.hpp`` + :align: center + + +--------------+----------------------------------------------+ + | Headers | ``sundials/sundials_context.hpp`` | + | +----------------------------------------------+ + | | ``sundials/sundials_core.h`` | + | +----------------------------------------------+ + | | ``sundials/sundials_linearsolver.hpp`` | + | +----------------------------------------------+ + | | ``sundials/sundials_matrix.hpp`` | + | +----------------------------------------------+ + | | ``sundials/sundials_memory.hpp`` | + | +----------------------------------------------+ + | | ``sundials/sundials_nonlinearsolver.hpp`` | + | +----------------------------------------------+ + | | ``sundials/sundials_nvector.hpp`` | + | +----------------------------------------------+ + | | ``sundials/sundials_profiler.hpp`` | + +--------------+----------------------------------------------+ + +When MPI support is enabled (:cmakeop:`ENABLE_MPI` is ``ON``), the following +header file provides aliases between MPI data types and SUNDIALS types. The +alias ``MPI_SUNREALTYPE`` is one of ``MPI_FLOAT``, ``MPI_DOUBLE``, or +``MPI_LONG_DOUBLE`` depending on the value of :cmakeop:`SUNDIALS_PRECISION`. The +alias ``MPI_SUNINDEXTYPE`` is either ``MPI_INT32_T`` or ``MPI_INT64_T`` +depending on the value of :cmakeop:`SUNDIALS_INDEX_SIZE`. + +.. table:: Header file defining aliases between SUNDIALS and MPI data types + :align: center + + +--------------+----------------------------------------------+ + | Headers | ``sundials/sundials_mpi_types.h`` | + +--------------+----------------------------------------------+ + +When XBraid support is enabled (:cmakeop:`ENABLE_XBRAID` is ``ON``), the +following header file defines types and functions for interfacing SUNDIALS with +XBraid. + +.. table:: SUNDIALS header for interfacing with XBraid + :align: center + + +--------------+----------------------------------------------+ + | Headers | ``sundials/sundials_xbraid.h`` | + +--------------+----------------------------------------------+ + +.. _Installation.LibrariesAndHeaders.Packages: + +SUNDIALS Packages +^^^^^^^^^^^^^^^^^ + +.. _Installation.LibrariesAndHeaders.Packages.CVODE: + +CVODE +""""" + +To use the :ref:`CVODE ` package, include the header file and link to the +library given below. + +.. table:: CVODE library, header file, and CMake target + :align: center + + +--------------+----------------------------------------------+ + | Libraries | ``libsundials_cvode.LIB`` | + +--------------+----------------------------------------------+ + | Headers | ``cvode/cvode.h`` | + +--------------+----------------------------------------------+ + | CMake target | ``SUNDIALS::cvode`` | + +--------------+----------------------------------------------+ + +The CVODE header file includes the files below which define functions, types, +and constants for the CVODE linear solver interface and using projection methods +with CVODE. + +.. table:: Additional header files included by ``cvode.h`` + :align: center + + +--------------+----------------------------------------------+ + | Headers | ``cvode/cvode_ls.h`` | + | +----------------------------------------------+ + | | ``cvode/cvode_proj.h`` | + +--------------+----------------------------------------------+ + +CVODE provides a specialized linear solver module for diagonal linear +systems. Include the header file below to access the related functions. + +.. table:: CVODE diagonal linear solver + :align: center + + +--------------+----------------------------------------------+ + | Headers | ``cvode/cvode_diag.h`` | + +--------------+----------------------------------------------+ + +For problems in which the user cannot define a more effective, problem-specific +preconditioner for Krylov iterative linear solvers, CVODE provides banded +(``bandpre``) and band-block-diagonal (``bbdpre``) preconditioner +modules. Include the header files below to access the related functions. + +.. table:: CVODE preconditioner modules + :align: center + + +--------------+----------------------------------------------+ + | Headers | ``cvode/cvode_bandpre.h`` | + | +----------------------------------------------+ + | | ``cvode/cvode_bbdpre.h`` | + +--------------+----------------------------------------------+ + +.. _Installation.LibrariesAndHeaders.Packages.CVODES: + +CVODES +"""""" + +To use the :ref:`CVODES ` package, include the header file and link to +the library given below. + +.. warning:: + + CVODES is a superset of CVODE and defines the same functions as provided by + CVODE. As such, applications should not link to both CVODES and CVODE. + +.. table:: CVODES library, header file, and CMake target + :align: center + + +--------------+----------------------------------------------+ + | Libraries | ``libsundials_cvodes.LIB`` | + +--------------+----------------------------------------------+ + | Headers | ``cvodes/cvodes.h`` | + +--------------+----------------------------------------------+ + | CMake target | ``SUNDIALS::cvodes`` | + +--------------+----------------------------------------------+ + +The CVODES header file includes the files below which define functions, types, +and constants for the CVODES linear solver interface and using projection +methods with CVODES. + +.. table:: Additional header files included by ``cvodes.h`` + :align: center + + +--------------+----------------------------------------------+ + | Headers | ``cvodes/cvodes_ls.h`` | + | +----------------------------------------------+ + | | ``cvodes/cvodes_proj.h`` | + +--------------+----------------------------------------------+ + +CVODES provides a specialized linear solver module for diagonal linear +systems. Include the header file below to access the related functions. + +.. table:: CVODES diagonal linear solver + :align: center + + +--------------+----------------------------------------------+ + | Headers | ``cvodes/cvodes_diag.h`` | + +--------------+----------------------------------------------+ + +For problems in which the user cannot define a more effective, problem-specific +preconditioner for Krylov iterative linear solvers, CVODES provides banded +(``bandpre``) and band-block-diagonal (``bbdpre``) preconditioner +modules. Include the header files below to access the related functions. + +.. table:: CVODES preconditioner modules + :align: center + + +--------------+----------------------------------------------+ + | Headers | ``cvodes/cvodes_bandpre.h`` | + | +----------------------------------------------+ + | | ``cvodes/cvodes_bbdpre.h`` | + +--------------+----------------------------------------------+ + +.. _Installation.LibrariesAndHeaders.Packages.ARKODE: + +ARKODE +"""""" + +To use the :ref:`ARKODE ` package, link to the library below and include +the header file for the desired module. + +.. table:: ARKODE library, header files, and CMake target + :align: center + + +--------------+----------------------------------------------+ + | Libraries | ``libsundials_arkode.LIB`` | + +--------------+----------------------------------------------+ + | Headers | ``arkode/arkode_arkstep.h`` | + | +----------------------------------------------+ + | | ``arkode/arkode_erkstep.h`` | + | +----------------------------------------------+ + | | ``arkode/arkode_forcingstep.h`` | + | +----------------------------------------------+ + | | ``arkode/arkode_lsrkstep.h`` | + | +----------------------------------------------+ + | | ``arkode/arkode_mristep.h`` | + | +----------------------------------------------+ + | | ``arkode/arkode_splittingstep.h`` | + | +----------------------------------------------+ + | | ``arkode/arkode_sprkstep.h`` | + +--------------+----------------------------------------------+ + | CMake target | ``SUNDIALS::arkode`` | + +--------------+----------------------------------------------+ + +The ARKODE module header files include the header file for the shared ARKODE +interface functions, constants, and types (``arkode.h``). As appropriate, the +module header files also include the ARKODE linear solver interface as well as +the header files defining method coefficients. + +.. table:: Additional header files included by ``arkode_*step.h`` header files + :align: center + + +--------------+----------------------------------------------+ + | Headers | ``arkode/arkode.h`` | + | +----------------------------------------------+ + | | ``arkode/arkode_butcher.h`` | + | +----------------------------------------------+ + | | ``arkode/arkode_butcher_dirk.h`` | + | +----------------------------------------------+ + | | ``arkode/arkode_butcher_erk.h`` | + | +----------------------------------------------+ + | | ``arkode/arkode_ls.h`` | + | +----------------------------------------------+ + | | ``arkode/arkode_sprk.h`` | + +--------------+----------------------------------------------+ + +For problems in which the user cannot define a more effective, problem-specific +preconditioner for Krylov iterative linear solvers, ARKODE provides banded +(``bandpre``) and band-block-diagonal (``bbdpre``) preconditioner +modules. Include the header files below to access the related functions. + +.. table:: ARKODE preconditioner modules + :align: center + + +--------------+----------------------------------------------+ + | Headers | ``arkode/arkode_bandpre.h`` | + | +----------------------------------------------+ + | | ``arkode/arkode_bbdpre.h`` | + +--------------+----------------------------------------------+ + +When XBraid support is enabled (:cmakeop:`ENABLE_XBRAID` is ``ON``), include the +ARKODE-XBraid interface header file and link to the interface library given +below to use ARKODE and XBraid together. + +.. table:: ARKODE library, header, and CMake target for interfacing with XBraid + :align: center + + +--------------+----------------------------------------------+ + | Libraries | ``libsundials_arkode_xbraid.LIB`` | + +--------------+----------------------------------------------+ + | Headers | ``arkode/arkode_xbraid.h`` | + +--------------+----------------------------------------------+ + | CMake target | ``SUNDIALS::arkode_xbraid`` | + +--------------+----------------------------------------------+ + +.. _Installation.LibrariesAndHeaders.Packages.IDA: + +IDA +""" + +To use the :ref:`IDA ` package, include the header file and link to the +library given below. + +.. table:: IDA library, header file, and CMake target + :align: center + + +--------------+----------------------------------------------+ + | Libraries | ``libsundials_ida.LIB`` | + +--------------+----------------------------------------------+ + | Headers | ``ida/ida.h`` | + +--------------+----------------------------------------------+ + | CMake target | ``SUNDIALS::ida`` | + +--------------+----------------------------------------------+ + +The IDA header file includes the header file below which defines functions, +types, and constants for the IDA linear solver interface. + +.. table:: Additional header files included by ``ida.h`` + :align: center + + +--------------+----------------------------------------------+ + | Headers | ``ida/ida_ls.h`` | + +--------------+----------------------------------------------+ + +For problems in which the user cannot define a more effective, problem-specific +preconditioner for Krylov iterative linear solvers, IDA provides a +band-block-diagonal (``bbdpre``) preconditioner module. Include the header +file below to access the related functions. + +.. table:: IDA preconditioner modules + :align: center + + +--------------+----------------------------------------------+ + | Headers | ``ida/ida_bbdpre.h`` | + +--------------+----------------------------------------------+ + +.. _Installation.LibrariesAndHeaders.Packages.IDAS: + +IDAS +"""" + +To use the :ref:`IDAS ` package, include the header file and link to the +library given below. + +.. warning:: + + IDAS is a superset of IDA and defines the same functions as provided by + IDA. As such, applications should not link to both IDAS and IDA. + + +.. table:: IDAS library, header file, and CMake target + :align: center + + +--------------+----------------------------------------------+ + | Libraries | ``libsundials_idas.LIB`` | + +--------------+----------------------------------------------+ + | Headers | ``idas/idas.h`` | + +--------------+----------------------------------------------+ + | CMake target | ``SUNDIALS::idas`` | + +--------------+----------------------------------------------+ + +The IDAS header file includes the header file below which defines functions, +types, and constants for the IDAS linear solver interface. + +.. table:: Additional header files included by ``idas.h`` + :align: center + + +--------------+----------------------------------------------+ + | Headers | ``idas/idas_ls.h`` | + +--------------+----------------------------------------------+ + +For problems in which the user cannot define a more effective, problem-specific +preconditioner for Krylov iterative linear solvers, IDAS provides a +band-block-diagonal (``bbdpre``) preconditioner module. Include the header +file below to access the related functions. + +.. table:: IDAS preconditioner modules + :align: center + + +--------------+----------------------------------------------+ + | Headers | ``idas/idas_bbdpre.h`` | + +--------------+----------------------------------------------+ + +.. _Installation.LibrariesAndHeaders.Packages.KINSOL: + +KINSOL +"""""" + +To use the :ref:`KINSOL ` package, include the header file and link to +the library given below. + +.. table:: KINSOL library, header file, and CMake target + :align: center + + +--------------+----------------------------------------------+ + | Libraries | ``libsundials_kinsol.LIB`` | + +--------------+----------------------------------------------+ + | Headers | ``kinsol/kinsol.h`` | + +--------------+----------------------------------------------+ + | CMake target | ``SUNDIALS::kinsol`` | + +--------------+----------------------------------------------+ + +The KINSOL header file includes the header file below which defines functions, +types, and constants for the KINSOL linear solver interface. + +.. table:: Additional header files included by ``kinsol.h`` + :align: center + + +--------------+----------------------------------------------+ + | Headers | ``kinsol/kinsol_ls.h`` | + +--------------+----------------------------------------------+ + +For problems in which the user cannot define a more effective, problem-specific +preconditioner for Krylov iterative linear solvers, KINSOL provides a +band-block-diagonal (``bbdpre``) preconditioner module. Include the header +file below to access the related functions. + +.. table:: KINSOL preconditioner modules + :align: center + + +--------------+----------------------------------------------+ + | Headers | ``kinsol/kinsol_bbdpre.h`` | + +--------------+----------------------------------------------+ + +.. _Installation.LibrariesAndHeaders.Vector: + +Vectors +^^^^^^^ -.. cmakeoption:: ENABLE_CALIPER +.. _Installation.LibrariesAndHeaders.Vector.Serial: - Enable CALIPER support +Serial +"""""" - Default: OFF +To use the :ref:`serial NVector `, include the header file +and link to the library given below. - .. note:: +When using SUNDIALS time integration packages or the KINSOL package, the serial +NVector is bundled with the package library and it is not necessary to link to +the library below when using those packages. - Using Caliper requires setting :cmakeop:`SUNDIALS_BUILD_WITH_PROFILING` to - ``ON``. +.. table:: The serial NVector library, header file, and CMake target + :align: center -.. cmakeoption:: CALIPER_DIR + +--------------+----------------------------------------------+ + | Libraries | ``libsundials_nvecserial.LIB`` | + +--------------+----------------------------------------------+ + | Headers | ``nvector/nvector_serial.h`` | + +--------------+----------------------------------------------+ + | CMake target | ``SUNDIALS::nvecserial`` | + +--------------+----------------------------------------------+ - Path to the root of a Caliper installation +.. _Installation.LibrariesAndHeaders.Vector.ManyVector: - Default: None +ManyVector +"""""""""" -.. cmakeoption:: ENABLE_ADIAK +To use the :ref:`ManyVector NVector `, include the header +file and link to the library given below. - Enable Adiak support +.. table:: The ManyVector NVector library, header file, and CMake target + :align: center - Default: OFF + +--------------+----------------------------------------------+ + | Libraries | ``libsundials_nvecmanyvector.LIB`` | + +--------------+----------------------------------------------+ + | Headers | ``nvector/nvector_manyvector.h`` | + +--------------+----------------------------------------------+ + | CMake target | ``SUNDIALS::nvecmanyvector`` | + +--------------+----------------------------------------------+ -.. cmakeoption:: adiak_DIR +.. _Installation.LibrariesAndHeaders.Vector.Parallel: - Path to the root of an Adiak installation +Parallel (MPI) +"""""""""""""" - Default: None +To use the :ref:`parallel (MPI) NVector `, include the +header file and link to the library given below. -.. cmakeoption:: SUNDIALS_LAPACK_CASE +.. table:: The parallel (MPI) NVector library, header file, and CMake target + :align: center - Specify the case to use in the Fortran name-mangling scheme, - options are: ``lower`` or ``upper`` + +--------------+----------------------------------------------+ + | Libraries | ``libsundials_nvecparallel.LIB`` | + +--------------+----------------------------------------------+ + | Headers | ``nvector/nvector_parallel.h`` | + +--------------+----------------------------------------------+ + | CMake target | ``SUNDIALS::nvecparallel`` | + +--------------+----------------------------------------------+ - Default: +.. _Installation.LibrariesAndHeaders.Vector.MPIManyVector: - .. note:: +MPI ManyVector +"""""""""""""" - 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_LAPACK_UNDERSCORES`` must also be set. +To use the :ref:`MPI ManyVector NVector `, include the +header file and link to the library given below. -.. cmakeoption:: SUNDIALS_LAPACK_UNDERSCORES +.. table:: The MPI ManyVector NVector library, header file, and CMake target + :align: center - Specify the number of underscores to append in the Fortran - name-mangling scheme, options are: ``none``, ``one``, or ``two`` + +--------------+----------------------------------------------+ + | Libraries | ``libsundials_nvecmpimanyvector.LIB`` | + +--------------+----------------------------------------------+ + | Headers | ``nvector/nvector_mpimanyvector.h`` | + +--------------+----------------------------------------------+ + | CMake target | ``SUNDIALS::nvecmpimanyvector`` | + +--------------+----------------------------------------------+ - Default: +.. _Installation.LibrariesAndHeaders.Vector.MPIPlusX: - .. note:: +MPI+X +""""" - 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_LAPACK_CASE`` - must also be set. +To use the :ref:`MPI+X NVector `, include the header +file and link to the library given below. -.. cmakeoption:: SUNDIALS_INDEX_TYPE +.. table:: The MPI+X NVector library, header file, and CMake target + :align: center - Integer type used for SUNDIALS indices. The size must match the size - provided for the ``SUNDIALS_INDEX_SIZE`` option. + +--------------+----------------------------------------------+ + | Libraries | ``libsundials_nvecmpiplusx.LIB`` | + +--------------+----------------------------------------------+ + | Headers | ``nvector/nvector_mpiplusx.h`` | + +--------------+----------------------------------------------+ + | CMake target | ``SUNDIALS::nvecmpiplusx`` | + +--------------+----------------------------------------------+ - Default: Automatically determined based on :cmakeop:`SUNDIALS_INDEX_SIZE` +.. _Installation.LibrariesAndHeaders.Vector.OpenMP: - .. note:: +OpenMP +"""""" - 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 :cmakeop:`SUNDIALS_INDEX_SIZE` - option in most cases. +To use the :ref:`OpenMP NVector `, include the header file and +link to the library given below. -.. cmakeoption:: SUNDIALS_INDEX_SIZE +.. table:: The OpenMP NVector library, header file, and CMake target + :align: center - Integer size (in bits) used for indices in SUNDIALS, options are: ``32`` or - ``64`` + +--------------+----------------------------------------------+ + | Libraries | ``libsundials_nvecopenmp.LIB`` | + +--------------+----------------------------------------------+ + | Headers | ``nvector/nvector_openmp.h`` | + +--------------+----------------------------------------------+ + | CMake target | ``SUNDIALS::nvecopenmp`` | + +--------------+----------------------------------------------+ - Default: ``64`` +.. _Installation.LibrariesAndHeaders.Vector.OpenMPDEV: - .. note:: +OpenMPDEV +""""""""" - 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, :cmakeop:`SUNDIALS_INDEX_TYPE` can be used to provide - a type not listed here. +To use the :ref:`OpenMP device offload NVector `, include +the header file and link to the library given below. -.. cmakeoption:: SUNDIALS_PRECISION +.. table:: The OpenMP device offload NVector library, header file, and CMake + target + :align: center - The floating-point precision used in SUNDIALS packages and class - implementations, options are: ``double``, ``single``, or ``extended`` + +--------------+----------------------------------------------+ + | Libraries | ``libsundials_nvecopenmpdev.LIB`` | + +--------------+----------------------------------------------+ + | Headers | ``nvector/nvector_openmpdev.h`` | + +--------------+----------------------------------------------+ + | CMake target | ``SUNDIALS::nvecopenmpdev`` | + +--------------+----------------------------------------------+ - Default: ``double`` +.. _Installation.LibrariesAndHeaders.Vector.PThreads: -.. cmakeoption:: SUNDIALS_MATH_LIBRARY +PThreads +"""""""" - The standard C math library (e.g., ``libm``) to link with. +To use the :ref:`POSIX Threads NVector `, include the header +file and link to the library given below. - Default: ``-lm`` on Unix systems, none otherwise +.. table:: The POSIX Threads NVector library, header file, and CMake target + :align: center -.. cmakeoption:: SUNDIALS_INSTALL_CMAKEDIR + +--------------+----------------------------------------------+ + | Libraries | ``libsundials_nvecpthreads.LIB`` | + +--------------+----------------------------------------------+ + | Headers | ``nvector/nvector_pthreads.h`` | + +--------------+----------------------------------------------+ + | CMake target | ``SUNDIALS::nvecpthreads`` | + +--------------+----------------------------------------------+ - Installation directory for the SUNDIALS cmake files (relative to - :cmakeop:`CMAKE_INSTALL_PREFIX`). +.. _Installation.LibrariesAndHeaders.Vector.ParHyp: - Default: ``CMAKE_INSTALL_PREFIX/cmake/sundials`` +*hypre* (ParHyp) +"""""""""""""""" -.. cmakeoption:: ENABLE_XBRAID +To use the :ref:`hypre (ParHyp) NVector `, include the header +file and link to the library given below. - Enable or disable the ARKStep + XBraid interface. +.. table:: The *hypre* (ParHyp) NVector library, header file, and CMake target + :align: center - Default: ``OFF`` + +--------------+----------------------------------------------+ + | Libraries | ``libsundials_nvecparhyp.LIB`` | + +--------------+----------------------------------------------+ + | Headers | ``nvector/nvector_parhyp.h`` | + +--------------+----------------------------------------------+ + | CMake target | ``SUNDIALS::nvecparhyp`` | + +--------------+----------------------------------------------+ - .. note:: See additional information on building with *XBraid* - enabled in :numref:`Installation.CMake.ExternalLibraries`. +.. _Installation.LibrariesAndHeaders.Vector.PETSc: -.. cmakeoption:: XBRAID_DIR +PETSc +""""" - The root directory of the XBraid installation. +To use the :ref:`PETSc NVector `, include the header file and +link to the library given below. - Default: ``OFF`` +.. table:: The PETSc NVector library, header file, and CMake target + :align: center -.. cmakeoption:: XBRAID_INCLUDES + +--------------+----------------------------------------------+ + | Libraries | ``libsundials_nvecpetsc.LIB`` | + +--------------+----------------------------------------------+ + | Headers | ``nvector/nvector_petsc.h`` | + +--------------+----------------------------------------------+ + | CMake target | ``SUNDIALS::nvecpetsc`` | + +--------------+----------------------------------------------+ - 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``. +.. _Installation.LibrariesAndHeaders.Vector.CUDA: - Default: none +CUDA +"""" -.. cmakeoption:: XBRAID_LIBRARIES +To use the :ref:`CUDA NVector `, include the header +file and link to the library given below. - 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``. +.. table:: The CUDA NVector library, header file, and CMake target + :align: center - Default: none + +--------------+----------------------------------------------+ + | Libraries | ``libsundials_nveccuda.LIB`` | + +--------------+----------------------------------------------+ + | Headers | ``nvector/nvector_cuda.h`` | + +--------------+----------------------------------------------+ + | CMake target | ``SUNDIALS::nveccuda`` | + +--------------+----------------------------------------------+ -.. cmakeoption:: USE_XSDK_DEFAULTS +.. _Installation.LibrariesAndHeaders.Vector.HIP: - Enable xSDK (see `https://xsdk.info `_ for more - information) default configuration settings. This sets ``CMAKE_BUILD_TYPE`` - to ``Debug``, ``SUNDIALS_INDEX_SIZE`` to 32 and ``SUNDIALS_PRECISION`` to - double. +HIP +""" - Default: ``OFF`` +To use the :ref:`HIP NVector `, include the header +file and link to the library given below. +.. table:: The HIP NVector library, header file, and CMake target + :align: center -.. _Installation.CMake.Examples: + +--------------+----------------------------------------------+ + | Libraries | ``libsundials_nvechip.LIB`` | + +--------------+----------------------------------------------+ + | Headers | ``nvector/nvector_hip.h`` | + +--------------+----------------------------------------------+ + | CMake target | ``SUNDIALS::nvechip`` | + +--------------+----------------------------------------------+ -Configuration examples ------------------------------------ +.. _Installation.LibrariesAndHeaders.Vector.RAJA: -The following examples will help demonstrate usage of the CMake -configure options. +RAJA +"""" -To configure SUNDIALS using the default C and Fortran compilers, -and default ``mpicc`` and ``mpif90`` parallel compilers, -enable compilation of examples, and install libraries, headers, and -example sources under subdirectories of ``/home/myname/sundials/``, use: +To use the :ref:`RAJA NVector `, include the header +file and link to the library given below for the desired backend. -.. code-block:: bash +.. table:: The RAJA NVector libraries, header file, and CMake targets + :align: center - % cmake \ - > -DCMAKE_INSTALL_PREFIX=/home/myname/sundials/instdir \ - > -DEXAMPLES_INSTALL_PATH=/home/myname/sundials/instdir/examples \ - > -DENABLE_MPI=ON \ - > /home/myname/sundials/srcdir + +--------------+----------------------------------------------+ + | Libraries | ``libsundials_nveccudaraja.LIB`` | + | +----------------------------------------------+ + | | ``libsundials_nvechipraja.LIB`` | + | +----------------------------------------------+ + | | ``libsundials_nvecsyclraja.LIB`` | + +--------------+----------------------------------------------+ + | Headers | ``nvector/nvector_raja.h`` | + +--------------+----------------------------------------------+ + | CMake target | ``SUNDIALS::nveccudaraja`` | + | +----------------------------------------------+ + | | ``SUNDIALS::nvechipraja`` | + | +----------------------------------------------+ + | | ``SUNDIALS::nvecsyclraja`` | + +--------------+----------------------------------------------+ + +.. _Installation.LibrariesAndHeaders.Vector.SYCL: + +SYCL +"""" + +To use the :ref:`SYCL NVector `, include the header +file and link to the library given below. + +.. table:: The SYCL NVector library, header file, and CMake target + :align: center - % make install + +--------------+----------------------------------------------+ + | Libraries | ``libsundials_nvecsycl.LIB`` | + +--------------+----------------------------------------------+ + | Headers | ``nvector/nvector_sycl.h`` | + +--------------+----------------------------------------------+ + | CMake target | ``SUNDIALS::nvecsycl`` | + +--------------+----------------------------------------------+ +.. _Installation.LibrariesAndHeaders.Vector.Trilinos: -To disable installation of the examples, use: +Trilinos (Tpetra) +""""""""""""""""" -.. code-block:: bash +To use the :ref:`Trilinos (Tpetra) NVector `, include the +header file and link to the library given below. - % cmake \ - > -DCMAKE_INSTALL_PREFIX=/home/myname/sundials/instdir \ - > -DEXAMPLES_INSTALL_PATH=/home/myname/sundials/instdir/examples \ - > -DENABLE_MPI=ON \ - > -DEXAMPLES_INSTALL=OFF \ - > /home/myname/sundials/srcdir +.. table:: The Trilinos (Tpetra) NVector library, header file, and CMake target + :align: center - % make install + +--------------+----------------------------------------------+ + | Libraries | ``libsundials_nvectrilinos.LIB`` | + +--------------+----------------------------------------------+ + | Headers | ``nvector/nvector_trilinos.h`` | + +--------------+----------------------------------------------+ + | CMake target | ``SUNDIALS::nvectrilinos`` | + +--------------+----------------------------------------------+ +.. _Installation.LibrariesAndHeaders.Vector.Kokkos: +Kokkos +"""""" +To use the :ref:`Kokkos NVector `, include the header +file and link to the library given below. -.. _Installation.CMake.ExternalLibraries: +.. table:: The Kokkos NVector library, header file, and CMake target + :align: center -Working with external Libraries ------------------------------------ + +--------------+----------------------------------------------+ + | Headers | ``nvector/nvector_kokkos.hpp`` | + +--------------+----------------------------------------------+ + | CMake target | ``SUNDIALS::nveckokkos`` | + +--------------+----------------------------------------------+ -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. +.. _Installation.LibrariesAndHeaders.Matrix: +Matrices +^^^^^^^^ -.. _Installation.CMake.ExternalLibraries.Ginkgo: +.. _Installation.LibrariesAndHeaders.Matrix.Band: -Building with Ginkgo -^^^^^^^^^^^^^^^^^^^^ +Banded +"""""" -`Ginkgo `_ is a high-performance linear algebra library for -manycore systems, with a focus on solving sparse linear systems. It is implemented using modern -C++ (you will need at least a C++14 compliant compiler to build it), with GPU kernels implemented in -CUDA (for NVIDIA devices), HIP (for AMD devices) and SYCL/DPC++ (for Intel devices and other -supported hardware). To enable Ginkgo in SUNDIALS, set the :cmakeop:`ENABLE_GINKGO` to ``ON`` -and provide the path to the root of the Ginkgo installation in :cmakeop:`Ginkgo_DIR`. -Additionally, :cmakeop:`SUNDIALS_GINKGO_BACKENDS` must be set to a list of Ginkgo target -architectures/executors. E.g., +To use the :ref:`banded SUNMatrix `, include the header file and +link to the library given below. -.. code-block:: bash +When using SUNDIALS time integration packages or the KINSOL package, the banded +SUNMatrix is bundled with the package library and it is not necessary to link to +the library below when using those packages. - % cmake \ - > -DENABLE_GINKGO=ON \ - > -DGinkgo_DIR=/path/to/ginkgo/installation \ - > -DSUNDIALS_GINKGO_BACKENDS="REF;OMP;CUDA" \ - > /home/myname/sundials/srcdir +.. table:: The banded SUNMatrix library, header file, and CMake target + :align: center -The SUNDIALS interfaces to Ginkgo are not compatible with :cmakeop:`SUNDIALS_PRECISION` set -to ``extended``. + +--------------+----------------------------------------------+ + | Libraries | ``libsundials_sunmatrixband.LIB`` | + +--------------+----------------------------------------------+ + | Headers | ``sunmatrix/sunmatrix_band.h`` | + +--------------+----------------------------------------------+ + | CMake target | ``SUNDIALS::sunmatrixband`` | + +--------------+----------------------------------------------+ -.. _Installation.CMake.ExternalLibraries.Kokkos: +.. _Installation.LibrariesAndHeaders.Matrix.cuSPARSE: -Building with Kokkos -^^^^^^^^^^^^^^^^^^^^ +cuSPARSE +"""""""" -`Kokkos `_ is a modern C++ (requires -at least C++14) programming model for witting performance portable code for -multicore CPU and GPU-based systems including NVIDIA, AMD, and Intel -accelerators. To enable Kokkos in SUNDIALS, set the :cmakeop:`ENABLE_KOKKOS` to -``ON`` and provide the path to the root of the Kokkos installation in -:cmakeop:`Kokkos_DIR`. Additionally, the -`Kokkos-Kernels `_ library provides -common computational kernels for linear algebra. To enable Kokkos-Kernels in -SUNDIALS, set the :cmakeop:`ENABLE_KOKKOS_KERNELS` to ``ON`` and provide the -path to the root of the Kokkos-Kernels installation in -:cmakeop:`KokkosKernels_DIR` e.g., +To use the :ref:`cuSPARSE SUNMatrix `, include the header +file and link to the library given below. -.. code-block:: bash +.. table:: The cuSPARSE SUNMatrix library, header file, and CMake target + :align: center - % cmake \ - > -DENABLE_KOKKOS=ON \ - > -DKokkos_DIR=/path/to/kokkos/installation \ - > -DENABLE_KOKKOS_KERNELS=ON \ - > -DKokkosKernels_DIR=/path/to/kokkoskernels/installation \ - > /home/myname/sundials/srcdir + +--------------+----------------------------------------------+ + | Libraries | ``libsundials_sunmatrixcusparse.LIB`` | + +--------------+----------------------------------------------+ + | Headers | ``sunmatrix/sunmatrix_cusparse.h`` | + +--------------+----------------------------------------------+ + | CMake target | ``SUNDIALS::sunmatrixcusparse`` | + +--------------+----------------------------------------------+ -.. note:: +.. _Installation.LibrariesAndHeaders.Matrix.Dense: - The minimum supported version of Kokkos-Kernels 3.7.00. +Dense +""""" -.. _Installation.CMake.ExternalLibraries.LAPACK: +To use the :ref:`dense SUNMatrix `, include the header file and +link to the library given below. -Building with LAPACK -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +When using SUNDIALS time integration packages or the KINSOL package, the dense +SUNMatrix is bundled with the package library and it is not necessary to link to +the library below when using those packages. -To enable LAPACK, set the :cmakeop:`ENABLE_LAPACK` option to ``ON``. CMake will -attempt to find BLAS and LAPACK installations on the system and set the -variables :cmakeop:`BLAS_LIBRARIES`, :cmakeop:`BLAS_LINKER_FLAGS`, -:cmakeop:`LAPACK_LIBRARIES`, and :cmakeop:`LAPACK_LINKER_FLAGS`. To explicitly -specify the LAPACK library to build with, manually set the aforementioned -variables to the desired values when configuring the build. +.. table:: The dense SUNMatrix library, header file, and CMake target + :align: center -.. code-block:: bash + +--------------+----------------------------------------------+ + | Libraries | ``libsundials_sunmatrixdense.LIB`` | + +--------------+----------------------------------------------+ + | Headers | ``sunmatrix/sunmatrix_dense.h`` | + +--------------+----------------------------------------------+ + | CMake target | ``SUNDIALS::sunmatrixdense`` | + +--------------+----------------------------------------------+ - % cmake \ - > -DCMAKE_INSTALL_PREFIX=/home/myname/sundials/instdir \ - > -DEXAMPLES_INSTALL_PATH=/home/myname/sundials/instdir/examples \ - > -DENABLE_LAPACK=ON \ - > -DBLAS_LIBRARIES=/mylapackpath/lib/libblas.so \ - > -DLAPACK_LIBRARIES=/mylapackpath/lib/liblapack.so \ - > /home/myname/sundials/srcdir +.. _Installation.LibrariesAndHeaders.Matrix.Ginkgo: - % make install +Ginkgo +"""""" -.. note:: +To use the :ref:`Ginkgo SUNMatrix `, include the header file +given below. - 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. +.. table:: The Ginkgo SUNMatrix library, header file, and CMake target + :align: center -SUNDIALS has been tested with OpenBLAS 0.3.27. + +--------------+----------------------------------------------+ + | Headers | ``sunmatrix/sunmatrix_ginkgo.hpp`` | + +--------------+----------------------------------------------+ + | CMake target | ``SUNDIALS::sunmatrixginkgo`` | + +--------------+----------------------------------------------+ +.. _Installation.LibrariesAndHeaders.Matrix.KokkosKernels: -.. _Installation.CMake.ExternalLibraries.KLU: +KokkosKernels Dense +""""""""""""""""""" -Building with KLU -^^^^^^^^^^^^^^^^^^^^^^^^^^^ +To use the :ref:`KokkosKernels dense SUNMatrix `, include the +header file given below. -KLU is a software package for the direct solution of sparse nonsymmetric linear -systems of equations that arise in circuit simulation and is part of -SuiteSparse, a suite of sparse matrix software. The library is developed by -Texas A&M University and is available from the `SuiteSparse GitHub repository -`_. +.. table:: The dense KokkosKernels SUNMatrix library, header file, and CMake + target + :align: center -To enable KLU, set ``ENABLE_KLU`` 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. In that case, 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``. + +--------------+----------------------------------------------+ + | Headers | ``sunmatrix/sunmatrix_kokkosdense.hpp`` | + +--------------+----------------------------------------------+ + | CMake target | ``SUNDIALS::sunmatrixkokkosdense`` | + +--------------+----------------------------------------------+ -For SuiteSparse 7.4.0 and newer, the necessary information can also be gathered -from a CMake import target. If SuiteSparse is installed in a non-default -prefix, the path to the CMake Config file can be set using -``CMAKE_PREFIX_PATH``. In that case, the CMake configure step won't populate -the previously mentioned variables. It is still possible to set -``KLU_INCLUDE_DIR`` and ``KLU_LIBRARY_DIR`` which take precedence over a -potentially installed CMake import target file. +.. _Installation.LibrariesAndHeaders.Matrix.MAGMADense: -In either case, a CMake target ``SUNDIALS::KLU`` will be created if the KLU -library could be found. Dependent targets should link to that target. +MAGMA Dense +""""""""""" -SUNDIALS has been tested with SuiteSparse version 5.10.1. +To use the :ref:`MAGMA dense SUNMatrix `, include the +header file and link to the library given below. +.. table:: The dense MAGMA SUNMatrix library, header file, and CMake target + :align: center -.. _Installation.CMake.ExternalLibraries.SuperLU_DIST: + +--------------+----------------------------------------------+ + | Libraries | ``libsundials_sunmatrixmagmadense.LIB`` | + +--------------+----------------------------------------------+ + | Headers | ``sunmatrix/sunmatrix_magmadense.h`` | + +--------------+----------------------------------------------+ + | CMake target | ``SUNDIALS::sunmatrixmagmadense`` | + +--------------+----------------------------------------------+ -Building with SuperLU_DIST -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. _Installation.LibrariesAndHeaders.Matrix.oneMKLDense: -SuperLU_DIST is a general purpose library for the direct solution of large, -sparse, nonsymmetric systems of linear equations in a distributed memory -setting. The library is developed by Lawrence Berkeley National Laboratory and -is available from the `SuperLU_DIST GitHub repository -`_. +oneMKL Dense +"""""""""""" -To enable SuperLU_DIST, set :cmakeop:`ENABLE_SUPERLUDIST` to ``ON``, set -:cmakeop:`SUPERLUDIST_DIR` to the path where SuperLU_DIST is installed. -If SuperLU_DIST was built with OpenMP then the option :cmakeop:`SUPERLUDIST_OpenMP` -and :cmakeop:`ENABLE_OPENMP` should be set to ``ON``. +To use the :ref:`oneMKL dense SUNMatrix `, include the +header file and link to the library given below. -SUNDIALS supports SuperLU_DIST v7.0.0 -- v8.x.x and has been tested with -v7.2.0 and v8.1.0. +.. table:: The dense oneMKL SUNMatrix library, header file, and CMake target + :align: center + +--------------+----------------------------------------------+ + | Libraries | ``libsundials_sunmatrixonemkldense.LIB`` | + +--------------+----------------------------------------------+ + | Headers | ``sunmatrix/sunmatrix_onemkldense.h`` | + +--------------+----------------------------------------------+ + | CMake target | ``SUNDIALS::sunmatrixonemkldense`` | + +--------------+----------------------------------------------+ -.. _Installation.CMake.ExternalLibraries.SuperLU_MT: +.. _Installation.LibrariesAndHeaders.Matrix.Sparse: -Building with SuperLU_MT -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Sparse +"""""" -SuperLU_MT is a general purpose library for the direct solution of large, -sparse, nonsymmetric systems of linear equations on shared memory parallel -machines. The library is developed by Lawrence Berkeley National Laboratory and -is available from the `SuperLU_MT GitHub repository -`_. +To use the :ref:`sparse SUNMatrix `, include the header file +and link to the library given below. -To enable SuperLU_MT, set ``ENABLE_SUPERLUMT`` 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``. +When using SUNDIALS time integration packages or the KINSOL package, the sparse +SUNMatrix is bundled with the package library and it is not necessary to link to +the library below when using those packages. -Do not mix thread types when building SUNDIALS solvers. -If threading is enabled for SUNDIALS by having either -``ENABLE_OPENMP`` or ``ENABLE_PTHREAD`` set to ``ON`` then SuperLU_MT -should be set to use the same threading type. +.. table:: The sparse SUNMatrix library, header file, and CMake target + :align: center -SUNDIALS has been tested with SuperLU_MT version 3.1. + +--------------+----------------------------------------------+ + | Libraries | ``libsundials_sunmatrixsparse.LIB`` | + +--------------+----------------------------------------------+ + | Headers | ``sunmatrix/sunmatrix_sparse.h`` | + +--------------+----------------------------------------------+ + | CMake target | ``SUNDIALS::sunmatrixsparse`` | + +--------------+----------------------------------------------+ +.. _Installation.LibrariesAndHeaders.Matrix.SuperLU_DIST: -.. _Installation.CMake.ExternalLibraries.PETSc: +SuperLU_DIST (SLUNRloc) +""""""""""""""""""""""" -Building with PETSc -^^^^^^^^^^^^^^^^^^^^^^^^^^^ +To use the :ref:`SuperLU_DIST (SLUNRloc) SUNMatrix `, +include the header file and link to the library given below. -The Portable, Extensible Toolkit for Scientific Computation (PETSc) is a suite -of data structures and routines for simulating applications modeled by partial -differential equations. The library is developed by Argonne National Laboratory -and is available from the `PETSc GitLab repository -`_. +.. table:: The SuperLU_DIST (SLUNRloc) SUNMatrix library, header file, and CMake + target + :align: center -To enable PETSc, set ``ENABLE_PETSC`` to ``ON``, and set ``PETSC_DIR`` to the -path of the PETSc installation. Alternatively, a user can provide a list of -include paths in ``PETSC_INCLUDES`` and a list of complete paths to the PETSc -libraries in ``PETSC_LIBRARIES``. + +--------------+----------------------------------------------+ + | Libraries | ``libsundials_sunmatrixslunrloc.LIB`` | + +--------------+----------------------------------------------+ + | Headers | ``sunmatrix/sunmatrix_slunrloc.h`` | + +--------------+----------------------------------------------+ + | CMake target | ``SUNDIALS::sunmatrixslunrloc`` | + +--------------+----------------------------------------------+ -SUNDIALS is regularly tested with the latest PETSc versions, specifically -up to version 3.18.1 as of SUNDIALS version |version|. SUNDIALS -requires PETSc 3.5.0 or newer. +.. _Installation.LibrariesAndHeaders.LinearSolver: +Linear Solvers +^^^^^^^^^^^^^^ -.. _Installation.CMake.ExternalLibraries.hypre: +.. _Installation.LibrariesAndHeaders.LinearSolver.Band: -Building with *hypre* -^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Banded +"""""" -*hypre* is a library of high performance preconditioners and solvers featuring -multigrid methods for the solution of large, sparse linear systems of equations -on massively parallel computers. The library is developed by Lawrence Livermore -National Laboratory and is available from the `hypre GitHub repository -`_. +To use the :ref:`banded SUNLinearSolver `, include the header +file and link to the library given below. -To enable *hypre*, set ``ENABLE_HYPRE`` 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. +When using SUNDIALS time integration packages or the KINSOL package, the banded +SUNLinearSolver is bundled with the package library and it is not necessary to +link to the library below when using those packages. -.. note:: +.. table:: The banded SUNLinearSolver library, header file, and CMake target + :align: center - SUNDIALS must be configured so that ``SUNDIALS_INDEX_SIZE`` is compatible - with ``HYPRE_BigInt`` in the *hypre* installation. + +--------------+----------------------------------------------+ + | Libraries | ``libsundials_sunlinsolband.LIB`` | + +--------------+----------------------------------------------+ + | Headers | ``sunlinsol/sunlinsol_band.h`` | + +--------------+----------------------------------------------+ + | CMake target | ``SUNDIALS::sunlinsolband`` | + +--------------+----------------------------------------------+ -SUNDIALS is regularly tested with the latest versions of *hypre*, specifically -up to version 2.26.0 as of SUNDIALS version |version|. +.. _Installation.LibrariesAndHeaders.LinearSolver.cuSPARSE: +cuSPARSE Batched QR +""""""""""""""""""" -.. _Installation.CMake.ExternalLibraries.Magma: +To use the :ref:`cuSPARSE batched QR SUNLinearSolver `, +include the header file and link to the library given below. -Building with MAGMA -^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. table:: The cuSPARSE batched QR SUNLinearSolver library, header file, and + CMake target + :align: center -The Matrix Algebra on GPU and Multicore Architectures (MAGMA) project provides a -dense linear algebra library similar to LAPACK but targeting heterogeneous -architectures. The library is developed by the University of Tennessee and is -available from the `UTK webpage `_. + +--------------+----------------------------------------------+ + | Libraries | ``libsundials_sunlinsolcusolversp.LIB`` | + +--------------+----------------------------------------------+ + | Headers | ``sunlinsol/sunlinsol_cusolversp_batchqr.h`` | + +--------------+----------------------------------------------+ + | CMake target | ``SUNDIALS::sunlinsolcusolversp`` | + +--------------+----------------------------------------------+ -To enable the SUNDIALS MAGMA interface set ``ENABLE_MAGMA`` to ``ON``, -``MAGMA_DIR`` to the MAGMA installation path, and ``SUNDIALS_MAGMA_BACKENDS`` to -the desired MAGMA backend to use with SUNDIALS e.g., ``CUDA`` or ``HIP``. +.. _Installation.LibrariesAndHeaders.LinearSolver.Dense: -SUNDIALS has been tested with MAGMA version v2.6.1 and v2.6.2. +Dense +""""" +To use the :ref:`dense SUNLinearSolver `, include the header +file and link to the library given below. -.. _Installation.CMake.ExternalLibraries.OneMKL: +When using SUNDIALS time integration packages or the KINSOL package, the dense +SUNLinearSolver is bundled with the package library and it is not necessary to +link to the library below when using those packages. -Building with oneMKL for SYCL -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. table:: The dense SUNLinearSolver library, header file, and CMake target + :align: center -The Intel `oneAPI Math Kernel Library (oneMKL) -`_ -includes CPU and SYCL/DPC++ interfaces for LAPACK dense linear algebra routines. The -SUNDIALS oneMKL interface targets the SYCL/DPC++ routines, to utilize the CPU routine -see :numref:`Installation.CMake.ExternalLibraries.LAPACK`. + +--------------+----------------------------------------------+ + | Libraries | ``libsundials_sunlinsoldense.LIB`` | + +--------------+----------------------------------------------+ + | Headers | ``sunlinsol/sunlinsol_dense.h`` | + +--------------+----------------------------------------------+ + | CMake target | ``SUNDIALS::sunlinsoldense`` | + +--------------+----------------------------------------------+ -To enable the SUNDIALS oneMKL interface set ``ENABLE_ONEMKL`` to ``ON`` and -``ONEMKL_DIR`` to the oneMKL installation path. +.. _Installation.LibrariesAndHeaders.LinearSolver.Ginkgo: -SUNDIALS has been tested with oneMKL version 2021.4. +Ginkgo +"""""" +To use the :ref:`Ginkgo SUNLinearSolver `, include the header +file given below. -.. _Installation.CMake.ExternalLibraries.CUDA: +.. table:: The Ginkgo SUNLinearSolver header file and CMake target + :align: center -Building with CUDA -^^^^^^^^^^^^^^^^^^^^^^ + +--------------+----------------------------------------------+ + | Headers | ``sunlinsol/sunlinsol_ginkgo.hpp`` | + +--------------+----------------------------------------------+ + | CMake target | ``SUNDIALS::sunlinsolginkgo`` | + +--------------+----------------------------------------------+ -The NVIDIA CUDA Toolkit provides a development environment for GPU-accelerated -computing with NVIDIA GPUs. The CUDA Toolkit and compatible NVIDIA drivers are -available from the `NVIDIA developer website -`_. +.. _Installation.LibrariesAndHeaders.LinearSolver.KLU: -To enable CUDA, set ``ENABLE_CUDA`` 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``. +KLU +""" -SUNDIALS has been tested with the CUDA toolkit versions 10 and 11. +To use the :ref:`KLU SUNLinearSolver `, include the header file +and link to the library given below. +.. table:: The KLU SUNLinearSolver library, header file, and CMake target + :align: center -.. _Installation.Cmake.ExternalLibraries.HIP: + +--------------+----------------------------------------------+ + | Libraries | ``libsundials_sunlinsolklu.LIB`` | + +--------------+----------------------------------------------+ + | Headers | ``sunlinsol/sunlinsol_klu.h`` | + +--------------+----------------------------------------------+ + | CMake target | ``SUNDIALS::sunlinsolklu`` | + +--------------+----------------------------------------------+ -Building with HIP -^^^^^^^^^^^^^^^^^^^^^^ -HIP(heterogeneous-compute interface for portability) allows developers to create portable applications for AMD and NVIDIA GPUs. HIP can be obtained from `HIP GitHub repository `_. +.. _Installation.LibrariesAndHeaders.LinearSolver.KokkosKernels: -To enable HIP, set ``ENABLE_HIP`` to ``ON`` and set ``AMDGPU_TARGETS`` to the desired target(ex. gfx705). -In addition, set ``CMAKE_C_COMPILER`` and ``CMAKE_CXX_COMPILER`` to point to an installation of ``hipcc``. +KokkosKernels Dense +""""""""""""""""""" -SUNDIALS has been tested with HIP versions between 5.0.0 to 5.4.3. +To use the :ref:`KokkosKernels dense SUNLinearSolver `, include the +header file given below. +.. table:: The KokkosKernels dense SUNLinearSolver header file and CMake target + :align: center -.. _Installation.CMake.ExternalLibraries.RAJA: + +--------------+----------------------------------------------+ + | Headers | ``sunlinsol/sunlinsol_kokkosdense.hpp`` | + +--------------+----------------------------------------------+ + | CMake target | ``SUNDIALS::sunlinsolkokkosdense`` | + +--------------+----------------------------------------------+ -Building with RAJA -^^^^^^^^^^^^^^^^^^^^^ +.. _Installation.LibrariesAndHeaders.LinearSolver.LAPACKBand: -RAJA is a performance portability layer developed by Lawrence Livermore National -Laboratory and can be obtained from the `RAJA GitHub repository -`_. +LAPACK Banded +""""""""""""" -Building SUNDIALS RAJA modules requires a CUDA, HIP, or SYCL -enabled RAJA installation. To enable RAJA, set ``ENABLE_RAJA`` to ``ON``, set -``SUNDIALS_RAJA_BACKENDS`` to the desired backend (``CUDA``, ``HIP``, or -``SYCL``), and set ``ENABLE_CUDA``, ``ENABLE_HIP``, or ``ENABLE_SYCL`` to -``ON`` depending on the selected backend. 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_CXX`` to ``ON``. +To use the :ref:`LAPACK banded SUNLinearSolver `, include +the header file and link to the library given below. -SUNDIALS has been tested with RAJA version 0.14.0. +.. table:: The LAPACK banded SUNLinearSolver library, header file, and CMake + target + :align: center + +--------------+----------------------------------------------+ + | Libraries | ``libsundials_sunlinsollapackband.LIB`` | + +--------------+----------------------------------------------+ + | Headers | ``sunlinsol/sunlinsol_lapackband.h`` | + +--------------+----------------------------------------------+ + | CMake target | ``SUNDIALS::sunlinsollapackband`` | + +--------------+----------------------------------------------+ -.. _Installation.CMake.ExternalLibraries.XBraid: +.. _Installation.LibrariesAndHeaders.LinearSolver.LAPACKDense: -Building with XBraid -^^^^^^^^^^^^^^^^^^^^ +LAPACK Dense +"""""""""""" -XBraid is parallel-in-time library implementing an optimal-scaling multigrid -reduction in time (MGRIT) solver. The library is developed by Lawrence Livermore -National Laboratory and is available from the `XBraid GitHub repository -`_. +To use the :ref:`LAPACK dense SUNLinearSolver `, include +the header file and link to the library given below. -To enable XBraid support, 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. +.. table:: The LAPACK dense SUNLinearSolver library, header file, and CMake + target + :align: center -.. note:: + +--------------+----------------------------------------------+ + | Libraries | ``libsundials_sunlinsollapackdense.LIB`` | + +--------------+----------------------------------------------+ + | Headers | ``sunlinsol/sunlinsol_lapackdense.h`` | + +--------------+----------------------------------------------+ + | CMake target | ``SUNDIALS::sunlinsollapackdense`` | + +--------------+----------------------------------------------+ - 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``. +.. _Installation.LibrariesAndHeaders.LinearSolver.MAGMADense: -SUNDIALS has been tested with XBraid version 3.0.0. +MAGMA Dense +""""""""""" +To use the :ref:`MAGMA dense SUNLinearSolver `, include +the header file and link to the library given below. -.. _Installation.CMake.ExternalLibraries.Trilinos: +.. table:: The MAGMA dense SUNLinearSolver library, header file, and CMake + target + :align: center -Building with Trilinos -^^^^^^^^^^^^^^^^^^^^^^ + +--------------+----------------------------------------------+ + | Libraries | ``libsundials_sunlinsolmagmadense.LIB`` | + +--------------+----------------------------------------------+ + | Headers | ``sunlinsol/sunlinsol_magmadense.h`` | + +--------------+----------------------------------------------+ + | CMake target | ``SUNDIALS::sunlinsolmagmadense`` | + +--------------+----------------------------------------------+ -`Trilinos `_ is a collection of C++ libraries of -linear solvers, non-linear solvers, optimization solvers, etc. To enable the -SUNDIALS interface to the Trilinos Tpetra vector, set the -:cmakeop:`ENABLE_TRILINOS` to ``ON`` and provide the path to the root of the -Trilinos installation in :cmakeop:`Trilinos_DIR`. +.. _Installation.LibrariesAndHeaders.LinearSolver.oneMKLDense: -.. code-block:: bash +oneMKL Dense +"""""""""""" - % cmake \ - > -DENABLE_TRILONOS=ON \ - > -DTRILINOS_DIR=/path/to/ginkgo/installation \ - > /home/myname/sundials/srcdir +To use the :ref:`oneMKL dense SUNLinearSolver `, include +the header file and link to the library given below. +.. table:: The oneMKL dense SUNLinearSolver library, header file, and CMake + target + :align: center -.. _Installation.CMake.Testing: + +--------------+----------------------------------------------+ + | Libraries | ``libsundials_sunlinsolonemkldense.LIB`` | + +--------------+----------------------------------------------+ + | Headers | ``sunlinsol/sunlinsol_onemkldense.h`` | + +--------------+----------------------------------------------+ + | CMake target | ``SUNDIALS::sunlinsolonemkldense`` | + +--------------+----------------------------------------------+ -Testing the build and installation ---------------------------------------- +.. _Installation.LibrariesAndHeaders.LinearSolver.PCG: -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: +Preconditioned Conjugate Gradient (PCG) +""""""""""""""""""""""""""""""""""""""" -.. code-block:: bash +To use the :ref:`PCG SUNLinearSolver `, include the header file +and link to the library given below. - % make test +When using SUNDIALS time integration packages or the KINSOL package, the PCG +SUNLinearSolver is bundled with the package library and it is not necessary to +link to the library below when using those packages. -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: +.. table:: The PCG SUNLinearSolver library, header file, and CMake target + :align: center -.. code-block:: bash + +--------------+----------------------------------------------+ + | Libraries | ``libsundials_sunlinsolpcg.LIB`` | + +--------------+----------------------------------------------+ + | Headers | ``sunlinsol/sunlinsol_pcg.h`` | + +--------------+----------------------------------------------+ + | CMake target | ``SUNDIALS::sunlinsolpcg`` | + +--------------+----------------------------------------------+ - % make test_install +.. _Installation.LibrariesAndHeaders.LinearSolver.SPBCGS: +Scaled, Preconditioned Bi-Conjugate Gradient, Stabilized (SPBCGS) +""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.. _Installation.CMake.BuildRunExamples: +To use the :ref:`SPBCGS SUNLinearSolver `, include the header +file and link to the library given below. -Building and Running Examples -------------------------------------- +When using SUNDIALS time integration packages or the KINSOL package, the SPBCGS +SUNLinearSolver is bundled with the package library and it is not necessary to +link to the library below when using those packages. -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. +.. table:: The SPBCGS SUNLinearSolver library, header file, and CMake target + :align: center -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``. + +--------------+----------------------------------------------+ + | Libraries | ``libsundials_sunlinsolspbcgs.LIB`` | + +--------------+----------------------------------------------+ + | Headers | ``sunlinsol/sunlinsol_spbcgs.h`` | + +--------------+----------------------------------------------+ + | CMake target | ``SUNDIALS::sunlinsolspbcgs`` | + +--------------+----------------------------------------------+ -The resulting output from running the examples can be compared with example -output bundled in the SUNDIALS distribution. +.. _Installation.LibrariesAndHeaders.LinearSolver.SPFGMR: -.. note:: +Scaled, Preconditioned, Flexible, Generalized Minimum Residual (SPFGMR) +""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" - There will potentially be differences in the output due to machine - architecture, compiler versions, use of third party libraries etc. +To use the :ref:`SPFGMR SUNLinearSolver `, include the header +file and link to the library given below. +When using SUNDIALS time integration packages or the KINSOL package, the SPFGMR +SUNLinearSolver is bundled with the package library and it is not necessary to +link to the library below when using those packages. -.. _Installation.CMake.Windows: +.. table:: The SPFGMR SUNLinearSolver library, header file, and CMake target + :align: center -Configuring, building, and installing on Windows ----------------------------------------------------------------- + +--------------+----------------------------------------------+ + | Libraries | ``libsundials_sunlinsolspfgmr.LIB`` | + +--------------+----------------------------------------------+ + | Headers | ``sunlinsol/sunlinsol_spfgmr.h`` | + +--------------+----------------------------------------------+ + | CMake target | ``SUNDIALS::sunlinsolspfgmr`` | + +--------------+----------------------------------------------+ -CMake can also be used to build SUNDIALS on Windows. To build SUNDIALS -for use with Visual Studio the following steps should be performed: +.. _Installation.LibrariesAndHeaders.LinearSolver.SPGMR: -#. Unzip the downloaded tar file(s) into a directory. This will be the - ``SOLVERDIR`` +Scaled, Preconditioned, Generalized Minimum Residual (SPGMR) +"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -#. Create a separate ``BUILDDIR`` +To use the :ref:`SPGMR SUNLinearSolver `, include the header +file and link to the library given below. -#. Open a Visual Studio Command Prompt and cd to ``BUILDDIR`` +When using SUNDIALS time integration packages or the KINSOL package, the SPGMR +SUNLinearSolver is bundled with the package library and it is not necessary to +link to the library below when using those packages. -#. Run ``cmake-gui ../SOLVERDIR`` +.. table:: The SPGMR SUNLinearSolver library, header file, and CMake target + :align: center - a. Hit Configure + +--------------+----------------------------------------------+ + | Libraries | ``libsundials_sunlinsolspgmr.LIB`` | + +--------------+----------------------------------------------+ + | Headers | ``sunlinsol/sunlinsol_spgmr.h`` | + +--------------+----------------------------------------------+ + | CMake target | ``SUNDIALS::sunlinsolspgmr`` | + +--------------+----------------------------------------------+ - b. Check/Uncheck solvers to be built +.. _Installation.LibrariesAndHeaders.LinearSolver.SPTFQMR: - c. Change ``CMAKE_INSTALL_PREFIX`` to ``INSTDIR`` +Scaled, Preconditioned, Transpose-Free Quasi-Minimum Residual (SPTFQMR) +""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" - d. Set other options as desired +To use the :ref:`SPTFQMR SUNLinearSolver `, include the +header file and link to the library given below. - e. Hit Generate +When using SUNDIALS time integration packages or the KINSOL package, the SPTFQMR +SUNLinearSolver is bundled with the package library and it is not necessary to +link to the library below when using those packages. -#. Back in the VS Command Window: +.. table:: The SPTFQMR SUNLinearSolver library, header file, and CMake target + :align: center - a. Run ``msbuild ALL_BUILD.vcxproj`` + +--------------+----------------------------------------------+ + | Libraries | ``libsundials_sunlinsolsptfqmr.LIB`` | + +--------------+----------------------------------------------+ + | Headers | ``sunlinsol/sunlinsol_sptfqmr.h`` | + +--------------+----------------------------------------------+ + | CMake target | ``SUNDIALS::sunlinsolsptfqmr`` | + +--------------+----------------------------------------------+ - b. Run ``msbuild INSTALL.vcxproj`` +.. _Installation.LibrariesAndHeaders.LinearSolver.SuperLU_DIST: -The resulting libraries will be in the ``INSTDIR``. +SuperLU_DIST +"""""""""""" -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. +To use the :ref:`SuperLU_DIST SUNLinearSolver `, include +the header file and link to the library given below. +.. table:: The SuperLU_DIST SUNLinearSolver library, header file, and CMake + target + :align: center + +--------------+----------------------------------------------+ + | Libraries | ``libsundials_sunlinsolsuperludist.LIB`` | + +--------------+----------------------------------------------+ + | Headers | ``sunlinsol/sunlinsol_superludist.h`` | + +--------------+----------------------------------------------+ + | CMake target | ``SUNDIALS::sunlinsolsuperludist`` | + +--------------+----------------------------------------------+ -.. _Installation.Results: +.. _Installation.LibrariesAndHeaders.LinearSolver.SuperLU_MT: -Installed libraries and exported header files ---------------------------------------------- +SuperLU_MT +"""""""""" -Using the CMake SUNDIALS build system, the command +To use the :ref:`SuperLU_MT SUNLinearSolver `, include +the header file and link to the library given below. -.. code-block:: bash +.. table:: The SuperLU_MT SUNLinearSolver library, header file, and CMake target + :align: center - $ make install + +--------------+----------------------------------------------+ + | Libraries | ``libsundials_sunlinsolsuperlumt.LIB`` | + +--------------+----------------------------------------------+ + | Headers | ``sunlinsol/sunlinsol_superlumt.h`` | + +--------------+----------------------------------------------+ + | CMake target | ``SUNDIALS::sunlinsolsuperlumt`` | + +--------------+----------------------------------------------+ -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``. +.. _Installation.LibrariesAndHeaders.NonlinearSolver: -The installed libraries and exported header files are listed for reference in -the table below. 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. +Nonlinear Solvers +^^^^^^^^^^^^^^^^^ -.. warning:: +.. _Installation.LibrariesAndHeaders.NonlinearSolver.Newton: - SUNDIALS installs some header files to ``INSTDIR/include/sundials/priv``. - All of the header files in this directory are private and **should not - be included in user code**. The private headers are subject to change - without any notice and relying on them may break your code. +Newton +"""""" +To use the :ref:`Newton SUNNonlinearSolver `, include the +header file and link to the library given below. -Using SUNDIALS in your project ------------------------------- +When using SUNDIALS time integration packages, the Newton SUNNonlinearSolver is +bundled with the package library and it is not necessary to link to the library +below when using those packages. -After building and installing SUNDIALS, using SUNDIALS in your application involves -two steps: including the right header files and linking to the right libraries. +.. table:: The Newton SUNNonlinearSolver library, header file, and CMake target + :align: center -Depending on what features of SUNDIALS that your application uses, the header -files needed will vary. For example, if you want to use CVODE for serial computations -you need the following includes: + +--------------+----------------------------------------------+ + | Libraries | ``libsundials_sunnonlinsolnewton.LIB`` | + +--------------+----------------------------------------------+ + | Headers | ``sunnonlinsol/sunnonlinsol_newton.h`` | + +--------------+----------------------------------------------+ + | CMake target | ``SUNDIALS::sunnonlinsolnewton`` | + +--------------+----------------------------------------------+ -.. code-block:: c +.. _Installation.LibrariesAndHeaders.NonlinearSolver.FixedPoint: - #include - #include +Fixed-point +""""""""""" -If you wanted to use CVODE with the GMRES linear solver and our CUDA -enabled vector: +To use the :ref:`fixed-point SUNNonlinearSolver `, +include the header file and link to the library given below. -.. code-block:: c +When using SUNDIALS time integration packages, the fixed-point +SUNNonlinearSolver is bundled with the package library and it is not necessary +to link to the library below when using those packages. - #include - #include - #include +.. table:: The Fixed-point SUNNonlinearSolver library, header file, and CMake + target + :align: center -The story is similar for linking to SUNDIALS. Starting in v7.0.0, all -applications will need to link to ``libsundials_core``. Furthermore, depending -on the packages and modules of SUNDIALS of interest an application will need to -link to a few more libraries. Using the same examples as for the includes, we -would need to also link to ``libsundials_cvode``, ``libsundials_nvecserial`` for -the first example and ``libsundials_cvode``, ``libsundials_nveccuda``, -``libsundials_sunlinsolspgmr`` for the second. - -Refer to the documentations sections for the individual packages and modules of -SUNDIALS that interest you for the proper includes and libraries to link to. - -Furthermore, each of the sundials solvers is distributed with a set of examples demonstrating basic -usage. To build and install the examples, set both ``EXAMPLES_ENABLE_`` and -:cmakeop:`EXAMPLES_INSTALL` to ``ON`` and specify the example installation directory -:cmakeop:`EXAMPLES_INSTALL_PATH`. CMake will generate a ``CMakeLists.txt`` configuration file (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. Note -that if CMake is used, it will overwrite the traditional ``Makefile`` with a new CMake generated -``Makefile``. + +--------------+----------------------------------------------+ + | Libraries | ``libsundials_sunnonlinsolfixedpoint.LIB`` | + +--------------+----------------------------------------------+ + | Headers | ``sunnonlinsol/sunnonlinsol_fixedpoint.h`` | + +--------------+----------------------------------------------+ + | CMake target | ``SUNDIALS::sunnonlinsolfixedpoint`` | + +--------------+----------------------------------------------+ +.. _Installation.LibrariesAndHeaders.NonlinearSolver.PETScSNES: -Using SUNDIALS as a Third Party Library in other CMake Projects ---------------------------------------------------------------- - -The ``make install`` command will also install a `CMake package configuration file -`_ -that other CMake projects can load to get all the information needed to build -against SUNDIALS. In the consuming project's CMake code, the ``find_package`` -command may be used to search for the configuration file, which will be -installed to ``instdir/SUNDIALS_INSTALL_CMAKEDIR/SUNDIALSConfig.cmake`` -alongside a package version file -``instdir/SUNDIALS_INSTALL_CMAKEDIR/SUNDIALSConfigVersion.cmake``. Together -these files contain all the information the consuming project needs to use -SUNDIALS, including exported CMake targets. The SUNDIALS exported CMake targets -follow the same naming convention as the generated library binaries, e.g. the -exported target for CVODE is ``SUNDIALS::cvode``. The CMake code snipped -below shows how a consuming project might leverage the SUNDIALS package -configuration file to build against SUNDIALS in their own CMake project. +PETSc SNES +"""""""""" -.. code-block:: cmake +To use the :ref:`PETSc SNES SUNNonlinearSolver `, include +the header file and link to the library given below. - project(MyProject) +.. table:: The PETSc SNES SUNNonlinearSolver library, header file, and CMake + target + :align: center - # Set the variable SUNDIALS_DIR to the SUNDIALS instdir. - # When using the cmake CLI command, this can be done like so: - # cmake -D SUNDIALS_DIR=/path/to/sundials/installation + +--------------+----------------------------------------------+ + | Libraries | ``libsundials_sunnonlinsolpetscsnes.LIB`` | + +--------------+----------------------------------------------+ + | Headers | ``sunnonlinsol/sunnonlinsol_petscsnes.h`` | + +--------------+----------------------------------------------+ + | CMake target | ``SUNDIALS::sunnonlinsolpetscsnes`` | + +--------------+----------------------------------------------+ - # Find any SUNDIALS version... - find_package(SUNDIALS REQUIRED) +.. _Installation.LibrariesAndHeaders.MemoryHelper: - # ... or find any version newer than some minimum... - find_package(SUNDIALS 7.1.0 REQUIRED) +Memory Helpers +^^^^^^^^^^^^^^ - # ... or find a version in a range - find_package(SUNDIALS 7.0.0...7.1.0 REQUIRED) +System +"""""" - add_executable(myexec main.c) +When using SUNDIALS time integration packages or the KINSOL package, the system +SUNMemoryHelper is bundled with the package library and it is not necessary to +link to the library below when using those packages. - # Link to SUNDIALS libraries through the exported targets. - # This is just an example, users should link to the targets appropriate - # for their use case. - target_link_libraries(myexec PUBLIC SUNDIALS::cvode SUNDIALS::nvecpetsc) +.. table:: SUNDIALS system memory helper header file + :align: center + +--------------+----------------------------------------------+ + | Headers | ``sunmemory/sunmemory_system.h`` | + +--------------+----------------------------------------------+ -.. note:: +CUDA +"""" - .. versionchanged:: 7.1.0 +To use the :ref:`CUDA SUNMemoryHelper `, include the header file +given below when using a CUDA-enabled NVector or SUNMatrix. - A single version provided to ``find_package`` denotes the minimum version - of SUNDIALS to look for, and any version equal or newer than what is - specified will match. In prior versions ``SUNDIALSConfig.cmake`` required - the version found to have the same major version number as the single - version provided to ``find_package``. +.. table:: SUNDIALS CUDA memory helper header file + :align: center + +--------------+----------------------------------------------+ + | Headers | ``sunmemory/sunmemory_cuda.h`` | + +--------------+----------------------------------------------+ -Table of SUNDIALS libraries and header files --------------------------------------------- - -.. _Installation.Table: - -.. tabularcolumns:: |\Y{0.3}|\Y{0.2}|\Y{0.5}| - -.. table:: SUNDIALS shared libraries and header files - :align: center - - +------------------------------+--------------+----------------------------------------------+ - | Core | Libraries | ``libsundials_core.LIB`` | - | +--------------+----------------------------------------------+ - | | Headers | ``sundials/sundials_band.h`` | - | | +----------------------------------------------+ - | | | ``sundials/sundials_config.h`` | - | | +----------------------------------------------+ - | | | ``sundials/sundials_context.h`` | - | | +----------------------------------------------+ - | | | ``sundials/sundials_cuda_policies.hpp`` | - | | +----------------------------------------------+ - | | | ``sundials/sundials_dense.h`` | - | | +----------------------------------------------+ - | | | ``sundials/sundials_direct.h`` | - | | +----------------------------------------------+ - | | | ``sundials/sundials_hip_policies.hpp`` | - | | +----------------------------------------------+ - | | | ``sundials/sundials_iterative.h`` | - | | +----------------------------------------------+ - | | | ``sundials/sundials_linearsolver.h`` | - | | +----------------------------------------------+ - | | | ``sundials/sundials_math.h`` | - | | +----------------------------------------------+ - | | | ``sundials/sundials_matrix.h`` | - | | +----------------------------------------------+ - | | | ``sundials/sundials_memory.h`` | - | | +----------------------------------------------+ - | | | ``sundials/sundials_mpi_types.h`` | - | | +----------------------------------------------+ - | | | ``sundials/sundials_nonlinearsolver.h`` | - | | +----------------------------------------------+ - | | | ``sundials/sundials_nvector.h`` | - | | +----------------------------------------------+ - | | | ``sundials/sundials_types.h`` | - | | +----------------------------------------------+ - | | | ``sundials/sundials_version.h`` | - | | +----------------------------------------------+ - | | | ``sundials/sundials_xbraid.h`` | - +------------------------------+--------------+----------------------------------------------+ - | | - | **NVECTOR Modules** | - | | - +------------------------------+--------------+----------------------------------------------+ - | SERIAL | Libraries | ``libsundials_nvecserial.LIB`` | - | +--------------+----------------------------------------------+ - | | Headers | ``nvector/nvector_serial.h`` | - +------------------------------+--------------+----------------------------------------------+ - | PARALLEL | Libraries | ``libsundials_nvecparallel.LIB`` | - | +--------------+----------------------------------------------+ - | | Headers | ``nvector/nvector_parallel.h`` | - +------------------------------+--------------+----------------------------------------------+ - | OPENMP | Libraries | ``libsundials_nvecopenmp.LIB`` | - | +--------------+----------------------------------------------+ - | | Headers | ``nvector/nvector_openmp.h`` | - +------------------------------+--------------+----------------------------------------------+ - | PTHREADS | Libraries | ``libsundials_nvecpthreads.LIB`` | - | +--------------+----------------------------------------------+ - | | 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`` | - +------------------------------+--------------+----------------------------------------------+ - | HIP | Libraries | ``libsundials_nvechip.LIB`` | - | +--------------+----------------------------------------------+ - | | Headers | ``nvector/nvector_hip.h`` | - +------------------------------+--------------+----------------------------------------------+ - | RAJA | Libraries | ``libsundials_nveccudaraja.LIB`` | - | | +----------------------------------------------+ - | | | ``libsundials_nvechipraja.LIB`` | - | +--------------+----------------------------------------------+ - | | Headers | ``nvector/nvector_raja.h`` | - +------------------------------+--------------+----------------------------------------------+ - | SYCL | Libraries | ``libsundials_nvecsycl.LIB`` | - | +--------------+----------------------------------------------+ - | | Headers | ``nvector/nvector_sycl.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`` | - | +--------------+----------------------------------------------+ - | | Headers | ``sunmatrix/sunmatrix_band.h`` | - +------------------------------+--------------+----------------------------------------------+ - | CUSPARSE | Libraries | ``libsundials_sunmatrixcusparse.LIB`` | - | +--------------+----------------------------------------------+ - | | Headers | ``sunmatrix/sunmatrix_cusparse.h`` | - +------------------------------+--------------+----------------------------------------------+ - | DENSE | Libraries | ``libsundials_sunmatrixdense.LIB`` | - | +--------------+----------------------------------------------+ - | | Headers | ``sunmatrix/sunmatrix_dense.h`` | - +------------------------------+--------------+----------------------------------------------+ - | Ginkgo | Headers | ``sunmatrix/sunmatrix_ginkgo.hpp`` | - +------------------------------+--------------+----------------------------------------------+ - | MAGMADENSE | Libraries | ``libsundials_sunmatrixmagmadense.LIB`` | - | +--------------+----------------------------------------------+ - | | Headers | ``sunmatrix/sunmatrix_magmadense.h`` | - +------------------------------+--------------+----------------------------------------------+ - | ONEMKLDENSE | Libraries | ``libsundials_sunmatrixonemkldense.LIB`` | - | +--------------+----------------------------------------------+ - | | Headers | ``sunmatrix/sunmatrix_onemkldense.h`` | - +------------------------------+--------------+----------------------------------------------+ - | SPARSE | Libraries | ``libsundials_sunmatrixsparse.LIB`` | - | +--------------+----------------------------------------------+ - | | Headers | ``sunmatrix/sunmatrix_sparse.h`` | - +------------------------------+--------------+----------------------------------------------+ - | SLUNRLOC | Libraries | ``libsundials_sunmatrixslunrloc.LIB`` | - | +--------------+----------------------------------------------+ - | | Headers | ``sunmatrix/sunmatrix_slunrloc.h`` | - +------------------------------+--------------+----------------------------------------------+ - | | - | **SUNLINSOL Modules** | - | | - +------------------------------+--------------+----------------------------------------------+ - | BAND | Libraries | ``libsundials_sunlinsolband.LIB`` | - | +--------------+----------------------------------------------+ - | | Headers | ``sunlinsol/sunlinsol_band.h`` | - +------------------------------+--------------+----------------------------------------------+ - | CUSOLVERSP_BATCHQR | Libraries | ``libsundials_sunlinsolcusolversp.LIB`` | - | +--------------+----------------------------------------------+ - | | Headers | ``sunlinsol/sunlinsol_cusolversp_batchqr.h`` | - +------------------------------+--------------+----------------------------------------------+ - | DENSE | Libraries | ``libsundials_sunlinsoldense.LIB`` | - | +--------------+----------------------------------------------+ - | | Headers | ``sunlinsol/sunlinsol_dense.h`` | - +------------------------------+--------------+----------------------------------------------+ - | Ginkgo | Headers | ``sunlinsol/sunlinsol_ginkgo.hpp`` | - +------------------------------+--------------+----------------------------------------------+ - | KLU | Libraries | ``libsundials_sunlinsolklu.LIB`` | - | +--------------+----------------------------------------------+ - | | Headers | ``sunlinsol/sunlinsol_klu.h`` | - +------------------------------+--------------+----------------------------------------------+ - | LAPACKBAND | Libraries | ``libsundials_sunlinsollapackband.LIB`` | - | +--------------+----------------------------------------------+ - | | Headers | ``sunlinsol/sunlinsol_lapackband.h`` | - +------------------------------+--------------+----------------------------------------------+ - | LAPACKDENSE | Libraries | ``libsundials_sunlinsollapackdense.LIB`` | - | +--------------+----------------------------------------------+ - | | Headers | ``sunlinsol/sunlinsol_lapackdense.h`` | - +------------------------------+--------------+----------------------------------------------+ - | MAGMADENSE | Libraries | ``libsundials_sunlinsolmagmadense.LIB`` | - | +--------------+----------------------------------------------+ - | | Headers | ``sunlinsol/sunlinsol_magmadense.h`` | - +------------------------------+--------------+----------------------------------------------+ - | ONEMKLDENSE | Libraries | ``libsundials_sunlinsolonemkldense.LIB`` | - | +--------------+----------------------------------------------+ - | | Headers | ``sunlinsol/sunlinsol_onemkldense.h`` | - +------------------------------+--------------+----------------------------------------------+ - | PCG | Libraries | ``libsundials_sunlinsolpcg.LIB`` | - | +--------------+----------------------------------------------+ - | | Headers | ``sunlinsol/sunlinsol_pcg.h`` | - +------------------------------+--------------+----------------------------------------------+ - | SPBCGS | Libraries | ``libsundials_sunlinsolspbcgs.LIB`` | - | +--------------+----------------------------------------------+ - | | Headers | ``sunlinsol/sunlinsol_spbcgs.h`` | - +------------------------------+--------------+----------------------------------------------+ - | SPFGMR | Libraries | ``libsundials_sunlinsolspfgmr.LIB`` | - | +--------------+----------------------------------------------+ - | | Headers | ``sunlinsol/sunlinsol_spfgmr.h`` | - +------------------------------+--------------+----------------------------------------------+ - | SPGMR | Libraries | ``libsundials_sunlinsolspgmr.LIB`` | - | +--------------+----------------------------------------------+ - | | Headers | ``sunlinsol/sunlinsol_spgmr.h`` | - +------------------------------+--------------+----------------------------------------------+ - | SPTFQMR | Libraries | ``libsundials_sunlinsolsptfqmr.LIB`` | - | +--------------+----------------------------------------------+ - | | Headers | ``sunlinsol/sunlinsol_sptfqmr.h`` | - +------------------------------+--------------+----------------------------------------------+ - | SUPERLUDIST | Libraries | ``libsundials_sunlinsolsuperludist.LIB`` | - | +--------------+----------------------------------------------+ - | | Headers | ``sunlinsol/sunlinsol_superludist.h`` | - +------------------------------+--------------+----------------------------------------------+ - | SUPERLUMT | Libraries | ``libsundials_sunlinsolsuperlumt.LIB`` | - | +--------------+----------------------------------------------+ - | | Headers | ``sunlinsol/sunlinsol_superlumt.h`` | - +------------------------------+--------------+----------------------------------------------+ - | | - | **SUNNONLINSOL Modules** | - | | - +------------------------------+--------------+----------------------------------------------+ - | NEWTON | Libraries | ``libsundials_sunnonlinsolnewton.LIB`` | - | +--------------+----------------------------------------------+ - | | Headers | ``sunnonlinsol/sunnonlinsol_newton.h`` | - +------------------------------+--------------+----------------------------------------------+ - | FIXEDPOINT | Libraries | ``libsundials_sunnonlinsolfixedpoint.LIB`` | - | +--------------+----------------------------------------------+ - | | Headers | ``sunnonlinsol/sunnonlinsol_fixedpoint.h`` | - +------------------------------+--------------+----------------------------------------------+ - | PETSCSNES | Libraries | ``libsundials_sunnonlinsolpetscsnes.LIB`` | - | +--------------+----------------------------------------------+ - | | Headers | ``sunnonlinsol/sunnonlinsol_petscsnes.h`` | - +------------------------------+--------------+----------------------------------------------+ - | | - | **SUNMEMORY Modules** | - | | - +------------------------------+--------------+----------------------------------------------+ - | SYSTEM | Libraries | ``libsundials_sunmemsys.LIB`` | - | +--------------+----------------------------------------------+ - | | Headers | ``sunmemory/sunmemory_system.h`` | - +------------------------------+--------------+----------------------------------------------+ - | CUDA | Libraries | ``libsundials_sunmemcuda.LIB`` | - | +--------------+----------------------------------------------+ - | | Headers | ``sunmemory/sunmemory_cuda.h`` | - +------------------------------+--------------+----------------------------------------------+ - | HIP | Libraries | ``libsundials_sunmemhip.LIB`` | - | +--------------+----------------------------------------------+ - | | Headers | ``sunmemory/sunmemory_hip.h`` | - +------------------------------+--------------+----------------------------------------------+ - | SYCL | Libraries | ``libsundials_sunmemsycl.LIB`` | - | +--------------+----------------------------------------------+ - | | Headers | ``sunmemory/sunmemory_sycl.h`` | - +------------------------------+--------------+----------------------------------------------+ - | | - | **SUNDIALS Packages** | - | | - +------------------------------+--------------+----------------------------------------------+ - | CVODE | Libraries | ``libsundials_cvode.LIB`` | - | +--------------+----------------------------------------------+ - | | Headers | ``cvode/cvode.h`` | - | | +----------------------------------------------+ - | | | ``cvode/cvode_bandpre.h`` | - | | +----------------------------------------------+ - | | | ``cvode/cvode_bbdpre.h`` | - | | +----------------------------------------------+ - | | | ``cvode/cvode_diag.h`` | - | | +----------------------------------------------+ - | | | ``cvode/cvode_impl.h`` | - | | +----------------------------------------------+ - | | | ``cvode/cvode_ls.h`` | - | | +----------------------------------------------+ - | | | ``cvode/cvode_proj.h`` | - +------------------------------+--------------+----------------------------------------------+ - | CVODES | Libraries | ``libsundials_cvodes.LIB`` | - | +--------------+----------------------------------------------+ - | | Headers | ``cvodes/cvodes.h`` | - | | +----------------------------------------------+ - | | | ``cvodes/cvodes_bandpre.h`` | - | | +----------------------------------------------+ - | | | ``cvodes/cvodes_bbdpre.h`` | - | | +----------------------------------------------+ - | | | ``cvodes/cvodes_diag.h`` | - | | +----------------------------------------------+ - | | | ``cvodes/cvodes_impl.h`` | - | | +----------------------------------------------+ - | | | ``cvodes/cvodes_ls.h`` | - +------------------------------+--------------+----------------------------------------------+ - | ARKODE | Libraries | ``libsundials_arkode.LIB`` | - | | +----------------------------------------------+ - | | | ``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_mristep.h`` | - | | +----------------------------------------------+ - | | | ``arkode/arkode_xbraid.h`` | - +------------------------------+--------------+----------------------------------------------+ - | IDA | Libraries | ``libsundials_ida.LIB`` | - | +--------------+----------------------------------------------+ - | | Headers | ``ida/ida.h`` | - | | +----------------------------------------------+ - | | | ``ida/ida_bbdpre.h`` | - | | +----------------------------------------------+ - | | | ``ida/ida_impl.h`` | - | | +----------------------------------------------+ - | | | ``ida/ida_ls.h`` | - +------------------------------+--------------+----------------------------------------------+ - | IDAS | Libraries | ``libsundials_idas.LIB`` | - | +--------------+----------------------------------------------+ - | | Headers | ``idas/idas.h`` | - | | +----------------------------------------------+ - | | | ``idas/idas_bbdpre.h`` | - | | +----------------------------------------------+ - | | | ``idas/idas_impl.h`` | - +------------------------------+--------------+----------------------------------------------+ - | KINSOL | Libraries | ``libsundials_kinsol.LIB`` | - | +--------------+----------------------------------------------+ - | | Headers | ``kinsol/kinsol.h`` | - | | +----------------------------------------------+ - | | | ``kinsol/kinsol_bbdpre.h`` | - | | +----------------------------------------------+ - | | | ``kinsol/kinsol_impl.h`` | - | | +----------------------------------------------+ - | | | ``kinsol/kinsol_ls.h`` | - +------------------------------+--------------+----------------------------------------------+ - - -Installing SUNDIALS on HPC Clusters ------------------------------------ - -.. _Installation.HPC: - -This section is a guide for installing SUNDIALS on specific HPC clusters. -In general, the procedure is the same as described previously for Linux machines. -The main differences are in the modules and environment variables that are specific -to different HPC clusters. We aim to keep this section as up to date as possible, -but it may lag the latest software updates to each cluster. +HIP +""" -Frontier -^^^^^^^^ +To use the :ref:`HIP SUNMemoryHelper `, include the header file +given below when using a HIP-enabled NVector or SUNMatrix. -`Frontier `_ is an Exascale supercomputer at the Oak Ridge -Leadership Computing Facility. If you are new to this system, then we recommend that you review the -`Frontier user guide `_. +.. table:: SUNDIALS HIP memory helper header file + :align: center -**A Standard Installation** + +--------------+----------------------------------------------+ + | Headers | ``sunmemory/sunmemory_hip.h`` | + +--------------+----------------------------------------------+ -Clone SUNDIALS: +SYCL +"""" -.. code-block:: bash +To use the :ref:`SYCL SUNMemoryHelper `, include the header file +given below when using a SYCL-enabled NVector or SUNMatrix. - git clone https://github.com/LLNL/sundials.git && cd sundials +.. table:: SUNDIALS SYCL memory helper header file + :align: center -Next we load the modules and set the environment variables needed to build SUNDIALS. -This configuration enables both MPI and HIP support for distributed and GPU parallelism. -It uses the HIP compiler for C and C++ and the Cray Fortran compiler. Other configurations -are possible. + +--------------+----------------------------------------------+ + | Headers | ``sunmemory/sunmemory_sycl.h`` | + +--------------+----------------------------------------------+ -.. code-block:: bash +.. _Installation.LibrariesAndHeaders.ExecutionPolicies: - # required dependencies - module load PrgEnv-cray-amd/8.5.0 - module load craype-accel-amd-gfx90a - module load rocm/5.3.0 - module load cmake/3.23.2 +Execution Policies +^^^^^^^^^^^^^^^^^^ - # GPU-aware MPI - export MPICH_GPU_SUPPORT_ENABLED=1 +CUDA +"""" - # compiler environment hints - export CC=$(which hipcc) - export CXX=$(which hipcc) - export FC=$(which ftn) - export CFLAGS="-I${ROCM_PATH}/include" - export CXXFLAGS="-I${ROCM_PATH}/include -Wno-pass-failed" - export LDFLAGS="-L${ROCM_PATH}/lib -lamdhip64 ${PE_MPICH_GTL_DIR_amd_gfx90a} -lmpi_gtl_hsa" +When using a CUDA-enabled NVector or SUNMatrix, include the header file below to +access the CUDA execution policy C++ classes. -Now we can build SUNDIALS. In general, this is the same procedure described in the previous sections. -The following command builds and installs SUNDIALS with MPI, HIP, and the Fortran interface enabled, where `` is your desired installation location, and `` is your allocation account on Frontier: +.. table:: SUNDIALS CUDA execution policies header file + :align: center -.. code-block:: bash + +--------------+----------------------------------------------+ + | Headers | ``sundials/sundials_cuda_policies.hpp`` | + +--------------+----------------------------------------------+ - cmake -S . -B builddir -DCMAKE_INSTALL_PREFIX= -DAMDGPU_TARGETS=gfx90a \ - -DENABLE_HIP=ON -DENABLE_MPI=ON -DBUILD_FORTRAN_MODULE_INTERFACE=ON - cd builddir - make -j8 install - # Need an allocation to run the tests: - salloc -A -t 10 -N 1 -p batch - make test - make test_install_all +HIP +""" +When using a HIP-enabled NVector or SUNMatrix, include the header file below to +access the HIP execution policy C++ classes. -Building with SUNDIALS Addons ------------------------------ +.. table:: SUNDIALS HIP execution policies header file + :align: center -SUNDIALS "addons" are community developed code additions for SUNDIALS that can be subsumed by the -SUNDIALS build system so that they have full access to all internal SUNDIALS symbols. The intent is -for SUNDIALS addons to function as if they are part of the SUNDIALS library, while allowing them to -potentially have different licenses (although we encourage BSD-3-Clause still), code style (although -we encourage them to follow the SUNDIALS style outlined :ref:`here `). + +--------------+----------------------------------------------+ + | Headers | ``sundials/sundials_hip_policies.hpp`` | + +--------------+----------------------------------------------+ -.. warning:: +SYCL +"""" - SUNDIALS addons are not maintained by the SUNDIALS team and may come with different - licenses. Use them at your own risk. +When using a SYCL-enabled NVector or SUNMatrix, include the header file below to +access the SYCL execution policy C++ classes. -To build with SUNDIALS addons, +.. table:: SUNDIALS SYCL execution policies header file + :align: center -1. Clone/copy the addon(s) into ``/external/`` -2. Copy the ``sundials-addon-example`` block in the ``/external/CMakeLists.txt``, - paste it below the example block, and modify the path listed for your own external addon(s). -3. When building SUNDIALS, set the CMake option :cmakeop:`SUNDIALS_ENABLE_EXTERNAL_ADDONS` to `ON` -4. Build SUNDIALS as usual. + +--------------+----------------------------------------------+ + | Headers | ``sundials/sundials_sycl_policies.hpp`` | + +--------------+----------------------------------------------+ diff --git a/doc/shared/sundials/Types.rst b/doc/shared/sundials/Types.rst index a1be93f378..55a6bcdcbd 100644 --- a/doc/shared/sundials/Types.rst +++ b/doc/shared/sundials/Types.rst @@ -84,7 +84,7 @@ usage is consistent with the typedef for ``sunrealtype``) and call the appropria math library functions directly. Thus, a previously existing piece of C or C++ code can use SUNDIALS without modifying the code to use ``sunrealtype``, ``SUN_RCONST``, or the ``SUNR`` macros so long as the SUNDIALS libraries are built -to use the corresponding precision (see :numref:`Installation.CMake.Options`). +to use the corresponding precision (see :numref:`Installation.Options`). Integer types used for indexing ------------------------------- @@ -112,7 +112,7 @@ this usage is consistent with the typedef for ``sunindextype`` on their architecture. Thus, a previously existing piece of C or C++ code can use SUNDIALS without modifying the code to use ``sunindextype``, so long as the SUNDIALS libraries use the appropriate index storage type (for details see -:numref:`Installation.CMake.Options`). +:numref:`Installation.Options`). Boolean type ------------ diff --git a/doc/shared/sunlinsol/SUNLinSol_Ginkgo.rst b/doc/shared/sunlinsol/SUNLinSol_Ginkgo.rst index 5b1a4e0a3d..3635f853c4 100644 --- a/doc/shared/sunlinsol/SUNLinSol_Ginkgo.rst +++ b/doc/shared/sunlinsol/SUNLinSol_Ginkgo.rst @@ -26,7 +26,7 @@ a header only library. To use the SUNLINEARSOLVER_GINKGO ``SUNLinearSolver``, us need to include ``sunlinsol/sunlinsol_ginkgo.hpp``. The module is meant to be used with the SUNMATRIX_GINKGO module described in :numref:`SUNMatrix.Ginkgo`. Instructions on building SUNDIALS with Ginkgo enabled are given -in :numref:`Installation.CMake.ExternalLibraries`. For instructions on +in :numref:`Installation.Options.Ginkgo`. For instructions on building and using Ginkgo itself, refer to the `Ginkgo website and documentation `_. diff --git a/doc/shared/sunlinsol/SUNLinSol_KLU.rst b/doc/shared/sunlinsol/SUNLinSol_KLU.rst index ff3a9e2712..7250187baa 100644 --- a/doc/shared/sunlinsol/SUNLinSol_KLU.rst +++ b/doc/shared/sunlinsol/SUNLinSol_KLU.rst @@ -220,7 +220,7 @@ Davis and collaborators (:cite:p:`KLU_site,DaPa:10`). In order to use the SUNLinSol_KLU interface to KLU, it is assumed that KLU has been installed on the system prior to installation of SUNDIALS, and that SUNDIALS has been configured appropriately to link with KLU -(see :numref:`Installation.CMake.ExternalLibraries` for details). +(see :numref:`Installation.Options.KLU` for details). Additionally, this wrapper only supports double-precision calculations, and therefore cannot be compiled if SUNDIALS is configured to have :c:type:`sunrealtype` set to either ``extended`` or diff --git a/doc/shared/sunlinsol/SUNLinSol_KokkosDense.rst b/doc/shared/sunlinsol/SUNLinSol_KokkosDense.rst index 763bdfae5f..226f969f15 100644 --- a/doc/shared/sunlinsol/SUNLinSol_KokkosDense.rst +++ b/doc/shared/sunlinsol/SUNLinSol_KokkosDense.rst @@ -25,7 +25,7 @@ C++ library, the module is also written in modern C++ (it requires C++14) as a header only library. To utilize this ``SUNLinearSolver`` user will need to include ``sunlinsol/sunlinsol_kokkosdense.hpp``. More instructions on building SUNDIALS with Kokkos and KokkosKernels enabled are given in -:numref:`Installation.CMake.ExternalLibraries`. For instructions on building and +:numref:`Installation.Options.KokkosKernels`. For instructions on building and using Kokkos and KokkosKernels, refer to the `Kokkos `_ and `KokkosKernels `_. diff --git a/doc/shared/sunlinsol/SUNLinSol_LapackBand.rst b/doc/shared/sunlinsol/SUNLinSol_LapackBand.rst index 9d4686cdaa..08a985f00f 100644 --- a/doc/shared/sunlinsol/SUNLinSol_LapackBand.rst +++ b/doc/shared/sunlinsol/SUNLinSol_LapackBand.rst @@ -105,7 +105,7 @@ In order to use the SUNLinSol_LapackBand module it is assumed that LAPACK has been installed on the system prior to installation of SUNDIALS, and that SUNDIALS has been configured appropriately to link with LAPACK (see -:numref:`Installation.CMake.ExternalLibraries` for details). We note +:numref:`Installation.Options.LAPACK` for details). We note that since there do not exist 128-bit floating-point factorization and solve routines in LAPACK, this interface cannot be compiled when using ``extended`` precision for :c:type:`sunrealtype`. Similarly, since diff --git a/doc/shared/sunlinsol/SUNLinSol_LapackDense.rst b/doc/shared/sunlinsol/SUNLinSol_LapackDense.rst index 0e41a21c8a..767fcc9827 100644 --- a/doc/shared/sunlinsol/SUNLinSol_LapackDense.rst +++ b/doc/shared/sunlinsol/SUNLinSol_LapackDense.rst @@ -102,7 +102,7 @@ SUNLinSol_LapackDense module it is assumed that LAPACK has been installed on the system prior to installation of SUNDIALS, and that SUNDIALS has been configured appropriately to link with LAPACK (see -:numref:`Installation.CMake.ExternalLibraries` for details). +:numref:`Installation.Options.LAPACK` for details). We note that since there do not exist 128-bit floating-point factorization and solve routines in LAPACK, this interface cannot be compiled when using ``extended`` precision for :c:type:`sunrealtype`. diff --git a/doc/shared/sunlinsol/SUNLinSol_SuperLUDIST.rst b/doc/shared/sunlinsol/SUNLinSol_SuperLUDIST.rst index 462c0c7c7e..bee1a9a3c4 100644 --- a/doc/shared/sunlinsol/SUNLinSol_SuperLUDIST.rst +++ b/doc/shared/sunlinsol/SUNLinSol_SuperLUDIST.rst @@ -193,7 +193,7 @@ OpenMP for threading, and CUDA for GPU support. In order to use the SUNLinSol_SuperLUDIST interface to SuperLU_DIST, it is assumed that SuperLU_DIST has been installed on the system prior to installation of SUNDIALS, and that SUNDIALS has been configured appropriately to link with SuperLU_DIST -(see :numref:`Installation.CMake.ExternalLibraries` for details). +(see :numref:`Installation.Options.SuperLU_DIST` for details). Additionally, the wrapper only supports double-precision calculations, and therefore cannot be compiled if SUNDIALS is configured to use single or extended precision. Moreover, since the SuperLU_DIST diff --git a/doc/shared/sunlinsol/SUNLinSol_SuperLUMT.rst b/doc/shared/sunlinsol/SUNLinSol_SuperLUMT.rst index 60c344ab9c..f25eec4d87 100644 --- a/doc/shared/sunlinsol/SUNLinSol_SuperLUMT.rst +++ b/doc/shared/sunlinsol/SUNLinSol_SuperLUMT.rst @@ -155,7 +155,7 @@ order to use the SUNLinSol_SuperLUMT interface to SuperLU_MT, it is assumed that SuperLU_MT has been installed on the system prior to installation of SUNDIALS, and that SUNDIALS has been configured appropriately to link with SuperLU_MT (see -:numref:`Installation.CMake.ExternalLibraries` for details). +:numref:`Installation.Options.SuperLU_MT` for details). Additionally, this wrapper only supports single- and double-precision calculations, and therefore cannot be compiled if SUNDIALS is configured to have :c:type:`sunrealtype` set to ``extended`` diff --git a/doc/shared/sunmatrix/SUNMatrix_Ginkgo.rst b/doc/shared/sunmatrix/SUNMatrix_Ginkgo.rst index b003e26039..969dc86578 100644 --- a/doc/shared/sunmatrix/SUNMatrix_Ginkgo.rst +++ b/doc/shared/sunmatrix/SUNMatrix_Ginkgo.rst @@ -26,7 +26,7 @@ Since Ginkgo is a modern C++ library, SUNMATRIX_GINKGO is also written in modern C++ (it requires C++14). Unlike most other SUNDIALS modules, it is a header only library. To use the SUNMATRIX_GINKGO ``SUNMatrix``, users will need to include ``sunmatrix/sunmatrix_ginkgo.hpp``. More instructions on building SUNDIALS with Ginkgo enabled are given in -:numref:`Installation.CMake.ExternalLibraries`. For instructions on building and using +:numref:`Installation.Options.Ginkgo`. For instructions on building and using Ginkgo itself, refer to the `Ginkgo website and documentation `_. .. note:: diff --git a/doc/shared/sunmatrix/SUNMatrix_KokkosDense.rst b/doc/shared/sunmatrix/SUNMatrix_KokkosDense.rst index bbcadfe20c..7cfbc17877 100644 --- a/doc/shared/sunmatrix/SUNMatrix_KokkosDense.rst +++ b/doc/shared/sunmatrix/SUNMatrix_KokkosDense.rst @@ -27,7 +27,7 @@ written in modern C++ (it requires C++14) as a header only library. To utilize this ``SUNMatrix`` users will need to include ``sunmatrix/sunmatrix_kokkosdense.hpp``. More instructions on building SUNDIALS with Kokkos and KokkosKernels enabled are given in -:numref:`Installation.CMake.ExternalLibraries`. For instructions on building and +:numref:`Installation.Options.KokkosKernels`. For instructions on building and using Kokkos and KokkosKernels, refer to the `Kokkos `_ and `KokkosKernels `_. diff --git a/doc/shared/sunnonlinsol/SUNNonlinSol_PetscSNES.rst b/doc/shared/sunnonlinsol/SUNNonlinSol_PetscSNES.rst index 1cb332300d..d1025f0148 100644 --- a/doc/shared/sunnonlinsol/SUNNonlinSol_PetscSNES.rst +++ b/doc/shared/sunnonlinsol/SUNNonlinSol_PetscSNES.rst @@ -21,7 +21,7 @@ This section describes the SUNNonlinSol interface to the `PETSc SNES nonlinear solver(s) `_. To enable the SUNonlinSol_PetscSNES module, SUNDIALS must be configured to use PETSc. Instructions on how to do this are given in -:numref:`Installation.CMake.ExternalLibraries.PETSc`. To access the +:numref:`Installation.Options.PETSc`. To access the SUNNonlinSol_PetscSNES module, include the header file ``sunnonlinsol/sunnonlinsol_petscsnes.h``. The library to link to is ``libsundials_sunnonlinsolpetsc.lib`` where ``.lib`` is typically ``.so`` for