Installation of Fleur

We are aware of the fact that installing Fleur can be a tricky task on many machines. While we tried to make the process as userfriendly as possible, there are still a couple of challenges you might encounter.

Quick guide

If you are using a standard toolchain and do not require too many functionalities that depend on external libraries(e.g Wannier90, libXC, ...) installation can be very simple:

1. Run the configuration script 'PATH_TO_SOURCE_CODE/configure.sh. You can do that in any directory in which the 'build' directory should be created. The script accepts some useful arguments, you can run the script with configure.sh -h to get a list of supported arguments. If all the environment variables for the compilers are set correctly see below or you use the interactive setup this should work.
2. The script creates the build directory and runs cmake. If all goes well (look at the output) you can then change to the build directory and run cd build; make.
3. If make does not report any error you are done!

Please be aware that there are different executables that could be be build:

• inpgen: The input generator used to construct the full input file for Fleur
• fleur: A serial version (i.e. no MPI distributed memory parallelism, multithreading might still be used)
• fleur_MPI: A parallel version of Fleur able to run on multiple nodes using MPI.

Usually only the serial or the MPI version will be build. You can run the MPI-version in serial while it is of course not possible to use the non-MPI version with MPI.

You might want to run the automatic tests.

Requirements

There are a couple of external dependencies in the build process of Fleur.

Required are:

• cmake: The build process uses cmake to configure FLEUR. You should have at least version 3.0. Some options might require newer versions. Cmake is available for free at www.cmake.org.
• Compilers: You will need a Fortran compiler and a corresponding C-compiler (i.e. the two have to be able to work together via the iso-c bindings of Fortran). Please check how to specify your compiler.
• BLAS/LAPACK: These standard linear algebra libraries are required. You should try your best not to use a reference implementation from Netlib but look for an optimized version for your system. In general compiler and/or hardware vendors provide optimized libraries such as the MKL (Intel) or ESSL (IBM). If you do not have access to those, check openBLAS.
• libxml2: This is a standard XML-library that is available on most systems. If it is missing on your computer you should really complain with your admin. Please note that you might need a development package of this library as well. To compile this library yourself, see xmlsoft.org.

Optional:

Fleur can benefit significantly if the following further software components are available. Please be aware that some of these can be difficult to use for FLEUR and see the Instructions for adjusting your configuration for details on how to provide input into the build process to use these libraries.

• MPI: Probably most important is the possibility to compile a version of Fleur running on multiple nodes using MPI. If you have a proper MPI installation on your system this should be straightforward to use.
• HDF5: Fleur can use the HDF5 library for input/output. This is useful in two situations. On the one hand you might want to use HDF5 for reading/writing your charge density files to avoid having a machine-dependent format that can prevent portability. Also the HDF5 IO gives you some more features here. On the other hand you have to use parallel-HDF5 if you do IO of the eigenvectors in an MPI parallel calculation. This is needed if you can not store the data in memory or want to postprocess the eigenvectors. Please be aware that you need the Fortran-90 interface of the HDF5 and that the HDF5 library should be compiled with the same compiler you use to compile Fleur!
• SCALAPACK/ELPA: If you use MPI and want to solve a single eigenvalue problem with more than a single MPI-Task, you need a library with a distributed memory eigensolver. Here you can use the SCALAPACK or the [[http://elpa.mpcdf.mpg.de/|ELPA]] library. Please note that the ELPA library changed its API several times, hence you might see problems in compiling with it.
• MAGMA: Fleur can also use the MAGMA library to run on GPUs. If you intend to use this feature, please get in contact with us.

You should also check the output of configure.sh -h for further dependencies and hints.

Configure

The configure.sh script found in the main Fleur source directory can (and should) be used to start the configuration of Fleur. It is called as configure.sh [-l LABEL ] [-d] [CONFIG].

The most used options are:

• -l LABEL: This specifies a label for the build. This is used to custimize the build-directory to build.LABEL and can be used to facilitate different builds from the same source.
• -d: This specifies a debugging build.
• -c Toolchain: This is a string to choose one of the preconfigured compiler toolchains. It can be useful if you find one which matches your setup.

The configure.sh script performs the following steps:

1. It creates a subdirectory called 'build' or 'build.LABEL'. If this directory is already present, the old directory will be overwritten.
2. It copies the CONFIG dependent configuration into this directory (this is actually done in the script 'cmake/machines.sh'). The special choice of "AUTO" for CONFIG will not provide any further configuration but relies completely on cmake. You can specify a config.cmake file in the working directory (from which you call configure.sh) to modify this AUTO mode. 3 Finally cmake is run in the build directory to determine your configuration.

If you specify -d as argument of configure.sh, the string "debug" will be added to LABEL and a debugging version of FLEUR will be build, i.e., the corresponding compiler switches will be set.

How to adjust the Configuration

While cmake and the configure.sh script can determine the correct compilation switches automatically in some cases (mostly those known to us), in many other instances fine-tuning is needed. In particular you might have to:

• provide hints on which compiler to use
• provide hints on how to use libraries.

Setting the compiler to use

One of the most important steps when compiling FLEUR is the choice of the compiler toolchain to use. This can be achieved in three ways with the configure.sh script:

• by defining the environment variables FC, CXX and CC to point to the Fortran, C++ and C compiler you can make sure that cmake uses the correct compilers, e.g., you might want to say export FC=mpif90.
• by providing the -c ### option with ### being the name of a predefined toolchain. Use the -h option to see a list of possible values. This option in general will not overwrite the environment variables. Use -dc to overwrite them.
• if neither a -c ### option nor the environment variables are set, the script will offer to search your system for compilers and let you choose interactively

Adding flags for the compiler

This should be done using the -flags option to configure.sh. So for example you might want to say configure.sh -flags "-r8 -nowarn".

In general for a compiler not known in cmake/compilerflags.cmake you need at least an option to specify the promotion of standard real variables to double precision (like -r8). But additional switches can/should be used.

Adding include directories

For libraries with a Fortran-90 interface, ELPA, HDF5, MAGMA, ... you probably will have to provide an include path. This can be achieved using the -includedir option. So you might want to say something like configure.sh -includedir SOMEPATH.

Adding linker flags

To add flags to the linker you can

• add a directory in which the linker looks for libraries with -libdir SOMEDIR
• add the corresponding link option(s) with, e.g., -link "-lxml2;-llapack;-lblas". Please note that the specification is different from the compiler switches as different switches are separated by ';'.

Building with LibXC

If the user decides to compile Fleur together with LibXC support, LibXC needs to be of version >=5.0.0. The easiest way to install Fleur with LibXC is to download Fleur with git:

git clone --branch release https://iffgit.fz-juelich.de/fleur/fleur.git

Then you can configure Fleur with

./configure.sh -libxc TRUE

which will download the correct libxc version, compile and link it. Notice this only works if you download Fleur using git.

Compiler specifics

Fleur is known to work with the following compilers:

INTEL:

The classic Intel Fortran compilers (ifort) is able to compile Fleur. Depending on the version you might experience the following problems:

• Versions < 16.0 will most probably not work correctly.
• Version 19.0 has issues with the debugging version of Fleur.

The llvm based newer compiler (ifx) in general shows more issues. In particular, some versions tend to optimize too agressively and produce incorrect result. Check carefully and run the tests GFortran:

GFortran is known to work with versions newer than 6.3.

NVHPC:

The NVHPC compilers also can compile FLEUR. Here you need at least version 21.3. Please be aware that this compiler is currently the only one supporting the OpenACC version of FLEUR for GPUs.

Tests

After the build was finished you might want to run the automatic test.

Just type ./run_tests.sh in the build directory for this purpose.

Please note:

• The tests run on the computer you just compiled on. Hence a cross-compiled executable will not run.
• You can use the environment variables juDFT_MPI to specify any additional command needed to start fleur_MPI, e.g., say export juDFT_MPI="mpirun -n 2" to run with two MPI tasks.
• You can use the environment variable juDFT to pass command line arguments to Fleur, e.g., say export juDFT='-mem'.
• To run a specific test only (or a range of tests) use the -k option the script (check ./run_tests.sh -h for details).
• The tests are run in the subdirectory Testing. You can check this directory to see why a specific test fails.
• The testing infrastructure is based on the Python package pytest. It requires this package and also the Python packages py and pytest-html.

Experimental features

The Fleur code is under rapid development. This implies that in each release there are features that are considered to be experimental. These features are either not well tested or their implementation is incomplete. The user will not find explicit documentation on these features in the Fleur user guide, but may become aware of them due to information from other sources. Especially the output of the configure.sh script may indicate certain features because it lists for several software libraries whether they have been detected and will be linked to Fleur.