Install Required Dependencies

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

$ 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

$ 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

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.

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)

# Homebrew (Apple Silicon):
$ cmake -S alps-src -B alps-build ... -DPython3_EXECUTABLE=/opt/homebrew/bin/python3
Homebrew (Intel):
$ cmake -S alps-src -B alps-build … -DPython3_EXECUTABLE=/usr/local/bin/python3
MacPorts:
$ cmake -S alps-src -B alps-build … -DPython3_EXECUTABLE=/opt/local/bin/python3

<div class="hextra-copy-icon hx:group-[.copied]/copybtn:hidden hx:pointer-events-none hx:h-4 hx:w-4"></div>

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).

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.