ALPS Installation on Mac/Linux from Sources

Install Required Dependencies

ALPS relies on a handful of external libraries. Choose one MPI and one BLAS provider that fit your system:

⚠ Caution — virtual environments. Any environment (a Python virtual environment, micromamba, conda) changes which Python and libraries CMake finds. The cmake command in Download and Build then needs custom flags naming them — without those the build picks up the wrong interpreter and fails. See the no-root guide for the flags each kind of environment needs; a conda environment also has a known Boost/Python ABI problem — see Common Errors.

sudo apt update
sudo apt install build-essential cmake \
                   libhdf5-dev \
                   libopenblas-dev \
                   libopenmpi-dev openmpi-bin # or: libmpich-dev mpich

# install Python libs:
pip install numpy scipy # python libraries 
# or 
python3 -m pip install numpy scipy

sudo dnf install -y epel-release
sudo dnf install -y 'dnf-command(config-manager)'

sudo dnf config-manager --set-enabled crb        # Rocky/RHEL 9
# sudo dnf config-manager --set-enabled powertools # Rocky/RHEL 8

sudo dnf makecache

sudo dnf install -y \
    gcc gcc-c++ gcc-gfortran make cmake git \
    hdf5 hdf5-devel \
    openblas openblas-devel \
    openmpi openmpi-devel \
    environment-modules \
    python3.11 python3.11-devel python3.11-numpy python3.11-scipy

sudo dnf install -y \
    gcc-toolset-14 gcc-toolset-14-gcc-c++ gcc-toolset-14-gcc-gfortran \
    make cmake git \
    hdf5 hdf5-devel \
    openblas openblas-devel \
    openmpi openmpi-devel \
    environment-modules \
    python3.11 python3.11-devel python3.11-numpy python3.11-scipy

source /opt/rh/gcc-toolset-14/enable   # per shell; add to ~/.bashrc and any job script
gcc --version                          # 14.x

source /etc/profile.d/modules.sh
module load mpi/openmpi-x86_64         # per shell; add to ~/.bashrc and any job script
mpirun --version                       # Open MPI >= 4.1

brew update
brew install cmake hdf5 \
               openblas open-mpi # or: mpich

# install Python libs:
pip3 install numpy scipy

sudo port selfupdate
sudo port install cmake \
                   hdf5 \
                   OpenBLAS \
                   openmpi-clang20   # see note below about choosing a variant
sudo port select --set mpi openmpi-clang20-fortran

# install Python libs:
pip3 install numpy scipy

module avail
module load gcc/12 hdf5 openmpi openblas   # names vary by site

claude "Read alps-install-agent.md and no_root_guide.pdf and install ALPS following them."

Verify Dependencies

gcc -v              # must be >= 10.5.0
cmake --version     # must be >= 3.18
mpirun --version    # OpenMPI 4.0 or MPICH 4
python3 --version   # must be >= 3.9
python3 -c "import numpy, scipy; print('numpy', numpy.__version__, 'scipy', scipy.__version__)"

macOS — which Python will CMake use? CMake on macOS searches Apple’s framework paths before $PATH, so it may silently select the Xcode-bundled Python 3.9 even if you have a newer Python installed via Homebrew or MacPorts. During cmake configuration, look for a line like:

-- Found Python: /path/to/python (found version "X.Y.Z")

If the path or version is not what you expect, pin it explicitly by adding -DPython3_EXECUTABLE=/path/to/your/python3 to your cmake command. Typical paths are /opt/homebrew/bin/python3 (Homebrew) or /opt/local/bin/python3 (MacPorts). Make sure numpy and scipy are installed for whichever Python CMake will use.

Download and Build

We can now proceed to download and build the ALPS library. In the snippet below, replace </path/to/install/dir> with the directory where you want ALPS installed.

Before you run these commands, note two expected pauses:

1. cmake configuration (~1–3 min): CMake silently downloads Boost 1.87 (~130 MB) during configuration. The terminal will produce no output for a minute or two while the download completes — this is normal, do not interrupt it.
2. cmake --build (5–20 min): Compiling ALPS and Boost from source takes several minutes even with all CPU cores. The terminal will be busy printing compiler lines throughout — also normal.

git clone https://github.com/alpsim/ALPS alps-src
cmake -S alps-src -B alps-build                                       \
       -DCMAKE_INSTALL_PREFIX=</path/to/install/dir>                  \
       -DCMAKE_CXX_FLAGS="-DBOOST_NO_AUTO_PTR                         \
       -DBOOST_FILESYSTEM_NO_CXX20_ATOMIC_REF"
# ^ Boost (~130 MB) is downloaded here; no output for 1-3 min is normal
cmake --build alps-build -j$(nproc 2>/dev/null || sysctl -n hw.logicalcpu)
cmake --build alps-build -t test

-j controls parallel compilation. The expression above automatically uses all logical CPU cores on both Linux (nproc) and macOS (sysctl -n hw.logicalcpu). You can also set the number manually, e.g. -j 8 for 8 cores. On a machine with many cores but limited RAM, set it manually — the DMFT and maxent translation units each need roughly 1 GB under -O3, so a full-core build can be killed by the out-of-memory killer.

Offline or slow-connection build: By default CMake fetches Boost 1.87 at configure time. To avoid the download, extract the archive manually first and pass the path:

cmake -S alps-src -B alps-build                                       \
       -DCMAKE_INSTALL_PREFIX=</path/to/install/dir>                  \
       -DBoost_SRC_DIR=</path/to/boost_1_87_0>                        \
       -DCMAKE_CXX_FLAGS="-DBOOST_NO_AUTO_PTR                         \
       -DBOOST_FILESYSTEM_NO_CXX20_ATOMIC_REF"

Troubleshooting

Build notes

export SDKROOT=$(xcrun --show-sdk-path)

cmake -S alps-src -B alps-build ... -DPython3_EXECUTABLE=/opt/homebrew/bin/python3

cmake -S alps-src -B alps-build ... -DPython3_EXECUTABLE=/usr/local/bin/python3

cmake -S alps-src -B alps-build ... -DPython3_EXECUTABLE=/opt/local/bin/python3

If you have a non-standard installation location of the dependent packages installed in step 1, cmake will fail to find the package. ALPS uses the standard cmake mechanism (FindXXX.cmake) to find packages. The following pointers may help:

• For MPI: Follow the instructions on cmake with mpi
• For BLAS: Follow the instructions on cmake with BLAS
• For HDF5: Follow the instructions on cmake with HDF5

After successfully building the code, you will need to install it. The install location is specified with -DCMAKE_INSTALL_PREFIX=/path/to/install/directory as a cmake command during configuration. Alternatively, it can be changed by explicitly providing a new installation path to the --prefix parameter during the installation phase (see cmake manual).
To install the code run:

cmake --install alps-build

Set up your environment

The install directory is self-contained but your shell does not know about it yet. ALPS provides a setup script that adds the right directories to PATH, LD_LIBRARY_PATH, and PYTHONPATH. Source it once before using ALPS:

# bash / zsh:
source </path/to/install/dir>/bin/alpsvars.sh

# csh / tcsh:
source </path/to/install/dir>/bin/alpsvars.csh

To avoid running this command in every new terminal session, add the source line to your shell’s startup file (~/.bashrc, ~/.zshrc, or ~/.cshrc). Batch job scripts (Slurm/PBS) must source it too — a job that runs in a different environment than the build will fail at load time on missing shared libraries.

If import pyalps fails with ModuleNotFoundError, append the site-packages directory to PYTHONPATH as well. The generated alpsvars.sh sets PYTHONPATH=$ALPS_HOME/lib, but the package installs one level deeper:

export PYTHONPATH="</path/to/install/dir>/lib/python3.11/site-packages:$PYTHONPATH"

Adjust python3.11 to the Python version CMake built against.

Verify the installation by running one of the ALPS executables:

spinmc --help

If the command is found and prints a help message, ALPS is installed and your environment is set up correctly.