Update readme

CMakeLists.txt

@@ -2,15 +2,18 @@ cmake_minimum_required(VERSION 3.23)
 project(kokkos-fft LANGUAGES CXX)
 
 # Add cmake helpers for FFTW
-list(INSERT CMAKE_MODULE_PATH 0 "${CMAKE_SOURCE_DIR}/cmake")
+list(INSERT CMAKE_MODULE_PATH 0 "${CMAKE_CURRENT_SOURCE_DIR}/cmake")
 
 # Options
 option(BUILD_EXAMPLES "Build kokkos-fft examples" ON)
 option(KokkosFFT_ENABLE_HOST_AND_DEVICE "Enable fft on both host and device" OFF)
 option(KokkosFFT_INTERNAL_Kokkos "Build internal Kokkos instead of relying on external one" OFF)
 
 if (NOT KokkosFFT_INTERNAL_Kokkos)
-    find_package(Kokkos REQUIRED)
+    # First check, Kokkos is added as subdirectory or not
+    if(NOT TARGET Kokkos::kokkos)
+        find_package(Kokkos REQUIRED)
+    endif()
 else ()
     add_subdirectory(tpls/kokkos)
 endif ()

README.md

@@ -4,10 +4,8 @@
 
 UNOFFICIAL FFT interfaces for Kokkos C++ Performance Portability Programming EcoSystem
 
-KokkosFFT implements local interfaces Kokkos and de facto standard FFT libraries, including fftw, cufft and hipfft. 
-"Local" means not using MPI, or running within a
-single MPI process without knowing about MPI. We are inclined to implement the numpy FFT interfaces based on Kokkos.
-Here is the example for 1D case in python and KokkosFFT.
+KokkosFFT implements local interfaces Kokkos and de facto standard FFT libraries, including [fftw](http://www.fftw.org), [cufft](https://developer.nvidia.com/cufft) and [hipfft](https://github.com/ROCm/hipFFT). "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). 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)
@@ -33,7 +31,9 @@ Kokkos::fence();
 KokkosFFT::rfft(execution_space(), x, x_hat);
 ```
 
-Depending on the View dimension, it automatically uses the batched plans as follows
+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
 ```python3
 import numpy as np
 x = np.random.rand(4, 8)
@@ -60,7 +60,99 @@ int axis = -1;
 KokkosFFT::rfft(execution_space(), x, x_hat, KokkosFFT::FFT_Normalization::BACKWARD, axis); // FFT along -1 axis and batched along 0th axis
 ```
 
-## Building KokkosFFT
+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).
+
+## 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.**
+
+## Using KokkosFFT
+For the moment, there are two ways to use KokkosFFT: including as a subdirectory in CMake project or installing as a library. First of all, you need to clone this repo.
+```bash
+git clone --recursive https://github.com/CExA-project/kokkos-fft.git
+```
 
 ### CMake
-Up to now, we just rely on the CMake options for Kokkos.
+Since KokkosFFT is a header-only library, it is enough to simply add as a subdirectory. It is assumed that kokkos and kokkosFFT are placed under `<project_directory>/tpls`.
+
+Here is an example to use KokkosFFT in the following CMake project.
+```
+---/
+ |
+ └──<project_directory>/
+    |--tpls
+    |    |--kokkos/
+    |    └──kokkos-fft/
+    |--CMakeLists.txt
+    └──hello.cpp
+```
+
+The `CMakeLists.txt` would be
+```CMake
+cmake_minimum_required(VERSION 3.23)
+project(kokkos-fft-as-subdirectory LANGUAGES CXX)
+
+add_subdirectory(tpls/kokkos)
+add_subdirectory(tpls/kokkos-fft)
+
+add_executable(hello-kokkos-fft hello.cpp)
+target_link_libraries(hello-kokkos-fft PUBLIC Kokkos::kokkos KokkosFFT::fft)
+```
+
+For compilation, we basically rely on the CMake options for Kokkos. For example, the configure options for A100 GPU is as follows.
+```
+cmake -DBUILD_TESTING=ON \
+      -DCMAKE_CXX_COMPILER=<project_directory>/tpls/kokkos/bin/nvcc_wrapper \
+      -DCMAKE_BUILD_TYPE=Release \
+      -DKokkos_ENABLE_CUDA=ON \
+      -DKokkos_ENABLE_CUDA_CONSTEXPR=ON \
+      -DKokkos_ARCH_AMPERE80=ON \
+      -DKokkos_ENABLE_CUDA_LAMBDA=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 -DBUILD_TESTING=OFF \
+      -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
+```
+
+## LICENCE
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)  
+KokkosFFT is licensed under the MIT License.