H.2 All CMake variables

The following variables and options should be sufficient to build a well optimized FHI-aims binary. In order to see all the CMake cache variables that the user has control over, open a CMake GUI and toggle the advanced mode (many of those will have little or no effect).

Attention! Take special care when setting the Fortran compiler, the compiler flags, and any libraries, especially the linear algebra libraries. A nonoptimal choice here could easily cost you a significant amount of computer time.

• •

  CMAKE_Fortran_COMPILER — Name of the Fortran compiler executable. Use a full path if location not automatically detected.

• •

  CMAKE_Fortran_FLAGS — Compilation flags that control the optimization level and other features that the compiler will use.

• •

  CMAKE_EXE_LINKER_FLAGS — These flags will be used by the linker when creating an executable (i.e. equivalent to LDFLAGS)

• •

  LIB_PATHS — List of directories to search in when linking against external libraries (e.g., “/opt/intel/mkl/lib/intel64”)

• •

  LIBS — List of libraries to link against (e.g., “mkl_blacs_intelmpi_lp64 mkl_scalapack_lp64”)

• •

  INC_PATHS — Additional directories containing header files.

• •

  USE_MPI — Whether to use MPI parallelization when building FHI-aims. This should always be enabled except for rare debugging purposes. (Default: automatically determined by the compiler)

• •

  USE_SCALAPACK — Whether to use Scalapack’s parallel linear algebra subroutines and the basic linear algebra communications (BLACS) subroutines. It is recommended to always use this option. In particular, large production runs are not possible without it. The Scalapack libraries themselves should be set in LIB_PATHS and LIBS. (Default: automatically determined by LIBS)

• •

  ARCHITECTURE — Can have multiple meanings, including specific handling of a few compilers’ quirks (the PGI compiler, for example, needs a different call to erf()) and potentially optimization levels for CPU-specific extensions such as AVX. For many purposes, leaving this variable empty (using the so-called generic architecture) is good enough but do take the time to look into CPU-specific optimizations if you intend to run very large, demanding calculations.

• •

  BUILD_STATIC_LIBS — Whether to build FHI-aims as a static library instead of as an executable. This propagates to subprojects like ELSI unless overridden. (Default: OFF, i.e. an executable)

• •

  BUILD_SHARED_LIBS — Whether to build FHI-aims as a shared library instead of as an executable. This propagates to subprojects like ELSI unless overridden. (Default: OFF, i.e. an executable)

• •

  CMAKE_BUILD_TYPE — If set to “Release”, any flags defined in
  CMAKE_Fortran_FLAGS_RELEASE are appended to CMAKE_Fortran_FLAGS. If set to “Debug”, any flags defined in CMAKE_Fortran_FLAGS_DEBUG are appended instead.

• •

  CMAKE_C_COMPILER — C compiler.

• •

  CMAKE_C_FLAGS — C compiler flags.

• •

  USE_CXX_FILES — Whether source files written in C++ should be compiled into FHI-aims. (Default: ON)

• •

  CMAKE_CXX_COMPILER — C++ compiler.

• •

  CMAKE_CXX_FLAGS — C++ compiler flags.

• •

  CMAKE_ASM_COMPILER — Assembler. Usually not needed.

• •

  EXTERNAL_ELSI_PATH — Path to the external ELSI installation. If empty, internal ELSI is used instead. See also external ELSI notes below. FHI-aims requires at least ELSI v2.8.2.

• •

  ENABLE_PEXSI — Enable the PEXSI (pole expansion and selected inversion) density matrix solver. C and CXX compilers are mandatory for this purpose. PEXSI relies on the SuperLU_DIST and PT-SCOTCH libraries. By default, redistributed versions will be used. This option is ignored when an external ELSI installation is in use. (Default: OFF)

• •

  ENABLE_EIGENEXA — Enable the EigenExa eigensolver. Requires an externally compiled EigenExa library. This option is ignored when an external ELSI installation is in use. (Default: OFF)

• •

  ENABLE_MAGMA — Enable GPU-accelerated eigensolvers in the MAGMA library. Requires an externally compiled MAGMA library. This option is ignored when an external ELSI installation is in use. (Default: OFF)

• •

  ENABLE_SIPS — Enable the SLEPc-SIPs eigensolver. Requires externally compiled SLEPc and PETSc libraries. This option is ignored when an external ELSI installation is in use. (Default: OFF)

• •

  ADD_UNDERSCORE — In the redistributed PEXSI and SuperLU_DIST code (written in C and C++), there are calls to basic linear algebra routines such as dgemm. When ADD_UNDERSCORE is enabled, which is the default behavior, the C/C++ code will call dgemm_ instead of dgemm. Therefore, turn this option off if you know routine names in your linear algebra library are not suffixed with an underscore. This option takes no effect if PEXSI is not enabled. It is ignored when an external ELSI installation is in use. (Default: ON)

• •

  ELPA2_KERNEL — The ELPA eigensolver comes with a number of linear algebra “kernels” specifically optimized for some certain processor architectures. By default, FHI-aims uses a generic kernel which will compile with any Fortran compiler and will give reasonable speed. However, if one knows which specific computer chip one is using, it is possible to substitute this kernel with an architecture specific kernel and compile a faster version of ELPA. When using the internal version of ELSI/ELPA, available “kernels” other than the generic one may be selected by setting the ELPA2_KERNEL option to one of the following: “AVX” (Intel AVX), “AVX2” (Intel AVX2), and “AVX512” (Intel AVX512). This option is ignored when an external version of ELSI and/or ELPA is in use. (Default: a generic Fortran kernel will be used)

• •

  USE_EXTERNAL_ELPA — Use an externally compiled ELPA library. Relevant libraries and include paths must be present in LIBS, LIB_PATHS, and INC_PATHS. This option is ignored when an external ELSI installation is in use. Remember to build external ELPA on the same node used for computation. (Default: OFF)

• •

  USE_EXTERNAL_PEXSI — When PEXSI is enabled, use an externally compiled PEXSI library. Relevant libraries and include paths must be present in LIBS, LIB_PATHS, and INC_PATHS. This option takes no effect if PEXSI is not enabled. It is ignored when an external ELSI installation is in use. (Default: OFF)

• •

  USE_CUDA — Whether to use GPU acceleration in certain subroutines. See also appendix G. (Default: OFF)

  • –

    CMAKE_CUDA_COMPILER — CUDA compiler. Automatically detected with CMake version $\ge 3.8$.

  • –

    CMAKE_CUDA_FLAGS — Flags for the CUDA compiler. Example: “-O3 -DAdd_ -arch=sm_70 -lcublas”. With CMake version $\ge 3.18$, it is recommended to define CMAKE_CUDA_ARCHITECTURES, which automatically sets “-arch=” etc.

  • –

    ENABLE_CUDA_BY_DEFAULT — Automatically enable CUDA GPU acceleration at runtime (wherever possible). (Default: OFF)

• •

  USE_LIBXC — Whether additional subroutines for exchange correlation functionals, provided in the LibXC library, should be used. It is advised to always use this. Please respect the open-source license of this tool and cite the authors if you use it. (Default: ON)

• •

  LIBXC_VERSION — If given, this version of LibXC will be downloaded and compiled into FHI-aims. This variable is meant for developers for testing new features of LibXC, and must match exactly the LibXC version numbering (e.g. version.subversion.subsubversion). (Default: ““, i.e. the shipped version is used)

• •

  USE_EXTERNAL_LIBXC — Use an externally compiled LibXC library. Relevant libraries and include paths must be present in LIBS, LIB_PATHS, and INC_PATHS. (Default: OFF)

• •

  USE_CFFI — Whether to provide a Python 2 or 3 interface to FHI-aims. (Default: OFF)

• •

  ELPA_MT — Whether the hybrid MPI OpenMP version of ELPA is used. (Default: OFF)

• •

  USE_IPC — Whether to support inter-process communication. (Default: OFF)

• •

  USE_iPI — Whether to support path integral molecular dynamics through the i-PI python wrapper. (Default: ON)

• •

  USE_HDF5 — Whether to enable HDF5 support. If enabled, also set INC_PATHS, LIB_PATHS, and LIBS accordingly. (Default: OFF)

• •

  Fortran_MIN_FLAGS — Minimal flags to be used instead of the primary flags to speed up compilation. (Default set by the current Fortran flags and the build type)

• •

  KNOWN_COMPILER_BUGS — If set, reduced compiler flags are used instead of the primary flags. Options: “ifort-14.0.1-O3”, “ifort-17.0.0-O3”. (Default: none)

• •

  FFLAGS — Flags used for compiling .f files. (Default: same as for .f90 files)

• •

  SERIAL_Fortran_COMPILER — Deprecated. No effect.

• •

  USE_PLUMED — Whether to use the PLUMED library. (Default: OFF)

• •

  USE_MPI_MODULE — Use MPI module instead of “mpif.h” in Fortran code. (Default: OFF)

• •

  USE_TREXIO — Whether to compile with support for TREXIO export of the wave function. (Default: OFF)

• •

  HDF5_ROOT — HDF5 installation directory should TREXIO be compiled with HDF5 support

• •

  TREXIO_DIR — Path to installed TREXIO binaries, if linking against an already installed build is desired