diff --git a/CMakeLists.txt b/CMakeLists.txt index abe4edca..f5b02b65 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -2,7 +2,7 @@ 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) @@ -10,7 +10,10 @@ 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 () diff --git a/README.md b/README.md index 9600ad14..b8580eb7 100644 --- a/README.md +++ b/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 `/tpls`. + +Here is an example to use KokkosFFT in the following CMake project. +``` +---/ + | + └──/ + |--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=/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 `/kokkos` with OpenMP backend. Here is a recipe to install KokkosFFT under `/kokkos_fft`. + +```bash +export KOKKOSFFT_INSTALL_PREFIX=/kokkosFFT +export KokkosFFT_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. +``` +---/ + | + └──/ + |--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="/kokkos;/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.