Troubleshooting¶

ModuleNotFoundError: No module named 'pyhermes'¶

Check the active interpreter and extension:

echo "VIRTUAL_ENV=${VIRTUAL_ENV:-<unset>}"
type -a python python3
python -c 'import importlib.util, sys; print(sys.executable); print(importlib.util.find_spec("pyhermes"))'

For an installed build, activate the installation environment. For a local build, add the absolute HERMES build directory to PYTHONPATH.

Python loads the wrong HERMES¶

python -c 'import pyhermes; print(pyhermes.__file__)'
python -m pip show pyhermes

The second command may report nothing for a CMake installation. Search common prefixes for older extensions:

find /usr/local /opt/homebrew "$HOME/Library/Python" \
  -name 'pyhermes*.so' -print 2>/dev/null

Remove only paths you have inspected. Do not uninstall an unrelated PyPI package merely because it is named hermes.

Import fails with a missing libhermes¶

The Python extension and shared library must come from the same installation. Reconfigure with CMAKE_INSTALL_PREFIX set to the virtual environment, build, and run cmake --install build. Avoid copying the .so file by itself.

On macOS, inspect linkage with:

otool -L /absolute/path/to/pyhermes*.so

A data file cannot be found¶

python - <<'PY'
import os
import pyhermes
print(os.environ.get("HERMES_DATA_PATH", "<unset>"))
print(pyhermes.getDataPath("VERSION"))
print(pyhermes.getDataPath("RadiationField/Vernetto16/isrf.fits.gz"))
PY

HERMES_DATA_PATH must point to the directory containing VERSION, CosmicRays/, GasDensity/, and the other data subdirectories—not to the archive or its parent.

CMake still uses an old Python or data URL¶

Those selections are cached. Remove only the out-of-source build directory and configure again:

rm -rf -- /absolute/path/to/hermes/build
cmake -S /absolute/path/to/hermes -B /absolute/path/to/hermes/build ...

Never use git clean as an installation fix in a repository with uncommitted work.

Output file already exists¶

This is intentional protection. Choose another name or explicitly prefix a CFITSIO filename with !. The examples expose this decision as --overwrite.

Partial-sky spectrum is too low¶

Exclude BAD_DATA/UNSEEN pixels and divide by the number of valid pixels in the region, not full-sky NPIX. Use the validated reader in hermes-examples as a reference.

A long run appears slower than expected¶

Confirm NSIDE, unmasked pixel count, cache settings, and HERMES_NUM_THREADS. Benchmark a representative small mask and perform cache convergence before scaling to a full production map.