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
and then perform a simple calculation for a Silicon crystal.
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. nano
or 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.
export MY_HOME=$PWD ; echo $MY_HOME
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
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.
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
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.
There are a couple of external dependencies in the build process of Fleur.
Required are:
Optional:
Fleur can benefit significantly if the following further software components are available.
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:
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:
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.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"
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.
cd build ; make -j2
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.
export juDFT_MPI="mpirun -np 1"
pip install pytest ; ./run_tests.sh
There are two executables created in the build process:
inpgen
itself. The generated Fleur input file features unit-cell-adapted default parameters.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.
For this section of this tutorial please change into the Si
subdirectory of this tutorial part.
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.
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
.
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.
Have a closer look at the inp.xml
file.
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:
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.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.atomSpecies
section in which details about different atomic species used in the calculation are defined.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.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.
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.
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.
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:
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.
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.