First FLEUR run

Objectives

• see how to run FLEUR
• inspect the input/output files
• see the self-consistency process

Introduction

As a first example of a FLEUR run, we will calculate bulk Cu in fcc structure. In practice, DFT is implemented as an iterative algorithm that starts with a first guess the ground-state electron density and ends after several iterations with a self-consistent ground-state density. We will look at how this process is happening in FLEUR.

Steps needed for a simple FLEUR calculation: 1. create an inp.xml file using inpgen 2. run FLEUR to achieve self-consistency 3. Inspect the output

FLEUR steps

inpgen

As you already learned, we start with generating an inp.xml file by using the input generator. The corresponding basic input file is already provided in the CuBulk directory.

cd CuBulk

By now, you already know how to inspect and interpret the basic input for the input generator. In this case the example is particular simple and contains only a title, the specification of the lattice and a list of atoms with only a single element:

cat CuBulk.txt

Running inpgen we now create an input for FLEUR:

inpgen -f CuBulk.txt

Running FLEUR

One of the most basic usage info for FLEUR to learn is that the fleur or fleur_MPI executable will always read its input from an inp.xml file in the current directory.

The most basic call thus is simply

fleur_MPI

If all went well, the program should stop after some time with the message "all done". This is the message FLEUR will usually print out after a successful run. In Fleur by default up to 15 iterations of the self-consistency loop are performed, but the calculations already stops if a convergence criterion for the difference between input and output densities of an SCF iteration is underrun. By default this convergence criterion is set to $10^{-5} \text{me} / a_0^3$. The output of the fleur calculation is available in the out file and also in the out.xml file.

You can observe the development of the distance between the input and output densities of each iteration in the terminal output. Alternatively, this can also be obtained after the calculation finished by invoking 'grep dist out' to find the respective entries in the generated out file.

grep "distance of" out

The most important quantity that is directly obtainable from a DFT calculation is the total energy of the unit cell's ground state. Although this quantity cannot be measured, total energy differences can be used to calculate many measurable quantities. It is written out in each iteration of the self-consistency cycle but only meaningful for the self-consistent ground-state density. How large is the total energy for the Cu example ('grep "total energy" out' to obtain the respective values for all iterations)?

grep "total energy" out

FLEUR ouput

In general the most important output files of FLEUR are: - out: This is the most comprehensive output. It is meant to be human readable but sometimes contains a slightly overwhelming amount of information. - out.xml: This file is probably best suited for automatic processing. It contains a subset of the information in out. - cdn.hdf: This file contains the charge densities calculated. This is the key quantity you will need to run additional FLEUR calculations on top of your converged results or to restart a not-yet converged calculation. (if you use a version compiled without the HDF5 library you will find cdn* files instead.) - usage.json,juDFT_times.json: Files with technical info of the last run.

Inspect which files you now have in the directory.

ls

Starting FLEUR again

In some cases (not here) you will not achieve a converged calculation with a single call of FLEUR. In such a case you still get the "all done" message of FLEUR but the code did not terminate because your required density convergence criterion was reached, but simply because you reached the maximum number of iterations. You can then simply start FLEUR again.

fleur_MPI

In this case only a single iteration is performed as a self-consistent density was already present in the cdn.hdf file. The behaviour you have seen here can be controlled by the following section in the inp.xml file:

 <scfLoop itmax="15" minDistance=".00001000" maxIterBroyd="15" imix="Anderson" alpha=".05000000" precondParam="0.0" spinf="2.00000000"/>

Here you can see that FLEUR will: - perform at most 15 iterations per call (itmax="15"), - stop if the distance between input and output charge is lower than minDistance="0.00001", - use a maximal history length of maxIterBroyd="15 for the quasi-Newton scheme to accelerate convergence (after the here defined number of iterations the mixing history is reset), - use the Anderson mixer with an initial simple mixing step in which "5%" of the output density was used (alpha="0.05"), - and that FLEUR will use no preconditioner and no special mixing for spin-polarized systems.

The default of at most $15$ SCF iterations per FLEUR call was chosen because of several reasons. On the one side for many simple unit cells $15$ iterations are enough to reach the final result. On the other side slowly converging or nonconverging calculations can often be identified after 15 iterations. Causes for such calculations range from mistakes in the calculation setup like wrong units or a wrong structure in the inpgen input over poorly chosen parameters in the FLEUR input file to complicated physics in the unit cell, impeding a fast convergence.

There may also be other reasons to choose a rather small maximum number of iterations in a FLEUR run. For example, on a supercomputer calculations have a limited time available. For large unit cells this time may only be enough to perform a few iterations.

The default minDistance convergence criterion of $10^{-5} \text{me} / a_0^3$ for the density yields a high-enough precision for almost all applications. In some cases the user might even decide that an application does not require this degree of precision. One can always check in the out file, whether the quantity of interest still changes in relevant digits, even if the formal convergence criterion is not yet reached.

We construct for our simple Cu unit cell a situation in which multiple FLEUR runs are required to reach a self-consistent density. For this please change in an editor in inp.xml the itmax value to just 5 iterations. We next delete the charge density file, start fleur again, and check the contents of the directory.

rm cdn.hdf

fleur_MPI

ls

This FLEUR run only performed 5 iterations and it produced the additional file 'mixing_history'. This file contains the history of the quasi Newton mixing, with a maximal length that is defined by the maxIterBroyd parameter. It is written out whenever the last SCF iteration of the FLEUR run doesn't fulfill the convergence criterion and is read in by FLEUR when you start the program again. Please note that in the case of calculations employing multiple MPI processes of FLEUR, each of these processes writes out such a file, each with a number in the name indicating the process. In such a situation subsequent FLEUR runs need to employ the same parallelization, otherwise the input would be incompatible to the chosen parallelization. One can, of course, also delete these files to get more freedom on the choice of the parallelization.

Invoke FLEUR as often as it is needed to obtain a self-consistent density.

fleur_MPI

Using an AiiDA workflow

The procedure of achieving self-consistency by repeatedly calling FLEUR can also be achieved by using an AiiDA workflow. This can be done from the command line interface of aiida-fleur as:

aiida-fleur launch scf

By default the command line interface of aiida-fleur will only use the inp.xml file found in the current directory. It will not pick up the already converged density as this data is not available in the AiiDA repository.

In contrast to the simple call of FLEUR we performed above, this workflow might start FLEUR several times to achieve self-consistency. If set up for the use on a supercomputer, AiiDA can also manage the submission to the job scheduling system and the transmission of the data to and retrieval from the supercomputer. It is capable of dealing with certain types of technical errors and stores the complete process in a database to keep track of the provenance and ensure reproducibility of your results. If you want to publish a paper with results of your work, it is possible to systematically archive these database entries and create an additional data publication with it.

Idenitify in the output of the aiida-fleur call how often FLEUR was invoked and in how many iterations the convergence was obtained. You will notice that this output does not does not agree with the itmax setting to 5 as it was performed above. This is because aiida-fleur replaces some parameters in the inp.xml file related to the control of the SCF process by predefined but changable defaults.

The SCF workflow is the most basic aiida-fleur workflow. It is also used as a building block for more complex workflows that combine multiple FLEUR calculations.

The workflow will create some new output:

ls -l

The main output files you obtain from aiida-fleur are:

• scf.json: a summary of the scf-cycle and the main results. This file is also needed in further workflows if you need to start from a self-consistent density.
• cdn_last.hdf: density file of the last density
• out.xml: the usual output file of FLEUR
• distance_convergence.png/energ_convergence.png: plots of the convergence achieved.

The plots generated can give an impression of the convergence of the SCF cycle:

display < distance_convergence.png
display < energy_convergence.png

The scf workflow which we use here has some options for controlling its behaviour. These can be set by providing a python dictionary with some options. In order to do this using the command line interface, you can provide a json file with the required input. Most easily, you can create this file by using the special option template.json with the -wf option to let aiida-fleur provide a template file for the workflow parameters, containing the defaults.

aiida-fleur launch scf -wf template.json

cat wf_scf.json

As you can see here, the main options for achieving self-consistency alread discussed above are available as inputs to the workflow. In the case of the command-line interface, these are not so relevant as one could also set them in the inp.xml.

There is one exception, and this is the fleur_runmax option. Here, you can set the number of times FLEUR might be called by the workflow. As you can see, by default, we allow the workflow to run 30 iterations per FLEUR run and call FLEUR at most 4 times. Thus, a total maximum of 120 iterations will be performed.

Change in the wf_scf.json file the maximal number of iterations per FLEUR run to 5 again to simulate a similar situation as before.

To use the parameters in this json file you have to call the aiida-fleur command with the -wf wf_scf.json option. Again, as we do not provide a self-consistent density to the workflow, we will run a new self-conisteny process.

aiida-fleur launch scf -wf wf_scf.json

Identify in the aiida-fleur output the number of calls to FLEUR and how many iterations were needed to achieve a self-consistent density. You will find that the number of needed iterations is larger than before. This is the case because aiida-fleur deletes the 'mixing_history' files between the FLEUR calls.

For this case deleting the mixing history leads to a slower convergence. But it may also be that deleting the mixing history once in a while is beneficial to the convergence behavior. The default of the maxIterBroyd setting to 15 is typically a good choice.

Learn more

To learn more about the option for inpgen please visit:

• https://www.flapw.de/MaX-7.0/documentation/inpgen/

The inp.xml is documented here:

• https://www.flapw.de/MaX-7.0/documentation/fleurInputFile/