Troubleshooting

Quick fixes for common configure and runtime problems. The full install story is INSTALL.md.

Configure-time

fatal error: 'mpi.h' file not found

CMake or the compiler is not using the same MPI you intend. Before cmake:

  1. Load your modules (gcc, openmpi, …) — see INSTALL.md §1.

  2. Set CC / CXX to the MPI wrappers or module gcc explicitly.

  3. Remove a stale build tree or re-run cmake with -DCMAKE_C_COMPILER=… and -DCMAKE_CXX_COMPILER=… so CMakeCache.txt does not still point at /usr/bin/gcc.

HIP/Cray builds may need extra include flags for MPI in HIP translation units; see INSTALL.LUMI.md §2.

CMake finds the wrong GCC (e.g. GCC 8 instead of 11)

Same as above: configure after module load, set compilers explicitly, or delete the build directory. See INSTALL.md (“Stale CMake cache”).

Could not find Heffte / Heffte_DIR not set

  1. Build and install HeFFTe 2.4.1 (or compatible) for your backend — INSTALL.md §3.

  2. Point CMake at the install prefix: export CMAKE_PREFIX_PATH=$HOME/opt/heffte/2.4.1-cpu:$CMAKE_PREFIX_PATH (adjust path and variant: -cpu, -cuda, -rocm).

  3. Do not unpack HeFFTe inside the OpenPFC clone.

find_package(OpenPFC) fails in a downstream project

OpenPFC must be installed (or you must point CMake at a build tree that exports the package). Set CMAKE_PREFIX_PATH to the install prefix, or -DOpenPFC_DIR=/path/to/lib/cmake/OpenPFC. See getting_started/01-basics/README.md.

CUDA toolchain compatibility

<compare>/operator<=> are unavailable in CUDA device code

std::array::operator== (used internally by a defaulted operator<=>) is not usable in __device__ code, so strong_types.hpp cannot rely on the C++20 <compare> header/defaulted spaceship operator for CUDA translation units. This is a __CUDACC__-mode limitation, not a host-compiler-version issue — it applies to any GCC version, including current ones (verified with GCC 15.2.0 as the host compiler: <compare>, operator<=>, and concepts all compile cleanly for ordinary host-only code; the limitation is specific to device code, not to this GCC version).

Affected files: CUDA translation units (.cu files) that transitively include include/openpfc/kernel/data/strong_types.hpp.

Implementation detail: The hand-written comparison operators use element-by-element comparison of the underlying array members to avoid calling std::array::operator==, which is not available in device code.

Workaround: The code-level workaround is automatic - no user action required. The strong types in strong_types.hpp guard #include <compare> and the defaulted operator<=> behind #ifndef __CUDACC__, providing a hand-written __host__ __device__ operator== instead when compiling under nvcc.

Verification: Test CUDA compilation with:

echo '#include <openpfc/kernel/data/world.hpp>
int main(){return 0;}' | nvcc --std=c++20 -x cu -c -o /tmp/test_world_cu.o -

If you encounter similar issues with other C++20 features in CUDA device code, apply the same pattern: guard the C++20-only construct behind #ifndef __CUDACC__ and provide a hand-written __host__ __device__ equivalent for device code.

Process exits immediately with “validation” or parameter errors

Models such as tungsten validate model.params at startup. Read the printed report: missing keys, out-of-range values, or wrong types. Compare your file to apps/tungsten/inputs_json/ samples. See app_pipeline.md for which JSON sections are consumed and apps/tungsten/README.md for layout pointers.

“No such file” for the config path

Paths are resolved from the current working directory (often your build/ folder). Use a path relative to that directory, or an absolute path.

Still stuck?