Pr501 hosg final

[aaadelmann]

Summary

This PR extracts the higher-order scatter/gather and autotuning part of the original PR #501 into a finite, reviewable branch.

It adds a new interpolation framework for particle-to-grid scatter and grid-to-particle gather, including:

• runtime-selectable scatter/gather frontends
• NGP, linear/CIC, quadratic, cubic, and quartic interpolation kernels
• particle binning support for sorted interpolation paths
• atomic, tiled, and output-focused scatter implementations
• atomic gather and sorted gather support
• runtime scatter/gather configuration objects
• tile-size cache and autotune preset plumbing
• built-in autotune preset loading at ippl::initialize()
• regression tests for binning and higher-order gather/scatter behavior

User-Facing API

The new API is based on explicit kernel and config objects.

Example scatter:

using T = double;
constexpr unsigned Dim = 3;

ippl::Interpolation::LinearKernel<T> kernel;

ippl::Interpolation::ScatterConfig<Dim> cfg;
cfg.method = ippl::Interpolation::ScatterMethod::Atomic;
cfg.sort = true;

auto scatter = ippl::Scatter<decltype(kernel), Dim>(kernel, cfg);
scatter(field, bunch.R, bunch.Q);

Example gather:

ippl::Interpolation::LinearKernel<T> kernel;

ippl::Interpolation::GatherConfig<Dim> cfg;
cfg.method = ippl::Interpolation::GatherMethod::Atomic;

auto gather = ippl::Gather<decltype(kernel), Dim>(kernel, cfg);
gather(field, bunch.R, bunch.E);

Available kernels include:

ippl::Interpolation::NGPKernel<T>
ippl::Interpolation::LinearKernel<T>
ippl::Interpolation::QuadraticKernel<T>
ippl::Interpolation::CubicKernel<T>
ippl::Interpolation::QuarticKernel<T>

Autotuning

The PR adds CMake support for bundled autotune preset CSV files. These are configured into a generated IpplAutoTunePresets.h header and seeded during ippl::initialize().

At runtime, ippl::Interpolation::AutoTune::initialize() seeds scatter/gather defaults and can run autotuning sweeps when requested through the existing environment mechanism.

Regression Tests

Added:

• unit_tests/Interpolation/Binning.cpp
• unit_tests/Interpolation/KernelGatherScatterTest.cpp

The tests cover:

• bin permutation validity
• bin-offset consistency
• sorted particle grouping
• empty and single-particle binning cases
• scatter conservation
• gather from constant fields
• periodic boundary behavior
• convergence for NGP, linear, quadratic, and cubic kernels
• complex scatter/gather adjointness
• sorted versus unsorted scatter consistency
• scatter/gather roundtrip behavior

Supporting Changes

BareField::innerProduct now handles complex-valued fields using Hermitian convention:

f1 * conj(f2)

for Kokkos::complex<T>, while preserving the existing real-valued behavior.

This is required for the complex adjointness checks in the new scatter/gather regression tests.

A small VectorTraits<Vector<T, Dim>> helper was added to expose:

real_type = T
dim       = Dim

for generic interpolation code.

Commits

b03763d Add VectorTraits helper for vector-valued interpolation support
b451224 Add HOSG interpolation regression tests
4701b08 Update CIC helpers for Kokkos device use
5f5d11c Initialize interpolation autotune runtime state
1a77948 Add higher-order scatter/gather interpolation framework
cfbecd3 Add autotune preset plumbing for scatter/gather

Master was kept as the source of truth for newer fixes in particle communication, boundary conditions, halo handling, and current-deposition tests.

Verification

Tested locally with the OpenMP unit-test build:

cmake --build build-pr501-hosg-step1-openmp -j 8
ctest --test-dir build-pr501-hosg-step1-openmp --output-on-failure

Result:

39/39 tests passed