Pr501 nufft final

[aaadelmann]

Summary

This PR ports the NUFFT part of the original PR501 work onto current master.

The PR adds:

• native IPPL NUFFT support through FFT<NUFFTransform, ...>
• optional FINUFFT backend plumbing
• optional cuFINUFFT backend plumbing
• NUFFT unit tests and accuracy checks
• explicit documentation in code/CMake that cuFINUFFT is a single-rank GPU backend, not an MPI/distributed NUFFT backend

The native IPPL NUFFT path is the distributed-capable path. cuFINUFFT is only exposed for single-rank CUDA-backed execution because cuFINUFFT itself has no MPI decomposition.

What Is Included

Native NUFFT

Adds the native IPPL NUFFT implementation:

• src/FFT/NUFFT/Correction.h
• src/FFT/NUFFT/ESKernel.h
• src/FFT/NUFFT/NUFFTUtilities.h
• src/FFT/NUFFT/NativeNUFFT.h
• src/FFT/Transform/NUFFT.h
• src/FFT/Transform/NUFFT.hpp

The implementation supports Type 1 and Type 2 NUFFT through the existing IPPL FFT interface:

using FFT_t = ippl::FFT<ippl::NUFFTransform, real_field_type>;

auto fft = std::make_unique<FFT_t>(layout, localParticleCount, type, params);
fft->transform(R, Q, field);

Type 1:

fft->transform(R, Q, field);

spreads particle values Q at particle positions R onto the Fourier-mode field.

Type 2 uses the same entry point and interpolates from the field back to particle values depending on the transform type selected at construction.

FINUFFT / cuFINUFFT Plumbing

Adds CMake options:

-DIPPL_ENABLE_FINUFFT=ON
-DIPPL_ENABLE_CUFINUFFT=ON
-DIPPL_FINUFFT_USE_DUCC0=ON

IPPL_ENABLE_FINUFFT enables the optional external FINUFFT backend.

IPPL_ENABLE_CUFINUFFT enables the optional CUDA cuFINUFFT backend and requires CUDA in IPPL_PLATFORMS.

IPPL_FINUFFT_USE_DUCC0 defaults to ON for fetched FINUFFT builds. DUCC0 is FINUFFT's bundled FFT backend alternative to FFTW. This keeps fetched FINUFFT builds self-contained and avoids relying on a possibly inconsistent system FFTW CMake package.

cuFINUFFT Scope

cuFINUFFT is explicitly treated as:

• GPU-capable
• single-rank only (no MPI/distributed)
• requiring CUDA-backed IPPL/Kokkos memory

The code now rejects unsupported cuFINUFFT use cases clearly:

• Comm->size() != 1
• non-CUDA-backed memory spaces
• host-only SERIAL fields

This PR does not add a host-to-CUDA staging backend. Therefore, cuFINUFFT is not intended for a host-only serial IPPL build.

The intended message is:

Native IPPL NUFFT is the distributed path. cuFINUFFT is a single-rank CUDA-backed GPU backend because cuFINUFFT itself does not provide MPI decomposition.

Tests

Added:

• unit_tests/FFT/NUFFT.cpp
• unit_tests/FFT/NUFFTAccuracy.cpp
• unit_tests/FFT/NUFFTTestUtils.h

Coverage includes:

• Type 1 native NUFFT correctness
• Type 2 native NUFFT correctness
• tolerance sweep against direct DFT reference
• optional FINUFFT/cuFINUFFT backend checks when enabled
• skips for unsupported cuFINUFFT multi-rank execution
• skips for FINUFFT/cuFINUFFT non-3D backend instantiations

Validation

Validated locally on macOS with OpenMP and FINUFFT disabled:

cmake --build build-pr501-nufft-final-openmp -j 8
ctest --test-dir build-pr501-nufft-final-openmp -R 'NUFFT|FFT' --output-on-failure

Result:

FFT             Passed
NUFFT           Passed
NUFFTAccuracy   Passed
TestFFTCC       Passed
TestFFTRC       Passed

Also checked:

git diff --check

Result: clean.

A previous full local OpenMP run with FINUFFT disabled passed all tests:

72/72 tests passed

Notes

The core NUFFT implementation is intentionally kept close to the original PR501 NUFFT implementation.

Intentional deviations from PR501 are limited to:

• adapting tests to current master particle layout API
• keeping current master CMake/CUDA architecture handling authoritative
• adding explicit cuFINUFFT single-rank and CUDA-memory-space guards
• adding DUCC0 as the default fetched FINUFFT FFT backend
• making FINUFFT/cuFINUFFT optional and off by default

Out Of Scope

This PR does not include:

• PIF integration
• host-only serial IPPL to CUDA staging for cuFINUFFT
• non-3D FINUFFT/cuFINUFFT backend support