Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve macros documentation #27

Draft
wants to merge 10 commits into
base: main
Choose a base branch
from
Draft

Improve macros documentation #27

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
f894a6b
KOKKOS_ARCH_INTEL_GEN: use description based on CMake code
cz4rs May 16, 2022
e54405f
Link the architecture keywords list
cz4rs May 16, 2022
2137cb9
Add missing architectures
cz4rs May 16, 2022
f93cf53
Added descriptions of macros that are defined in Kokkos_Macros.hpp an…
ldh4 May 17, 2022
9d14cd5
Adjusted some descriptions and removed internal macros
ldh4 May 25, 2022
a79edc1
Improve wording for CMake keywords explanation
cz4rs Jul 1, 2022
899c97c
Improve consistency
cz4rs Jul 11, 2022
ba8fd8c
Explain Google Test integration
cz4rs Jul 14, 2022
eb3c6ef
Move changes in Macros.md to the correct file
cz4rs Jan 4, 2023
ad09076
Do not change outdated file
cz4rs Jan 4, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 41 additions & 1 deletion docs/source/API/core/Macros.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -75,26 +75,66 @@ with.
| `KOKKOS_ENABLE_MEMKIND` | Defined if Kokkos enables the [Memkind](https://github.com/memkind/memkind) heap manager, enables HBWSpace. |
| `KOKKOS_ENABLE_LIBDL` | Defined if Kokkos links to the dynamic linker (libdl). |
| `KOKKOS_ENABLE_LIBQUADMATH` | Defined if Kokkos links to the [GCC Quad-Precision Math Library API](https://gcc.gnu.org/onlinedocs/libquadmath/). |
## Compilers

The following macros can be used to query the integral version values of used compilers.

| Macro | Description |
| ------| ---------------|
| `KOKKOS_COMPILER_NVCC` | Defined if NVIDIA compiler is used. |
| `KOKKOS_COMPILER_GNU` | Defined if GCC compiler is used. |
| `KOKKOS_COMPILER_INTEL` | Defined if Intel Compiler Classic or Intel oneAPI DPC++/C++ Compiler is used. |
| `KOKKOS_COMPILER_IBM` | Defined if IBM compiler or XLClang is used. |
| `KOKKOS_COMPILER_CRAYC` | Defined if CRAY compiler is used for host code. |
| `KOKKOS_COMPILER_APPLECC` | Defined if Apple cc compiler is used. |
| `KOKKOS_COMPILER_CLANG` | Defined if Clang compiler is used. |
| `KOKKOS_COMPILER_PGI` | Defined if PGI compiler is used. |
| `KOKKOS_COMPILER_NVHPC` | Defined if NVHPC compiler is used. |
| `KOKKOS_COMPILER_MSVC` | Defined if MSVC compiler is used. |

## Compiler Options for Vectorization

| Macro | Description |
| ------| ---------------|
| `KOKKOS_ENABLE_PRAGMA_IVDEP` | Defined if the compiler is enabled to ignore assumed vector dependencies. [#pragma ivdep](https://www.intel.com/content/www/us/en/develop/documentation/cpp-compiler-developer-guide-and-reference/top/compiler-reference/pragmas/intel-specific-pragma-reference/ivdep.html) |
| `KOKKOS_ENABLE_PRAGMA_LOOPCOUNT` | Defined if the compiler is enabled to specify loop iterations for optimization. [#pragma loop count](https://www.intel.com/content/www/us/en/develop/documentation/cpp-compiler-developer-guide-and-reference/top/compiler-reference/pragmas/intel-specific-pragma-reference/loop-count.html) |
| `KOKKOS_ENABLE_PRAGMA_SIMD` | Defined if the compiler has SIMD intrinsics enabled. [#pragma simd](https://www.intel.com/content/www/us/en/develop/documentation/cpp-compiler-developer-guide-and-reference/top/compiler-reference/pragmas/intel-specific-pragma-reference/simd.html) |
| `KOKKOS_ENABLE_PRAGMA_UNROLL` | Defined if the compiler is enabled to do the loop unrolling. [#pragma unroll](https://www.intel.com/content/www/us/en/develop/documentation/cpp-compiler-developer-guide-and-reference/top/compiler-reference/pragmas/intel-specific-pragma-reference/unroll-nounroll.html) |
| `KOKKOS_ENABLE_PRAGMA_VECTOR` | Defined if the compiler is enabled to force vectorization. [#pragma vector](https://www.intel.com/content/www/us/en/develop/documentation/cpp-compiler-developer-guide-and-reference/top/compiler-reference/pragmas/intel-specific-pragma-reference/vector-1.html) |

## Architectures

| Macro | Description |
| ------| ---------------|
| `KOKKOS_ARCH_NATIVE` | Optimize for local machine |
| `KOKKOS_ARCH_SSE42` | Optimize for SSE 4.2 |
| `KOKKOS_ARCH_ARMV80` | Optimize for ARMv8.0 Compatible CPU (HOST) |
| `KOKKOS_ARCH_ARMV8_THUNDERX` | Optimize for ARMv8 Cavium ThunderX CPU (HOST) |
| `KOKKOS_ARCH_ARMV81` | Optimize for ARMv8.1 Compatible CPU (HOST) |
| `KOKKOS_ARCH_ARMV8_THUNDERX2` | Optimize for ARMv8 Cavium ThunderX2 CPU (HOST) |
| `KOKKOS_ARCH_A64FX` | Optimize for ARMv8.2 with SVE Support |
| `KOKKOS_ARCH_AMD_AVX2` | Optimize for AVX2 (enabled for Zen) |
| `KOKKOS_ARCH_AMDAVX` | Optimize for AMD chip |
| `KOKKOS_ARCH_AVX` | Optimize for AVX |
| `KOKKOS_ARCH_AVX2` | Optimize for AVX2 |
| `KOKKOS_ARCH_AVX512XEON` | Optimize for Skylake(AVX512) |
| `KOKKOS_ARCH_WSM` | Optimize for Intel Westmere CPU |
| `KOKKOS_ARCH_SNB` | Optimize for Intel Sandy/Ivy Bridge CPUs |
| `KOKKOS_ARCH_HSW` | Optimize for Intel Haswell CPUs |
| `KOKKOS_ARCH_BDW` | Optimize for Intel Broadwell Xeon E-class CPUs |
| `KOKKOS_ARCH_ICL` | Optimize for Intel Ice Lake Client CPUs (AVX512) |
| `KOKKOS_ARCH_ICX` | Optimize for Intel Ice Lake Xeon Server CPUs (AVX512) |
| `KOKKOS_ARCH_SKL` | Optimize for Intel Skylake Client CPUs |
| `KOKKOS_ARCH_SKX` | Optimize for Intel Skylake Xeon Server CPUs (AVX512) |
| `KOKKOS_ARCH_KNC` | Optimize for Intel Knights Corner Xeon Phi (HOST) |
| `KOKKOS_ARCH_KNL` | Optimize for Intel Knights Landing Xeon Phi |
| `KOKKOS_ARCH_SPR` | Optimize for Intel Sapphire Rapids Xeon Server CPUs (AVX512) |
| `KOKKOS_ARCH_AVX512MIC` | Optimize for Many Integrated Core (MIC; AVX512) |
| `KOKKOS_ARCH_BGQ` | Optimize for IBM Blue Gene Q |
| `KOKKOS_ARCH_POWER7` | Optimize for IBM POWER7 CPUs (HOST) |
| `KOKKOS_ARCH_POWER8` | Optimize for IBM POWER8 CPUs (HOST) |
| `KOKKOS_ARCH_POWER9` | Optimize for IBM POWER9 CPUs (HOST)|
| `KOKKOS_ARCH_INTEL_GEN` | Optimize for Intel GPUs Gen9+ (GPU) |
| `KOKKOS_ARCH_INTEL_GEN` | Optimize for SPIR64-based devices, e.g. Intel GPUs, using JIT |
| `KOKKOS_ARCH_INTEL_DG1` | Optimize for Intel Iris XeMAX GPU (GPU) |
| `KOKKOS_ARCH_INTEL_GEN9` | Optimize for Intel GPU Gen9 (GPU)|
| `KOKKOS_ARCH_INTEL_GEN11` | Optimize for Intel GPU Gen11 (GPU) |
Expand Down
38 changes: 22 additions & 16 deletions docs/source/keywords.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,9 +5,9 @@ CMake Keywords

.. important::

With version 3.0 all Kokkos CMake keywords are prefixed with `Kokkos_` which is case-sensitive.
With version 3.0 all Kokkos CMake keywords are prefixed with ``Kokkos_`` which is case-sensitive.

Recall that to set a keyword in CMake you used the syntax ``-Dkeyword_name``.
Options can be enabled / disabled by specifying ``-DKokkos_ENABLE_X=ON`` / ``-DKokkos_ENABLE_X=OFF``.


This page is organized in four sections:
Expand All @@ -33,35 +33,35 @@ Device Backends
- Default

* - ``Kokkos_ENABLE_CUDA``
- To build CUDA backend
- Enable CUDA backend
- ``OFF``

* - ``Kokkos_ENABLE_OPENMP``
- To build OpenMP backend
- Enable OpenMP backend
- ``OFF``

* - ``Kokkos_ENABLE_THREADS``
- To build C++ Threads backend
- Enable C++ Threads backend
- ``OFF``

* - ``Kokkos_ENABLE_SERIAL``
- To build serial backend
- Enable serial backend
- ``ON``

* - ``Kokkos_ENABLE_HIP``
- To build HIP backend
- Enable HIP backend
- ``OFF``

* - ``Kokkos_ENABLE_OPENMPTARGET``
- :red:`[Experimental]` To build the OpenMP target backend
- :red:`[Experimental]` Enable the OpenMP target backend
- ``OFF``

* - ``Kokkos_ENABLE_SYCL``
- :red:`[Experimental]` To build SYCL backend
- :red:`[Experimental]` Enable SYCL backend
- ``OFF``

* - ``Kokkos_ENABLE_HPX``
- :red:`[Experimental]` To build HPX backend
- :red:`[Experimental]` Enable HPX backend
- ``OFF``


Expand Down Expand Up @@ -194,19 +194,19 @@ The following options control enabling TPLs:
* ``OFF``
* * ``Kokkos_ENABLE_HWLOC``
* Whether to enable the HWLOC library
* ``Off``
* ``OFF``
* * ``Kokkos_ENABLE_LIBNUMA``
* Whether to enable the LIBNUMA library
* ``Off``
* ``OFF``
* * ``Kokkos_ENABLE_MEMKIND``
* Whether to enable the MEMKIND library
* ``Off``
* ``OFF``
* * ``Kokkos_ENABLE_LIBDL``
* Whether to enable the LIBDL library
* ``On``
* ``ON``
* * ``Kokkos_ENABLE_LIBRT``
* Whether to enable the LIBRT library
* ``Off``
* ``OFF``

The following options control finding and configuring non-CMake TPLs:

Expand Down Expand Up @@ -256,7 +256,13 @@ The following options control ``find_package`` paths for CMake-based TPLs:

* * ``HPX_DIR`` or ``HPX_ROOT``
* Location of HPX prefix (ROOT) or CMake config file (DIR)
* PATH Default:
* PATH Default

.. note::

When building tests, Kokkos will by default use ``find_package`` to search for an installed Google Test library. To force use of internal copy instead, use CMake's built-in `CMAKE_DISABLE_FIND_PACKAGE <https://cmake.org/cmake/help/latest/variable/CMAKE_DISABLE_FIND_PACKAGE_PackageName.html>`_::

-DCMAKE_DISABLE_FIND_PACKAGE_GTest=ON

.. _keywords_arch:

Expand Down
130 changes: 0 additions & 130 deletions wiki-md-files-to-port/API-Reference/Macros.md
View file
Open in desktop

This file was deleted.