Troubleshooting

For numeric contact, geometry, and owner codes seen in logs or a debugger, see Internal type codes for debugging.

CUDA or PTX mismatch

Errors such as CUDA_ERROR_UNSUPPORTED_PTX_VERSION usually indicate that the installed NVIDIA driver cannot execute code produced by the selected CUDA Toolkit. Verify the driver/toolkit compatibility and rebuild with a supported toolkit.

Runtime JIT compilation cannot find headers

For binary wheels, install "deme[cuda12]" to supply matching libraries and headers. A complete pip CUDA installation takes precedence over system CUDA discovery inside the Python extension only. It does not export CUDA paths to child processes. If another GPU package has already loaded a different NVRTC version, use compatible dependencies in a fresh Python process or separate environment.

DEME compiles kernels at runtime. Confirm that the CUDA Toolkit headers and the share/DEME/kernel and include resources installed with DEME are available. The CUDA header major and minor version must match the loaded NVRTC library. If several CUDA Toolkits are installed, set CUDA_HOME to the one providing that NVRTC version, for example:

export CUDA_HOME=/usr/local/cuda-12.8

Errors in CUDA or CURAND headers involving undefined internal identifiers often mean that an unversioned /usr/local/cuda link selected headers from a newer Toolkit than the loaded libnvrtc. Current DEME releases reject that mismatch and report both the required NVRTC version and how to select matching headers.

Import works but initialization fails

import deme verifies only that the extension and its immediate shared libraries can load. A meaningful installation test must construct a solver and run a small simulation through Initialize() so NVRTC, kernel resources, and the GPU driver are exercised.

Conda GLIBCXX errors

Build with compilers compatible with the target Conda environment. A wheel built against a newer system libstdc++ may import on the build host but fail inside another environment.

Cannot open or read a JIT source file

JIT source-loading errors report the attempted absolute path. Check that the runtime kernel/header resources exist there and are readable. On Windows, also check which DEMERuntimeDataHelper.dll the application loads: a stale copy can point to resources from another build. Refresh the helper library and runtime resources together. Files that exist but contain older source code are not identified by the file-read check; see the stale-kernel guidance below.

Stale runtime kernels

After changing kernel or force-model sources, use a clean build or ensure the runtime kernel assets have been refreshed. Old copied text sources can make the runtime behavior disagree with the compiled host code.

Persistent Jitify startup cache

DEME uses Jitify and NVRTC to discover CUDA headers and compile runtime kernels during solver initialization. Workloads that repeatedly start fresh DEME processes can persist the discovered header sources and avoid repeating much of that startup work. Set DEME_PERSISTENT_JITIFY_CACHE to a writable cache-file path:

export DEME_PERSISTENT_JITIFY_CACHE="$HOME/.cache/deme/jitify_header_cache.bin"
mkdir -p "$(dirname "$DEME_PERSISTENT_JITIFY_CACHE")"

On Windows, set the variable in the PowerShell session that launches the executable:

$cacheDirectory = Join-Path $env:LOCALAPPDATA "deme"
New-Item -ItemType Directory -Force -Path $cacheDirectory | Out-Null
$env:DEME_PERSISTENT_JITIFY_CACHE = Join-Path $cacheDirectory "jitify_header_cache.bin"

The first run still discovers headers and compiles kernels. Later fresh processes can reuse the saved headers when compiling new kernels, while matching compiled kernels are reused separately through DEME_JIT_CACHE_DIR. To measure the header cache’s benefit, keep its file but select an empty compiled-kernel cache for each comparison run. A fully populated compiled-kernel cache can hide the header-discovery cost.

Values such as 1, true, on, and yes select an automatic temporary path. Values such as 0, false, off, and no, as well as an unset variable, disable the persistent cache. The cache is opt-in because an automatic shared temporary path can be unsafe on multi-user systems, concurrent writers can contend, and header contents can change without their paths or CUDA version changing. Prefer an explicit, user-owned path and remove the file after changing CUDA toolchains or headers. An unreadable, incompatible, or unwritable cache falls back to normal Jitify discovery.

Custom force models

If a custom force kernel fails to launch, try a smaller block size such as SetForceCalcThreadsPerBlock(128) during setup. Large kernels can exceed register limits. Check CUDA errors before treating missing contacts or a subsequent too-many-geometries-in-bin error as a geometry problem.

For JIT errors involving material arrays or missing wildcard variables, compare your model declarations with DEMdemo_Electrostatic. Declare pairwise material properties with SetMustPairwiseMatProp and contact wildcards with SetPerContactWildcards before initialization.