Building the Library¶

This page outlines the process of building the dtFFT library using CMake, including compiler requirements, configuration options, and integration instructions for downstream projects. The library supports both host and GPU environments, leveraging modern Fortran and optional dependencies like CUDA, FFTW3, MKL, cuFFT, and VkFFT.

Prerequisites¶

Since dtFFT is primarily written in Fortran, a modern Fortran compiler (2008 standard or later) is required. The library has been successfully tested with:

GNU Fortran (gfortran): Version 12 and above
Intel Fortran (ifort / ifx): Version 18 and above
NVHPC Fortran (nvfortran): Version 24.5 and above

Currently, dtFFT can only be built using CMake (version 3.25 or higher recommended). Ensure CMake is installed and available in your PATH before proceeding.

Requirements:

CMake: Version 3.25 or higher
Modern Fortran compiler: 2008 standard or later
MPI: Message Passing Interface (MPI) implementation
Caliper (optional): For performance profiling and analysis

For CUDA support:

CUDA-aware MPI: Required for GPU acceleration
NCCL (optional): NVIDIA Collective Communications Library (automatically linked if nvfortran is used)
nvfortran (optional): NVHPC Fortran compiler (enables additional features like NCCL and cuFFTMp)
NVTX3 (optional): NVIDIA Tools Extension for profiling and debugging

Configuration Options¶

The build process is controlled via CMake options, listed below. These options enable or disable features such as GPU support, FFT library integration, and additional utilities. Set them using -D<OPTION>=<VALUE> during CMake configuration.

CMake Configuration Options¶
Option	Possible Values	Default	Description
`DTFFT_WITH_CUDA`	`ON` / `OFF`	`OFF`	Enables CUDA support. Requires `nvcc` in the PATH for the target CUDA version.
`DTFFT_WITH_FFTW`	`ON` / `OFF`	`OFF`	Enables FFTW3 support. Requires the `FFTWDIR` environment variable to point to a directory with single- and double-precision FFTW3 libraries.
`DTFFT_WITH_MKL`	`ON` / `OFF`	`OFF`	Enables MKL DFTI support. Requires the `MKLROOT` environment variable to be set to the MKL installation path.
`DTFFT_WITH_CUFFT`	`ON` / `OFF`	`OFF`	Enables cuFFT support. Automatically sets `DTFFT_WITH_CUDA` to `ON`.
`DTFFT_WITH_VKFFT`	`ON` / `OFF`	`OFF`	Enables VkFFT support. Requires the `VKFFT_DIR` variable to point to `vkFFT.h` and automatically sets `DTFFT_WITH_CUDA` to `ON`.
`DTFFT_BUILD_TESTS`	`ON` / `OFF`	`OFF`	Builds the library’s test suite.
`DTFFT_ENABLE_COVERAGE`	`ON` / `OFF`	`OFF`	Enables code coverage analysis (gfortran only).
`DTFFT_BUILD_SHARED`	`ON` / `OFF`	`ON`	Builds a shared library instead of a static one.
`DTFFT_USE_MPI`	`ON` / `OFF`	`ON`	Uses the Fortran `mpi` module instead of `mpi_f08` for MPI integration. This make possible to pass `integer` to `comm` parameter when creating plan instead of `type(MPI_Comm)`, but can produce integer overflow when using CUDA build and big array sizes.
`DTFFT_BUILD_C_CXX_API`	`ON` / `OFF`	`ON`	Builds the C and C++ APIs alongside the Fortran API.
`DTFFT_ENABLE_PERSISTENT_COMM`	`ON` / `OFF`	`OFF`	Enables persistent MPI communications for multiple plan executions. Communications are initialized on the first call to `execute()` or `transpose()`, with pointers stored internally by MPI. Users must ensure these pointers remain valid and are not freed prematurely.
`DTFFT_WITH_PROFILER`	`ON` / `OFF`	`OFF`	Enables profiling. Uses NVTX3 with CUDA support or Caliper otherwise (requires `caliper_DIR` if Caliper is used).
`DTFFT_WITH_NCCL`	`ON` / `OFF`	`OFF`	Requires the `NCCL_ROOT` environment variable to point to the custom NCCL directory.
`DTFFT_WITHOUT_NCCL`	`ON` / `OFF`	`OFF`	Disables use of NCCL shipped with HPC-SDK. NCCL Backends will be unavailable
`DTFFT_WITHOUT_NVSHMEM`	`ON` / `OFF`	`OFF`	Disables use of NVSHMEM-based backends shipped with HPC-SDK.
`DTFFT_ENABLE_DEVICE_CHECKS`	`ON` / `OFF`	`ON`	Enable error checking for all GPU libraries calls. Can be turned off for best performance.
`DTFFT_WITH_RMA`	`ON` / `OFF`	`OFF`	Enable MPI RMA backends (currently in beta). It has been noticed that call to `MPI_Win_create` fails with OpenMPI 4.0.5 with UCX enabled.
`DTFFT_WITH_SIMD`	`ON` / `OFF`	`OFF`	Enables SIMD optimizations for some host kernels (requires OpenMP support in the compiler).
`DTFFT_ENABLE_INPUT_CHECK`	`ON` / `OFF`	`ON`	Enables input parameter checks for plan execution functions. Should be turned off by advanced users to best performance.

Building the Library¶

Configure the Build: Run CMake to generate build files, specifying the installation prefix and desired options. For example:

cmake -S . -B build -DCMAKE_INSTALL_PREFIX=/path/to/install -DDTFFT_WITH_CUDA=ON -DDTFFT_WITH_CUFFT=ON

Replace /path/to/install with your target installation directory.

Note

CUDA support in dtFFT does not replace the host version but extends it. For more details, refer to the guide here and the environment variable DTFFT_PLATFORM.

Build the Library: Compile the library using:

cmake --build build --target install

This compiles and installs dtFFT to the specified prefix.

Integration with CMake Projects¶

Once installed, dtFFT can be integrated into other CMake projects using find_package. Example configuration:

find_package(dtfft REQUIRED)
add_executable(my_prog my_prog.c)
target_link_libraries(my_prog PRIVATE dtfft)

The dtfft target automatically sets include directories and links required libraries. Specify the installation path when configuring your project:

cmake -S . -B build -Ddtfft_DIR=/path/to/install/lib[64]/cmake/dtfft ..

The installation also provides the following CMake variables for conditional compilation:

DTFFT_WITH_CUDA: Indicates CUDA support
DTFFT_WITH_C_CXX_API: Indicates C/C++ API availability
DTFFT_WITH_MPI_MODULE: Indicates use of the mpi module