Skip to main content

20  Integration Tests

Executable documentation and examples.

Examples should be treated as executable documentation. Each example page should include the physics or numerical purpose, build flags, run command, expected output, and the IPPL concepts exercised.

20.1 Example page template

Each example should use this structure:

## Example name

Source: `path/to/example.cpp`

Purpose:
: One paragraph explaining the numerical or physics problem.

Build requirements:
: Relevant CMake flags, backend assumptions, and optional dependencies.

Run:
: Command line and argument meaning.

Expected result:
: Key output lines, conservation check, convergence rate, or generated file.

Concepts exercised:
: IPPL classes and subsystems used by the example.

20.2 First executable examples to expand

20.2.1 PICnd

Purpose: tests a dimension-specialized particle-in-cell workflow with periodic particle boundary conditions, cloud-in-cell gather/scatter, and optional ORB-based repartitioning.

srun ./PICnd 128 128 128 10000 10 --info 10

Concepts exercised: ParticleBase, ParticleSpatialLayout, ParticleAttrib, Field, FieldLayout, UniformCartesian, CIC, OrthogonalRecursiveBisection, reductions, and particle migration.

Expected checks: particle count is conserved after migration, scatterCIC checks charge conservation against the mesh field sum, and timers report particle update, scatter, gather, repartitioning, and velocity/position updates.

20.2.2 LandauDamping

Purpose: runs a production-style electrostatic particle-in-cell mini-app through the ALPINE manager stack. The driver in alpine/LandauDamping.cpp creates a LandauDampingManager, which wires together AlpineManager, FieldContainer, ParticleContainer, FieldSolver, and load balancing. It is the best example for users who want to see the library-level particle, field, interpolation, solver, timing, and manager machinery in one executable.

srun ./LandauDamping Nx Ny Nz Np Nt solver_type load_balancing LeapFrog \
  [preconditioner_type [preconditioner_params...]] \
  --overallocate 2.0 --info 5
Argument Meaning
Nx Ny Nz Number of grid points in each direction.
Np Number of simulation particles.
Nt Number of time steps.
solver_type Landau-compatible paths are FFT, CG, PCG, FEM, or FEM_PRECON; the generic OPEN solver exists in ALPINE but this miniapp rejects it because Landau damping is periodic.
load_balancing Particle load-balancing threshold; 0.1 means 10 percent.
LeapFrog Time-stepper used by the current Landau damping path.

CG selects the plain conjugate-gradient path. PCG and FEM_PRECON select preconditioned paths. The current executable reads a fixed five-token preconditioner block after PCG or FEM_PRECON; pass the relevant values first and use harmless padding values for unused entries until the parser is generalized.

Preconditioner Extra arguments
newton level
chebyshev degree
richardson iterations communication, where communication is 0 or 1.
gauss-seidel inner_iterations outer_iterations communication, where communication is 0 or 1.
ssor inner_iterations outer_iterations omega, commonly with omega = 1.5707963.

Example PCG run:

srun ./LandauDamping 256 256 256 134217728 20 PCG 0.1 LeapFrog \
  ssor 4 2 1.5707963 0 --overallocate 2.0 --info 5

Concepts exercised: LandauDampingManager, AlpineManager, FieldContainer, ParticleContainer, FieldSolver, PoissonCG, ParameterList, ORB load balancing, particle migration, field solve, gather/scatter, diagnostics, and timings. The ALPINE/IPPL paper gives the broader performance-portability context for Landau damping mini-apps [1]; recent ETH theses document preconditioner behavior and Landau damping scaling studies [2], [3].

For the local manager stack and execution flow, see Chapter 22.

20.2.3 TestGaussian

Purpose: tests FFTOpenPoissonSolver with a Gaussian source and analytic potential.

srun ./TestGaussian 64 64 64 pencils a2a no-reorder HOCKNEY --info 5

Concepts exercised: Field, UniformCartesian, FieldLayout, ParameterList, HeFFTe options, Hockney/Vico algorithms, norms, and timing output.

20.2.4 TestRepeatedGreensFunction and TestRepeatedGreensFunctionAnalytic

Purpose: verify the repeated kernel copies of FFTOpenPoissonSolver that model a bunch train (see Section 16.3.2). TestRepeatedGreensFunction compares the solver with itself. For STANDARD, INTEGRATED, and TRUNCATED, one repeated solve must equal the plain solve plus \(2K\) shiftedGreensFunction() solves, and setting repeat_count back to 0 must restore the plain kernel. It uses anisotropic cells and a spacing that is not a multiple of \(h_z\). On a single rank, for STANDARD and INTEGRATED, it also compares with the same charge tiled \(2K+1\) times on a longer mesh. TestRepeatedGreensFunctionAnalytic compares \(\phi_K - \phi_0\) and \(\mathbf{E}_K - \mathbf{E}_0\) for the Gaussian source of TestGaussian_convergence with the summed exact field. \(\mathbf{E}\) comes from the spectral gradient (SOL_AND_GRAD).

srun ./TestRepeatedGreensFunction --info 5
srun ./TestRepeatedGreensFunctionAnalytic --info 5

Expected result: every check prints a PASS line (visible with --info 5) and the exit code is 0. In the analytic test, copies outside the box (\(a = 1\) and \(2.5\), \(K = 1\) and \(8\), \(N = 64\)) match to round-off for STANDARD and TRUNCATED (relative \(L_2\) error below \(10^{-12}\)). For INTEGRATED they match within the cell-averaging error (below \(10^{-8}\) for \(\phi\) and \(2\cdot 10^{-7}\) for \(\mathbf{E}\)). Copies that overlap the box (\(a = 0.37\), \(K = 2\)) converge at second order from \(N = 32\) to \(N = 64\). TRUNCATED runs with a non-default force_constant, so the copies must scale with it.

Concepts exercised: FFTOpenPoissonSolver, ParameterList, updateParameter, kernel regeneration in solve(), shiftedGreensFunction(), SOL_AND_GRAD output, field expressions, and global norms.

20.2.5 TestFieldBC

Purpose: demonstrates mixed face boundary conditions on a 3D scalar field.

Concepts exercised: BConds, PeriodicFace, NoBcFace, ConstantFace, ZeroFace, ExtrapolateFace, findBCNeighbors, apply, and per-rank field output.

20.2.6 TestLaplace

Purpose: verifies laplace(field) against the analytic Laplacian of a trigonometric function.

srun ./TestLaplace 64 10

Concepts exercised: periodic boundary conditions, local-to-global coordinate conversion, field expressions, pow, sum, relative error computation, timers, and ippl::fence().

20.2.7 ParticleSendRecv

Purpose: verifies that spatial particle migration sends particles to the rank owning the region that contains their position.

Concepts exercised: ParticleSpatialLayout, RegionLayout, particle packing/unpacking, MPI exchange, particle boundary conditions, and global particle-count conservation.

20.2.8 ParticleBC

Purpose: verifies particle boundary-condition behavior on upper and lower faces for PERIODIC, REFLECTIVE, SINK, and NO.

Concepts exercised: NDRegion, PRegion, ParticleLayout::applyBC, and position attribute updates.

20.2.9 GatherScatterTest

Purpose: verifies CIC gather/scatter behavior across one, two, and three dimensions.

Concepts exercised: constant-field gather, additive gather, charge-conserving scatter, custom scatter range policies, and hashed scatter.

20.2.10 TestP3MPairKernels

Purpose: compares the two pair loops of TruncatedGreenParticleInteraction, CELL_PAIRS and OWNED_PARTICLE (see Section 8.9), on the same overlap layout, and serves as their benchmark. Particles fill the unit box uniformly or as a Gaussian of rms width 0.06 around its centre (clustered, dense search cells). The test counts the directed candidate pairs with forEachOwnedParticle, then runs one warm-up solve and the given number of timed solves with each pair loop and compares the fields. With moving, every particle gets a random normalized momentum (components between \(-2\) and \(2\)) and both loops run the moving-source mode, so E and B are compared. In both modes the moving-source mode with all momenta zero must reproduce the static field and leave B exactly zero; the program prints both times for this case.

srun ./TestP3MPairKernels [N=20000] [timed solves=3] [uniform|clustered] [rcut=0.08] [static|moving] --info 1
# GPU benchmark: 2^24 particles, 64^3 search cells, about 64 particles per cell
srun -n 1 ./TestP3MPairKernels 16777216 3 uniform 0.0156248438 --info 1

The arguments are positional, so IPPL options such as --info can only follow all of them. CTest runs the test on two ranks with the default arguments.

Expected result: the program prints the directed candidates per particle, the time per solve and the candidate pairs per second per rank for both pair loops, the speedup, the relative maximum differences of E (and of B with moving), and the zero-momentum comparison. The exit code is 0 if the differences between the loops are below \(10^{-12}\), the zero-momentum E agrees with the static E to \(10^{-13}\), and B stays exactly zero. On one CPU core both loops take the same time and the fields agree exactly. Measured GPU times are listed in Table 8.3.

Concepts exercised: ParticleSpatialOverlapLayout, forEachOwnedParticle, TruncatedGreenParticleInteraction, the pair_kernel parameter, ParameterList, Kokkos::Random_XorShift64_Pool, parallel_reduce, and MPI reductions.

20.2.11 TestTruncatedGreenParticleInteraction

Purpose: verifies the short-range P3M interaction (Section 8.9.3) with two unit charges in a periodic ParticleSpatialOverlapLayout. Zero-distance pairs must give a finite zero field with the default and an updated regularization_cutoff, and a non-positive regularization_cutoff is rejected. Pair scenarios check open, periodic, and rank-internal pairs, a cutoff changed between updates, and periodic ghosts of particles that are not the first ones in the container. An interaction cutoff above the layout cutoff and a pair loop after a rejected updateLayout() must both throw. In the moving-source mode, two particles with different charges and momenta must receive the rest-frame field of their partner Lorentz-transformed to the lab, to \(10^{-12}\); in a second case one partner lies inside the lab cutoff but outside the rest-frame cutoff and must contribute nothing. On two ranks each particle sees its partner only as a ghost. The test uses the default pair loop, OWNED_PARTICLE.

srun -n 2 ./TestTruncatedGreenParticleInteraction --info 5

Concepts exercised: ParticleSpatialOverlapLayout, ghost particles, periodic images, setCutoff, updateLayout, TruncatedGreenParticleInteraction, and IpplException.

20.2.12 TestFFTCC and TestFFTRC

Purpose: verify forward/backward FFT consistency for complex-to-complex and real-to-complex transforms.

Concepts exercised: FFT<CCTransform>, FFT<RCTransform>, input/output layouts, r2c_direction, HeFFTe defaults, and ghost-free owned-region transforms.

20.2.13 TestFFTPeriodicPoissonSolver

Purpose: verifies the periodic FFT Poisson solver on a smooth manufactured solution over grid refinements.

Concepts exercised: FFTPeriodicPoissonSolver, Poisson::OutputType, ParameterList, RHS assignment in a Kokkos kernel, solution/gradient output modes, and relative error norms.

20.2.14 TestSphere

Purpose: verifies FFTOpenPoissonSolver on the gravitational potential of a sphere.

srun ./TestSphere HOCKNEY --info 5

Concepts exercised: open-boundary algorithms, analytic source/solution kernels, grid refinement, and norm(rho) / norm(exact) style error measurement.

20.2.15 FEM Poisson and Lagrange tests

Purpose: verify scalar finite-element spaces on structured meshes with homogeneous, periodic, and non-homogeneous boundary conditions.

Concepts exercised: FiniteElementSpace, LagrangeSpace, element-local to global DOF mapping, load-vector assembly, operator application through evaluateAx, lumped mass construction, and L2 error computation.

Expected checks: manufactured-solution error decreases under refinement, boundary DOFs match the selected condition, and preconditioned variants report residual behavior.

20.2.16 FEM Maxwell diffusion tests

Purpose: verify the Nedelec finite-element path for vector-valued Maxwell diffusion problems.

Concepts exercised: NedelecSpace, vector DOFs, basis curls, FEMVector, PCG solver parameters, reconstruction to points, and L2 error checks.

Expected checks: the solver reaches the requested tolerance or iteration limit, exposes residue and iteration count, and produces the expected convergence behavior for the manufactured vector field.

20.2.17 Maxwell FDTD tests

Purpose: verify finite-difference time-domain electromagnetic stepping and boundary handling.

Concepts exercised: FDTDSolverBase, StandardFDTDSolver, NonStandardFDTDSolver, source fields, electric and magnetic fields, fdtd_bc, timeShift, applyBCs, and evaluate_EB.

Expected checks: examples should state the time step and grid spacing, report field diagnostics, and make boundary assumptions explicit.