Installing FLEUR from source

Objectives

In this tutorial we discuss the basic steps needed to obtain and install FLEUR. Not all aspect can be covered, but the basic steps are described.

Introduction

While there are several ways to install FLEUR, we will discuss here the most basic procedure, which should be applicable to most systems. Additional details can be found in the FLEUR documentation: https://www.flapw.de/rel/documentation/installation/

In addition to the procedure outlines below, other installation paths might also be available to you. E.g. the installation using conda, the use of the spack package manager or even preinstalled FLEUR versions or container images. Again, please check the FLEUR documentation for more details.

```{note} Requirements to install FLEUR

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++ and C-compiler (i.e. these have to be able to work together via the iso-c bindings of Fortran).
  • 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.

  • 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! Note that the configure procedure of FLEUR will try to download a HDF5 version and compile it if no HDF5 is found.
  • SCALAPACK/ELPA/ELSI: 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 e.g. the SCALAPACK, the ELPA, or the ELSI library. 
## Steps:
Installing FLEUR from scratch will require three main steps, discussed below in detail:
- obtaining the FLEUR source code
- running the configure script
- compiling fleur & inpgen executables

## 1. Obtaining the source code

While the FLEUR download page at (https://www.flapw.de/rel/downloads/) offers several possible ways to obtain FLEUR, we will demonstrate here the use of a simple clone of the FLEUR git repository as it will ensure you work with a recent version and the cloning is rather simple as well. If you don't have git available on your computer, you can get it from [https://git-scm.com/](https://git-scm.com/).

You start by cloning the FLEUR repository by


```bash
git clone https://iffgit.fz-juelich.de/fleur/fleur.git

This will create a subdirectory called "fleur" with a copy of the git repository. Further commands will have to be issued in this subdirectory.

cd fleur

By default you will now work with the most recent developers version of the code. As a non-developer we would recommend to use the official releases of FLEUR that are available in the 'release' branch. Hence you should do

git checkout -t origin/release

Please refer to the gitlab page of FLEUR (https://iffgit.fz-juelich.de/fleur/fleur) for more details on available branches and tags.

2. Running the configure script

The configure.sh script found in the main Fleur source directory can (and should) be used to start the configuration of FLEUR.

It 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 uses cmake in the build directory to determine your configuration.

```{note} Debugging version 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.

```{hint} Options of the configure script
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. 

More options for the configure script can be seen by using the ```-h``` flag.

./configure.sh -h

Choosing your compiler toolchain

Choosing the compilers is probably the most important choice you have to make while compiling FLEUR. Here, we discuss three options: * Environment variables: You can specify your compilers using the corresponding environment variables 'FC', 'CC' and 'CXX' for the Fortran, C and C++ compiler. This is usually a very good option you should consider. * -c TOOLCHAIN: By specifying the name of a predefined toolchain using the -c option of the configure.sh script, you can add settings for additional compilers not specified by the environment variables. Check the output of configure.sh -h for possible values. * Interactive option: If you have not set all compilers (or you explicitly ask for this option), the script will search your system for compilers and offer you to choose interactively. While this can be useful for exploring your options, we generally do not recommend this as you might find it difficult to reproduce.

In the docker-image we are using for this tutorial, only a rather minimal software stack is included and the configure script can be executed with the -c auto option that lets cmake choose the compilers.

./configure.sh -c auto

If the configuration succeeded, the script will have created a directory called 'build' or 'build.

While this simple call to configure.sh might work, in many situations you have to provide more hints and details about the system. For example the MPI compiler wrappers are not used and HDF5 library will be compiled in this case. By additionally specifying a detailed linker string and an include directory we can use the HDF5 library available on the system and use MPI.

FC=mpif90 ./configure.sh -c auto -includedir /usr/include/hdf5/serial -link "-L/usr/lib/x86_64-linux-gnu/ -lhdf5_serial_fortran -lhdf5_serial"

3. Build process

The actual build is performed by using make. You can also perform the build using several processes for example by using make -j 2. This process will take some time and you might want to have a look at the more extensive documentation at https://www.flapw.de/rel/documentation/installation/ on how to customize your build.

cd build ; make -j2

4. Testing the executables

After compilation it might be a good idea to test your build. This can be achieved using the ./run_tests.sh command. These tests will take some time to run. You might want to continue and come back later to check the results.

Note: If the SCALAPACK library or an equivalent ibrary would not be linked to FLEUR, many of theses tests would fail, because they employ parallelization schemes that require this library. In such a case Fleur stops with some error message explaining the problem and you typically have to choose a different parallelization scheme. For such FLEUR executables you can either run the tests with the default parallelization to get a feeling on which tests fail in such a situation or define the environment variable juDFT_MPI="mpirun -np 1". In the latter case most tests will pass, besides a few tests on hybrid functionals where the parallelization cannot be changed. For our example this is not needed, because the SCALAPACK library was automatically downloaded, compiled, and linked to FLEUR by the configure.sh script.

Note: You also need the python packages pytest and pytest_html to run the tests. If this is not already available on your system you can install it with the respective pip command. At the moment, pytest versions newer than version 7.1.3 produce an error, so that we stick to version 7.1.3 in this example.

pip install pytest==7.1.3 ; pip install pytest_html ; ./run_tests.sh

Summary of the build process

There are two executables created in the build process sketched above:

  • inpgen: The input generator used to construct the full Fleur input file using only basic structural input about the unit cell for inpgen itself. The generated Fleur input file features unit-cell-adapted default parameters.
  • fleur: A serial version (i.e. no MPI distributed memory parallelism, multithreading can still be used) of FLEUR.

If you have an MPI installation and the ./configure.sh script found the corresponding setting, you will build a parallel version of FLEUR able to run on multiple nodes using MPI. In this case, the FLEUR executable will be named fleur_MPI. In general, this is the executable to aim for, since it can also be started in a serial way without the respective MPI command.

Within this tutorial inpgen and fleur_MPI have been preinstalled in the /bin directory, so they are ready to use, even without exercising this installation part o the tutorial. We also included some more features for these binaries. Some examples will rely on them.