Installation#
General requirements#
To build LibRPA, you need:
A C++17 compiler with a working
std::filesystemimplementation, and a Fortran compiler.MPI and OpenMP development libraries compatible with these compilers.
BLAS, LAPACK and ScaLAPACK libraries compatible with that MPI installation.
CMake 3.18 or newer, and a build tool such as
makeor Ninja.Git or
patch.
GPU builds also need the CUDA toolkit and NCCL, or ROCm and RCCL.
Third-party dependencies#
LibRPA uses the third-party libraries below:
Library |
Needed when |
|---|---|
GreenX |
Always |
LibRI, LibComm, cereal |
|
ELPA |
|
LibDDLA |
|
You do not have to install them beforehand: CMake downloads and prepares the ones that the selected options need. In case your machine does not have network acess or you would like to use your own copies of these libraries, please refer to Third-party library details.
Overview of build procedure#
Get the LibRPA source code.
Configure the build with CMake. CMake also prepares the third-party libraries in this step when needed.
Build LibRPA on the target platform.
Install LibRPA, if necessary.
Preparation: get the code#
You can download a source archive from the releases page and extract it on your machine. For the development version, clone the repository:
git clone https://github.com/AESM-Group/LibRPA
By default, CMake prepares the third-party libraries during configuration. It downloads the versions that LibRPA uses, checks the archives and applies LibRPA’s patches. For an offline machine, download the archives on a connected machine and transfer them before the build. See Offline installation for this procedure. To experiment with a third-party component, you can also supply the path to your own copy.
Build#
Once the compilers and libraries listed above are available in your environment, enter the LibRPA source directory. You can then configure, build and install LibRPA with:
cmake -B build -DCMAKE_INSTALL_PREFIX="$HOME/opt/librpa"
cmake --build build -j 2
# Install public APIs and libraries to $HOME/opt/librpa
cmake --build build --target install
CMake searches your environment for the required components.
You can select a compiler toolchain, such as Intel oneAPI or GCC with OpenBLAS, through CMake built-in options like -DCMAKE_CXX_COMPILER.
LibRPA also provides its own options to select the features to build.
For examples with different toolchains and platforms, please refer to Build Examples. For all build options, see Compile Options.
Build products#
The build produces the following files. Installation paths are relative to CMAKE_INSTALL_PREFIX ($HOME/opt/librpa in the example above).
Product |
Location in the build or source tree |
Installation directory |
|---|---|---|
Driver |
|
|
LibRPA library |
|
|
Public C and C++ headers |
|
|
Optional Fortran binding library and module |
|
Library: |
Fortran binding is built when -DLIBRPA_ENABLE_FORTRAN_BIND=ON.
When you change the compiler or MPI installation, make sure you use a new build directory to avoid potential incompatibility issue.
Run tests#
To run the tests, configure with -DLIBRPA_ENABLE_TEST=ON, build, and run ctest:
cmake -B build -DLIBRPA_ENABLE_TEST=ON -DENABLE_GREENX_CTEST=OFF
cmake --build build -j 2
cd build && ctest --output-on-failure
This runs the LibRPA unit tests. Some tests use several MPI processes (at most 4).
For regression tests and comparisons with reference results, see the regression test guide.
Third-party library details#
You can use the sources that LibRPA prepares, supply your own copies, or share dependencies with a parent CMake project.
Offline installation#
You can download the dependency archives on a connected machine and upload them to the machine where you will build LibRPA. Use the same LibRPA source version on both machines so that the archive names, hashes and patches match. From the LibRPA source directory on the connected machine, run:
cmake -DLIBRPA_THIRDPARTY_ARCHIVE_DIR="$HOME/Downloads" \
-P cmake/LibRPADownloadThirdparty.cmake
This command saves the archives in ~/Downloads and verifies their SHA-256 hashes. Extraction and patching take place on the build machine.
To download only the default CPU dependencies, use:
cmake -DLIBRPA_THIRDPARTY_ARCHIVE_DIR="$HOME/Downloads" \
'-DCOMPONENTS=LibRI;LibComm;cereal;greenX' \
-P cmake/LibRPADownloadThirdparty.cmake
You can add ELPA or LibDDLA to this list for builds that use them.
COMPONENTS selects which archives the script downloads and verifies. Use the component names with the capitalization shown above.
Upload the downloaded archives to the build machine, keeping the ARCHIVE filenames listed in thirdparty/manifest.cmake.
You can choose the archive location independently on each machine:
Archive location on the build machine |
Configuration |
|---|---|
|
Use the default archive directory |
|
Set |
For archives in LibRPA/thirdparty/downloads/, run from the LibRPA source directory:
cmake -B build -DLIBRPA_THIRDPARTY_DOWNLOAD=OFF
cmake --build build --parallel 2
For archives in the build machine’s ~/Downloads, use:
cmake -B build \
-DLIBRPA_THIRDPARTY_ARCHIVE_DIR="$HOME/Downloads" \
-DLIBRPA_THIRDPARTY_DOWNLOAD=OFF
cmake --build build --parallel 2
Both configurations use local archives with downloads disabled.
CMake checks the archives, extracts them and applies patches in the build machine’s LibRPA/thirdparty/src/ directory.
Git or patch is needed on that machine to apply the patches.
You can add your compiler, math-library and installation options to either configuration command.
Choosing dependency sources#
For compiled dependencies (greenX, ELPA and LibDDLA), the following options suit different build setups:
Managed sources are the recommended starting point for standalone builds. CMake downloads the selected versions, checks the archives and applies LibRPA’s patches. It builds these sources with the compilers and settings selected for LibRPA.
A parent project’s CMake target lets LibRPA share a dependency that the parent already builds. The parent supplies its build settings and link dependencies.
An external source path lets you develop or test your own copy of a dependency. LibRPA builds it with the same compilers as the rest of the project.
A prebuilt installation lets you reuse an installed library. Source builds are generally easier to match to LibRPA’s toolchain. For a prebuilt library, choose one with compatible compilers, flags, C++ ABI, math libraries and Fortran modules. CMake displays a reminder about these requirements.
To use managed ELPA sources, set LIBRPA_USE_ELPA=ON.
CMake gives supplied dependencies precedence over managed sources. It first looks for a parent target, then an explicit path. For a path, choose either a source directory or an installation prefix. The table below lists the targets and options for each dependency.
Dependency |
Parent target |
Source path |
Installation prefix |
|---|---|---|---|
greenX |
|
|
|
ELPA |
|
|
|
LibDDLA |
|
|
|
ELPA is optional and disabled by default. Set LIBRPA_USE_ELPA=ON to download and build the managed release. A parent ELPA::ELPA target, ELPA_SOURCE_DIR, or ELPA_PATH automatically enables ELPA. ELPA_ROOT also selects an installation when ELPA_PATH is absent. A parent target takes precedence over the supplied path.
For a source directory, CMake compares its contents with the version recorded in the manifest.
It uses a matching patched tree directly (pinned) or creates a patched copy of a matching upstream tree (overlay).
Other versions remain available with status unpinned. The copy preserves the original sources and symbolic links. LibDDLA uses the supplied source directly.
Local dependencies and parent projects#
For LibRI, LibComm and cereal, you can supply a parent target or an include directory. CMake uses managed headers for the remaining libraries. For example, to use local LibRI and LibComm headers:
cmake -B build \
-DLIBRI_INCLUDE_DIR=/path/to/LibRI/include \
-DLIBCOMM_INCLUDE_DIR=/path/to/LibComm/include
In this example, CMake prepares cereal automatically. A parent target takes precedence over an include path, and a nonempty CMake path option takes precedence over its environment variable. When configuration selects a path from the environment, it saves that path in the cache for later configurations. CMake checks explicit paths before it prepares the headers.
Header source |
Result |
|---|---|
Headers match the pinned, patched tree |
Used directly, status |
LibComm headers match the pinned pristine tree |
Copied and patched in managed storage, status |
Other header contents |
Used with a warning, status |
Existing parent target |
Headers supplied by the parent project, status |
LibRPA applies patches to a copy in managed storage, keeping your source directory unchanged.
cereal uses its upstream headers directly, with status pinned when they match the manifest.
During configuration, a compile check tests the three header libraries together. For other revisions, regression tests can help assess numerical compatibility.
Parent projects can provide LibRI::LibRI, LibComm::LibComm and cereal::cereal before adding LibRPA. See Parent-project integration for a complete example.
For GPU builds, you can supply LibDDLA::ddla, a source directory through LIBDDLA_SOURCE_DIR, or an installation through LIBDDLA_PATH.
CMake uses the parent target first, then the selected path, and otherwise prepares managed sources. LibDDLA source builds use a separate CMake build.
GreenX is always enabled. Supply a parent target, GREENX_SOURCE_DIR or GREENX_PATH to select your own copy. Otherwise, CMake prepares managed sources.
See Compile Options for defaults, accepted values and precedence rules.
How LibRPA builds and installs the libraries#
Library |
Default source |
Build and installation |
|---|---|---|
GreenX |
Managed source |
Built with LibRPA. The LibRPA install target also installs GreenX. |
LibRI, LibComm, cereal |
Managed headers |
Used during compilation and kept in the source cache. |
ELPA |
Managed source with |
Built in a separate sub-build. It stays in the build directory. |
LibDDLA |
Managed source |
Built in a separate sub-build and installed with LibRPA. |
Managed sources and patched copies are stored in thirdparty/src/<Name>-<hash12>/ in the LibRPA checkout.
Explicit component paths select your own sources through the options described above.
Build outputs stay in the build directory, so several builds of the same checkout can use the same prepared sources.
To build ELPA from downloaded sources or ELPA_SOURCE_DIR, you also need a C compiler, make, Bash and a C preprocessor. The LIBRPA_ELPA_* build options configure these source builds; installed libraries and parent targets keep their own build settings.
For managed ELPA, choose a LibRPA checkout and build directory without spaces. An explicit ELPA_SOURCE_DIR also needs a path without spaces.
For ELPA or LibDDLA, a fresh build directory is useful when you change compiler flags or backend options.
For a shared-library build, load the MPI, compiler and math-library runtimes in the environment where you run LibRPA.
A parent CMake project can add LibRPA with add_subdirectory and link to rpa_lib.
See Parent-project integration for the setup.
Troubleshooting#
Migration from cmake.inc#
LibRPA no longer loads cmake.inc. Setting LIBRPA_USE_CMAKE_INC=ON
stops configuration and prints migration instructions.
Move your compiler settings, flags, and library settings to an initial cache
file, using set(... CACHE <type> <description>) for each entry:
set(CMAKE_CXX_COMPILER "mpicxx" CACHE FILEPATH "C++ compiler")
set(CMAKE_Fortran_COMPILER "mpifort" CACHE FILEPATH "Fortran compiler")
set(CMAKE_BUILD_TYPE "Release" CACHE STRING "Build type")
set(SCALAPACK_DIR "/path/to/scalapack" CACHE PATH "ScaLAPACK installation")
Load this file with CMake’s -C option:
cmake -B build -C initial-cache.cmake
# Remove the old option when reusing an existing build directory.
cmake -B build -C initial-cache.cmake -U LIBRPA_USE_CMAKE_INC
The -U argument clears the old option from the cache. You can leave an
existing LIBRPA_USE_CMAKE_INC=OFF entry in place.
Use a new build directory if you change compilers.
Do not copy the math library line from cmake.inc without a check.
The old cmake.inc path linked its LAPACK_LIBRARIES value, often a full MKL
link line, and skipped the search for math, MPI and OpenMP libraries.
LibRPA now always does this search:
If
MKLROOTis set, LibRPA links Intel MKL from that installation. ALAPACK_LIBRARIESvalue does not replace it, so an MKL setup needs no library entry.If
MKLROOTis empty, LibRPA usesLAPACK_LIBRARIESfrom the cache, or detects LAPACK. It finds ScaLAPACK separately, withSCALAPACK_DIRas a hint. LibRPA does not readSCALAPACK_LIBRARIES.
For details, see MKLROOT, LAPACK_LIBRARIES and SCALAPACK_DIR.
A dependency is missing or a download fails#
The CMake message gives the component name, archive filename and upstream URL.
You can use these to obtain the archive and place it in LIBRPA_THIRDPARTY_ARCHIVE_DIR.
The offline preparation procedure also prepares the dependencies for transfer from another machine.
Downloads use CMake’s built-in libcurl.
If your network uses a proxy, set https_proxy or ALL_PROXY before preparation or configuration.
For a TLS certificate error, you can supply your network’s CA certificate bundle with -DCMAKE_TLS_CAINFO=/path/to/ca-bundle.crt.
This option also works with cmake -P.
A managed tree differs from the reference version#
You can edit sources under thirdparty/src/<Name>-<hash12>/ and use them in your next build.
During configuration, CMake compares them with the reference hash in the manifest. It reports differences with a warning and status unpinned, then continues with your sources.
For ELPA and LibDDLA, use a fresh build directory after source edits so their separate builds compile the changes.
The comparison covers include/ for header-only dependencies and the whole tree for compiled dependencies.
Added and removed files also affect this comparison, including .DS_Store files.
For modified LibComm headers, the automatic MPI thread level is MPI_THREAD_MULTIPLE. You can select a level explicitly with LIBRPA_MPI_THREAD_LEVEL.
To restore the reference sources, first save any edits you want to keep. Then remove the affected source directory and reconfigure. LibRPA prepares a new copy from the cached archive.
An archive fails verification#
LibRPA checks the SHA-256 of each archive before extraction. This check includes local archives and covers the compressed file. If a downloaded archive differs from the manifest, CMake reports the mismatch and removes the temporary download. For an archive already in the cache, the error message identifies the file to replace. Obtain the archive specified in the manifest, replace that file, and run configuration again. Normal configuration and the preparation script reuse prepared sources independently of their archives. The download script checks the archives so they are ready for transfer.
Removing old dependency trees#
When a component’s reference hash changes, CMake prepares it in a new thirdparty/src/<Name>-<hash12>/ directory and keeps the earlier version.
You can remove an older source directory once the builds of that checkout have finished using it.
Shared archives can be removed once the checkouts that use them have finished with those versions.
Save any local edits you want to keep before removing a source directory.
After an interrupted preparation, temporary directories can remain under thirdparty/src/.tmp-*, and temporary downloads can remain as *.tmp-* in the selected archive directory.
You can remove these once configuration and preparation processes have finished.
An explicit path or the LibRI compile probe fails#
Set each path to the include directory that contains the corresponding header:
Option |
Header relative to that directory |
|---|---|
|
|
|
|
|
|
To return to managed headers, clear both the environment variable and the CMake cache entry. For example:
unset LIBRI_INCLUDE_DIR
cmake -B build -U LIBRI_INCLUDE_DIR
You can clear the other include paths in the same way. In a parent project, CMake continues to use any supplied dependency targets.
If the header compile check fails, the CMake message lists the selected paths and their statuses.
The logs under the build directory’s CMakeFiles/ contain the compiler diagnostics.
std::filesystem link errors with Intel compilers#
Intel compilers on Linux use GCC’s C++ standard library. An old system libstdc++ can cause unresolved std::filesystem symbols. Load the compatible GCC runtime for your Intel installation before configuring a fresh build directory. LibRPA probes both direct linking and linking with stdc++fs.
ELPA <complex.h> macro conflict#
Older external ELPA headers can define the macro I through <complex.h>. This conflicts with C++ variable names in LibRPA. Use ELPA headers with a C++ guard that includes <complex> for C++ and <complex.h> for C. Reconfigure after replacing an affected external installation. The managed ELPA release already has that guard.