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

16.1 Initial example set

Example Source location Manual purpose
Hello world Doxygen extras and minimal program Runtime lifecycle and communicator basics.
PIC test test/particle/PICnd.cpp End-to-end particle-mesh loop.
Landau damping alpine/LandauDamping.cpp Production-style manager and PIC mini-app.
Gaussian Poisson test/solver/TestGaussian.cpp Solver setup and convergence verification.
Maxwell FDTD test/maxwell Electromagnetic solver setup.
P3M heating examples/collisions/P3MHeating.cpp Collision/P3M application pattern.
Cosmology cosmology/StructureFormation.cpp Particle-mesh gravity workflow.
Field boundary conditions test/field/TestFieldBC.cpp Mixed face boundary-condition setup.
Laplace field operator test/field/TestLaplace.cpp Differential operator, periodic BCs, and error reduction.
FFT CC/RC transforms test/FFT/TestFFTCC.cpp, test/FFT/TestFFTRC.cpp Forward/backward transform consistency.
FFT sine/cosine transforms test/FFT/TestSine.cpp, test/FFT/TestCos.cpp, test/FFT/TestCos1.cpp Real in-place spectral transforms.
Periodic Poisson test/solver/TestFFTPeriodicPoissonSolver.cpp Periodic FFT solver with manufactured solution.
Open Poisson sphere test/solver/TestSphere.cpp Open-boundary gravitational sphere verification.
FEM Lagrange spaces unit_tests/FEM/LagrangeSpace.cpp, test/solver/fem/TestZeroBC_sin* Scalar FEM basis, assembly, and convergence verification.
FEM Nedelec spaces unit_tests/FEM/NedelecSpace.cpp, test/solver/fem/TestMaxwellDiffusion* Edge-element basis, curl operators, and Maxwell diffusion.
Maxwell FDTD test/maxwell Standard and non-standard FDTD setup and time stepping.

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

16.3 First executable examples to expand

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

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

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

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

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

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

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

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

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

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

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

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

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

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