Compile Options

Compile Options#

Overview#

Option

Type

Default

LIBRPA_USE_LIBRI

bool

ON

LIBRPA_USE_LIBRI_GPU

bool

OFF

LIBRPA_USE_CUDA

bool

OFF

LIBRPA_USE_HIP

bool

OFF

LIBRPA_USE_CMAKE_INC

bool

OFF

LIBRPA_USE_EXTERNAL_GREENX

bool

OFF

LIBRPA_ENABLE_FORTRAN_BIND

bool

OFF

LIBRPA_FORTRAN_DP

string or integer

c_double

LIBRPA_ENABLE_DRIVER

bool

ON

LIBRPA_MPI_THREAD_LEVEL

string

automatic

LIBRPA_VERBOSE_OUTPUT

bool

ON

LIBRPA_ENABLE_TEST

bool

ON

LIBRPA_ENABLE_CPP_TEST

bool

ON

LIBRPA_ENABLE_FORTRAN_TEST

bool

ON

LIBRI_INCLUDE_DIR

string

empty

LIBCOMM_INCLUDE_DIR

string

empty

CEREAL_INCLUDE_DIR

string

empty

LIBDDLA_PATH

string

empty

SCALAPACK_DIR

string

empty

LIBRPA_USE_EXTERNAL_ELPA

bool

OFF

EXTERNAL_ELPA_DIR

string

empty

LIBRPA_USE_BUNDLED_ELPA

bool

OFF

LIBRPA_BUNDLED_ELPA_VERSION

string

2026.02.001

LIBRPA_BUNDLED_ELPA_KERNEL

string

empty

LIBRPA_BUNDLED_ELPA_OPENMP

bool

OFF

LIBRPA_BUNDLED_ELPA_CONFIGURE_ARGS

string

empty

LIBRPA_BUNDLED_ELPA_LIBS

string

empty

These options can be parsed on the CMake command line, for example:

cmake -DLIBRPA_USE_LIBRI=ON

LIBRPA_USE_LIBRI#

When enabled, LibRPA is compiled with LibRI for RI tensor contractions.

The GW and EXX functionalities require LibRPA to be compiled with LibRI, i.e. -DLIBRPA_USE_LIBRI=ON. By contrast, the RPA correlation energy can also be computed without this option.

LIBRPA_USE_LIBRI_GPU#

Enables GPU-accelerated LibRI tensor contractions. This option is meaningful only when LIBRPA_USE_LIBRI and exactly one of LIBRPA_USE_CUDA or LIBRPA_USE_HIP are enabled.

When LIBRI_INCLUDE_DIR is empty, LibRPA uses the bundled GPU-enabled LibRI variant under thirdparty/LibRI_GPU. When an external LIBRI_INCLUDE_DIR is supplied, that LibRI installation must support the selected GPU backend.

Example:

cmake -B build \
      -DLIBRPA_USE_CUDA=ON \
      -DLIBRPA_USE_LIBRI_GPU=ON

LIBRPA_USE_CUDA#

Enables the NVIDIA CUDA backend. CUDA and HIP backends are mutually exclusive. The CUDA toolkit, NCCL, and LibDDLA must be discoverable by the build.

If CMAKE_CUDA_ARCHITECTURES is not specified, LibRPA uses 70;75;80. Set this standard CMake variable explicitly when building for other GPU architectures. An external LibDDLA installation can be selected with LIBDDLA_PATH; otherwise the bundled LibDDLA is built.

Example:

cmake -B build \
      -DLIBRPA_USE_CUDA=ON \
      -DCMAKE_CUDA_ARCHITECTURES=80

LIBRPA_USE_HIP#

Enables the AMD HIP/ROCm backend. HIP and CUDA backends are mutually exclusive. The HIP/ROCm libraries, RCCL, and LibDDLA must be discoverable by the build.

Set CMAKE_HIP_ARCHITECTURES for the target GPU when necessary. ROCM_PATH can be used when the ROCm installation cannot be inferred from the environment. An external LibDDLA installation can be selected with LIBDDLA_PATH; otherwise the bundled LibDDLA is built.

Example:

cmake -B build -DLIBRPA_USE_HIP=ON

LIBRPA_USE_EXTERNAL_ELPA#

When enabled, LibRPA is linked against an external ELPA installation.

ELPA support is intended for optimized linear algebra subroutines, such as ELPA-provided dense eigensolver routines, in ELPA-backed implementations. This option provides the build interface for those code paths.

Set EXTERNAL_ELPA_DIR to the ELPA installation prefix so CMake can find the ELPA headers, Fortran module directory, and library.

Example:

cmake -DLIBRPA_USE_EXTERNAL_ELPA=ON -DEXTERNAL_ELPA_DIR=/path/to/elpa

LIBRPA_USE_BUNDLED_ELPA#

When enabled, LibRPA builds and links against a bundled ELPA source release under thirdparty/ELPA.

This option is mutually exclusive with LIBRPA_USE_EXTERNAL_ELPA.

The bundled ELPA build is managed through CMake’s ExternalProject mechanism. After ELPA has been built in an existing build directory, changing compiler flags or CMAKE_BUILD_TYPE may not automatically reconfigure and rebuild ELPA. Use a fresh build directory, or clean the bundled ELPA sub-build, when those settings need to be applied to ELPA itself.

Example:

cmake -DLIBRPA_USE_BUNDLED_ELPA=ON

LIBRPA_BUNDLED_ELPA_VERSION#

Selects which bundled ELPA release is built when LIBRPA_USE_BUNDLED_ELPA is enabled.

Supported values are:

  • 2026.02.001

LIBRPA_BUNDLED_ELPA_KERNEL#

Selects an x86 SIMD kernel family for the bundled ELPA build.

By default, this option is empty. In that case, LibRPA disables ELPA’s x86-specific SIMD kernels and lets ELPA build portable generic kernels. Set this option on compatible x86 systems when an optimized kernel family is desired.

Supported values are:

  • empty

  • SSE

  • SSE_ASSEMBLY

  • AVX

  • AVX2

  • AVX512

Example:

cmake -DLIBRPA_USE_BUNDLED_ELPA=ON \
      -DLIBRPA_BUNDLED_ELPA_KERNEL=AVX512

LIBRPA_BUNDLED_ELPA_OPENMP#

Controls whether the bundled ELPA library is built with ELPA’s own OpenMP support.

The default is OFF. In that case, ELPA is built as an MPI-only static library, even if LibRPA itself is compiled with OpenMP. Set this option to ON only when the runtime process and thread layout is chosen with ELPA threading in mind. For example, with MPI ranks, OpenMP regions in LibRPA, threaded BLAS, and OpenMP-enabled ELPA all active at the same time, the total number of runnable threads can exceed the available cores unless OMP_NUM_THREADS, BLAS-specific thread controls, and the MPI rank count are coordinated.

When this option is ON, LibRPA also enables ELPA’s runtime MPI threading support checks and allows ELPA to limit its OpenMP thread count when the MPI library does not provide the thread level ELPA needs.

Example:

cmake -DLIBRPA_USE_BUNDLED_ELPA=ON \
      -DLIBRPA_BUNDLED_ELPA_OPENMP=ON

LIBRPA_BUNDLED_ELPA_CONFIGURE_ARGS#

Additional arguments passed to the bundled ELPA configure script.

Arguments passed through this option are appended after LibRPA’s defaults, including LIBRPA_BUNDLED_ELPA_KERNEL, so they can override the default kernel selection when a specific ELPA setup is needed.

Example:

cmake -DLIBRPA_USE_BUNDLED_ELPA=ON \
      -DLIBRPA_BUNDLED_ELPA_CONFIGURE_ARGS="--enable-store-build-config"

LIBRPA_BUNDLED_ELPA_LIBS#

Linker flags passed to the bundled ELPA configure script through its LIBS environment variable.

By default, LibRPA forwards the detected LAPACK and ScaLAPACK libraries to the bundled ELPA build. Set this option only when the autodetected flags are not suitable for a particular compiler or math library setup.

When static math libraries are used, ELPA’s libtool build may try to include those static archives inside libelpa.a. LibRPA removes such nested archive members after the bundled ELPA install step and links the math libraries separately through CMake.

Example:

cmake -DLIBRPA_USE_BUNDLED_ELPA=ON \
      -DLIBRPA_BUNDLED_ELPA_LIBS="-L/path/to/lib -lscalapack -llapack -lblas"

LIBRPA_USE_CMAKE_INC#

When enabled, the cmake.inc file is used to initialize compilers and other build options.

Deprecated. It is recommended to use standard CMake command-line options such as -C or -D to specify custom variables.

LIBRPA_USE_EXTERNAL_GREENX#

Controls whether LibRPA uses the bundled GreenX library or an external one.

The minimax grids used by LibRPA are provided through the GreenX library.

When this option is OFF (default), LibRPA builds and links against the bundled GreenX source distributed with LibRPA under thirdparty/greenX.

When this option is ON, LibRPA does not build the bundled GreenX copy. Instead, it expects an external GreenX library to be provided by the parent or higher-level CMake project. In particular, the CMake target LibGXMiniMax must already be defined and available for linking.

This option is mainly intended for developer workflows or project setups in which GreenX is managed outside LibRPA.

LIBRPA_ENABLE_FORTRAN_BIND#

When enabled, the Fortran bindings of LibRPA are built.

LIBRPA_FORTRAN_DP#

Specifies the Fortran kind used for double-precision real and complex data in the Fortran bindings.

The default value is c_double, which is suitable when interoperability with C is desired. This option may also be set to an integer kind value if needed by the calling code.

This option is meaningful only if LIBRPA_ENABLE_FORTRAN_BIND=ON.

LIBRPA_ENABLE_DRIVER#

When enabled, the LibRPA driver executable is built.

LIBRPA_MPI_THREAD_LEVEL#

Selects the MPI thread-support level requested by the LibRPA driver and C++ tests. Supported values are MPI_THREAD_SINGLE, MPI_THREAD_FUNNELED, MPI_THREAD_SERIALIZED, and MPI_THREAD_MULTIPLE.

When left empty, LibRPA selects the value from the enabled components: CPU ELPA builds use MPI_THREAD_MULTIPLE, builds with bundled LibComm use MPI_THREAD_FUNNELED, and other builds use MPI_THREAD_MULTIPLE. An explicit value takes precedence over this automatic selection:

cmake -B build -DLIBRPA_MPI_THREAD_LEVEL=MPI_THREAD_FUNNELED

The override must remain compatible with the selected dependencies and their threading requirements.

LIBRPA_VERBOSE_OUTPUT#

Compiles additional per-timer timestamp and memory diagnostics into LibRPA. The runtime output level still controls which diagnostic messages are emitted. Disable this option when those detailed diagnostics are not needed.

LIBRPA_ENABLE_TEST#

When enabled, the unit tests of LibRPA are built.

After LibRPA has been compiled successfully, the tests can be run from the build directory with:

ctest

or equivalently

make test

Note

At present, the unit tests do not cover the entire code base. Test coverage is still being expanded.

LIBRPA_ENABLE_CPP_TEST#

When enabled, the C++ unit tests are built.

This option is meaningful only if LIBRPA_ENABLE_TEST=ON.

LIBRPA_ENABLE_FORTRAN_TEST#

When enabled, the Fortran unit tests are built.

This option is meaningful only if both LIBRPA_ENABLE_TEST=ON and LIBRPA_ENABLE_FORTRAN_BIND=ON.

LIBRI_INCLUDE_DIR#

Specifies the path to the LibRI include directory.

If this variable is empty, the internal LibRI copy is used. Otherwise, CMake searches for RI/ri/RI_Tools.h under the specified directory. An error is raised if the file cannot be found.

Example:

cmake -DLIBRI_INCLUDE_DIR=/path/to/LibRI/include

LIBCOMM_INCLUDE_DIR#

Specifies the path to the LibComm include directory.

If this variable is empty, the internal LibComm copy is used. Otherwise, CMake searches for Comm/Comm_Tools.h under the specified directory. An error is raised if the file cannot be found.

Example:

cmake -DLIBCOMM_INCLUDE_DIR=/path/to/LibComm/include

CEREAL_INCLUDE_DIR#

Specifies the path to the cereal include directory.

If this variable is empty, the bundled cereal copy is used. Otherwise, CMake searches for cereal/cereal.hpp under the specified directory. An error is raised if the file cannot be found.

Example:

cmake -DCEREAL_INCLUDE_DIR=/path/to/cereal/include

LIBDDLA_PATH#

Specifies the installation prefix of an external LibDDLA library for CUDA or HIP builds. It can be set as either a CMake variable or an environment variable.

CMake expects include/ddla/ddla.h and a libddla shared library under lib/ or lib64/. If this variable is empty, LibRPA builds the bundled LibDDLA source.

Example:

cmake -B build \
      -DLIBRPA_USE_CUDA=ON \
      -DLIBDDLA_PATH=/path/to/libddla

SCALAPACK_DIR#

SCALAPACK_DIR specifies the installation path of ScaLAPACK and is used to locate the ScaLAPACK libraries when MKLROOT is not defined.

This variable can be provided in two ways:

  • as a CMake option:

    cmake -DSCALAPACK_DIR=/path/to/scalapack

  • or as an environment variable:

    export SCALAPACK_DIR=/path/to/scalapack
cmake

This option is intended for environments where ScaLAPACK is provided as a standalone installation rather than through Intel MKL.

EXTERNAL_ELPA_DIR#

EXTERNAL_ELPA_DIR specifies the installation prefix of an external ELPA library. It is used when LIBRPA_USE_EXTERNAL_ELPA is enabled.

CMake searches below this prefix for:

  • headers such as include/elpa-*/elpa/elpa.h

  • Fortran modules such as include/elpa-*/modules/elpa.mod

  • libraries such as lib/libelpa.so or lib/libelpa_openmp.so

This variable can be provided as a CMake option:

cmake -DLIBRPA_USE_EXTERNAL_ELPA=ON -DEXTERNAL_ELPA_DIR=/path/to/elpa

or as an environment variable:

export EXTERNAL_ELPA_DIR=/path/to/elpa
cmake -DLIBRPA_USE_EXTERNAL_ELPA=ON