Installing FLEUR code

 

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 decribed. Additional details can be found in the FLEUR docu: https://www.flapw.de/MaX-5.0/documentation/installation/

Here we will discuss the three basic steps: - obtaining the FLEUR source code - runing the configure script - compiling fleur & inpgen executables

1. Obtaining the source code

While the FLEUR download page at (https://www.flapw.de/MaX-5.0/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 is rather simple as well.

You start by cloning the FLEUR repository by

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 command 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.

Additional 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).
• 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!
• 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 ELPA library.

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.

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.
• CONFIG: This is a string to choose one of the preconfigured configurations. It can be useful if you find one which matches your setup.

Check out! More options are available. Please check the output of configure.sh -h. You might find options to include dependencies into the build useful.

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.

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

./configure.sh -h

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 without further options.

./configure.sh

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

While this simple call to configure might work in many situations you have to provide more hints and details about the system. For example to change the compiler we might want to set the FC environment variable. By additionally specifying a detailed linker string and an include directory we can for example include the HDF5 library in the build process.

FC=mpif90 ./configure.sh -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/MaX-5.0/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 make test command. These tests will take some time to run. You might want to continue and come back later to check the results.

Note: In the current setup many tests will fail. This is because we compiled a parallelized Fleur version but did not link to SCALAPACK. The tests will by default be run with a parallelization that in some tests is inompatible to this setup. In such a case Fleur stops with some error message explaining the problem and you typically have to choose a different parallelization scheme. 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.

export juDFT_MPI="mpirun -np 1"

make test

Summary of the build process

There are two executables created in the build process:

• 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 we 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 you can directly use the versions. We also included some more features for these binaries so some example will rely on them.

Possible further aspects to learn

As mentioned, the installation can become pretty complex depending on you system and your need to specify details of libaries and other dependencies. For details please consult the FLEUR documentation and the corresponding discussions on the Forum.

https://www.flapw.de/MaX-5.1/future/F1/