Repository: kokkos/kokkos-fft
Pull request #256: Unuse kokkos fft enable host and device
Author: login: yasahi-hpc
Labels: name: enhancement
description: New feature or request
name: CI
name: CMake
Created: 2025-04-15T09:13:18Z | Merged: 2025-04-15T15:57:37Z

Resolves #150 

This PR aims at deprecating the usage of KokkosFFT_ENABLE_HOST_AND_DEVICE.

- [x] Remove `ENABLE_HOST_AND_DEVICE` from the source code.
- [x] Unuse `KokkosFFT_ENABLE_HOST_AND_DEVICE` in CI
- [x] Documented that `KokkosFFT_ENABLE_HOST_AND_DEVICE` is deprecated

Modified on 15/Apr
- [x] Add docs for enums and macros

Linked issue #150: About ensuring that `KokkosFFT_ENABLE_HOST_AND_DEVICE` is enabled
If a project relies on the option `KokkosFFT_ENABLE_HOST_AND_DEVICE`, it will likely need to know if the installed KokkosFFT provides it or not.

Could adding `#cmakedefine KOKKOSFFT_ENABLE_HOST_AND_DEVICE` do the job ?

cc @jbigot 
Linked issue comments: user: login: yasahi-hpc
created_at: 2024-10-06T08:19:52Z
body: Makes sense. Can you wait for v0.3.0?
author_association: COLLABORATOR
user: login: tpadioleau
created_at: 2024-10-06T09:20:08Z
body: yes it is fine for me
author_association: MEMBER
user: login: jbigot
created_at: 2024-10-06T20:31:15Z
body: I was thinking of offering support for the `COMPONENTS` keyword of `find_package` so that the requirement can be expressed from CMake and in case multiple versions are installed, the right one is found
author_association: MEMBER

Diff:
diff --git a/.github/workflows/build_test.yaml b/.github/workflows/build_test.yaml
index 0fcf5cf5..cfd8b91d 100644
--- a/.github/workflows/build_test.yaml
+++ b/.github/workflows/build_test.yaml
@@ -141,7 +141,7 @@ jobs:
           - name: native
             cmake_flags: ""
           - name: host_device
-            cmake_flags: -DKokkosFFT_ENABLE_HOST_AND_DEVICE=ON
+            cmake_flags: -DKokkosFFT_ENABLE_FFTW=ON
         exclude:
           - backend:
               name: clang-tidy
diff --git a/docs/api/enums/direction.rst b/docs/api/enums/direction.rst
new file mode 100644
index 00000000..d844279c
--- /dev/null
+++ b/docs/api/enums/direction.rst
@@ -0,0 +1,9 @@
+.. SPDX-FileCopyrightText: (C) The kokkos-fft development team, see COPYRIGHT.md file
+..
+.. SPDX-License-Identifier: MIT OR Apache-2.0 WITH LLVM-exception
+
+KokkosFFT::Direction
+--------------------
+
+.. doxygenenum:: KokkosFFT::Direction
+   :project: KokkosFFT
diff --git a/docs/api/enums/normalization.rst b/docs/api/enums/normalization.rst
new file mode 100644
index 00000000..b8e62c40
--- /dev/null
+++ b/docs/api/enums/normalization.rst
@@ -0,0 +1,9 @@
+.. SPDX-FileCopyrightText: (C) The kokkos-fft development team, see COPYRIGHT.md file
+..
+.. SPDX-License-Identifier: MIT OR Apache-2.0 WITH LLVM-exception
+
+KokkosFFT::Normalization
+------------------------
+
+.. doxygenenum:: KokkosFFT::Normalization
+   :project: KokkosFFT
diff --git a/docs/api_reference.rst b/docs/api_reference.rst
index cb8401cc..5c90c2d3 100644
--- a/docs/api_reference.rst
+++ b/docs/api_reference.rst
@@ -171,4 +171,47 @@ Helper routines
      - `numpy.fft.fftshift <https://numpy.org/doc/stable/reference/generated/numpy.fft.fftshift.html>`_
    * - The inverse of :doc:`fftshift<api/helper/fftshift>`
      - :doc:`api/helper/ifftshift`
-     - `numpy.fft.ifftshift <https://numpy.org/doc/stable/reference/generated/numpy.fft.ifftshift.html>`_
\ No newline at end of file
+     - `numpy.fft.ifftshift <https://numpy.org/doc/stable/reference/generated/numpy.fft.ifftshift.html>`_
+
+Enums
+-----
+
+.. toctree::
+   :maxdepth: 1
+   :hidden:
+
+   api/enums/normalization
+   api/enums/direction
+
+.. list-table::
+   :widths: 50 50
+   :header-rows: 1
+
+   * - Description
+     - ``kokkos-fft``
+   * - Tag to specify when and how to normalize
+     - :doc:`api/enums/normalization`
+   * - Tag to specify FFT direction
+     - :doc:`api/enums/direction`
+
+Macros
+------
+
+Following macros can be used to check whether a backend library is enabled or not.
+
+.. list-table::
+   :widths: 50 50
+   :header-rows: 1
+
+   * - Description
+     - Macros
+   * - Defined if the FFTW is enabled.
+     - ``KOKKOSFFT_ENABLE_TPL_FFTW``
+   * - Defined if the cufft is enabled.
+     - ``KOKKOSFFT_ENABLE_TPL_CUFFT``
+   * - Defined if the hipfft is enabled.
+     - ``KOKKOSFFT_ENABLE_TPL_HIPFFT``
+   * - Defined if the rocfft is enabled.
+     - ``KOKKOSFFT_ENABLE_TPL_ROCFFT``
+   * - Defined if the oneMKL is enabled.
+     - ``KOKKOSFFT_ENABLE_TPL_ONEMKL``
diff --git a/docs/finding_libraries.rst b/docs/finding_libraries.rst
index d1d6247b..294e6c1c 100644
--- a/docs/finding_libraries.rst
+++ b/docs/finding_libraries.rst
@@ -38,7 +38,7 @@ If CMake fails to find ``fftw``, please try to set ``FFTWDIR`` in the following
 ------------------------------------------
 
 `oneMKL <https://www.intel.com/content/www/us/en/developer/tools/oneapi/onemkl.html>`_
-------------------------------------------------------------------------------------
+--------------------------------------------------------------------------------------
 
 The most likely scenario to miss ``oneMKL`` is that forgetting to initialize ``oneAPI``.
 Please make sure to initialize ``oneAPI`` as
diff --git a/docs/intro/building.rst b/docs/intro/building.rst
index 552e9c20..55546099 100644
--- a/docs/intro/building.rst
+++ b/docs/intro/building.rst
@@ -76,9 +76,10 @@ CMake options
 
 We rely on CMake to build kokkos-fft, more specifically ``CMake 3.22+``. Here is the list of CMake options. 
 For FFTs on Kokkos device only, we do not need to add extra compile options but for Kokkos ones.
-In order to use kokkos-fft from both host and device, it is necessary to add ``KokkosFFT_ENABLE_HOST_AND_DEVICE=ON``.
+In order to use kokkos-fft from both host and device, it is necessary to add ``KokkosFFT_ENABLE_FFTW=ON``.
 This option may be useful, for example FFT is used for initialization at host. 
 However, to enable this option, we need a pre-installed ``fftw`` for FFT on host, so it is disabled in default
+if one of the device backend is enabled.
 (see :doc:`minimum working example<../samples/05_1DFFT_HOST_DEVICE>`).
 
 .. list-table:: CMake options
@@ -88,7 +89,7 @@ However, to enable this option, we need a pre-installed ``fftw`` for FFT on host
    * - 
      - Description
      - Default
-   * - ``KokkosFFT_ENABLE_HOST_AND_DEVICE``
+   * - ``KokkosFFT_ENABLE_HOST_AND_DEVICE`` :red:`[Deprecated since 0.3]`
      - Enable FFT on both host and device.
      - OFF
    * - ``KokkosFFT_ENABLE_INTERNAL_KOKKOS``
@@ -103,9 +104,27 @@ However, to enable this option, we need a pre-installed ``fftw`` for FFT on host
    * - ``KokkosFFT_ENABLE_BENCHMARK``
      - Build benchmarks for kokkos-fft
      - OFF
+   * - ``KokkosFFT_ENABLE_FFTW``
+     - Use `fftw <http://www.fftw.org>`_ for Host backend
+     - ON (if none of Kokkos devices is enabled, otherwise OFF)
+   * - ``KokkosFFT_ENABLE_CUFFT``
+     - Use `cufft <https://developer.nvidia.com/cufft>`_ for CUDA backend
+     - ON (if ``Kokkos_ENABLE_CUDA`` is ON, otherwise OFF)
    * - ``KokkosFFT_ENABLE_ROCFFT``
      - Use `rocfft <https://github.com/ROCm/rocFFT>`_ for HIP backend
      - OFF
+   * - ``KokkosFFT_ENABLE_HIPFFT``
+     - Use `hipfft <https://github.com/ROCm/hipFFT>`_ for HIP backend
+     - ON (if ``Kokkos_ENABLE_HIP`` is ON, otherwise OFF)
+   * - ``KokkosFFT_ENABLE_ONEMKL``
+     - Use `oneMKL <https://www.intel.com/content/www/us/en/developer/tools/oneapi/onemkl.html>`_ for SYCL backend
+     - ON (if ``Kokkos_ENABLE_SYCL`` is ON, otherwise OFF)
+
+.. note::
+
+   To enable kokkos-fft on both host and device, set ``KokkosFFT_ENABLE_FFTW=ON`` instead of setting ``KokkosFFT_ENABLE_HOST_AND_DEVICE=ON``.
+   Multiple device tpls cannot be enabled at the same time. In addition, at least one tpl must be enabled to configure.
+   For example, it is allowed to set ``KokkosFFT_ENABLE_CUFFT=OFF`` even if ``Kokkos_ENABLE_CUDA=ON`` as long as ``KokkosFFT_ENABLE_FFTW=ON``.
 
 Kokkos backends
 ---------------
diff --git a/fft/src/CMakeLists.txt b/fft/src/CMakeLists.txt
index ca7d55c1..b0c7f10f 100644
--- a/fft/src/CMakeLists.txt
+++ b/fft/src/CMakeLists.txt
@@ -45,10 +45,6 @@ elseif("FFTW_SERIAL" IN_LIST KOKKOSFFT_TPL_LIST)
   target_compile_definitions(fft INTERFACE KOKKOSFFT_ENABLE_TPL_FFTW)
 endif()
 
-if(KokkosFFT_ENABLE_HOST_AND_DEVICE)
-  target_compile_definitions(fft INTERFACE ENABLE_HOST_AND_DEVICE)
-endif()
-
 target_include_directories(
   fft INTERFACE $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}> $<INSTALL_INTERFACE:${INSTALL_INCLUDEDIR}>
 )
diff --git a/fft/src/KokkosFFT_Cuda_types.hpp b/fft/src/KokkosFFT_Cuda_types.hpp
index 00e123a2..ebbe31ee 100644
--- a/fft/src/KokkosFFT_Cuda_types.hpp
+++ b/fft/src/KokkosFFT_Cuda_types.hpp
@@ -11,7 +11,7 @@
 #include "KokkosFFT_common_types.hpp"
 #include "KokkosFFT_asserts.hpp"
 
-#if defined(ENABLE_HOST_AND_DEVICE)
+#if defined(KOKKOSFFT_ENABLE_TPL_FFTW)
 #include "KokkosFFT_FFTW_Types.hpp"
 #endif
 
@@ -76,7 +76,7 @@ struct ScopedCufftPlan {
   }
 };
 
-#if defined(ENABLE_HOST_AND_DEVICE)
+#if defined(KOKKOSFFT_ENABLE_TPL_FFTW)
 template <typename ExecutionSpace>
 struct FFTDataType {
   using float32 =
diff --git a/fft/src/KokkosFFT_HIP_types.hpp b/fft/src/KokkosFFT_HIP_types.hpp
index 16e5eea1..2becf7c8 100644
--- a/fft/src/KokkosFFT_HIP_types.hpp
+++ b/fft/src/KokkosFFT_HIP_types.hpp
@@ -11,7 +11,7 @@
 #include "KokkosFFT_common_types.hpp"
 #include "KokkosFFT_asserts.hpp"
 
-#if defined(ENABLE_HOST_AND_DEVICE)
+#if defined(KOKKOSFFT_ENABLE_TPL_FFTW)
 #include "KokkosFFT_FFTW_Types.hpp"
 #endif
 
@@ -76,7 +76,7 @@ struct ScopedHIPfftPlan {
   }
 };
 
-#if defined(ENABLE_HOST_AND_DEVICE)
+#if defined(KOKKOSFFT_ENABLE_TPL_FFTW)
 template <typename ExecutionSpace>
 struct FFTDataType {
   using float32 =
diff --git a/fft/src/KokkosFFT_ROCM_types.hpp b/fft/src/KokkosFFT_ROCM_types.hpp
index 38c6682e..0f30a89b 100644
--- a/fft/src/KokkosFFT_ROCM_types.hpp
+++ b/fft/src/KokkosFFT_ROCM_types.hpp
@@ -14,7 +14,7 @@
 #include "KokkosFFT_common_types.hpp"
 #include "KokkosFFT_traits.hpp"
 #include "KokkosFFT_asserts.hpp"
-#if defined(ENABLE_HOST_AND_DEVICE)
+#if defined(KOKKOSFFT_ENABLE_TPL_FFTW)
 #include "KokkosFFT_FFTW_Types.hpp"
 #endif
 
@@ -32,7 +32,7 @@ using FFTDirectionType                     = int;
 constexpr FFTDirectionType ROCFFT_FORWARD  = 1;
 constexpr FFTDirectionType ROCFFT_BACKWARD = -1;
 
-#if !defined(ENABLE_HOST_AND_DEVICE)
+#if !defined(KOKKOSFFT_ENABLE_TPL_FFTW)
 enum class FFTWTransformType { R2C, D2Z, C2R, Z2D, C2C, Z2Z };
 #endif
 
@@ -315,7 +315,7 @@ struct transform_type<ExecutionSpace, Kokkos::complex<T1>,
   static constexpr FFTWTransformType type() { return m_type; };
 };
 
-#if defined(ENABLE_HOST_AND_DEVICE)
+#if defined(KOKKOSFFT_ENABLE_TPL_FFTW)
 
 template <typename ExecutionSpace>
 struct FFTDataType {
diff --git a/fft/src/KokkosFFT_SYCL_types.hpp b/fft/src/KokkosFFT_SYCL_types.hpp
index 9c6cb86b..c1dbd8b5 100644
--- a/fft/src/KokkosFFT_SYCL_types.hpp
+++ b/fft/src/KokkosFFT_SYCL_types.hpp
@@ -12,7 +12,7 @@
 #include "KokkosFFT_common_types.hpp"
 #include "KokkosFFT_utils.hpp"
 
-#if defined(ENABLE_HOST_AND_DEVICE)
+#if defined(KOKKOSFFT_ENABLE_TPL_FFTW)
 #include "KokkosFFT_FFTW_Types.hpp"
 #endif
 
@@ -31,7 +31,7 @@ using FFTDirectionType                      = int;
 constexpr FFTDirectionType MKL_FFT_FORWARD  = 1;
 constexpr FFTDirectionType MKL_FFT_BACKWARD = -1;
 
-#if !defined(ENABLE_HOST_AND_DEVICE)
+#if !defined(KOKKOSFFT_ENABLE_TPL_FFTW)
 enum class FFTWTransformType { R2C, D2Z, C2R, Z2D, C2C, Z2Z };
 #endif
 
@@ -76,7 +76,7 @@ struct transform_type<ExecutionSpace, Kokkos::complex<T1>,
   static constexpr FFTWTransformType type() { return m_type; };
 };
 
-#if defined(ENABLE_HOST_AND_DEVICE)
+#if defined(KOKKOSFFT_ENABLE_TPL_FFTW)
 
 template <typename ExecutionSpace>
 struct FFTDataType {


Reviews:
user: login: tpadioleau
body: Ok for me
state: DISMISSED
author_association: MEMBER
submitted_at: 2025-04-15T13:08:08Z
user: login: yasahi-hpc
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-04-15T13:29:07Z
user: login: tpadioleau
state: DISMISSED
author_association: MEMBER
submitted_at: 2025-04-15T14:28:07Z
user: login: tpadioleau
state: APPROVED
author_association: MEMBER
submitted_at: 2025-04-15T15:50:06Z

Review comments:
diff_hunk: @@ -103,9 +104,27 @@ However, to enable this option, we need a pre-installed ``fftw`` for FFT on host
    * - ``KokkosFFT_ENABLE_BENCHMARK``
      - Build benchmarks for kokkos-fft
      - OFF
+   * - ``KokkosFFT_ENABLE_FFTW``
+     - Use `fftw <http://www.fftw.org>`_ for Host backend
+     - ON (if non of Kokkos devices is enabled, otherwise OFF)
path: docs/intro/building.rst
user: login: tpadioleau
body: ```suggestion
     - ON (if none of Kokkos devices is enabled, otherwise OFF)
```
created_at: 2025-04-15T13:02:34Z
author_association: MEMBER
diff_hunk: @@ -103,9 +104,27 @@ However, to enable this option, we need a pre-installed ``fftw`` for FFT on host
    * - ``KokkosFFT_ENABLE_BENCHMARK``
      - Build benchmarks for kokkos-fft
      - OFF
+   * - ``KokkosFFT_ENABLE_FFTW``
+     - Use `fftw <http://www.fftw.org>`_ for Host backend
+     - ON (if non of Kokkos devices is enabled, otherwise OFF)
path: docs/intro/building.rst
user: login: yasahi-hpc
body: Thanks! I have fixed this
created_at: 2025-04-15T13:29:06Z
author_association: COLLABORATOR

PR comments:
user: login: yasahi-hpc
created_at: 2025-04-15T11:54:19Z
body: @tpadioleau Hi, can I have your review? I have updated based on the discussions in #249 
author_association: COLLABORATOR
user: login: yasahi-hpc
created_at: 2025-04-15T14:03:02Z
body: @tpadioleau Thank you for the review.
I will merge this. Is it OK for you to close #150 ?
author_association: COLLABORATOR
user: login: tpadioleau
created_at: 2025-04-15T14:27:17Z
body: > @tpadioleau Thank you for the review. I will merge this. Is it OK for you to close #150 ?

Can you clarify what would be the conclusion of #150 in kokkos-fft 0.3 ? To use the macro `KOKKOSFFT_ENABLE_TPL_FFTW` ?
author_association: MEMBER
user: login: yasahi-hpc
created_at: 2025-04-15T14:34:27Z
body: > > @tpadioleau Thank you for the review. I will merge this. Is it OK for you to close #150 ?
> 
> Can you clarify what would be the conclusion of #150 in kokkos-fft 0.3 ? To use the macro `KOKKOSFFT_ENABLE_TPL_FFTW` ?

Yes. You can use that macro to check if `FFTW` is available or not.
author_association: COLLABORATOR
user: login: yasahi-hpc
created_at: 2025-04-15T15:40:07Z
body: > > > @tpadioleau Thank you for the review. I will merge this. Is it OK for you to close #150 ?
> > 
> > 
> > Can you clarify what would be the conclusion of #150 in kokkos-fft 0.3 ? To use the macro `KOKKOSFFT_ENABLE_TPL_FFTW` ?
> 
> Yes. You can use that macro to check if `FFTW` is available or not.

@tpadioleau I added the docs for macros. Is it sufficient to understand the usage of macros?
author_association: COLLABORATOR
user: login: tpadioleau
created_at: 2025-04-15T15:49:58Z
body: > @tpadioleau I added the docs for macros. Is it sufficient to understand the usage of macros?

Yes seems very fine to me
author_association: MEMBER