Improve docs (kokkos#195)

* Cleanup docstrings for FFT APIs

* rename   library name to kokkos-fft in docs

* rename KokkosFFT into kokkos-fft in README.md

* fix: doxygenfunction of fftshift and ifftshift

* fix: new line at eof in rst files

---------

Co-authored-by: Yuuichi Asahi <[email protected]>

README.md

@@ -77,7 +77,7 @@ 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](examples).
 
 ## Disclaimer
-**KokkosFFT is under development and subject to change without warning. The authors do not guarantee that this code runs correctly in all the environments.**
+**kokkos-fft is under development and subject to change without warning. The authors do not guarantee that this code runs correctly in all the environments.**
 
 ## Using kokkos-fft
 For the moment, there are two ways to use kokkos-fft: including as a subdirectory in CMake project or installing as a library. First of all, you need to clone this repo.

docs/api/helper/fftshift.rst

@@ -5,8 +5,8 @@
 KokkosFFT::fftshift
 -------------------
 
-.. doxygenfunction:: KokkosFFT::fftshift(const ExecutionSpace& exec_space, ViewType& inout, std::optional<int> axes = std::nullopt)
-.. doxygenfunction:: KokkosFFT::fftshift(const ExecutionSpace& exec_space, ViewType& inout, axis_type<DIM> axes)
+.. doxygenfunction:: KokkosFFT::fftshift(const ExecutionSpace& exec_space, const ViewType& inout, std::optional<int> axes = std::nullopt)
+.. doxygenfunction:: KokkosFFT::fftshift(const ExecutionSpace& exec_space, const ViewType& inout, axis_type<DIM> axes)
 
 .. note::
 

docs/api/helper/ifftshift.rst

@@ -5,8 +5,8 @@
 KokkosFFT::ifftshift
 --------------------
 
-.. doxygenfunction:: KokkosFFT::ifftshift(const ExecutionSpace& exec_space, ViewType& inout, std::optional<int> axes = std::nullopt)
-.. doxygenfunction:: KokkosFFT::ifftshift(const ExecutionSpace& exec_space, ViewType& inout, axis_type<DIM> axes)
+.. doxygenfunction:: KokkosFFT::ifftshift(const ExecutionSpace& exec_space, const ViewType& inout, std::optional<int> axes = std::nullopt)
+.. doxygenfunction:: KokkosFFT::ifftshift(const ExecutionSpace& exec_space, const ViewType& inout, axis_type<DIM> axes)
 
 .. note::
 

docs/api_reference.rst

@@ -7,7 +7,7 @@
 API Reference
 =============
 
-This section documents the public user interface of ``Kokkos-fft``. 
+This section documents the public user interface of ``kokkos-fft``. 
 APIs are defined in ``KokkosFFT`` namespace and implementation details are defined in ``KokkosFFT::Impl`` namespace. 
 Thus, it is highly discouraged for users to access functions in ``KokkosFFT::Impl`` namespace. 
 Except for ``KokkosFFT::Plan``, there are corresponding functions in ``numpy.fft`` as shown below.
@@ -26,7 +26,7 @@ FFT Plan
    :header-rows: 1
 
    * - Description
-     - ``KokkosFFT``
+     - ``kokkos-fft``
      - ``numpy.fft``
    * - A class that manages a FFT plan of backend FFT library
      - :doc:`api/plan`
@@ -51,7 +51,7 @@ Standard FFTs
    :header-rows: 1
 
    * - Description
-     - ``KokkosFFT``
+     - ``kokkos-fft``
      - ``numpy.fft``
    * - One dimensional FFT in forward direction
      - :doc:`api/standard/fft`
@@ -91,7 +91,7 @@ Real FFTs
    :header-rows: 1
 
    * - Description
-     - ``KokkosFFT``
+     - ``kokkos-fft``
      - ``numpy.fft``
    * - One dimensional FFT for real input
      - :doc:`api/real/rfft`
@@ -128,7 +128,7 @@ Hermitian FFTs
    :header-rows: 1
 
    * - Description
-     - ``KokkosFFT``
+     - ``kokkos-fft``
      - ``numpy.fft``
    * - One dimensional FFT of a signal that has Hermitian symmetry
      - :doc:`api/hermitian/hfft`
@@ -154,7 +154,7 @@ Helper routines
    :header-rows: 1
 
    * - Description
-     - ``KokkosFFT``
+     - ``kokkos-fft``
      - ``numpy.fft``
    * - Return the DFT sample frequencies
      - :doc:`api/helper/fftfreq`

docs/examples.rst

@@ -9,7 +9,7 @@ Examples
 
 There are some `examples
 <https://github.com/kokkos/kokkos-fft/tree/main/examples>`_ in the
-Kokkos-fft repository. Most of the examples include Kokkos and numpy implementations.
+kokkos-fft repository. Most of the examples include Kokkos and numpy implementations.
 For example, `01_1DFFT
 <https://github.com/kokkos/kokkos-fft/tree/main/examples/01_1DFFT>`_ includes,
 
@@ -19,7 +19,7 @@ For example, `01_1DFFT
      |
      └──01_1DFFT/
         |--CMakeLists.txt
-        |--01_1DFFT.cpp (Kokkos-fft version)
+        |--01_1DFFT.cpp (kokkos-fft version)
         └──numpy_1DFFT.py (numpy version)
 
 Please find the examples from following links.
@@ -33,4 +33,6 @@ Please find the examples from following links.
    samples/04_batchedFFT.rst
    samples/05_1DFFT_HOST_DEVICE.rst
    samples/06_1DFFT_reuse_plans.rst
-   samples/07_unmanaged_views.rst
+   samples/07_unmanaged_views.rst
+   samples/08_inplace_FFT.rst
+

docs/index.rst

@@ -2,10 +2,10 @@
 ..
 .. SPDX-License-Identifier: MIT OR Apache-2.0 WITH LLVM-exception
 
-Kokkos-fft documentation
+kokkos-fft documentation
 =======================================
 
-Kokkos-fft implements local interfaces between `Kokkos <https://kokkos.org>`_ 
+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>`_,
@@ -15,9 +15,9 @@ We are inclined to implement the `numpy.fft <https://numpy.org/doc/stable/refere
 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. 
 
-Kokkos-fft is open source and available on `GitHub <https://github.com/kokkos/kokkos-fft>`_.
+kokkos-fft is open source and available on `GitHub <https://github.com/kokkos/kokkos-fft>`_.
 
-Here is an example for 1D real to complex transform with ``rfft`` in Kokkos-fft.
+Here is an example for 1D real to complex transform with ``rfft`` in kokkos-fft.
 
 .. code-block:: C++
 

docs/intro/building.rst

@@ -4,29 +4,29 @@
 
 .. _building:
 
-Building Kokkos-fft
+Building kokkos-fft
 ===================
 
-This section describes how to build Kokkos-fft with some advanced options.
-In order to build Kokkos-fft, we use ``CMake`` with following compilers. 
+This section describes how to build kokkos-fft with some advanced options.
+In order to build kokkos-fft, we use ``CMake`` with following compilers. 
 Kokkos and backend FFT libraries are also necessary.
-Available CMake options for Kokkos-fft are listed. 
+Available CMake options for kokkos-fft are listed. 
 
 Compiler versions
 -----------------
 
-Kokkos-fft relies on quite basic functionalities of Kokkos, and thus it is supposed to work with compilers used for `Kokkos <https://kokkos.org/kokkos-core-wiki/requirements.html>`_.
+kokkos-fft relies on quite basic functionalities of Kokkos, and thus it is supposed to work with compilers used for `Kokkos <https://kokkos.org/kokkos-core-wiki/requirements.html>`_.
 However, we have not tested all the listed compilers there and thus recommend the following compilers which we use frequently for testing.
 
 * ``gcc 8.3.0+`` - CPUs
 * ``IntelLLVM 2023.0.0+`` - CPUs, Intel GPUs
 * ``nvcc 11.0.0+`` - NVIDIA GPUs
 * ``rocm 5.3.0+`` - AMD GPUs
 
-Install Kokkos-fft as a library
+Install kokkos-fft as a library
 -------------------------------
 
-Let's assume Kokkos is installed under ``<path/to/kokkos>`` with ``OpenMP`` backend. We build and install Kokkos-fft under ``<path/to/kokkos-fft>``.
+Let's assume Kokkos is installed under ``<path/to/kokkos>`` with ``OpenMP`` backend. We build and install kokkos-fft under ``<path/to/kokkos-fft>``.
 
 .. code-block:: bash
 
@@ -39,7 +39,7 @@ Let's assume Kokkos is installed under ``<path/to/kokkos>`` with ``OpenMP`` back
     cmake --build build_KokkosFFT -j 8
     cmake --install build_KokkosFFT
 
-Here is an example to use Kokkos-fft in the following CMake project.
+Here is an example to use kokkos-fft in the following CMake project.
 
 .. code-block:: bash
 
@@ -74,9 +74,9 @@ The code can be built as
 CMake options
 -------------
 
-We rely on CMake to build Kokkos-fft, more specifically ``CMake 3.22+``. Here is the list of 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_HOST_AND_DEVICE=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
 (see :doc:`minimum working example<../samples/05_1DFFT_HOST_DEVICE>`).
@@ -95,13 +95,13 @@ However, to enable this option, we need a pre-installed ``fftw`` for FFT on host
      - Build internal Kokkos instead of relying on external one.
      - OFF
    * - ``KokkosFFT_ENABLE_EXAMPLES``
-     - Build Kokkos-fft examples
+     - Build kokkos-fft examples
      - OFF
    * - ``KokkosFFT_ENABLE_TESTS``
-     - Build Kokkos-fft tests
+     - Build kokkos-fft tests
      - OFF
    * - ``KokkosFFT_ENABLE_BENCHMARK``
-     - Build benchmarks for Kokkos-fft
+     - Build benchmarks for kokkos-fft
      - OFF
    * - ``KokkosFFT_ENABLE_ROCFFT``
      - Use `rocfft <https://github.com/ROCm/rocFFT>`_ for HIP backend
@@ -110,7 +110,7 @@ However, to enable this option, we need a pre-installed ``fftw`` for FFT on host
 Kokkos backends
 ---------------
 
-Kokkos-fft requires ``Kokkos 4.2+``. For the moment, we support following backends for CPUs and GPUs.
+kokkos-fft requires ``Kokkos 4.4+``. For the moment, we support following backends for CPUs and GPUs.
 A FFT library dedicated to Kokkos Device backend (e.g. cufft for CUDA backend) is automatically used. 
 If CMake fails to find a backend FFT library, see :doc:`How to find fft libraries?<../finding_libraries>`.
 We may support experimental backends like ``OPENMPTARGET`` in the future.

docs/intro/quick_start.rst

@@ -7,20 +7,20 @@
 Quickstart guide
 ================
 
-This section will quickly illustrate how to use Kokkos-fft.
+This section will quickly illustrate how to use kokkos-fft.
 First of all, you need to clone this repo. 
 
 .. code-block:: bash
 
     git clone --recursive https://github.com/kokkos/kokkos-fft.git
 
-To configure Kokkos-fft, we can just use CMake options for Kokkos, which automatically enables the FFT interface on Kokkos device. 
+To configure kokkos-fft, we can just use CMake options for Kokkos, which automatically enables the FFT interface on Kokkos device. 
 If CMake fails to find a backend FFT library, see :doc:`How to find fft libraries?<../finding_libraries>`.
 
 Requirements
 ------------
 
-Kokkos-fft requires ``Kokkos 4.4+`` and dedicated compilers for CPUs or GPUs.
+kokkos-fft requires ``Kokkos 4.4+`` and dedicated compilers for CPUs or GPUs.
 It employs ``CMake 3.22+`` for building.
 
 Here are list of compilers we frequently use for testing. 
@@ -33,11 +33,11 @@ Here are list of compilers we frequently use for testing.
 Building
 --------
 
-For the moment, there are two ways to use Kokkos-fft: including as a subdirectory in CMake project or installing as a library.
-For simplicity, however, we demonstrate an example to use Kokkos-fft as a subdirectory in a CMake project. For installation, see :ref:`Building Kokkos-fft<building>`.
-Since Kokkos-fft is a header-only library, it is enough to simply add as a subdirectory. It is assumed that kokkos and Kokkos-fft are placed under ``<project_directory>/tpls``.
+For the moment, there are two ways to use kokkos-fft: including as a subdirectory in CMake project or installing as a library.
+For simplicity, however, we demonstrate an example to use kokkos-fft as a subdirectory in a CMake project. For installation, see :ref:`Building kokkos-fft<building>`.
+Since kokkos-fft is a header-only library, it is enough to simply add as a subdirectory. It is assumed that kokkos and kokkos-fft are placed under ``<project_directory>/tpls``.
 
-Here is an example to use Kokkos-fft in the following CMake project.
+Here is an example to use kokkos-fft in the following CMake project.
 
 .. code-block:: bash
 
@@ -80,7 +80,7 @@ Trying
 ------
 
 For those who are familiar with `numpy.fft <https://numpy.org/doc/stable/reference/routines.fft.html>`_, 
-you may use Kokkos-fft quite easily. Here is an example for 1D real to complex transform with ``rfft`` in Kokkos-fft and python.
+you may use kokkos-fft quite easily. Here is an example for 1D real to complex transform with ``rfft`` in kokkos-fft and python.
 
 .. code-block:: C++
 
@@ -90,7 +90,7 @@ you may use Kokkos-fft quite easily. Here is an example for 1D real to complex t
    #include <KokkosFFT.hpp>
    using execution_space = Kokkos::DefaultExecutionSpace;
    template <typename T> using View1D = Kokkos::View<T*, execution_space>;
-   constexpr int n = 4;
+   const int n = 4;
 
    View1D<double> x("x", n);
    View1D<Kokkos::complex<double> > x_hat("x_hat", n/2+1);
@@ -112,4 +112,4 @@ There are two major differences: ``execution_space`` argument and output value (
 Instead of numpy.array, we rely on `Kokkos Views <https://kokkos.org/kokkos-core-wiki/API/core/View.html>`_.
 The accessibilities of Views from ``execution_space`` are statically checked (compilation errors if not accessible). 
 It is easiest to rely only on the ``Kokkos::DefaultExecutionSpace`` for both View allocation and KokkosFFT APIs.
-See :ref:`Using Kokkos-fft<using>` for detail.
+See :ref:`Using kokkos-fft<using>` for detail.