Merge pull request #74 from CExA-project/update-docs

Update docs

AUTHORS

@@ -6,4 +6,9 @@ contributions.
 Yuuichi Asahi - CEA (yuuichi.asahi(at)cea.fr)
 * Maintainer
 * Initial designer and first development steps
-* Co-developer
+* Developer
+
+Paul Zehner - CEA (paul.Zehner(at)cea.fr)
+* Co-maintainer
+* CI/CD
+* Developer

README.md

@@ -3,18 +3,13 @@
 [![CI](https://github.com/CExA-project/kokkos-fft/actions/workflows/build_test.yaml/badge.svg)](https://github.com/CExA-project/kokkos-fft/actions)
 [![docs](https://readthedocs.org/projects/kokkosfft/badge/?version=latest)](https://kokkosfft.readthedocs.io/en/latest/?badge=latest)
 
-UNOFFICIAL FFT interfaces for Kokkos C++ Performance Portability Programming EcoSystem
+> [!WARNING]
+> UNOFFICIAL FFT interfaces for Kokkos C++ Performance Portability Programming EcoSystem
 
-KokkosFFT 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), 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).
+KokkosFFT 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).
 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++ exceptions or assertions). See [documentations](https://kokkosfft.readthedocs.io/) for more information.
 
-Here is an example for 1D real to complex transform with `rfft` in python and KokkosFFT.
-```python3
-import numpy as np
-x = np.random.rand(4)
-x_hat = np.fft.rfft(x)
-```
-
+Here is an example for 1D real to complex transform with `rfft` in KokkosFFT.
 ```C++
 #include <Kokkos_Core.hpp>
 #include <Kokkos_Complex.hpp>
@@ -34,15 +29,17 @@ Kokkos::fence();
 KokkosFFT::rfft(execution_space(), x, x_hat);
 ```
 
-There are two major differences: [`execution_space`](https://kokkos.org/kokkos-core-wiki/API/core/execution_spaces.html) argument and output value (`x_hat`) is an argument of API (not returned value from API). As imagined, KokkosFFT only accepts [Kokkos Views](https://kokkos.org/kokkos-core-wiki/API/core/View.html) as input data. The accessibilities of Views from `execution_space` are statically checked (compilation errors if not accessible).
+This is equivalent to the following python code.
 
-Depending on a View dimension, it automatically uses the batched plans as follows
 ```python3
 import numpy as np
-x = np.random.rand(4, 8)
-x_hat = np.fft.rfft(x, axis=-1)
+x = np.random.rand(4)
+x_hat = np.fft.rfft(x)
 ```
 
+There are two major differences: [`execution_space`](https://kokkos.org/kokkos-core-wiki/API/core/execution_spaces.html) argument and output value (`x_hat`) is an argument of API (not returned value from API). As imagined, KokkosFFT only accepts [Kokkos Views](https://kokkos.org/kokkos-core-wiki/API/core/View.html) as input data. The accessibilities of Views from `execution_space` are statically checked (compilation errors if not accessible).
+
+Depending on a View dimension, it automatically uses the batched plans as follows
 ```C++
 #include <Kokkos_Core.hpp>
 #include <Kokkos_Complex.hpp>
@@ -60,7 +57,15 @@ Kokkos::fill_random(x, random_pool, 1);
 Kokkos::fence();
 
 int axis = -1;
-KokkosFFT::rfft(execution_space(), x, x_hat, KokkosFFT::FFT_Normalization::BACKWARD, axis); // FFT along -1 axis and batched along 0th axis
+KokkosFFT::rfft(execution_space(), x, x_hat, KokkosFFT::Normalization::backward, axis); // FFT along -1 axis and batched along 0th axis
+```
+
+This is equivalent to
+
+```python3
+import numpy as np
+x = np.random.rand(4, 8)
+x_hat = np.fft.rfft(x, axis=-1)
 ```
 
 In this example, the 1D batched `rfft` over 2D View along `axis -1` is executed. Some basic examples are found in [examples](https://github.com/CExA-project/kokkos-fft/tree/main/examples).
@@ -108,49 +113,7 @@ cmake -DCMAKE_CXX_COMPILER=g++ \
       -DKokkos_ENABLE_CUDA=ON \
       -DKokkos_ARCH_AMPERE80=ON ..
 ```
-This way, all the functionalities are executed on A100 GPUs.
-
-### Install as a library
-Is is assumed that the Kokkos is installed under `<install_dir>/kokkos` with OpenMP backend. Here is a recipe to install KokkosFFT under `<install_dir>/kokkos_fft`.
-
-```bash
-export KOKKOSFFT_INSTALL_PREFIX=<lib_dir>/kokkosFFT
-export KokkosFFT_DIR=<lib_dir>/kokkosFFT/lib64/cmake/kokkos-fft
-
-mkdir build_KokkosFFT && cd build_KokkosFFT
-cmake -DCMAKE_CXX_COMPILER=icpx \
-      -DCMAKE_INSTALL_PREFIX=${KOKKOSFFT_INSTALL_PREFIX} ..
-cmake --build . -j 8
-cmake --install .
-```
-
-Here is an example to use KokkosFFT in the following CMake project.
-```
----/
- |
- └──<project_directory>/
-    |--CMakeLists.txt
-    └──hello.cpp
-```
-
-The `CMakeLists.txt` would be
-```CMake
-cmake_minimum_required(VERSION 3.23)
-project(kokkos-fft-as-library LANGUAGES CXX)
-
-find_package(Kokkos CONFIG REQUIRED)
-find_package(KokkosFFT CONFIG REQUIRED)
-
-add_executable(hello-kokkos-fft hello.cpp)
-target_link_libraries(hello-kokkos-fft PUBLIC Kokkos::kokkos KokkosFFT::fft)
-```
-
-The code can be built as
-```bash
-mkdir build && cd build
-cmake -DCMAKE_PREFIX_PATH="<install_dir>/kokkos;<install_dir>/kokkos_fft" ..
-cmake --build . -j 8
-```
+This way, all the functionalities are executed on A100 GPUs. For installation, details are provided in the [documentation](https://kokkosfft.readthedocs.io/en/latest/intro/building.html#install-kokkosfft-as-a-library).
 
 ## LICENCE
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)  

common/src/KokkosFFT_common_types.hpp

@@ -2,20 +2,31 @@
 #define KOKKOSFFT_COMMON_TYPES_HPP
 
 namespace KokkosFFT {
-// Define type to specify transform axis
+//! Type to specify transform axis
 template <std::size_t DIM>
 using axis_type = std::array<int, DIM>;
 
-// Define type to specify new shape
+//! Type to specify new shape
 template <std::size_t DIM>
 using shape_type = std::array<std::size_t, DIM>;
 
-// Tag to specify when and how to normalize
-enum class Normalization { forward, backward, ortho, none };
+//! Tag to specify when and how to normalize
+enum class Normalization {
+  //! 1/n scaling for forward transform
+  forward,
+  //! 1/n scaling for backward transform
+  backward,
+  //! 1/sqrt(n) scaling for both direction
+  ortho,
+  //! No scaling
+  none
+};
 
-// Tag to specify FFT direction
+//! Tag to specify FFT direction
 enum class Direction {
+  //! Forward FFT
   forward,
+  //! Inverse FFT
   backward,
 };
 

docs/Doxyfile.in

@@ -813,7 +813,8 @@ WARN_LOGFILE           =
 # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  = "@DOXYGEN_INPUT_DIR@"
+INPUT                  = ../fft/src/ \
+                         ../common/src/
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses

docs/Makefile

@@ -1,5 +1,4 @@
-Minimal makefile for Sphinx documentation
-#
+#Minimal makefile for Sphinx documentation
 
 # You can set these variables from the command line.
 SPHINXOPTS    =

docs/conf.py

@@ -23,7 +23,7 @@ def configureDoxyfile(src_dir, input_dir, output_dir, doxyfile_in, doxyfile_out)
         filedata = file.read()
 
     filedata = filedata.replace('@CMAKE_SOURCE_DIR@', src_dir)
-    filedata = filedata.replace('@DOXYGEN_INPUT_DIR@', input_dir)
+    #filedata = filedata.replace('@DOXYGEN_INPUT_DIR@', input_dir)
     filedata = filedata.replace('@DOXYGEN_OUTPUT_DIR@', output_dir)
 
     with open(doxyfile_out, 'w') as file:
@@ -62,11 +62,11 @@ def get_version(src_dir):
     cwd = os.getcwd()
     print(cwd)
 
-    src_dir = cwd + '/..'
-    input_dir = cwd + '/../fft/src/'
-    output_dir = cwd +'/doxygen/'
-    doxyfile_in = cwd + '/Doxyfile.in'
-    doxyfile_out = cwd + '/Doxyfile'
+    src_dir = f'{cwd}/..'
+    input_dir = f'{cwd}/../fft/src/' + os.linesep + f'{cwd}/../common/src/'
+    output_dir = f'{cwd}/doxygen/'
+    doxyfile_in = f'{cwd}/Doxyfile.in'
+    doxyfile_out = f'{cwd}/Doxyfile'
     configureDoxyfile(src_dir, input_dir, output_dir, doxyfile_in, doxyfile_out)
     subprocess.call('pwd; ls -lat; doxygen Doxyfile; ls -lat doxygen/xml', shell=True)
     breathe_projects[project] = output_dir + '/xml'

docs/finding_libraries.rst

@@ -9,27 +9,30 @@ Some tips to find FFT libraries for each backend.
 -----------------------------
 
 If ``fftw`` is offered as a module, our CMake helper would likely find ``fftw``.
-Assuming ``fftw`` is installed in ``<fftw_install_dir>``, it is expected that ``<fftw_install_dir>`` would be found under ``LIBRARY_PATH``, ``LD_LIBRARY_PATH``, and ``PATH``.
+Assuming ``fftw`` is installed in ``<path/to/fftw>``, it is expected that ``<path/to/fftw>`` would be found under ``LIBRARY_PATH``, ``LD_LIBRARY_PATH``, and ``PATH``.
 It would look like
 
 .. code-block:: bash
 
-    LIBRARY_PATH=...:<fftw_install_dir>/lib
-    LD_LIBRARY_PATH=...:<fftw_install_dir>/lib
-    PATH=...:<fftw_install_dir>/bin
+    LIBRARY_PATH=...:<path/to/fftw>/lib
+    LD_LIBRARY_PATH=...:<path/to/fftw>/lib
+    PATH=...:<path/to/fftw>/bin
 
 If CMake fails to find ``fftw``, please try to set ``FFTWDIR`` in the following way. 
 
 .. code-block:: bash
 
-    export FFTWDIR=<fftw_install_dir>
+    export FFTWDIR=<path/to/fftw>
 
 `cufft <https://developer.nvidia.com/cufft>`_
 ---------------------------------------------
 
 `hipfft <https://github.com/ROCm/hipFFT>`_
 ------------------------------------------
 
+`rocfft <https://github.com/ROCm/rocFFT>`_
+------------------------------------------
+
 `oneMKL <https://spec.oneapi.io/versions/latest/elements/oneMKL/source/index.html>`_
 ------------------------------------------------------------------------------------
 

docs/index.rst

@@ -6,21 +6,15 @@ KokkosFFT 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>`_, 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://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.
 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. 
 A FFT library dedicated to Kokkos Device backend (e.g. cufft for CUDA backend) is automatically used. 
 
 KokkosFFT is open source and available on `GitHub <https://github.com/CExA-project/kokkos-fft>`_.
 
-Here is an example for 1D real to complex transform with ``rfft`` in python and KokkosFFT.
-
-.. code-block:: python
-
-   import numpy as np
-   x = np.random.rand(4)
-   x_hat = np.fft.rfft(x)
+Here is an example for 1D real to complex transform with ``rfft`` in KokkosFFT.
 
 .. code-block:: C++
 
@@ -41,6 +35,14 @@ Here is an example for 1D real to complex transform with ``rfft`` in python and
 
    KokkosFFT::rfft(execution_space(), x, x_hat);
 
+This is equivalent to the following python script.
+
+.. code-block:: python
+
+   import numpy as np
+   x = np.random.rand(4)
+   x_hat = np.fft.rfft(x)
+
 .. note::
 
    It is assumed that backend FFT libraries are appropriately installed on the system.

docs/intro/building.rst

@@ -22,15 +22,15 @@ However, we have not tested all the listed compilers there and thus recommend th
 Install KokkosFFT as a library
 ------------------------------
 
-Is is assumed that Kokkos is installed under ``<install_dir>/kokkos`` with OpenMP backend. Here is a recipe to install KokkosFFT under ``<install_dir>/kokkos_fft``.
+Let's assume Kokkos is installed under ``<path/to/kokkos>`` with ``OpenMP`` backend. We build and install KokkosFFT under ``<path/to/kokkos-fft>``.
 
 .. code-block:: bash
 
-    export KOKKOSFFT_INSTALL_PREFIX=<install_dir>/kokkosFFT
+    export KOKKOSFFT_INSTALL_PREFIX=<path/to/kokkos-fft>
 
     mkdir build_KokkosFFT && cd build_KokkosFFT
-    cmake -DCMAKE_CXX_COMPILER=icpx \
-          -DCMAKE_PREFIX_PATH=<install_dir>/kokkos \
+    cmake -DCMAKE_CXX_COMPILER=<your c++ compiler> \
+          -DCMAKE_PREFIX_PATH=<path/to/kokkos> \
           -DCMAKE_INSTALL_PREFIX=${KOKKOSFFT_INSTALL_PREFIX} ..
     cmake --build . -j 8
     cmake --install .
@@ -52,7 +52,7 @@ The `CMakeLists.txt` would be
     cmake_minimum_required(VERSION 3.23)
     project(kokkos-fft-as-library LANGUAGES CXX)
 
-    ind_package(Kokkos CONFIG REQUIRED)
+    find_package(Kokkos CONFIG REQUIRED)
     find_package(KokkosFFT CONFIG REQUIRED)
 
     add_executable(hello-kokkos-fft hello.cpp)
@@ -63,7 +63,8 @@ The code can be built as
 .. code-block:: bash
 
     mkdir build && cd build
-    cmake -DCMAKE_PREFIX_PATH="<install_dir>/kokkos;<install_dir>/kokkos_fft" ..
+    cmake -DCMAKE_CXX_COMPILER=<your c++ compiler> \
+          -DCMAKE_PREFIX_PATH="<path/to/kokkos>;<path/to/kokkos-fft>" ..
     cmake --build . -j 8
 
 CMake options
@@ -98,6 +99,9 @@ However, to enable this option, we need a pre-installed ``fftw`` for FFT on host
    * - ``KokkosFFT_ENABLE_BENCHMARK``
      - Build benchmarks for KokkosFFT
      - OFF
+   * - ``KokkosFFT_ENABLE_ROCFFT``
+     - Use `rocfft <https://github.com/ROCm/rocFFT>`_ for HIP backend
+     - OFF
 
 Kokkos backends
 ---------------
@@ -136,7 +140,7 @@ We may support experimental backends like ``OPENMPTARGET`` in the future.
      - ``cufft``
    * - ``Kokkos_ENABLE_HIP``
      - HIP backend targeting AMD GPUs
-     - ``hipfft``
+     - ``hipfft`` or ``rocfft``
    * - ``Kokkos_ENABLE_SYCL``
      - SYCL backend targeting Intel GPUs
      - ``oneMKL``

docs/intro/quick_start.rst

@@ -76,13 +76,7 @@ Trying
 ------
 
 For those who are familiar with `numpy.fft <https://numpy.org/doc/stable/reference/routines.fft.html>`_, 
-you may use KokkosFFT quite easily. Here is an example for 1D real to complex transform with rfft in python and KokkosFFT.
-
-.. code-block:: python
-
-   import numpy as np
-   x = np.random.rand(4)
-   x_hat = np.fft.rfft(x)
+you may use KokkosFFT quite easily. Here is an example for 1D real to complex transform with ``rfft`` in KokkosFFT and python.
 
 .. code-block:: C++
 
@@ -103,6 +97,12 @@ you may use KokkosFFT quite easily. Here is an example for 1D real to complex tr
 
    KokkosFFT::rfft(execution_space(), x, x_hat);
 
+.. code-block:: python
+
+   import numpy as np
+   x = np.random.rand(4)
+   x_hat = np.fft.rfft(x)
+
 In most cases, a function ``numpy.fft.<function_name>`` is available by ``KokkosFFT::<function_name>``.
 There are two major differences: ``execution_space`` argument and output value (``x_hat``) is an argument of API (not a returned value from API).
 Instead of numpy.array, we rely on `Kokkos Views <https://kokkos.org/kokkos-core-wiki/API/core/View.html>`_.

docs/intro/using.rst

@@ -78,6 +78,18 @@ since we have not tested with static shaped Views. In addition, we have not test
 
    For the moment, ``Kokkos::LayoutStride`` is not allowed. This may be relaxed in the future.
 
+Normalization
+-------------
+
+After the transform, normalization can be applied by setting the ``norm`` argument. We have four options:
+
+* ``KokkosFFT::Normalization::forward``: :math:`1/n` scaling for forward transform
+* ``KokkosFFT::Normalization::backward``: :math:`1/n` scaling for backward transform (default)
+* ``KokkosFFT::Normalization::ortho``: :math:`1/\sqrt{n}` scaling for both forward and backward transform
+* ``KokkosFFT::Normalization::none``: No scaling
+
+For users who already have own normalization functions, please specify ``none`` option.
+
 Memory consmpution
 ------------------
 

docs/requirements.txt

@@ -1,3 +1,2 @@
 breathe
-cmake>=3.22
 sphinx-rtd-theme