Update readme #36

yasahi-hpc · 2024-01-25T08:23:49Z

Cherry-pick from the previous PR (#27) with modifications based on comments. Because of the breaking changes in PR (#30), I made a new PR. The README is planed to be further updated before release.

More explanations

yasahi-hpc · 2024-01-25T08:25:13Z

Hi @cedricchevalier19 , because of the breaking change in (#30), I made a new PR. If this is good for you, I will merge this.

cedricchevalier19

I think one big issue is left out: how user have to specify which fft libraries to use?

This should be in the CMake examples. You should try to copy and paste the lines to be sure that they work at least on one machine.

I am not sure by all the markdown syntax, specially where blank lines are needed, so please use a markdown linter.

cedricchevalier19 · 2024-01-25T11:30:44Z

README.md

-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.
+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.


Suggested change

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.

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.

Concerning assertions, I know it is done this way in some part of Kokkos, however I think it's a bad behaviour for a library. It should not interrupt the calling application, where a proper error handling can be done. Not something to correct now, but perhaps something to keep in mind for the Kokkos ecosystem.

OK. Let us discuss this point in our next meeting

cedricchevalier19 · 2024-01-25T11:32:35Z

README.md

@@ -33,6 +33,8 @@ 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). 


Suggested change

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 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).

cedricchevalier19 · 2024-01-25T11:33:25Z

README.md

@@ -60,7 +62,106 @@ 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).


Suggested change

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).

cedricchevalier19 · 2024-01-25T11:34:26Z

README.md

+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.


Suggested change

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. **

cedricchevalier19 · 2024-01-25T11:35:24Z

README.md

+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. 


Suggested change

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.

cedricchevalier19 · 2024-01-25T11:39:04Z

README.md

+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```.


Suggested change

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`.

cedricchevalier19 · 2024-01-25T11:44:23Z

README.md

+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 \
+      -DKokkos_ENABLE_OPENMP=ON \
+      -DKokkos_ARCH_SKX=ON \
+      -DCMAKE_INSTALL_PREFIX=${KOKKOSFFT_INSTALL_PREFIX} ..
+cmake --build . -j 8
+cmake --install .


Suggested change

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 \

-DKokkos_ENABLE_OPENMP=ON \

-DKokkos_ARCH_SKX=ON \

-DCMAKE_INSTALL_PREFIX=${KOKKOSFFT_INSTALL_PREFIX} ..

cmake --build . -j 8

cmake --install .

cmake -b build_kokkos_fft -DBUILD_TESTING=OFF -DKokkos_ROOT="<install_dir>/kokkos" -DCMAKE_INSTALL_PREFIX="<install_dir>/kokkos_fft" .

cmake --build build_kokkos_fft --parallel && cmake --install build_kokkos_fft

cedricchevalier19 · 2024-01-25T11:45:55Z

README.md

+    └──hello.cpp
+```
+
+The ```CMakeLists.txt``` would be 


Suggested change

The ```CMakeLists.txt``` would be

The `CMakeLists.txt` would be

cedricchevalier19 · 2024-01-25T11:46:15Z

README.md

+The ```CMakeLists.txt``` would be 
+```CMake
+cmake_minimum_required(VERSION 3.23)
+project(kokkos-fft LANGUAGES CXX)


Not a good project name

Sure. I will change it

cedricchevalier19 · 2024-01-25T11:50:20Z

README.md

+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 --build . -j 8


Suggested change

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 --build . -j 8

cmake -b build_dir -DCMAKE_PREFIX_PATH="<install_dir>/kokkos;<install_dir>/kokkos_fft" .

cmake --build build_dir --parallel

I do not understand why Kokkos_ENABLE_OPENMP was passed here if Kokkos is already installed.

That is true. May be unnecessary

yasahi-hpc · 2024-01-25T12:27:14Z

Thanks again for your review.

I think one big issue is left out: how user have to specify which fft libraries to use?

This should be in the CMake examples. You should try to copy and paste the lines to be sure that they work at least on one machine.

Actually, I am not planning to allow a user to specify fft libraries. A fft library dedicated to Kokkos Device backend is automatically chosen, e.g.,
cufft with -DKokkos_ENABLE_CUDA=ON
hipfft with -DKokkos_ENABLE_HIP=ON
oneMKL with -DKokkos_ENABLE_SYCL=ON
fftw with -DKokkos_ENABLE_<OPENMP, THREAD, SERIAL>=ON

If Kokkos Device backend is given, then only the library for device is available. If a user want to call fft from both host and device, it is needed to enable -DKokkosFFT_ENABLE_HOST_AND_DEVICE. With this option, the user can call fftw from host_execution_space on host Views. This point will be added in the prerelease stage.

I am not sure by all the markdown syntax, specially where blank lines are needed, so please use a markdown linter.

OK. I will try some plugin

cedricchevalier19 · 2024-01-25T12:59:32Z

I was talking on how to find or help finding the correct fft implementations.

However, adding a table and the corresponding library can be a great addition in the readme or the documentation.
Thanks for your clarifications.

yasahi-hpc · 2024-01-25T13:12:16Z

I was talking on how to find or help finding the correct fft implementations.

Do you mean the complete documentations of API? I agree it is the most important missing ingredient for this repo. I am currently working on that.

yasahi-hpc · 2024-01-25T14:24:48Z

Actually, I found an issue to build a code in case both Kokkos and KokkosFFT are added as subdirectories of a CMake project. Before find_package(Kokkos), I would test if Kokkos_PATH is set or not. I am not quite sure this is the best way to check whether Kokkos is already added as a subdirectory or not.

cedricchevalier19

I do not know how standard is kokkos-path

cedricchevalier19 · 2024-01-25T15:29:07Z

CMakeLists.txt

+    # First check, Kokkos is added as subdirectory or not
+    if (KOKKOS_PATH STREQUAL "")
+        find_package(Kokkos REQUIRED)
+    else()
+        message(STATUS "Using Kokkos at ${KOKKOS_PATH}")
+    endif()


Please, don't do this.
Use can check for kokkos::kokkos target or something like that.

Thank you. I modified. I will probably add a capability to display the Kokkos version detail in CMake in the future.

…t into update-readme-tmp

cedricchevalier19 · 2024-01-25T15:31:03Z

I was talking on how to find or help finding the correct fft implementations.

Do you mean the complete documentations of API? I agree it is the most important missing ingredient for this repo. I am currently working on that.

No, I mean how to find fftw and so if it is not straightforward.

yasahi-hpc · 2024-01-25T15:47:04Z

I was talking on how to find or help finding the correct fft implementations.

Do you mean the complete documentations of API? I agree it is the most important missing ingredient for this repo. I am currently working on that.

No, I mean how to find fftw and so if it is not straightforward.

As you said, finding fftw is not straightforward. I have prepared a helper to find it, but it would probably only work if fftw is installed in "conventional location". If a user manually install it, I am not sure what is the better way.

yasahi-hpc · 2024-01-25T17:40:08Z

@cedricchevalier19 Regarding the fftw documentations, I would like to make it in another PR. If you are OK, I would merge this

cedricchevalier19

Looks great!

yasahi-hpc · 2024-01-26T07:37:17Z

@cedricchevalier19 Thank you again for your review. I will merge this

yasahi-hpc added 3 commits January 25, 2024 16:55

Update README.md

9bb66d8

More explanations

Adding Disclaimer

227b19f

Update README.md based on Review

09e4a34

yasahi-hpc requested a review from cedricchevalier19 January 25, 2024 08:24

CMake configure commands are displayed in multiple lines

17e8a80

yasahi-hpc added documentation Improvements or additions to documentation enhancement New feature or request labels Jan 25, 2024

yasahi-hpc self-assigned this Jan 25, 2024

[README] minor fix

388814c

cedricchevalier19 approved these changes Jan 25, 2024

View reviewed changes

Yuuichi Asahi added 2 commits January 25, 2024 22:12

Update README.md based on the reviews

3f9c042

Modify CMake in order to rely on Kokkos added as a subdirectory

6b3b058

yasahi-hpc and others added 2 commits January 25, 2024 15:31

minor fix README.md

4f8bad4

comparison in string

071e567

cedricchevalier19 requested changes Jan 25, 2024

View reviewed changes

Merge branch 'update-readme-tmp' of github.com:CExA-project/kokkos-ff…

a208f3d

…t into update-readme-tmp

Test if Kokkos is already included

f3840ff

yasahi-hpc requested a review from cedricchevalier19 January 25, 2024 17:37

cedricchevalier19 approved these changes Jan 25, 2024

View reviewed changes

yasahi-hpc merged commit 1da85a9 into main Jan 26, 2024
5 checks passed

yasahi-hpc deleted the update-readme-tmp branch January 26, 2024 07:37

yasahi-hpc mentioned this pull request Jan 26, 2024

Minor improvement of README #27

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update readme #36

Update readme #36

yasahi-hpc commented Jan 25, 2024

yasahi-hpc commented Jan 25, 2024

cedricchevalier19 left a comment

cedricchevalier19 Jan 25, 2024

yasahi-hpc Jan 25, 2024

cedricchevalier19 Jan 25, 2024

cedricchevalier19 Jan 25, 2024

cedricchevalier19 Jan 25, 2024

cedricchevalier19 Jan 25, 2024

cedricchevalier19 Jan 25, 2024

cedricchevalier19 Jan 25, 2024

cedricchevalier19 Jan 25, 2024

cedricchevalier19 Jan 25, 2024

yasahi-hpc Jan 25, 2024

cedricchevalier19 Jan 25, 2024

yasahi-hpc Jan 25, 2024

yasahi-hpc commented Jan 25, 2024

cedricchevalier19 commented Jan 25, 2024

yasahi-hpc commented Jan 25, 2024

yasahi-hpc commented Jan 25, 2024

cedricchevalier19 left a comment

cedricchevalier19 Jan 25, 2024

yasahi-hpc Jan 25, 2024

cedricchevalier19 commented Jan 25, 2024

yasahi-hpc commented Jan 25, 2024

yasahi-hpc commented Jan 25, 2024

cedricchevalier19 left a comment

yasahi-hpc commented Jan 26, 2024

	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.
	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.

	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).

	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.

		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.

	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`.

	The ```CMakeLists.txt``` would be
	The `CMakeLists.txt` would be

Update readme #36

Update readme #36

Conversation

yasahi-hpc commented Jan 25, 2024

yasahi-hpc commented Jan 25, 2024

cedricchevalier19 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

yasahi-hpc commented Jan 25, 2024

cedricchevalier19 commented Jan 25, 2024

yasahi-hpc commented Jan 25, 2024

yasahi-hpc commented Jan 25, 2024

cedricchevalier19 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

cedricchevalier19 commented Jan 25, 2024

yasahi-hpc commented Jan 25, 2024

yasahi-hpc commented Jan 25, 2024

cedricchevalier19 left a comment

Choose a reason for hiding this comment

yasahi-hpc commented Jan 26, 2024