diff --git a/.github/workflows/typos.yml b/.github/workflows/typos.yml index e7ddbbc27..77e0e5067 100644 --- a/.github/workflows/typos.yml +++ b/.github/workflows/typos.yml @@ -13,5 +13,5 @@ jobs: uses: crate-ci/typos@v1.23.6 with: write_changes: true - files: ./docs/source/ProgrammingGuide/ ./docs/source/API/ ./docs/source/*.rst ./docs/source/*.md + files: ./docs/source/ProgrammingGuide/ ./docs/source/API/ ./docs/source/*.rst config: ./.typos.toml diff --git a/docs/source/API/algorithms-index.rst b/docs/source/API/algorithms-index.rst index 2efd63d19..debbd7b96 100644 --- a/docs/source/API/algorithms-index.rst +++ b/docs/source/API/algorithms-index.rst @@ -1,5 +1,5 @@ -API: Algorithms -############### +Algorithms API +############## .. toctree:: :maxdepth: 1 diff --git a/docs/source/API/containers-index.rst b/docs/source/API/containers-index.rst index 2aba3e863..69b91e5ca 100644 --- a/docs/source/API/containers-index.rst +++ b/docs/source/API/containers-index.rst @@ -1,5 +1,5 @@ -API: Containers -############### +Containers API +############## .. list-table:: :widths: 25 75 @@ -15,13 +15,13 @@ API: Containers - DynamicView comment. * - `DynRankView `__ - Kokkos Runtime-determined-dimension DynRankView class. - * - `Offset-View `__ + * - `OffsetView `__ - OffsetView comment. * - `ScatterView `__ - ScatterView comment. * - `StaticCrsGraph `__ - - StaticCrsGraph comment. - * - `Unordered-Map `__ + - [DEPRECATED] StaticCrsGraph compressed raw storage graph + * - `UnorderedMap `__ - UnorderedMap comment. * - `vector `__ - [DEPRECATED] std::vector compatible implementation that works with non-host memory spaces. diff --git a/docs/source/API/containers/StaticCrsGraph.rst b/docs/source/API/containers/StaticCrsGraph.rst index a03773ed1..cdae77d20 100644 --- a/docs/source/API/containers/StaticCrsGraph.rst +++ b/docs/source/API/containers/StaticCrsGraph.rst @@ -1,8 +1,10 @@ -``StaticCrsGraph`` -================== +``StaticCrsGraph`` [DEPRECATED] +=============================== -Header file: ```` +Header file: ```` (deprecated since Kokkos 4.5) + +``StaticCrsGraph`` was moved to KokkosKernels. The StaticCrsGraph is a Compressed row storage array with the row map, the column indices and the non-zero entries stored in 3 different Kokkos::Views. Appropriate types and functions are provided to simplify manipulation and access to CRS data on either a host or device. diff --git a/docs/source/API/core-index.rst b/docs/source/API/core-index.rst index 0996b0521..cfbc13f3f 100644 --- a/docs/source/API/core-index.rst +++ b/docs/source/API/core-index.rst @@ -1,5 +1,5 @@ -API: Core -######### +Core API +######## .. list-table:: :widths: 20 80 diff --git a/docs/source/API/simd-index.rst b/docs/source/API/simd-index.rst index 2c9b77bf4..aa12d4abe 100644 --- a/docs/source/API/simd-index.rst +++ b/docs/source/API/simd-index.rst @@ -1,5 +1,5 @@ -API: SIMD -############### +SIMD API +######## .. toctree:: :maxdepth: 1 diff --git a/docs/source/ProgrammingGuide/Compiling.md b/docs/source/ProgrammingGuide/Compiling.md index d9b515932..b8485ff6f 100644 --- a/docs/source/ProgrammingGuide/Compiling.md +++ b/docs/source/ProgrammingGuide/Compiling.md @@ -127,7 +127,7 @@ There are numerous device backends, options, and architecture-specific optimizat -DCMAKE_INSTALL_PREFIX=${my_install_folder} \ -DKokkos_ENABLE_OPENMP=On ``` -which activates the OpenMP backend. All the options controlling device backends, options, architectures, and third-party libraries (TPLs) are given in [CMake Keywords](../keywords). +which activates the OpenMP backend. All the options controlling device backends, options, architectures, and third-party libraries (TPLs) are given in the [Configuration Guide](../get-started/configuration-guide). ### Spack @@ -192,7 +192,7 @@ endif() ### Kokkos CMake Keyword Listing -Please see the [documentation page with all keywords](../keywords). +Please see the [documentation page with all keywords](../get-started/configuration-guide). ## 4.3 Using Trilinos' CMake build system @@ -200,7 +200,7 @@ The Trilinos project (see [`trilinos.org`](https://trilinos.org) and github for Trilinos' build system uses CMake. Thus, to build Kokkos as part of Trilinos, you must first install CMake (version `3.17` or newer). To enable Kokkos when building Trilinos, set the CMake option `Trilinos_ENABLE_Kokkos`. Trilinos' build system lets packages express dependencies on other packages or external libraries. If you enable any Trilinos package (e.g., Tpetra) that has a required dependency on Kokkos, Trilinos will enable Kokkos automatically. Configuration macros are automatically inferred from Trilinos settings. For example, if the CMake option `Trilinos_ENABLE_OpenMP` is `ON`, Trilinos will define the macro `Kokkos_ENABLE_OPENMP`. Trilinos' build system will autogenerate the previously mentioned `KokkosCore_config.h` file that contains those macros. -Trilinos' CMake build system utilizes Kokkos' build system to set compiler flags, compiler options, architectures, etc. CMake variables `CMAKE_CXX_COMPILER`, `CMAKE_C_COMPILER`, and `CMAKE_FORTRAN_COMPILER` are used to specify the compiler. To configure Trilinos for various architectures, with Kokkos enabled, the CMake variable `Kokkos_ARCH_` should be set, matching ArchCode to the appropriate architecture as specified in [Architecture Keywords](../keywords). +Trilinos' CMake build system utilizes Kokkos' build system to set compiler flags, compiler options, architectures, etc. CMake variables `CMAKE_CXX_COMPILER`, `CMAKE_C_COMPILER`, and `CMAKE_FORTRAN_COMPILER` are used to specify the compiler. To configure Trilinos for various architectures, with Kokkos enabled, the CMake variable `Kokkos_ARCH_` should be set, matching ArchCode to the appropriate architecture as specified in [Architecture Keywords](../get-started/configuration-guide). For example, `Kokkos_ARCH_HSW` sets the architecture variables for a machine with Intel Haswell CPUs. Also, when setting the `Kokkos_ARCH_` variable it is not necessary to pass required architecture-specific flags to CMake, for example via the `CMAKE_CXX_FLAGS` variable. diff --git a/docs/source/api-references.rst b/docs/source/api-references.rst new file mode 100644 index 000000000..da22f349a --- /dev/null +++ b/docs/source/api-references.rst @@ -0,0 +1,39 @@ +API References +############## + +.. toctree:: + :maxdepth: 1 + :hidden: + + API/core-index + API/algorithms-index + API/containers-index + API/simd-index + API/alphabetical + deprecations + +:doc:`API/core-index` +~~~~~~~~~~~~~~~~~~~~~ +The fundamental abstractions for execution (``parallel_for``, +``parallel_reduce``, ``parallel_scan``) and data (``View``). + +:doc:`API/algorithms-index` +~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Utility classes for pseudo-random number generation, sorting algorthms, +STL-like parallel algorithms. + +:doc:`API/containers-index` +~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Exotic view-based containers, such as ``DualView``, ``ScatterView``, or ``OffsetView``. + +:doc:`API/simd-index` +~~~~~~~~~~~~~~~~~~~~~ +Data-parallel vector types. + +:doc:`Alphabetical ` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +List of all library features in alphabetical order. + +:doc:`deprecations` +~~~~~~~~~~~~~~~~~~~ +List of obsolete features that have been deprecated and/or removed. diff --git a/docs/source/building.md b/docs/source/building.md deleted file mode 100644 index 0d6ad9bd9..000000000 --- a/docs/source/building.md +++ /dev/null @@ -1,145 +0,0 @@ -# Build, Install and Use - -## Kokkos Philosophy -Kokkos provides a modern CMake style build system. -As C++ continues to develop for C++20 and beyond, CMake is likely to provide the most robust support -for C++. Applications heavily leveraging Kokkos are strongly encouraged to use a CMake build system. - -You can either use Kokkos as an installed package (encouraged) or use Kokkos in-tree in your project. -Modern CMake is exceedingly simple at a high-level (with the devil in the details). -Once Kokkos is installed In your `CMakeLists.txt` simply use: -````cmake -find_package(Kokkos REQUIRED) -```` -Then for every executable or library in your project: -````cmake -target_link_libraries(myTarget Kokkos::kokkos) -```` -That's it! There is no checking Kokkos preprocessor, compiler, or linker flags. -Kokkos propagates all the necessary flags to your project. -This means not only is linking to Kokkos easy, but Kokkos itself can actually configure compiler and linker flags for *your* -project. -When configuring your project just set: -````bash -> cmake ${srcdir} \ - -DKokkos_ROOT=${kokkos_install_prefix} \ - -DCMAKE_CXX_COMPILER=${compiler_used_to_build_kokkos} -```` -Note: You may need the following if using some versions of CMake (e.g. 3.12): -````cmake -cmake_policy(SET CMP0074 NEW) -```` -If building in-tree, there is no `find_package`. You can use `add_subdirectory(kokkos)` with the Kokkos source and again just link with `target_link_libraries(Kokkos::kokkos)`. -The examples in `examples/cmake_build_installed` and `examples/cmake_build_in_tree` can help get you started. - -## Configuring CMake -A very basic installation of Kokkos is done with: -````bash -> cmake ${srcdir} \ - -DCMAKE_CXX_COMPILER=g++ \ - -DCMAKE_INSTALL_PREFIX=${kokkos_install_folder} -```` -which builds and installed a default Kokkos when you run `make install`. -There are numerous device backends, options, and architecture-specific optimizations that can be configured, e.g. -````bash -> cmake ${srcdir} \ - -DCMAKE_CXX_COMPILER=g++ \ - -DCMAKE_INSTALL_PREFIX=${kokkos_install_folder} \ - -DKokkos_ENABLE_OPENMP=ON -```` -which activates the OpenMP backend. All the options controlling device backends, options, architectures, and third-party libraries (TPLs) are given in [CMake Keywords](../keywords). - - -## Known Issues - -### Cray - -* The Cray compiler wrappers do static linking by default. This seems to break the Kokkos build. You will likely need to set the environment variable `CRAYPE_LINK_TYPE=dynamic` in order to link correctly. Kokkos warns during configure if this is missing. -* The Cray compiler identifies to CMake as Clang, but it sometimes has its own flags that differ from Clang. We try to include all exceptions, but flag errors may occur in which a Clang-specific flag is passed that the Cray compiler does not recognize. - -### Fortran - -* In a mixed C++/Fortran code, CMake will use the C++ linker by default. If you override this behavior and use Fortran as the link language, the link may break because Kokkos adds linker flags expecting the linker to be C++. Prior to CMake 3.18, Kokkos has no way of detecting in downstream projects that the linker was changed to Fortran. From CMake 3.18, Kokkos can use generator expressions to avoid adding flags when the linker is not C++. Note: Kokkos will not add any linker flags in this Fortran case. The user will be entirely on their own to add the appropriate linker flags. - -## Raw Makefile - -Raw Makefiles are only supported via inline builds. See below. - -## Inline Builds vs. Installed Package -For individual projects, it may be preferable to build Kokkos inline rather than link to an installed package. -The main reason is that you may otherwise need many different -configurations of Kokkos installed depending on the required compile time -features an application needs. For example there is only one default -execution space, which means you need different installations to have OpenMP -or C++ threads as the default space. Also for the CUDA backend there are certain -choices, such as allowing relocatable device code, which must be made at -installation time. Building Kokkos inline uses largely the same process -as compiling an application against an installed Kokkos library. - -For CMake, this means copying over the Kokkos source code into your project and adding `add_subdirectory(kokkos)` to your CMakeLists.txt. - -For raw Makefiles, see the example benchmarks/bytes_and_flops/Makefile which can be used with an installed library and or an inline build. - -## Kokkos and CUDA UVM - -Kokkos does support UVM as a specific memory space called CudaUVMSpace. -Allocations made with that space are accessible from host and device. -You can tell Kokkos to use that as the default space for Cuda allocations. -In either case UVM comes with a number of restrictions: -* You can't access allocations on the host while a kernel is potentially -running. This will lead to segfaults. To avoid that you either need to -call Kokkos::Cuda::fence() (or just Kokkos::fence()), after kernels, or -you can set the environment variable CUDA_LAUNCH_BLOCKING=1. -* In multi socket multi GPU machines without NVLINK, UVM defaults -to using zero copy allocations for technical reasons related to using multiple -GPUs from the same process. If an executable doesn't do that (e.g. each -MPI rank of an application uses a single GPU [can be the same GPU for -multiple MPI ranks]) you can set CUDA_MANAGED_FORCE_DEVICE_ALLOC=1. -This will enforce proper UVM allocations, but can lead to errors if -more than a single GPU is used by a single process. - -## Spack -An alternative to manually building with the CMake is to use the Spack package manager. -Make sure you have downloaded [Spack](https://github.com/spack/spack). -The easiest way to configure the Spack environment is: -````bash -> source spack/share/spack/setup-env.sh -```` -with other scripts available for other shells. - -You can display information about how to install packages with: -````bash -> spack info kokkos -```` -A basic installation would be done as: -````bash -> spack install kokkos -```` -Spack allows options and and compilers to be tuned in the install command. -````bash -> spack install kokkos@3.0 %gcc@7.3.0 +openmp -```` -This example illustrates the three most common parameters to Spack: -* Variants: specified with, e.g. `+openmp`, this activates (or deactivates with, e.g. `~openmp`) certain options. -* Version: immediately following `kokkos` the `@version` can specify a particular Kokkos to build -* Compiler: a default compiler will be chosen if not specified, but an exact compiler version can be given with the `%`option. - -For a complete list of Kokkos options, run: -````bash -> spack info kokkos -```` - - -### Spack Development -Spack currently installs packages to a location determined by a unique hash. This hash name is not really "human readable". -Generally, Spack usage should never really require you to reference the computer-generated unique install folder. -If you must know, you can locate Spack Kokkos installations with: -````bash -> spack find -p kokkos ... -```` -where `...` is the unique spec identifying the particular Kokkos configuration and version. - -A better way to use Spack for doing Kokkos development is the dev-build feature of Spack. -For dev-build details, try using `spack test run`. - - diff --git a/docs/source/contributing.rst b/docs/source/contributing.rst index 15bae31ef..104a21c8d 100644 --- a/docs/source/contributing.rst +++ b/docs/source/contributing.rst @@ -7,6 +7,7 @@ Contributing templates/index developer-guides/index + testing-and-issue-tracking We are open and try to encourage contributions from external developers. To do so please first open an issue describing the contribution and then @@ -27,3 +28,11 @@ Contributing Documentation Please see the `README `_ for general instructions on building the documentation. To make it easier to contribute API documentation, we have a page of documentation templates :doc:`here ` + +Developers' Corner +------------------ + +* :doc:`Developer Guide ` + +* :doc:`Kokkos Panning and Testing ` + diff --git a/docs/source/deprecation_page.rst b/docs/source/deprecations.rst similarity index 100% rename from docs/source/deprecation_page.rst rename to docs/source/deprecations.rst diff --git a/docs/source/get-started.rst b/docs/source/get-started.rst new file mode 100644 index 000000000..11393f9a3 --- /dev/null +++ b/docs/source/get-started.rst @@ -0,0 +1,51 @@ +Get Started +########### + +.. toctree:: + :maxdepth: 1 + :hidden: + + get-started/quick-start + get-started/requirements + get-started/integrating-kokkos-into-your-cmake-project + get-started/building-from-source + get-started/configuration-guide + get-started/package-managers + + +Want to try Kokkos right away? Check it out on `Compiler Explorer +`_. + +:doc:`Quick Start ` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +This guide provides the minimal first-steps instructions to get started with a +CMake project and start writting Kokkos code. + +:doc:`Integrating Kokkos into Your Project ` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +This guide discusses in details how to setup your project to use Kokkos. + +:doc:`Requirements ` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +This page details the supported versions of various components required to +build and use Kokkos, including build systems, vendor toolchains, compilers, +C++ standards, and target architectures (both CPU and GPU). A comprehensive +table lists compatible combinations of these components. + +:doc:`Building from Source ` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +This guide provides instructions for downloading the Kokkos source code, +configuring to generate the build system, compiling the library, and installing +it on your system. + +:doc:`Configuration Guide ` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +This page provides a comprehensive reference for all Kokkos configuration +options, including backend selection for targeting specific hardware setups, +general and backend-specific CMake options, control over third-party library +usage, and a complete list of supported CPU and GPU architectures. + +:doc:`Package Managers ` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +This page lists package managers that offer pre-built Kokkos packages, +providing a convenient alternative to building from source. diff --git a/docs/source/get-started/building-from-source.rst b/docs/source/get-started/building-from-source.rst new file mode 100644 index 000000000..d099c43d3 --- /dev/null +++ b/docs/source/get-started/building-from-source.rst @@ -0,0 +1,235 @@ +Building From Source +==================== + +Getting the Kokkos Source Code +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This section describes how to obtain the Kokkos source code. We recommend +downloading a tagged release for most users, as these releases undergo +extensive testing and are generally more stable. Development versions are also +available for advanced users who need the latest features and are comfortable +with potentially less stable code. + +Downloading a Release Archive (Recommended) +------------------------------------------- + +The recommended approach for most users is to download a release archive from GitHub. + +1. **Find the Latest Release:** Go to the `Kokkos releases + page `_ and find the latest + release (or a specific version you need). + +2. **Download the Archive and Checksum:** Download both the + ``kokkos-X.Y.Z.tar.gz`` archive and the corresponding + ``kokkos-X.Y.Z-SHA-256.txt`` checksum file. It's crucial to verify the + integrity of the downloaded archive using the checksum. + +3. **Verify the Archive Integrity (Important):** Use the following commands + (adjust the version number as needed) to verify the downloaded archive: + + .. code-block:: sh + + export KOKKOS_VERSION=4.5.01 # Replace with the actual version + export KOKKOS_DOWNLOAD_URL=https://github.com/kokkos/kokkos/releases/download/${KOKKOS_VERSION} + curl -sLO ${KOKKOS_DOWNLOAD_URL}/kokkos-${KOKKOS_VERSION}.tar.gz + curl -sLO ${KOKKOS_DOWNLOAD_URL}/kokkos-${KOKKOS_VERSION}-SHA-256.txt + grep kokkos-${KOKKOS_VERSION}.tar.gz kokkos-${KOKKOS_VERSION}-SHA-256.txt | shasum -c + + + The output should be ``kokkos-4.5.01.tar.gz: OK`` (or similar, depending on + the version). If the checksum doesn't match, **do not use the downloaded + archive** as it may be corrupted or tampered with. + +4. **Extract the Archive:** Once you've verified the checksum, extract the archive: + + .. code-block:: sh + + tar -xzvf kokkos-${KOKKOS_VERSION}.tar.gz + +Cloning the Git Repository (For Development Versions) +----------------------------------------------------- + +If you need the latest features or want to contribute to Kokkos, you can clone +the Git repository. + +1. **Clone the Repository:** + + .. code-block:: sh + + git clone https://github.com/kokkos/kokkos.git + + This will clone the repository into a directory named ``kokkos``. + +2. **Check Out a Release Tag (Recommended for Development):** + While the ``develop`` branch is generally kept stable, it's still under + active development. For more predictable behavior, check out a specific + release tag: + + .. code-block:: sh + + cd kokkos + git checkout 4.5.01 # Replace with the desired version tag + + To see available tags: + + .. code-block:: sh + + git tag + + Or, to stay on the bleeding edge (use with caution): + + .. code-block:: sh + + git checkout develop + + +Which Method Should I Use? +-------------------------- + +* **Tagged Releases:** Use this method unless you have a specific reason to use + a development version. Tagged releases are the most stable and well-tested. +* **Git Repository (Development Versions):** Use this method if you need the + very latest features, want to contribute to Kokkos, or need to debug a + specific issue that's been fixed in the development branch. Be aware that + development versions may be less stable than releases. + +No matter which method you choose, always verify the integrity of the +downloaded source code. This is a crucial security practice. + + +Configuring and Building Kokkos +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This section describes how to configure and build Kokkos. We assume you are in +the root directory of the Kokkos source code (or the project embedding Kokkos). + +Configuring Kokkos +------------------ + +Use the following command to configure Kokkos: + +.. code-block:: sh + + cmake -B builddir [] + + +``-B builddir`` creates a ``builddir`` directory named build (you can choose a +different name if you prefer). Kokkos requires out-of-source builds. The +``[]`` part is where you specify the configuration options. + +**Common CMake Options** + +These options are generally useful for any CMake project: + +* ``-DCMAKE_CXX_COMPILER=``: Specifies the full path to the C++ + compiler. For example, use ``hipcc`` for AMD GPUs, ``icpx`` for Intel GPUs, + or ``g++`` or ``clang++`` for CPUs. + + Example: ``-DCMAKE_CXX_COMPILER=/path/to/hipcc`` + +* ``-DCMAKE_CXX_STANDARD=``: Sets the C++ standard. The default is ``17``. + + Example: ``-DCMAKE_CXX_STANDARD=20`` + +* ``-DCMAKE_BUILD_TYPE=``: Controls optimization level and debugging + information. Common options are ``Debug``, ``Release``, ``RelWithDebInfo`` + (default), and ``MinSizeRel``. + + Example: ``-DCMAKE_BUILD_TYPE=Release`` + +* ``-DCMAKE_INSTALL_PREFIX=``: Specify the directory on disk to which + Kokkos will be installed. + + Example: ``-DCMAKE_INSTALL_PREFIX=/path/to/install/dir`` + +**Important Kokkos-specific options:** + +* ``-DKokkos_ENABLE_=ON``: Enables a specific backend for target devices. + See :ref:`keywords_backends` for a complete list, including currently open-sourced experimental backends. + Common backends: + + * ``OPENMP`` or ``THREADS``: Multithreading on CPUs + + * ``CUDA``: NVIDIA GPUs + + * ``HIP``: AMD GPUs + + * ``SYCL``: Intel GPUs + + Example: ``-DKokkos_ENABLE_CUDA=ON`` + + + + + include experimental backends and :ref:`keywords_enable_backend_specific_options`. + + +* ``-DKokkos_ARCH_=ON``: Specifies the target architecture for + code generation. Some backends can auto-detect the architecture, but it's + often best to specify it explicitly. + See :ref:`keywords_arch` for a complete list. + For instance: + + * ``AMD_GFX90A``: AMD MI210X (Frontier) + + * ``INTEL_PVC``: Intel Data Center Max 1550 (Aurora) + + * ``AMPERE80``: NVIDIA A100 (Perlmutter) + + Example: ``-DKokkos_ARCH_AMPERE80=ON`` + +* ``-DKokkos_ENABLE_DEPRECATED_CODE_4=ON``: Enables all code marked as + deprecated. Setting this to ``OFF`` removes deprecated symbols. + +* ``-DKokkos_ENABLE_DEPRECATION_WARNINGS=ON``: Enables deprecation warnings. + **Strongly recommended** to avoid surprises in future releases. Don't disable + this unless you have a very good reason. + + +**Example Configuration** + +.. code-block:: sh + + cmake -B builddir \ + -DCMAKE_CXX_COMPILER=g++ \ + -DCMAKE_BUILD_TYPE=Release \ + -DKokkos_ENABLE_OPENMP=ON \ + -DKokkos_ARCH_NATIVE=ON \ + -DKokkos_ENABLE_DEPRECATED_CODE_4=OFF + + +Building Kokkos +--------------- + +After configuring, build Kokkos using: + +.. code-block:: sh + + cmake --build builddir + +This compiles Kokkos. You can add ``-j`` to use multiple cores for faster +compilation (replace ```` with the number of cores). + +Example: ``cmake --build builddir -j8`` + + +Installing Kokkos +----------------- + +To install Kokkos (header files and libraries), use: + +.. code-block:: sh + + cmake --install builddir [--prefix ] + +The ``--prefix `` option specifies the installation directory. If +omitted, Kokkos will be installed to a default location, often ``/usr/local`` +(**not recommended**). + + +Advanced: Configuring Against the Build Directory +------------------------------------------------- + +(For experts only) You can configure your project directly against the +``/cmake_packages/`` directory in the out-of-tree build, similar to +using an install tree. This can be useful for development purposes. diff --git a/docs/source/keywords.rst b/docs/source/get-started/configuration-guide.rst similarity index 99% rename from docs/source/keywords.rst rename to docs/source/get-started/configuration-guide.rst index a15b95bb6..6fb9fe310 100644 --- a/docs/source/keywords.rst +++ b/docs/source/get-started/configuration-guide.rst @@ -1,4 +1,4 @@ -.. include:: mydefs.rst +.. include:: ../mydefs.rst CMake Keywords ############## @@ -186,6 +186,7 @@ Debugging * Debug check on dual views * ``OFF`` +.. _keywords_enable_backend_specific_options: Backend-specific options ------------------------ @@ -276,7 +277,7 @@ should not be setting these. .. _keywords_tpls: -Third-party Libraries (TPLs) +Third-Party Libraries (TPLs) ============================ The following options control enabling TPLs: diff --git a/docs/source/get-started/integrating-kokkos-into-your-cmake-project.rst b/docs/source/get-started/integrating-kokkos-into-your-cmake-project.rst new file mode 100644 index 000000000..9476dfb01 --- /dev/null +++ b/docs/source/get-started/integrating-kokkos-into-your-cmake-project.rst @@ -0,0 +1,141 @@ +Integrating Kokkos into Your Project +==================================== + +This document describes how to integrate the Kokkos library into your CMake +project. + +Kokkos provides the ``Kokkos::kokkos`` target, which simplifies the +process by automatically handling necessary include directories, link +libraries, compiler options, and other usage requirements. + +Here are several integration methods, each with its own advantages: + +1. External Kokkos (Recommended for most users) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The recommended approach is to use Kokkos as an external dependency. This +allows for easier management and updates. Use CMake's +`find_package() `_ +command to locate and link against an existing Kokkos installation: + +.. code-block:: cmake + + find_package(Kokkos 4.2 REQUIRED CONFIG) # Find Kokkos version 4.2 or later + # ... + target_link_libraries(MyTarget PRIVATE Kokkos::kokkos) + +* ``find_package(Kokkos ...)`` searches for a ``KokkosConfig.cmake`` file, which is + generated when Kokkos is built and installed. This file contains the + necessary information for linking against Kokkos. +* The ``4.2`` argument specifies the minimum required Kokkos version. It's + optional but recommended for ensuring compatibility. +* ``Kokkos::kokkos`` is the namespaced imported target that provides all + necessary build flags. +* The ``CONFIG`` keyword tells CMake to use the configuration files. + +You can install Kokkos separately and then point CMake to its location using +the ``Kokkos_ROOT`` variable. + +.. code-block:: sh + + MyProject> cmake -DKokkos_ROOT=/path/to/kokkos/install/dir -B builddir + + +2. Embedded Kokkos via ``add_subdirectory()`` and Git Submodules +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This method embeds the Kokkos source code directly into your project. It's +useful when you need very tight control over the Kokkos version or when you +can't install Kokkos separately. + +1. Add Kokkos as a `Git submodule `_: + +.. code-block:: sh + + MyProject> git submodule add -b 4.5.01 https://github.com/kokkos/kokkos.git tpls/kokkos + MyProject> git commit -m 'Adding Kokkos v4.5.1 as a submodule' + + +``tpls/kokkos/`` should now contain the full Kokkos source tree. + +2. Use ``add_subdirectory()`` in your CMakeLists.txt: + +.. code-block:: cmake + + add_subdirectory(tpls/kokkos) + # ... + target_link_libraries(MyTarget PRIVATE Kokkos::kokkos) + + +3. Embedded Kokkos via ``FetchContent`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +`FetchContent `_ +simplifies the process of downloading and including Kokkos as a dependency +during the CMake configuration stage. + +.. code-block:: cmake + + include(FetchContent) + FetchContent_Declare( + Kokkos + URL https://github.com/kokkos/kokkos/releases/download/4.5.01/kokkos-4.5.01.tar.gz + URL_HASH SHA256=52d003ffbbe05f30c89966e4009c017efb1662b02b2b73190670d3418719564c + ) + FetchContent_MakeAvailable(Kokkos) + # ... + target_link_libraries(MyTarget PRIVATE Kokkos::kokkos) + + +* ``URL_HASH`` is highly recommended for verifying the integrity of the + downloaded archive. You can find the SHA256 checksums for Kokkos releases in + the ``kokkos-X.Y.Z-SHA-256.txt`` file on the `Kokkos releases page + `_. + + +4. Supporting Both External and Embedded Kokkos +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This approach allows your project to use either an external Kokkos installation +or an embedded version, providing flexibility for different build environments. + +.. code-block:: cmake + + find_package(Kokkos CONFIG) # Try to find Kokkos externally + if(Kokkos_FOUND) + message(STATUS "Found Kokkos: ${Kokkos_DIR} (version \"${Kokkos_VERSION}\")") + else() + message(STATUS "Kokkos not found externally. Fetching via FetchContent.") + include(FetchContent) + FetchContent_Declare( + Kokkos + URL https://github.com/kokkos/kokkos/archive/refs/tags/4.4.01.tar.gz + ) + FetchContent_MakeAvailable(Kokkos) + endif() + # ... + target_link_libraries(MyTarget PRIVATE Kokkos::kokkos) + + +Controlling the Kokkos integration: + +* `CMAKE_DISABLE_FIND_PACKAGE_Kokkos `_: + Set this variable to ``TRUE`` to force the use of the embedded Kokkos, even if + an external installation is found. +* `CMAKE_REQUIRE_FIND_PACKAGE_Kokkos `_: + Set this variable to ``TRUE`` to require an external Kokkos installation. The + build will fail if Kokkos is not found. +* ``Kokkos_ROOT``: Use this variable to specify the directory where CMake should + search for Kokkos when using ``find_package()``. + +For example: + +.. code-block:: sh + + cmake -DCMAKE_REQUIRE_FIND_PACKAGE_Kokkos=ON -DKokkos_ROOT=/path/to/kokkos/install/dir + +or + +.. code-block:: sh + + cmake -DCMAKE_DISABLE_FIND_PACKAGE_Kokkos=ON diff --git a/docs/source/get-started/package-managers.rst b/docs/source/get-started/package-managers.rst new file mode 100644 index 000000000..cb63d5075 --- /dev/null +++ b/docs/source/get-started/package-managers.rst @@ -0,0 +1,24 @@ +Package Managers +================ + +Use your favorite package manager to install Kokkos. + +System package managers +~~~~~~~~~~~~~~~~~~~~~~~ + +**DNF** +You may use the Fedora Project package manager to install Kokkos +https://packages.fedoraproject.org/pkgs/kokkos/ + +Other package managers +~~~~~~~~~~~~~~~~~~~~~~ + +`Spack ` +-------------------------- +Spack is a popular package manager for HPC. Spack comes with installation recipes for Kokkos. +https://packages.spack.io/package.html?name=kokkos + +.. code-block:: + + spack install kokkos + diff --git a/docs/source/quick_start.rst b/docs/source/get-started/quick-start.rst similarity index 94% rename from docs/source/quick_start.rst rename to docs/source/get-started/quick-start.rst index cf291d696..e44c2ae83 100644 --- a/docs/source/quick_start.rst +++ b/docs/source/get-started/quick-start.rst @@ -1,5 +1,5 @@ Quick Start -============ +=========== This guide is intended to jump start new Kokkos users (and beginners, in particular). @@ -124,11 +124,11 @@ build system: .. code-block:: sh - MyProject> cmake -B build + MyProject> cmake -B builddir -- The C compiler identification is GNU 10.2.1 -- The CXX compiler identification is GNU 10.2.1 ... - -- Build files have been written to: .../MyProject/build + -- Build files have been written to: .../MyProject/builddir .. note:: @@ -137,14 +137,14 @@ build system: ``-DKokkos_ENABLE_CUDA=ON`` argument to the cmake command above. For an AMD or an Intel GPU, you would use ``-DKokkos_ENABLE_HIP=ON`` or ``-DKokkos_ENABLE_SYCL=ON`` respectively. For a list of options and variables - available at configuration time, see :doc:`keywords`. + available at configuration time, see :doc:`configuration-guide`. Then invoke that build system to actually compile/link the project: .. code-block:: sh - MyProject> cmake --build build + MyProject> cmake --build builddir Scanning dependencies of target ... ... [100%] Built target HelloKokkos @@ -153,9 +153,9 @@ Finally try to use the newly built ``HelloKokkos``: .. code-block:: sh - MyProject> cd build + MyProject> cd builddir - MyProject/build> HelloKokkos + MyProject/builddir> HelloKokkos Goodbye World .. note:: diff --git a/docs/source/requirements.rst b/docs/source/get-started/requirements.rst similarity index 100% rename from docs/source/requirements.rst rename to docs/source/get-started/requirements.rst diff --git a/docs/source/index.rst b/docs/source/index.rst index 2453e8d2a..125daf2c2 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -83,24 +83,13 @@ Website Content .. toctree:: :maxdepth: 1 - quick_start + get-started programmingguide - requirements - building - keywords - ./API/core-index - ./API/containers-index - ./API/algorithms-index - ./API/simd-index - ./API/alphabetical - deprecation_page - known-issues - usecases - testing-and-issue-tracking - Tutorials - videolectures - GitHub Repo + api-references + tutorials-and-examples contributing + GitHub Repo + known-issues faq citation license diff --git a/docs/source/tutorials-and-examples.rst b/docs/source/tutorials-and-examples.rst new file mode 100644 index 000000000..3eb7248df --- /dev/null +++ b/docs/source/tutorials-and-examples.rst @@ -0,0 +1,35 @@ +Tutorials and Examples +###################### + +.. toctree:: + :maxdepth: 1 + :hidden: + + Tutorials + tutorials-and-examples/video-lectures + tutorials-and-examples/use-cases-and-examples + + +`Tutorials `_ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The Kokkos Tutorials are organized within a separate repository under the +Kokkos organization on GitHub. Here is the `link +`_. + +:doc:`Video Lectures ` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +A series of video lectures on Kokkos was recorded in 2020 as part of an +Exascale Computing Project (ECP) initiative during the COVID-19 pandemic. +These lectures provide a comprehensive introduction to Kokkos and cover many of +its key features. While some details might be slightly outdated due to ongoing +development, most of the content is fully applicable even today. The lectures +are available on the `ECP event page +`_. A complete list +of videos and accompanying slides can be found :doc:`here +`. + +:doc:`Use Cases and Examples ` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Explore real-world applications of Kokkos and learn how it can be used to solve +diverse computational problems. This page showcases various use cases and +practical examples. diff --git a/docs/source/tutorials-and-examples/use-cases-and-examples.rst b/docs/source/tutorials-and-examples/use-cases-and-examples.rst new file mode 100644 index 000000000..7d22b4745 --- /dev/null +++ b/docs/source/tutorials-and-examples/use-cases-and-examples.rst @@ -0,0 +1,16 @@ +Use Cases and Examples +###################### + +.. toctree:: + :maxdepth: 1 + + ../usecases/MPI-Halo-Exchange + ../usecases/Average-To-Nodes + ../usecases/MDRangePolicy + ../usecases/TaggedOperators + ../usecases/OverlappingHostAndDeviceWork + ../usecases/Tasking + ../usecases/Kokkos-Fortran-Interoperability + ../usecases/SoA-and-AoSoA-with-Cabana + ../usecases/WindowsHeader + ../usecases/Moving_from_EnableUVM_to_SharedSpace diff --git a/docs/source/videolectures.rst b/docs/source/tutorials-and-examples/video-lectures.rst similarity index 100% rename from docs/source/videolectures.rst rename to docs/source/tutorials-and-examples/video-lectures.rst diff --git a/docs/source/usecases.rst b/docs/source/usecases.rst deleted file mode 100644 index 3dbb1a1c4..000000000 --- a/docs/source/usecases.rst +++ /dev/null @@ -1,16 +0,0 @@ -Use Cases and Examples -###################### - -.. toctree:: - :maxdepth: 1 - - ./usecases/MPI-Halo-Exchange - ./usecases/Average-To-Nodes - ./usecases/MDRangePolicy - ./usecases/TaggedOperators - ./usecases/OverlappingHostAndDeviceWork - ./usecases/Tasking - ./usecases/Kokkos-Fortran-Interoperability - ./usecases/SoA-and-AoSoA-with-Cabana - ./usecases/WindowsHeader - ./usecases/Moving_from_EnableUVM_to_SharedSpace