[Bug]: alpsvars.sh/.csh set PYTHONPATH=<prefix>/lib, but pyalps is installed in <prefix>/lib/pythonX.Y/site-packages

[shinaoka]

Note

Reported from an AI-assisted test of ALPS 3.0.0 on Ubuntu 24.04, then re-checked against the
v3.0.0 sources and by targeted reruns. No human has independently reviewed it yet — please
verify before acting on it, and corrections are very welcome.

Describe the bug

After cmake --install, sourcing <prefix>/bin/alpsvars.sh is not enough to import pyalps.

• tool/alpsvars.sh.in sets PYTHONPATH=${ALPS_HOME}/lib; tool/alpsvars.csh.in does the same with setenv.
• The package is installed one level deeper. The install step prints ALPS_PYTHON_LIB_DEST_ROOT: lib/python3.12/site-packages, and lib/pyalps/CMakeLists.txt installs into ${ALPS_PYTHON_LIB_DEST_ROOT}/pyalps.

So PYTHONPATH points at the directory that contains site-packages, not at site-packages
itself. CMake already knows the correct path at configure time (cmake/FindPythonMod.cmake:238 sets
ALPS_PYTHON_LIB_DEST_ROOT), but the templates do not use it.

The source installation page documents the manual
workaround ("If import pyalps fails with ModuleNotFoundError, append the site-packages directory
to PYTHONPATH as well"), which suggests the templates were not updated when the install location
changed.

To Reproduce

Use the interpreter that was used for the build (it has numpy and scipy), and start from a shell
where PYTHONPATH is unset:

prefix=/path/to/alps-prefix
python=/path/to/python3    # the interpreter used for the build

# exactly what alpsvars.sh sets:
export PYTHONPATH="$prefix/lib"

"$python" -s -c "import pyalps"
# -> ModuleNotFoundError: No module named 'pyalps'

# where the package actually is (printed by cmake --install):
#    $prefix/lib/python3.12/site-packages/pyalps

# the workaround from the installation page:
export PYTHONPATH="$prefix/lib/python3.12/site-packages:$PYTHONPATH"
"$python" -s -c "import pyalps; print(pyalps.__file__)"
# -> $prefix/lib/python3.12/site-packages/pyalps/__init__.py

The command-line tools are unaffected in the same shell: spinmc --help works before and after.

Expected behavior

alpsvars.sh and alpsvars.csh add <prefix>/@ALPS_PYTHON_LIB_DEST_ROOT@ — a value CMake already
substitutes — to PYTHONPATH, and the website keeps its workaround note as long as its instructions
still cover the affected releases.

Environment (please complete the following information)

• OS: Ubuntu 24.04 (Linux 6.8.0, x86_64)
• ALPS: v3.0.0 (commit 1950cc6), built from source and installed with cmake --install
• Toolchain: GCC 13.3.0, CMake 3.25.1, Open MPI 4.1.6, HDF5 1.10.10 (serial), OpenBLAS 0.3.26
• Python version: 3.12.11 (venv)
• Related module versions if applicable: numpy 2.5.3, scipy 1.18.1

Additional context

Related: #13 (install location of the pyalps Python modules).

Open PR #107 builds pyalps as a separate wheel. If it lands, the PYTHONPATH entry in alpsvars may
become unnecessary rather than needing a fix. For the released 3.0.0 the template is wrong either way.