General Installation on Linux machines

Prerequisites: HPC libraries and tools

Building Green requires a C++17 compiler, a working build toolchain, and the following third-party software:

• Third-Party Dependencies
  • Eigen3 >= 3.4.0
  • MPI
  • HDF5 >= 1.10.0
  • BLAS
  • CMake >= 3.18
  • CUDAToolkit >= 11.0 (optional, CUDA 13+ supported)

On a workstation, a package manager can install the compiler and libraries together. For example:

conda install -c conda-forge cxx-compiler cmake eigen hdf5 openmpi openblas gmp

or, on macOS with Homebrew:

brew install cmake eigen hdf5 open-mpi openblas gmp

or, on macOS with MacPorts:

sudo port install cmake eigen3 hdf5 openmpi OpenBLAS gmp

Activate the Conda environment, or ensure the Homebrew or MacPorts packages are on your search path, before configuring the build. HPC systems commonly provide the same compiler and libraries through environment modules instead.

These packages are external to Green. Their installation will depend on your computer. Important: ensure there is only one version of each dependency being used across all steps. Eigen3 is a C++ matrix library, you can find more information here. MPI is the Message Passing Interface, several standard implementations exist, including OpenMPI and MPICH. High performance computers will have proprietary MPI installations, and most clusters provide a version for all users. HDF5 is a library for binary data storage. More information on BLAS, the Basic Linear Algebra System, can be found on netlib.org. However, most computers provide highly optimized versions tuned for their respective hardware. Do NOT install the reference BLAS from netlib but instead have a look at a generic high-performance implementation from OpenBLAS and the hardware-specific vendor libraries (among many others: Apple, Intel MKL/OneAPI, AMD AOCL, IBM ESSL). Cmake is a build system that will find the locations of the above packages and generate compilation instructions in Makefiles. CUDA is an Nvidia GPU development environment.

Prerequisites: Python Libraries

Please make sure to have Python and the green-mbtools package available. green-mbtools declares PySCF, Numba, spglib, ASE, and its other Python dependencies, so pip installs them automatically:

python -m pip install green-mbtools

Numba depends on llvmlite. On platforms for which pip does not provide a compatible llvmlite wheel, pip attempts a lengthy source build that also requires a compatible LLVM installation. Check the installation output for this fallback and allow additional build time, or install a compatible LLVM toolchain before retrying. See the llvmlite installation guide for source-build requirements.

The minimal supported Python version is 3.8 (any minor version up to 3.12.x should work). For help with Python package installation, see the pip documentation.

Download and Build: CPU version

The following instructions will download and build the CPU-only version of the Many-Body Perturbation theory solver (replace /path/to/install/directory with the directory where you’d like to install the code).

We recommend building a specific released version. Check the releases page for the newest tags — as of this writing the latest stable release is v0.3.2 and the latest pre-release is v1.0.0a1. Clone the tag you want, for example:

# Latest stable release (v0.3.2)
git clone --branch v0.3.2 --depth 1 https://github.com/Green-Phys/green-mbpt

# Latest pre-release (v1.0.0a1)
git clone --branch v1.0.0a1 --depth 1 https://github.com/Green-Phys/green-mbpt

To track the development tip instead, omit --branch:

git clone https://github.com/Green-Phys/green-mbpt

The first CMake configure requires network access. Green uses CMake FetchContent to download its green-* component libraries and, when tests are enabled, Catch2. On an offline HPC system, configure the project only after arranging access to those sources or pre-populating CMake’s dependency cache.

Then configure and build:

cmake -S green-mbpt -B green-mbpt-build               \
     -DCMAKE_INSTALL_PREFIX=/path/to/install/directory  \
     -DCMAKE_BUILD_TYPE=Release
cmake --build green-mbpt-build -j 4
cmake --build green-mbpt-build -t test

A successful test run ends with CTest reporting 100% tests passed, 0 tests failed. The number of discovered tests and the runtime vary with the Green release, enabled options, machine, and build parallelism. On macOS, the linker may also report harmless duplicate -rpath ... ignored warnings; these do not indicate a failed build when linking completes and the tests pass.

If dependencies are installed under a non-default prefix, add that prefix to the configure command. For an active Conda environment, for example:

cmake -S green-mbpt -B green-mbpt-build               \
     -DCMAKE_INSTALL_PREFIX=/path/to/install/directory  \
     -DCMAKE_PREFIX_PATH="$CONDA_PREFIX"                 \
     -DCMAKE_BUILD_TYPE=Release

CMAKE_PREFIX_PATH gives CMake one common search root for packages including MPI, HDF5, BLAS, and Eigen. Separate multiple prefixes with semicolons. For a package-specific override, the following pointers may help:

• For Eigen: specify -DEigen3_DIR=/path/to/lib/cmake/eigen3, pointing to the directory that contains Eigen3Config.cmake
• 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 or 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 green-mbpt-build

Your install directory will be created. A successful installation places the following executables under its bin directory:

• mbpt.exe
• embedding.exe
• int-transform.exe

Download and Build: Nvidia GPU kernels

GPU kernels for the many-body perturbation framework use extensions from a custom repository. You enable the GPU kernels by setting the following CMake parameter:

• CUSTOM_KERNELS="https://github.com/Green-Phys/green-gpu"

By default, code is generated for sm_80, sm_86, and sm_90 (Ampere and Hopper). To target a specific GPU, add -DGPU_ARCHS="<cc>", where <cc> is your GPU’s compute capability with the dot removed (e.g. 89 for compute capability 8.9). You can find your GPU’s compute capability with:

nvidia-smi --query-gpu=compute_cap --format=csv,noheader

The following instructions will download and build the Many-Body Perturbation theory solver with additional GPU kernels (replace /path/to/install/directory with the directory where you’d like to install the code). Use the same --branch approach described above to target a specific release — for example the latest stable v0.3.2 or the latest pre-release v1.0.0a1. Then configure and build:

git clone --branch v0.3.2 --depth 1 https://github.com/Green-Phys/green-mbpt
cmake -S green-mbpt -B green-mbpt-build                         \
   -DCMAKE_INSTALL_PREFIX=/path/to/install/directory              \
   -DCMAKE_BUILD_TYPE=Release                                     \
   -DCUSTOM_KERNELS="https://github.com/Green-Phys/green-gpu"
cmake --build green-mbpt-build -j 4
cmake --build green-mbpt-build -t test
cmake --install green-mbpt-build