Cleanup docs (#231)

* update onemkl url in README.md * fix comments in inplace transform example * use const instead of constexpr in install_test * Add tparam in docstrings for fft APIs * Add tparam in docstrings for common APIs * fix oneMKL url and change the max depth of contents * fix: typos in docstrings based on a review --------- Co-authored-by: Yuuichi Asahi <[email protected]>
kokkos · Feb 24, 2025 · 07a18cc · 07a18cc
1 parent 77161f5
commit 07a18cc
Show file tree

Hide file tree

Showing 9 changed files with 97 additions and 13 deletions.
diff --git a/README.md b/README.md
@@ -13,7 +13,7 @@ SPDX-License-Identifier: MIT OR Apache-2.0 WITH LLVM-exception
 > [!WARNING]
 > EXPERIMENTAL FFT interfaces for Kokkos C++ Performance Portability Programming EcoSystem
 
-kokkos-fft implements local interfaces between [Kokkos](https://github.com/kokkos/kokkos) and de facto standard FFT libraries, including [fftw](http://www.fftw.org), [cufft](https://developer.nvidia.com/cufft), [hipfft](https://github.com/ROCm/hipFFT) ([rocfft](https://github.com/ROCm/rocFFT)), and [oneMKL](https://spec.oneapi.io/versions/latest/elements/oneMKL/source/index.html). "Local" means not using MPI, or running within a single MPI process without knowing about MPI. We are inclined to implement the [numpy.fft](https://numpy.org/doc/stable/reference/routines.fft.html)-like interfaces adapted for [Kokkos](https://github.com/kokkos/kokkos).
+kokkos-fft implements local interfaces between [Kokkos](https://github.com/kokkos/kokkos) and de facto standard FFT libraries, including [fftw](http://www.fftw.org), [cufft](https://developer.nvidia.com/cufft), [hipfft](https://github.com/ROCm/hipFFT) ([rocfft](https://github.com/ROCm/rocFFT)), and [oneMKL](https://www.intel.com/content/www/us/en/developer/tools/oneapi/onemkl.html). "Local" means not using MPI, or running within a single MPI process without knowing about MPI. We are inclined to implement the [numpy.fft](https://numpy.org/doc/stable/reference/routines.fft.html)-like interfaces adapted for [Kokkos](https://github.com/kokkos/kokkos).
 A key concept is that **"As easy as numpy, as fast as vendor libraries"**. Accordingly, our API follows the API by [numpy.fft](https://numpy.org/doc/stable/reference/routines.fft.html) with minor differences. A fft library dedicated to Kokkos Device backend (e.g. [cufft](https://developer.nvidia.com/cufft) for CUDA backend) is automatically used. If something is wrong with runtime values (say `View` extents), it will raise runtime errors (C++ `std::runtime_error`). See [documentations](https://kokkosfft.readthedocs.io/) for more information.
 
 Here is an example for 1D real to complex transform with `rfft` in kokkos-fft.
@@ -63,8 +63,9 @@ Kokkos::Random_XorShift64_Pool<> random_pool(12345);
 Kokkos::fill_random(x, random_pool, 1);
 Kokkos::fence();
 
+// FFT along -1 axis and batched along 0th axis
 int axis = -1;
-KokkosFFT::rfft(execution_space(), x, x_hat, KokkosFFT::Normalization::backward, axis); // FFT along -1 axis and batched along 0th axis
+KokkosFFT::rfft(execution_space(), x, x_hat, KokkosFFT::Normalization::backward, axis);
 ```
 
 This is equivalent to
@@ -138,4 +139,4 @@ This way, all the functionalities are executed on A100 GPUs. For installation, d
 [![License](https://img.shields.io/badge/License-Apache--2.0_WITH_LLVM--exception-blue)](https://spdx.org/licenses/LLVM-exception.html)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-kokkos-fft is distributed under either the MIT license, or at your option, the Apache-2.0 licence with LLVM exception.
+kokkos-fft is distributed under either the MIT license, or at your option, the Apache-2.0 license with LLVM exception.
diff --git a/common/src/KokkosFFT_Helpers.hpp b/common/src/KokkosFFT_Helpers.hpp
@@ -150,6 +150,9 @@ void ifftshift_impl(const ExecutionSpace& exec_space, const ViewType& inout,
 namespace KokkosFFT {
 /// \brief Return the DFT sample frequencies
 ///
+/// \tparam ExecutionSpace: The type of Kokkos execution space
+/// \tparam RealType: The floating point precision type to represent frequencies
+///
 /// \param exec_space [in] Kokkos execution space
 /// \param n [in] Window length
 /// \param d [in] Sample spacing (default, 1)
@@ -185,6 +188,9 @@ auto fftfreq(const ExecutionSpace&, const std::size_t n,
 
 /// \brief Return the DFT sample frequencies for Real FFTs
 ///
+/// \tparam ExecutionSpace: The type of Kokkos execution space
+/// \tparam RealType: The floating point precision type to represent frequencies
+///
 /// \param exec_space [in] Kokkos execution space
 /// \param n [in] Window length
 /// \param d [in] Sample spacing (default, 1)
@@ -214,6 +220,9 @@ auto rfftfreq(const ExecutionSpace&, const std::size_t n,
 
 /// \brief Shift the zero-frequency component to the center of the spectrum
 ///
+/// \tparam ExecutionSpace: The type of Kokkos execution space
+/// \tparam ViewType: Input/Output View type for the shift
+///
 /// \param exec_space [in] Kokkos execution space
 /// \param inout [in,out] Spectrum
 /// \param axes [in] Axes over which to shift (default: nullopt, shifting over
@@ -242,6 +251,10 @@ void fftshift(const ExecutionSpace& exec_space, const ViewType& inout,
 
 /// \brief Shift the zero-frequency component to the center of the spectrum
 ///
+/// \tparam ExecutionSpace: The type of Kokkos execution space
+/// \tparam ViewType: Input/Output View type for the shift
+/// \tparam DIM: The dimensionality of the shift
+///
 /// \param exec_space [in] Kokkos execution space
 /// \param inout [in,out] Spectrum
 /// \param axes [in] Axes over which to shift
@@ -264,6 +277,9 @@ void fftshift(const ExecutionSpace& exec_space, const ViewType& inout,
 
 /// \brief The inverse of fftshift
 ///
+/// \tparam ExecutionSpace: The type of Kokkos execution space
+/// \tparam ViewType: Input/Output View type for the shift
+///
 /// \param exec_space [in] Kokkos execution space
 /// \param inout [in,out] Spectrum
 /// \param axes [in] Axes over which to shift (default: nullopt, shifting over
@@ -291,6 +307,10 @@ void ifftshift(const ExecutionSpace& exec_space, const ViewType& inout,
 
 /// \brief The inverse of fftshift
 ///
+/// \tparam ExecutionSpace: The type of Kokkos execution space
+/// \tparam ViewType: Input/Output View type for the shift
+/// \tparam DIM: The dimensionality of the shift
+///
 /// \param exec_space [in] Kokkos execution space
 /// \param inout [in,out] Spectrum
 /// \param axes [in] Axes over which to shift

diff --git a/docs/index.rst b/docs/index.rst
@@ -9,7 +9,7 @@ kokkos-fft implements local interfaces between `Kokkos <https://kokkos.org>`_
 and de facto standard FFT libraries, 
 including `fftw <http://www.fftw.org>`_,
 `cufft <https://developer.nvidia.com/cufft>`_,
-`hipfft <https://github.com/ROCm/hipFFT>`_ (`rocfft <https://github.com/ROCm/rocFFT>`_), and `oneMKL <https://spec.oneapi.io/versions/latest/elements/oneMKL/source/index.html>`_. 
+`hipfft <https://github.com/ROCm/hipFFT>`_ (`rocfft <https://github.com/ROCm/rocFFT>`_), and `oneMKL <https://www.intel.com/content/www/us/en/developer/tools/oneapi/onemkl.html>`_. 
 "Local" means not using MPI, or running within a single MPI process without knowing about MPI.
 We are inclined to implement the `numpy.fft <https://numpy.org/doc/stable/reference/routines.fft.html>`_-like interfaces adapted for Kokkos.
 A key concept is that *"As easy as numpy, as fast as vendor libraries"*. Accordingly, our API follows the API by ``numpy.fft`` with minor differences. 
@@ -52,7 +52,7 @@ This is equivalent to the following python script.
 
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
    getting_started
    finding_libraries

diff --git a/docs/intro/using.rst b/docs/intro/using.rst
@@ -124,8 +124,7 @@ Reuse FFT plan
 
 Apart from the basic APIs, kokkos-fft offers the capability to create a FFT plan wrapping the FFT plans of backend libraries.
 We can reuse the FFT plan created once to perform FFTs multiple times on different data given that they have the same properties.
-In some backend, FFT plan creation leads to some overhead, wherein we need this functionality.
-(see :doc:`minimum working example<../samples/06_1DFFT_reuse_plans>`)
+In some backend, FFT plan creation leads to some overhead, wherein we need this functionality (see :doc:`minimum working example<../samples/06_1DFFT_reuse_plans>`).
 The following listing shows an example to reuse the FFT plan.
 
 .. code-block:: C++
@@ -207,7 +206,7 @@ Inplace transform
 Inplace transform is supported in kokkos-fft in case transpose or reshape is not needed. 
 For standard FFTs, we can just use the same input and output Views. For real FFTs, we need to use a single complex View and make 
 an unmanaged View which is an alias to the complex View. In addition, we need to pay attention to the extents of a real View,
-which should define the shape of the transform, not the reinterpreted shape of the complex View. (see :doc:`minimum working example<../samples/08_inplace_FFT>`)
+which should define the shape of the transform, not the reinterpreted shape of the complex View (see :doc:`minimum working example<../samples/08_inplace_FFT>`). 
 The following listing shows examples of inplace transforms. 
 
 .. code-block:: C++
@@ -229,7 +228,7 @@ The following listing shows examples of inplace transforms.
    // Create unmanaged views on the same data with the FFT shape,
    // that is (n0, n1) -> (n0, n1/2+1) R2C transform
    // The shape is incorrect from the view point of casting to real
-   // For casting, the shape should be (n0, (n0/2+1) * 2)
+   // For casting, the shape should be (n0, (n1/2+1) * 2)
    View2D<double> xr2c(reinterpret_cast<double *>(xr2c_hat.data()), n0, n1);
 
    // Perform the real to complex transform

diff --git a/examples/08_inplace_FFT/08_inplace_FFT.cpp b/examples/08_inplace_FFT/08_inplace_FFT.cpp
@@ -37,7 +37,7 @@ int main(int argc, char *argv[]) {
     // Create unmanaged views on the same data with the FFT shape,
     // that is (n0, n1) -> (n0, n1/2+1) R2C transform
     // The shape is incorrect from the view point of casting to real
-    // For casting, the shape should be (n0, (n0/2+1) * 2)
+    // For casting, the shape should be (n0, (n1/2+1) * 2)
     RightView2D<double> xr2c(reinterpret_cast<double *>(xr2c_hat.data()), n0,
                              n1),
         xr2c_padded(reinterpret_cast<double *>(xr2c_hat.data()), n0,

diff --git a/fft/src/KokkosFFT_Plans.hpp b/fft/src/KokkosFFT_Plans.hpp
@@ -64,6 +64,10 @@ namespace KokkosFFT {
 /// created. If there are inconsistency in input and output views, the
 /// compilation would fail.
 ///
+/// \tparam ExecutionSpace: The type of Kokkos execution space
+/// \tparam InViewType: Input View type for the fft
+/// \tparam OutViewType: Output View type for the fft
+/// \tparam DIM: The dimensionality of the fft
 template <typename ExecutionSpace, typename InViewType, typename OutViewType,
           std::size_t DIM = 1>
 class Plan {
@@ -136,7 +140,7 @@ class Plan {
  public:
   /// \brief Constructor
   ///
-  /// \param exec_space [in] Kokkos execution device
+  /// \param exec_space [in] Kokkos execution space for this plan
   /// \param in [in] Input data
   /// \param out [in] Output data
   /// \param direction [in] Direction of FFT (forward/backward)

diff --git a/fft/src/KokkosFFT_Transform.hpp b/fft/src/KokkosFFT_Transform.hpp
@@ -34,6 +34,10 @@ void execute(
 
 /// \brief One dimensional FFT in forward direction
 ///
+/// \tparam ExecutionSpace: The type of Kokkos execution space
+/// \tparam InViewType: Input View type for the fft
+/// \tparam OutViewType: Output View type for the fft
+///
 /// \param exec_space [in] Kokkos execution space
 /// \param in [in] Input data (complex)
 /// \param out [out] Output data (complex)
@@ -66,6 +70,10 @@ void fft(const ExecutionSpace& exec_space, const InViewType& in,
 
 /// \brief One dimensional FFT in backward direction
 ///
+/// \tparam ExecutionSpace: The type of Kokkos execution space
+/// \tparam InViewType: Input View type for the fft
+/// \tparam OutViewType: Output View type for the fft
+///
 /// \param exec_space [in] Kokkos execution space
 /// \param in [in] Input data (complex)
 /// \param out [out] Output data (complex)
@@ -98,6 +106,10 @@ void ifft(const ExecutionSpace& exec_space, const InViewType& in,
 
 /// \brief One dimensional FFT for real input
 ///
+/// \tparam ExecutionSpace: The type of Kokkos execution space
+/// \tparam InViewType: Input View type for the fft
+/// \tparam OutViewType: Output View type for the fft
+///
 /// \param exec_space [in] Kokkos execution space
 /// \param in [in] Input data (real)
 /// \param out [out] Output data (complex)
@@ -136,6 +148,10 @@ void rfft(const ExecutionSpace& exec_space, const InViewType& in,
 
 /// \brief Inverse of rfft
 ///
+/// \tparam ExecutionSpace: The type of Kokkos execution space
+/// \tparam InViewType: Input View type for the fft
+/// \tparam OutViewType: Output View type for the fft
+///
 /// \param exec_space [in] Kokkos execution space
 /// \param in [in] Input data (complex)
 /// \param out [out] Output data (real)
@@ -175,6 +191,10 @@ void irfft(const ExecutionSpace& exec_space, const InViewType& in,
 
 /// \brief One dimensional FFT of a signal that has Hermitian symmetry
 ///
+/// \tparam ExecutionSpace: The type of Kokkos execution space
+/// \tparam InViewType: Input View type for the fft
+/// \tparam OutViewType: Output View type for the fft
+///
 /// \param exec_space [in] Kokkos execution space
 /// \param in [in] Input data (complex)
 /// \param out [out] Output data (real)
@@ -221,6 +241,10 @@ void hfft(const ExecutionSpace& exec_space, const InViewType& in,
 
 /// \brief Inverse of hfft
 ///
+/// \tparam ExecutionSpace: The type of Kokkos execution space
+/// \tparam InViewType: Input View type for the fft
+/// \tparam OutViewType: Output View type for the fft
+///
 /// \param exec_space [in] Kokkos execution space
 /// \param in [in] Input data (real)
 /// \param out [out] Output data (complex)
@@ -265,6 +289,10 @@ void ihfft(const ExecutionSpace& exec_space, const InViewType& in,
 
 /// \brief Two dimensional FFT in forward direction
 ///
+/// \tparam ExecutionSpace: The type of Kokkos execution space
+/// \tparam InViewType: Input View type for the fft
+/// \tparam OutViewType: Output View type for the fft
+///
 /// \param exec_space [in] Kokkos execution space
 /// \param in [in] Input data (complex)
 /// \param out [out] Output data (complex)
@@ -296,6 +324,10 @@ void fft2(const ExecutionSpace& exec_space, const InViewType& in,
 
 /// \brief Two dimensional FFT in backward direction
 ///
+/// \tparam ExecutionSpace: The type of Kokkos execution space
+/// \tparam InViewType: Input View type for the fft
+/// \tparam OutViewType: Output View type for the fft
+///
 /// \param exec_space [in] Kokkos execution space
 /// \param in [in] Input data (complex)
 /// \param out [out] Output data (complex)
@@ -328,6 +360,10 @@ void ifft2(const ExecutionSpace& exec_space, const InViewType& in,
 
 /// \brief Two dimensional FFT for real input
 ///
+/// \tparam ExecutionSpace: The type of Kokkos execution space
+/// \tparam InViewType: Input View type for the fft
+/// \tparam OutViewType: Output View type for the fft
+///
 /// \param exec_space [in] Kokkos execution space
 /// \param in [in] Input data (real)
 /// \param out [out] Output data (complex)
@@ -366,6 +402,10 @@ void rfft2(const ExecutionSpace& exec_space, const InViewType& in,
 
 /// \brief Inverse of rfft2
 ///
+/// \tparam ExecutionSpace: The type of Kokkos execution space
+/// \tparam InViewType: Input View type for the fft
+/// \tparam OutViewType: Output View type for the fft
+///
 /// \param exec_space [in] Kokkos execution space
 /// \param in [in] Input data (complex)
 /// \param out [out] Output data (real)
@@ -406,6 +446,11 @@ void irfft2(const ExecutionSpace& exec_space, const InViewType& in,
 
 /// \brief N-dimensional FFT in forward direction
 ///
+/// \tparam ExecutionSpace: The type of Kokkos execution space
+/// \tparam InViewType: Input View type for the fft
+/// \tparam OutViewType: Output View type for the fft
+/// \tparam DIM: The dimensionality of the fft
+///
 /// \param exec_space [in] Kokkos execution space
 /// \param in [in] Input data (complex)
 /// \param out [out] Output data (complex)
@@ -449,6 +494,11 @@ void fftn(
 
 /// \brief Inverse of fftn
 ///
+/// \tparam ExecutionSpace: The type of Kokkos execution space
+/// \tparam InViewType: Input View type for the fft
+/// \tparam OutViewType: Output View type for the fft
+/// \tparam DIM: The dimensionality of the fft
+///
 /// \param exec_space [in] Kokkos execution space
 /// \param in [in] Input data (complex)
 /// \param out [out] Output data (complex)
@@ -494,6 +544,11 @@ void ifftn(
 
 /// \brief N-dimensional FFT for real input
 ///
+/// \tparam ExecutionSpace: The type of Kokkos execution space
+/// \tparam InViewType: Input View type for the fft
+/// \tparam OutViewType: Output View type for the fft
+/// \tparam DIM: The dimensionality of the fft
+///
 /// \param exec_space [in] Kokkos execution space
 /// \param in [in] Input data (real)
 /// \param out [out] Output data (complex)
@@ -545,6 +600,11 @@ void rfftn(
 
 /// \brief Inverse of rfftn
 ///
+/// \tparam ExecutionSpace: The type of Kokkos execution space
+/// \tparam InViewType: Input View type for the fft
+/// \tparam OutViewType: Output View type for the fft
+/// \tparam DIM: The dimensionality of the fft
+///
 /// \param exec_space [in] Kokkos execution space
 /// \param in [in] Input data (complex)
 /// \param out [out] Output data (real)

diff --git a/install_test/as_library/hello.cpp b/install_test/as_library/hello.cpp
@@ -14,7 +14,7 @@ using View1D = Kokkos::View<T*, execution_space>;
 int main(int argc, char* argv[]) {
   Kokkos::initialize(argc, argv);
   {
-    constexpr int n0 = 128;
+    const int n0 = 128;
     const Kokkos::complex<double> z(1.0, 1.0);
 
     // 1D C2C FFT (Forward and Backward)

diff --git a/install_test/as_subdirectory/hello.cpp b/install_test/as_subdirectory/hello.cpp
@@ -14,7 +14,7 @@ using View2D = Kokkos::View<T**, execution_space>;
 int main(int argc, char* argv[]) {
   Kokkos::initialize(argc, argv);
   {
-    constexpr int n0 = 128, n1 = 128;
+    const int n0 = 128, n1 = 128;
     const Kokkos::complex<double> z(1.0, 1.0);
 
     // 2D C2C FFT (Forward and Backward)