install.tex

\documentclass[
    kokkoshighlight,
    % print,
]{./cheat_sheet_kokkos}

\usepackage[T1]{fontenc}
\usepackage[utf8]{inputenc}
\usepackage{adjustbox}

% document properties
\title{Installation cheat sheet for Kokkos}
\author{CExA}
\date{\today}

\begin{document}

\maketitle

\begin{multicols}{2}

\section{Requirements}

\subsection{Compiler}

\begin{tblr}[theme=kokkostable]{Xll}
    Compiler & Minimum version & Notes \\
    ARM Clang & 20.1 &  \\
    Clang & 15.0.0 & For CUDA \\
    Clang & 14.0.0 & For CPU \\
    GCC & 10.4.0 &  \\
    Intel LLVM & 2024.2.1 & For SYCL \\
    Intel LLVM & 2022.0.0 & For CPU \\
    MSVC & 19.30 &  \\
    NVCC & 12.2 &  \\
    NVHPC & 22.3 &  \\
    ROCM & 6.2.0 &  \\
\end{tblr}

\subsection{Build system}

\begin{tblr}[theme=kokkostable]{llX}
    Build system & Min. vers. & Notes \\
    CMake & 3.25.2 & For Intel LLVM full support and CUDA CMake language support \\
    CMake & 3.22 &  \\
\end{tblr}

\section{How to integrate Kokkos}

\subsection{As an external dependency}

\subsubsection{Configure, build and install Kokkos}

\begin{minted}{sh}
    git clone -b x.y.z "https://github.com/kokkos/kokkos.git"
    cd kokkos
    cmake -B build \
        -DCMAKE_CXX_COMPILER="<your C++ compiler>" \
        -DCMAKE_INSTALL_PREFIX="path/to/kokkos/install" \
        "<Kokkos compile options>"
    cmake --build build
    cmake --install build
\end{minted}

\subsubsection{Install Kokkos with Spack}

\begin{minted}{sh}
    spack install kokkos@x.y.z "<Kokkos variants>"
\end{minted}

See \url{https://packages.spack.io} or \mintinline{text}{spack info kokkos} to list variants.

\subsubsection{Setup, and configure your code}

\begin{minted}{cmake}
    find_package(Kokkos x.y.z REQUIRED)
    target_link_libraries(
        my-app
        Kokkos::kokkos
    )
\end{minted}

\begin{minted}{sh}
    cd "path/to/your/code"
    cmake -B build \
        -DCMAKE_CXX_COMPILER="<your C++ compiler>" \
        -DKokkos_ROOT="path/to/kokkos/install"
\end{minted}

\subsection{As an internal dependency}

\subsubsection{Setup with a Git submodule}

\begin{minted}{sh}
    git submodule add -b x.y.z "https://github.com/kokkos/kokkos.git" tpls/kokkos
\end{minted}

\begin{minted}{cmake}
    add_subdirectory(path/to/kokkos)
    target_link_libraries(
        my-app
        Kokkos::kokkos
    )
\end{minted}

\subsubsection{Setup with FetchContent}

\begin{minted}[breakafter=/]{cmake}
    include(FetchContent)
    FetchContent_Declare(
        kokkos
        URL https://github.com/kokkos/kokkos/releases/download/x.y.z/kokkos-x.y.z.tar.gz
        URL_HASH SHA256=<hash for x.y.z archive>
    )
    FetchContent_MakeAvailable(kokkos)
    target_link_libraries(
        my-app
        Kokkos::kokkos
    )
\end{minted}

\subsubsection{Configure your code}

\begin{minted}{sh}
    cmake -B build \
        -DCMAKE_CXX_COMPILER="<your C++ compiler>" \
        "<Kokkos compile options>"
\end{minted}

You may combine the external/internal dependency approaches.

\section{Kokkos compile options}

\subsection{Host backends}

\begin{tblr}[theme=kokkostable]{Xl}
    Option & Backend \\
    \mintinline{text}{-DKokkos_ENABLE_SERIAL=ON} & Serial \\
    \mintinline{text}{-DKokkos_ENABLE_OPENMP=ON} & OpenMP \\
    \mintinline{text}{-DKokkos_ENABLE_THREADS=ON} & Threads \\
\end{tblr}

The serial backend is enabled by default if no other host backend is enabled.

\subsection{Device backends}

\begin{tblr}[theme=kokkostable]{Xll}
    Option & Backend & Device \\
    \mintinline{text}{-DKokkos_ENABLE_CUDA=ON} & CUDA & NVIDIA \\
    \mintinline{text}{-DKokkos_ENABLE_HIP=ON} & HIP & AMD \\
    \mintinline{text}{-DKokkos_ENABLE_SYCL=ON} & SYCL & Intel \\
\end{tblr}

You can only select the serial backend, plus another host backend and one device backend at a time.

See architecture-specific options.

\subsection{Specific options}

\begin{tblr}[theme=kokkostable]{lX}
    Option & Description \\
    \mintinline{text}{-DKokkos_ENABLE_DEBUG=ON} & Activate extra debug features, may increase compile times \\
    \mintinline{text}{-DKokkos_ENABLE_DEBUG_BOUNDS_CHECK=ON} & Use bounds checking, will increase runtime \\
    \mintinline{text}{-DKokkos_ENABLE_EXAMPLES=ON} & Build examples \\
    \mintinline{text}{-DKokkos_ENABLE_TUNING=ON} & Create bindings for tuning tools \\
\end{tblr}

\subsection{Architecture-specific options}

\subsubsection{Host architectures}

Host options are used for controlling optimization and are optional.

\begin{tblr}[theme=kokkostable]{Xl}
    Option & Architecture \\
    \mintinline{text}{-DKokkos_ARCH_NATIVE=ON} & Local host \\
\end{tblr}

\subsubsection{Device architectures}

Device options are mandatory. They can be deduced from the device if present at CMake configuration time.

\paragraph{AMD GPU architectures (HIP)}

{
% temporary disable justify align
\RenewDocumentCommand\TblrAlignBoth{}{\RaggedRight}

% squeeze cells to fit in the page
\NewDocumentCommand{\squeezecellbox}{m}{%
    % obliged to guess the cell width
    \adjustbox{scale={0.9}{1}, minipage={3.4cm}}{#1}%
}
\NewDocumentCommand{\squeezecell}{m}{%
    \adjustbox{scale={0.85}{1}}{#1}%
}
\begin{tblr}[theme=kokkostable]{colspec={llX}, cell{2-Z}{2}={cmd=\squeezecell}, cell{2-Z}{3}={cmd=\squeezecellbox}}
    Option & Arch. & Associated cards \\
    \mintinline{text}{-DKokkos_ARCH_AMD_GFX950=ON} & GFX950 & MI350X, MI355X \\
    \mintinline{text}{-DKokkos_ARCH_AMD_GFX942_APU=ON} & GFX942 \squeezecell{APU} & MI300A \\
    \mintinline{text}{-DKokkos_ARCH_AMD_GFX942=ON} & GFX942 & MI300X \\
    \mintinline{text}{-DKokkos_ARCH_AMD_GFX90A=ON} & GFX90A & MI210, MI250, MI250X \\
    \mintinline{text}{-DKokkos_ARCH_AMD_GFX908=ON} & GFX908 & MI100 \\
    \mintinline{text}{-DKokkos_ARCH_AMD_GFX906=ON} & GFX906 & MI50, MI60 \\
    \mintinline{text}{-DKokkos_ARCH_AMD_GFX1201=ON} & GFX1201 & Radeon AI PRO R9700, RX 9070 XT \\
    \mintinline{text}{-DKokkos_ARCH_AMD_GFX1152=ON} & GFX1152 & Radeon 860M \\
    \mintinline{text}{-DKokkos_ARCH_AMD_GFX1151=ON} & GFX1151 & Strix Halo \\
    \mintinline{text}{-DKokkos_ARCH_AMD_GFX1103=ON} & GFX1103 & Ryzen 8000G, Radeon 740M, 760M, 780M, 880M, 980M \\
    \mintinline{text}{-DKokkos_ARCH_AMD_GFX1101=ON} & GFX1101 & Radeon RX 7800 XT, RX 7700 XT, RX 7700 \\
    \mintinline{text}{-DKokkos_ARCH_AMD_GFX1100=ON} & GFX1100 & 7900xt \\
    \mintinline{text}{-DKokkos_ARCH_AMD_GFX1030=ON} & GFX1030 & V620, W6800 \\
\end{tblr}
}

\paragraph{Intel GPU architectures (SYCL)}

{
% temporary disable justify align
\RenewDocumentCommand\TblrAlignBoth{}{\RaggedRight}
\begin{tblr}[theme=kokkostable]{llX}
    Option & Arch. & Associated cards \\
    \mintinline{text}{-DKokkos_ARCH_INTEL_GEN=ON} & \SetCell[c=2]{l} (Generic JIT) \\
    \mintinline{text}{-DKokkos_ARCH_INTEL_PVC=ON} & Xe-HPC & GPU Max 1550 (Ponte Vecchio) \\
    \mintinline{text}{-DKokkos_ARCH_INTEL_XEHP=ON} & Xe-HP & \\
    \mintinline{text}{-DKokkos_ARCH_INTEL_DG2=ON} & DG2 & Flex, Arc \\
    \mintinline{text}{-DKokkos_ARCH_INTEL_DG1=ON} & DG1 & Iris Xe MAX \\
    \mintinline{text}{-DKokkos_ARCH_INTEL_GEN12LP=ON} & Gen12LP & UHD Graphics 770 \\
    \mintinline{text}{-DKokkos_ARCH_INTEL_GEN11=ON} & Gen11 & UHD Graphics \\
\end{tblr}
}

\paragraph{NVIDIA GPU architectures (CUDA)}

{
% temporary disable justify align
\RenewDocumentCommand\TblrAlignBoth{}{\RaggedRight}
\begin{tblr}[theme=kokkostable]{lllX}
    Option & Arch. & CC & Assoc.\ cards \\
    \mintinline{text}{-DKokkos_ARCH_BLACKWELL120=ON} & Blackwell & 12.0 & RTX 5080 \\
    \mintinline{text}{-DKokkos_ARCH_BLACKWELL103=ON} & Blackwell & 10.0 & B300 \\
    \mintinline{text}{-DKokkos_ARCH_BLACKWELL100=ON} & Blackwell & 10.0 & B200, B100 \\
    \mintinline{text}{-DKokkos_ARCH_HOPPER90=ON} & Hopper & 9.0 & H200, H100 \\
    \mintinline{text}{-DKokkos_ARCH_ADA89=ON} & Ada & 8.9 & L4, L40 \\
    \mintinline{text}{-DKokkos_ARCH_AMPERE87=ON} & Ampere & 8.7 & Jetson Orin \\
\end{tblr}
}

% table broken between two pages

\begin{tblr}[theme=kokkostable]{lllX}
    Option & Arch. & CC & Associated cards \\
    \mintinline{text}{-DKokkos_ARCH_AMPERE86=ON} & Ampere & 8.6 & A40, A10, A16, A2 \\
    \mintinline{text}{-DKokkos_ARCH_AMPERE80=ON} & Ampere & 8.0 & A100, A30 \\
    \mintinline{text}{-DKokkos_ARCH_TURING75=ON} & Turing & 7.5 & T4 \\
    \mintinline{text}{-DKokkos_ARCH_VOLTA70=ON} & Volta & 7.0 & V100 \\
    \mintinline{text}{-DKokkos_ARCH_PASCAL61=ON} & Pascal & 6.1 & P6, P40, P4 \\
    \mintinline{text}{-DKokkos_ARCH_PASCAL60=ON} & Pascal & 6.0 & P100 \\
    \mintinline{text}{-DKokkos_ARCH_MAXWELL53=ON} & Maxwell & 5.3 &  \\
    \mintinline{text}{-DKokkos_ARCH_MAXWELL52=ON} & Maxwell & 5.2 & M6, M60, M4, M40 \\
    \mintinline{text}{-DKokkos_ARCH_MAXWELL50=ON} & Maxwell & 5.0 & M10 \\
\end{tblr}

\subsection{Examples for the most common architectures}

\subsubsection{Current CPU with OpenMP}

\begin{minted}{sh}
    cmake \
        -B build \
        -DCMAKE_BUILD_TYPE=Release \
        -DKokkos_ENABLE_OPENMP=ON \
        -DKokkos_ARCH_NATIVE=ON
\end{minted}

\subsubsection{AMD MI300A APU with HIP}

\begin{minted}{sh}
    export HSA_XNACK=1
    cmake \
        -B build \
        -DCMAKE_CXX_COMPILER=hipcc \
        -DCMAKE_BUILD_TYPE=Release \
        -DKokkos_ENABLE_HIP=ON \
        -DKokkos_ARCH_AMD_GFX942_APU=ON
\end{minted}

The environment variable is required to access host allocations from the device.

\subsubsection{AMD MI250 GPU with HIP}

\begin{minted}{sh}
    cmake \
        -B build \
        -DCMAKE_CXX_COMPILER=hipcc \
        -DCMAKE_BUILD_TYPE=Release \
        -DKokkos_ENABLE_HIP=ON \
        -DKokkos_ARCH_AMD_GFX90A=ON
\end{minted}

\subsubsection{Intel GPU Max 1550 (Ponte Vecchio) with SYCL}

\begin{minted}{sh}
    cmake \
        -B build \
        -DCMAKE_CXX_COMPILER=icpx \
        -DCMAKE_BUILD_TYPE=Release \
        -DKokkos_ENABLE_SYCL=ON \
        -DKokkos_ARCH_INTEL_PVC=ON \
        -DCMAKE_CXX_FLAGS="-fp-model=precise"
\end{minted}

The last option is required for math operators precision.

\subsubsection{NVIDIA H100 GPU with CUDA}

\begin{minted}{sh}
    cmake \
        -B build \
        -DCMAKE_BUILD_TYPE=Release \
        -DKokkos_ENABLE_CUDA=ON \
        -DKokkos_ARCH_HOPPER90=ON
\end{minted}

\subsubsection{NVIDIA A100 GPU with CUDA}

\begin{minted}{sh}
    cmake \
        -B build \
        -DCMAKE_BUILD_TYPE=Release \
        -DKokkos_ENABLE_CUDA=ON \
        -DKokkos_ARCH_AMPERE80=ON
\end{minted}

\end{multicols}

% add a watermark here

%\watermark

% add a notes section here

%\notessection

% add a notes section followed by a watermark here

%\notessection{\watermark}

\end{document}