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 <[email protected]>
LLNL · Jan 18, 2025 · cc5e58c · cc5e58c
1 parent 72b88cc
commit cc5e58c
Show file tree

Hide file tree

Showing 15 changed files with 3,155 additions and 1,589 deletions.
diff --git 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 <NVectors.CUDA>` and :ref:`NVECTOR_HIP <NVectors.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
@@ -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 <www.cygwin.com>`_, 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 <https://www.cygwin.com/>`__, 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
@@ -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
 <https://kokkos.github.io/kokkos-core-wiki/index.html>`_ documentation.
 

diff --git a/doc/shared/sundials/Install.rst b/doc/shared/sundials/Install.rst
diff --git 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
@@ -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 <https://ginkgo-project.github.io/>`_.
 

diff --git 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
@@ -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 <https://kokkos.github.io/kokkos-core-wiki/index.html>`_
 and `KokkosKernels <https://github.com/kokkos/kokkos-kernels/wiki>`_.

diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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 <https://ginkgo-project.github.io/>`_.
 
 .. note::

diff --git 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 <https://kokkos.github.io/kokkos-core-wiki/index.html>`_
 and `KokkosKernels <https://github.com/kokkos/kokkos-kernels/wiki>`_.

diff --git 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) <https://petsc.org/release/docs/manual/snes/>`_.
 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