48  Common Problems

48.1 CMake cannot find a compiler or MPI

Load a consistent compiler and MPI toolchain, remove only the affected build directory, and configure it again. Do not reuse a build directory created with a different backend.

48.2 CUDA or HIP configuration fails

Check that PLATFORMS and ARCH match the installed toolkit and physical GPU. Confirm that the host compiler is supported by that toolkit.

48.3 The input parser rejects a statement

Start from a passing OPALX regression input. Check semicolons, object names, attribute spelling, and referenced paths. Historical OPAL examples may use features that are not registered in OPALX.

48.4 Several MPI ranks select the same GPU

Launch one rank per GPU and add --kokkos-map-device-id-by=mpi_rank.

48.5 A run completes but results change with the backend

Reduce the time step, repeat with a finer mesh, record rank and device counts, and compare a small deterministic case across serial and accelerator builds.

48.6 A bunch splits near a hard-edge field

A discontinuous fringe field can make nearby particles receive different numbers of kicks, especially when their path lengths differ. The numerical artifact can look like a physically split bunch. Prefer a resolved fringe model where one is available and repeat the run with a smaller time step.

48.7 A very short active element gives step-dependent results

If an active element is comparable in length to one integration step, some particles can enter or leave it on different steps and receive different numbers of kicks. Reduce the time step until the observable of interest is stable. Treat that convergence check as part of the simulation setup.