Skip to content

Commit

Permalink
Update README.md based on the reviews
Browse files Browse the repository at this point in the history
  • Loading branch information
Yuuichi Asahi committed Jan 25, 2024
1 parent 388814c commit 3f9c042
Showing 1 changed file with 18 additions and 27 deletions.
45 changes: 18 additions & 27 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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](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. If something is wrong with runtime values (say ```View``` extents), it will raise runtime errors (C++ exceptions or assertions). Here is the example for 1D real to complex transform with ```rfft``` 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)
Expand All @@ -33,9 +31,9 @@ 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 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``` is statically checked (compilation errors if not accessible).
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 the View dimension, it automatically uses the batched plans as follows
Depending on a View dimension, it automatically uses the batched plans as follows
```python3
import numpy as np
x = np.random.rand(4, 8)
Expand All @@ -62,10 +60,10 @@ int axis = -1;
KokkosFFT::rfft(execution_space(), x, x_hat, KokkosFFT::FFT_Normalization::BACKWARD, axis); // FFT along -1 axis and batched along 0th axis
```
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).
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.
**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.
Expand All @@ -74,8 +72,9 @@ git clone --recursive https://github.com/CExA-project/kokkos-fft.git
```

### CMake
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.
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.
```
---/
|
Expand All @@ -87,10 +86,10 @@ Here is an example to use KokkosFFT in the following CMake project.
└──hello.cpp
```

The ```CMakeLists.txt``` would be
The `CMakeLists.txt` would be
```CMake
cmake_minimum_required(VERSION 3.23)
project(kokkos-fft LANGUAGES CXX)
project(kokkos-fft-as-subdirectory LANGUAGES CXX)
add_subdirectory(tpls/kokkos)
add_subdirectory(tpls/kokkos-fft)
Expand All @@ -99,7 +98,7 @@ add_executable(hello-kokkos-fft hello.cpp)
target_link_libraries(hello-kokkos-fft PUBLIC Kokkos::kokkos KokkosFFT::fft)
```

For the compilation, we basically rely on the CMake options for Kokkos. For example, the configure options for A100 GPU is as follows.
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 \
Expand All @@ -112,7 +111,7 @@ cmake -DBUILD_TESTING=ON \
This way, all the functionalities are executed on A100 GPUs.

### Install as a library
Is is assumed that the Kokkos is installed under ```<lib_dir>/kokkos``` targeting Icelake with OpenMP backend. ```Kokkos_dir``` also needs to be set appropriately. Here is a recipe to install KokkosFFT under ```<lib_dir>/kokkosFFT```.
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
Expand All @@ -121,14 +120,12 @@ export KokkosFFT_DIR=<lib_dir>/kokkosFFT/lib64/cmake/kokkos-fft
mkdir build_KokkosFFT && cd build_KokkosFFT
cmake -DBUILD_TESTING=OFF \
-DCMAKE_CXX_COMPILER=icpx \
-DKokkos_ENABLE_OPENMP=ON \
-DKokkos_ARCH_SKX=ON \
-DCMAKE_INSTALL_PREFIX=${KOKKOSFFT_INSTALL_PREFIX} ..
cmake --build . -j 8
cmake --install .
```

Here is an example to use KokkosFFT in the following CMake project.
Here is an example to use KokkosFFT in the following CMake project.
```
---/
|
Expand All @@ -137,10 +134,10 @@ Here is an example to use KokkosFFT in the following CMake project.
└──hello.cpp
```

The ```CMakeLists.txt``` would be
The `CMakeLists.txt` would be
```CMake
cmake_minimum_required(VERSION 3.23)
project(kokkos-fft LANGUAGES CXX)
project(kokkos-fft-as-library LANGUAGES CXX)
find_package(Kokkos CONFIG REQUIRED)
find_package(KokkosFFT CONFIG REQUIRED)
Expand All @@ -151,17 +148,11 @@ target_link_libraries(hello-kokkos-fft PUBLIC Kokkos::kokkos KokkosFFT::fft)

The code can be built as
```bash
export KOKKOSFFT_INSTALL_PREFIX=<lib_dir>/kokkosFFT
export KokkosFFT_DIR=<lib_dir>/kokkosFFT/lib64/cmake/kokkos-fft

mkdir build && cd build
cmake -DCMAKE_CXX_COMPILER=icpx \
-DCMAKE_BUILD_TYPE=Release \
-DKokkos_ENABLE_OPENMP=ON \
-DKokkos_ARCH_SKX=ON ..
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.
KokkosFFT is licensed under the MIT License.

0 comments on commit 3f9c042

Please sign in to comment.