Installing FLEUR and a first calculation¶

In this tutorial we discuss the basic steps needed to obtain and install FLEUR. Not all aspects can be covered, but the basic steps are decribed. Additional details can be found in the FLEUR documentation: https://www.flapw.de/rel/documentation/installation/

Here we will discuss the three basic steps

  • obtaining the FLEUR source code
  • runing the configure script
  • compiling fleur & inpgen executables

and then perform a simple calculation for a Silicon crystal.

0. Preliminaries¶

The Jupyter notebooks which we will use in this tutorial consist of text fields like this and fields in which commands can be executed by pressing <Shift+Enter> in such a field. You can also open a terminal with the Launcher you should see in the top left tab. The commands can also be executed there and for some parts of the tutorial it is more convenient or even requied to work in the terminal. At several points in the tutorial text files have to be edited. You can either do this with a text-based editor (e.g. nanoor vi) in the terminal or with the editor that opens when you just click on the respective file and open it.

If you partially work with the terminal, you should be cautious to work in the correct directory, on which also the Jupyter notebooks are based. When working in auch a notebook the initial directory is the directory in which the notebook is located. For demonstration purposes we now store this directory in an environment variable MY_HOME and print that variable.

In [ ]:
export MY_HOME=$PWD ; echo $MY_HOME

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 this will ensure you work with a recent version of the code and it is rather simple as well.

You start by cloning the FLEUR repository by

In [ ]:
git -c http.sslVerify=false 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. The -c http.sslVerify=false part is only needed because it is not guaranteed that the docker image of this tutorial uses up-to-date certificates. Normally, one would not switch off this verification.

In [ ]:
cd fleur ; pwd

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

In [ ]:
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 build process for Fleur starts with a configuration step in which the available software infrastructure is detected and the flags for using the compiler and linking the available libraries are set. This is followed by the actual compilation of the code.

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. It is used to customize 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.

In [ ]:
./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.

In [ ]:
./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.

In [ ]:
FC=mpif90 ./configure.sh -includedir /usr/include/hdf5/serial -link "-L/usr/lib/x86_64-linux-gnu/ -lhdf5_serial_fortran -lhdf5_serial"

3. Compilation process¶

The actual compilation and linking is performed by using make. You can also perform this step 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.

In [ ]:
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: 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. You also need the python package pytest to run the tests. If this is not already available on your system you can install it with the respective pip command.

In [ ]:
export juDFT_MPI="mpirun -np 1"
In [ ]:
pip install pytest ; ./run_tests.sh

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.

5. Using the input generator¶

For this section of this tutorial please change into the Si subdirectory of this tutorial part.

In [ ]:
cd $MY_HOME/Si ; pwd

Performing Fleur calculations on some material always starts with the specification of a (prototype) unit cell. With this basic specification the Fleur input generator inpgen then generates a Fleur input file with a reasonable parametrization for the provided unit cell. In this section we discuss the basic usage of the input generator.

In general the input for the Fleur input generator consists of the definition of the unit cell shape as well as the definition of the atoms and atom positions in the cell. Optionally some additional parameters can be set to override or modify the automatic procedure used to determine the parametrization in the Fleur input file.

Using the input generator starts by writing a small text file containing the configuration of the unit cell. For a simple Si crystal such an input file (inpSi.txt) is already provided for this tutorial. We print it and discuss its contents.

In [ ]:
cat inpSi.txt

The first line of the file contains a comment. Here this comment is Si bulk. Next comes the definition of the crystal lattice. This is done in the &lattice line. It starts with the specification of the lattice system in latsys='cF'. cf specifies an fcc lattice. The line is completed with the setting of some parameters. In this case the parameter a is the lattice parameter of the fcc lattice and a0 is a factor that is multipied to all lattice parameters. Note that the input generator expects the lattice specification in units of Bohr radii ($a_0$). But since in this example a is provided in Angstrom we need the factor a0 to convert it to units of $a_0$.

In the next part of the inpgen input the atom positions are specified. This starts by providing the number of atoms in the next line. For this example system there are 2 atoms in the unit cell. The following lines define the atomic numbers and related atom positions in internal coordinates, i.e., in coordinates of the Bravais lattice vectors. 14 is the atomic number of Si and the two atoms are at $(1/8,1/8,1/8)$ and $(-1/8,-1/8,-1/8)$.

We generate the related Fleur input by invoking the input generator inpgen together with specifying the input file with the -f command line option. We also print out the contents of the directory after using inpgen with ls.

In [ ]:
inpgen -f inpSi.txt ; ls

With this command inpgen will generate a basic Fleur input file inp.xml. In addition a file sym.xml containing the symmetry operations and a file kpts.xml containing sets of k-points will be generated. These additional xml files are actually included into inp.xml by the parser and can also be included directly in the file. (See corresponding documention for inpgen).

Furthermore a file struct.xsf is generated. This is an XCrysden structure file that can be used to visualize the just defined unit cell, e.g., to check for complex structures whether the setup is as expected. The output of the input generator can be found in the file out. If there are problems in generating the Fleur input file, hints for the reason might be found in this file or directly on the terminal. The files default.econfig and profile.config contain some static parametrizations that are immediatly read by inpgen to construct parts of the actual Fleur input.

The FLEUR input file: inp.xml¶

Have a closer look at the inp.xml file.

In [ ]:
cat inp.xml

As you can see even for this very simple Si crystall the actual input for the fleur code is rather long. In general you will find the following sections:

  • a comment taken from inpgen
  • a section calculationSetup containing most switches controlling the setup. If you used other DFT codes before you will probably recognize settings like those of the used XC-Functional or certain cutoff parameters.
  • a cell section containing the actual unit cell, the symmetries of the system (included from sym.xml) and the information on the Brillouin zone integration with the k-point set.
  • an atomSpecies section in which details about different atomic species used in the calculation are defined.
  • an atomGoups section with the information about atomic positions and species. The atoms are grouped according to the symmetry of the system, which might lead to atoms being equivalent due to symmetry.
  • and finally an output section in which you can control some aspects of the calculation to produce special output.

The inpgen code generates defaults for most of the parameters and writes a standard inp.xml file. You should know that not all possible input is present in the file as Fleur supports additional optional parameters. Please have a look at the corresponding page of the documentation for reference.

6. A first Fleur calculation¶

Invoking fleur or fleur_MPI in a directory with Fleur input will automatically read in this input and run a calculation based on it. This starts by generating an initial guess for the gound-state density or reading in such a starting point from a cdn.hdf file present in the directory. The charge density will then be refined in an iterative process until a self-consistent fixpoint is reached, marking the actual ground-state density for the investigated structure and parametrization of the calculation. At most a number of iterations specified in the /calculationSetup/scfLoop/@itmax of the input file is performed. If this is not enough to reach the fixpoint Fleur stops anyway. In every iteration a distance is printed out to the terminal, indicating a measure for the self-consistency of the density.

In [ ]:
fleur_MPI

If everything worked as expected you can read a message Run finished successfully in the terminal output. We investigate the contents of the working directory after the Fleur calculation.

In [ ]:
ls

Fleur generates the files out and out.xml containing the text output for the calculation. Furthermore a file cdn.hdf is generated to store the charge densities from each iteration. The files FleurInputSchema.xsd and FleurOutputSchema.xsd are not importnt to the user. They are generated in every fleur run and only contain the formal specification of the Fleur input and output xml file format.

The contents in the out and out.xml files are extensive. We will get to know many parts of it during this course. You can already investigate the files in a text editor, but for now we focus on a few outputs from it. First of all, the charge density distances written out to the terminal during the Fleur run are also present in these output files:

In [ ]:
grep "distance" out.xml

You can use this output to check at a later stage whether a self-consistent density was reached in the calculation.

The most important output quantity of a DFT calculation is the total energy. Though this quantity is not measurable by experiments, total energy differences between different configurations of a unit cell, e.g. different test lattice constants or different magnetic settings, determine measureable quantities.

In [ ]:
grep "total energy" out

The different total energies stored in the output relate to each iteration of the Fleur run. Only the total energy relating to the self-consistent charge density has a well-defined meaning. If the distance indicates this, this is typically the last total energy stored in the output files.

This concludes the first tutorial. You can now use the code to perform calculations. In the following tutorials we will have a closer look at actual physical quantities and also investigate the input parameters in detail to understand how high-quality results are produced.

In [ ]: