[Bug]: -DPython3_EXECUTABLE (recommended in the install docs) is silently ignored; configure picks another Python and can fail

[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

The installation docs tell users to pin the Python interpreter with -DPython3_EXECUTABLE=/path/to/python3:

• install/source.md, in four sections: Verify Dependencies, Common Errors, Other Error Details and the macOS Build notes.
• no_root_guide.pdf, in four cmake commands and in the troubleshooting line "always pass an explicit -DPython3_EXECUTABLE=...".

ALPS ignores that flag. At v3.0.0, cmake/FindPythonMod.cmake:44 calls

find_package(Python COMPONENTS Interpreter Development REQUIRED)

using the unversioned module name, so CMake reads Python_EXECUTABLE, not Python3_EXECUTABLE.
The flag is accepted in silence and CMake falls back to whichever interpreter it finds first. If
that interpreter has no numpy, configuration fails at cmake/FindPythonMod.cmake:76.

codes/install/alps-install-agent.md already notes this in its text and open questions
("-DPython3_EXECUTABLE is silently ignored", around lines 424 and 633). This report confirms it.

To Reproduce

Setup: ALPS v3.0.0; a virtualenv that has numpy and scipy but is not activated; a different
python3 without numpy first on PATH. Only the flag differs between the three cases.

1. As documented — this fails:

   cmake -S alps-src -B build-A \
         -DBoost_SRC_DIR=/path/to/boost_1_87_0 \
         -DPython3_EXECUTABLE=/path/to/venv/bin/python \
         -DCMAKE_CXX_FLAGS="-DBOOST_NO_AUTO_PTR -DBOOST_FILESYSTEM_NO_CXX20_ATOMIC_REF"

   -- Found Python: .../Python-3.12.11/bin/python3.12 (found version "3.12.11") found components: Interpreter Development ...
   -- Python interpreter .../Python-3.12.11/bin/python3.12
   ModuleNotFoundError: No module named 'numpy'
   CMake Error at cmake/FindPythonMod.cmake:76 (MESSAGE):
     The script : import numpy
      did not run properly in the Python interpreter. Check your python installation.
   -- Configuring incomplete, errors occurred!
   

2. -DPython_EXECUTABLE=/path/to/venv/bin/python, everything else unchanged — this works:
   -- Found Python: /path/to/venv/bin/python ..., -- numpy version 2.5.3,
   -- Build files have been written to: ...

3. No flag, venv activated — this also works, because FindPython honours VIRTUAL_ENV.

Expected behavior

The flag the documentation recommends should select the interpreter. Any one of these would fix it:

• Document -DPython_EXECUTABLE=... instead of -DPython3_EXECUTABLE=... in install/source.md and no_root_guide.pdf.
• Make FindPythonMod.cmake accept both spellings:

  if(Python3_EXECUTABLE AND NOT Python_EXECUTABLE)
    set(Python_EXECUTABLE "${Python3_EXECUTABLE}")
  endif()

• Switch to find_package(Python3 ...) (and read the matching Python3_* variables) throughout.

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
• 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 (in a venv)
• Related module versions if applicable: numpy 2.5.3, scipy 1.18.1

Additional context

This affects users who follow the documentation when the default interpreter search picks the wrong
Python — on macOS, for example, the Build notes recommend the flag to avoid the Xcode Python. The
"just activate the venv first" path is not affected.

Open PR #107 (standalone nanobind wheel) deletes cmake/FindPythonMod.cmake. If it lands, the C++
side of this disappears and the install pages will need rewriting for the new Python flow anyway.
This report is about the released 3.0.0 behaviour and the website as published today.