Skip to content

Troubleshooting

Common issues and their solutions.

Self-test: 64-bit Atomic Operations Failed

Symptom: THOR aborts at startup with a self-test failure:

- FAIL: Device #0 [CPU] ... - 64-bit atomic FAILED: bad_function_call
-- Hint: This device does not support 64-bit atomics required by THOR.
         Try switching to the OpenMP backend instead.

You may also see AdaptiveCpp errors mentioning Symbols not found: [ _Z8atom_addPU3AS4Vll ].

Cause: The selected SYCL device (typically an OpenCL CPU or integrated GPU) does not support 64-bit atomic operations (cl_khr_int64_base_atomics), which THOR requires. This commonly happens when building with -DACPP_TARGETS="generic" (SSCP/JIT compilation) and the runtime picks an OpenCL device.

Solutions:

  1. Switch to the OpenMP backend (recommended for CPU execution): 

    # Option A: Set the device in your config.yaml
device: "cpu-openmp"

# Option B: Hide non-OpenMP backends via environment variable
export ACPP_VISIBILITY_MASK="omp"

  2. Build with the OpenMP target instead of generic: 

    cmake -S . -B build -DACPP_TARGETS="omp" ...

  3. Disable self-tests (not recommended — the simulation will likely crash later): 

    selftest: false

Self-test: ASSERT Device Compatibility Failed

Symptom: THOR aborts at startup with:

- FAIL: Device #0 ... - ASSERT device compatibility FAILED
-- Hint: The ASSERT macro is using ASSERT_THROW which is not device-compatible.

Cause: In debug builds with -DACPP_TARGETS="generic", the ASSERT_THROW macro pulls std::ostringstream and spdlog into device code, which cannot be JIT-compiled for GPU/OpenCL backends.

Solutions:

  1. Use the OpenMP target for debug builds: 

    cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug -DACPP_TARGETS="omp" ...

  2. Switch to simple asserts: 

    cmake -S . -B build -DTHOR_DEBUG_ASSERT=OFF ...

MPI Segfault at Startup

Symptom: Segmentation fault in MPI_Comm_size immediately on launch:

user@host:~$ mpirun -np 1 ./thor ./config.yaml
*** Process received signal ***
Signal: Segmentation fault (11)
Failing at address: 0x440000e8
...libmpi.so.40(MPI_Comm_size+0x3b)...

Cause: MPI library mismatch - the executable was compiled against a different MPI library than the one loaded at runtime.

Solution: Ensure consistent MPI environment:

# Check which MPI the executable was linked against
ldd /path/to/thor | grep mpi

# Verify mpirun comes from the same installation
which mpirun

Rebuild Thor using the MPI installation you intend to use at runtime.

Apptainer: fuse2fs not found / gocryptfs not found

Symptom: When running THOR via Apptainer, you see one or both of these warnings:

INFO:    fuse2fs not found, will not be able to mount EXT3 filesystems
INFO:    gocryptfs not found, will not be able to use gocryptfs

Cause: Apptainer checks for optional host utilities at startup. These are only needed for EXT3 overlay filesystems and encrypted containers, respectively.

Solution: These are harmless informational messages and can be safely ignored. THOR containers use Docker-based images and do not require either feature.

TBB Not Found

Symptom: CMake fails with an error about TBB not being found:

CMake Error at /usr/share/cmake/Modules/FindPackageHandleStandardArgs.cmake:XXX:
  Could NOT find TBB (missing: TBB_DIR)

Cause: TBB (Threading Building Blocks) is required when THOR_CGAL_PARALLEL is enabled (the default), which allows parallel CGAL triangulation construction.

Solutions:

  1. Disable parallel CGAL construction (easiest): 
    cmake -S . -B build -DTHOR_CGAL_PARALLEL=OFF ...
  2. Install TBB: Install TBB via your distribution's package manager where available. TBB has native CMake support via TBBConfig.cmake. If CMake can't find TBB after installation, add the TBB installation directory to CMAKE_PREFIX_PATH. For example, with Intel oneAPI this might be: 
    cmake -S . -B build -DCMAKE_PREFIX_PATH=/opt/intel/oneapi/tbb/latest ...