Using the input generator

Objectives:

  • getting to know the basic steps to setup a FLEUR calculation
  • first steps using the input generator inpgen
  • having a first glance at the FLEUR input file inp.xml

Introduction

FLEUR as an FLAPW code has a lot of imput options/switches. In particular, since we do not use a pseudopotential, the full core/valence separation as well as many nummerical paramters for the atomic basis setup have to be specified. In most cases, one can rely on defaults and thus we provide a tool called inpgen to generate the input of FLEUR starting from a simplified input for inpgen.

!!! info To create the input for FLEUR: 1. create a simple input file for inpgen 2. run inpgen to create the FLEUR input 3. Inspect and adjust the input for FLEUR

For this section of the tutorial please change into the tutorial directory.

cd inpgen

Steps for inpgen

The input for the input generator

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 ``ìnp.xml``` 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 with diamond structure (fcc lattice + 2 atom basis) such a file might look like:

Si bulk
&lattice latsys='cF', a0=1.8897269, a=5.43 /
2
14 0.125 0.125 0.125
14 -0.125 -0.125 -0.125

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 multiplied to all lattice parameters. Note that the input generator expects the lattice specification in units of Bohr radii (). But since in this example a is provided in Angstrom, we need the factor a0 to convert it to units of . If no explicit a0 factor is specified in the inpgen input, it is set to .

At this point it can also be noted that the &lattice line starts with an & and ends with a /. In the file format for the inpgen input every line that starts with an & has to end with a /. This is a special Fortran format for certain types of inputs, so-called namelists.

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

Running inpgen

In this tutorial the just discussed inpgen input is already provided in the file inpSi.txt. We check its contents.

cat inpSi.txt

Invoking inpgenin a simple way with this input is done by using its -f command line option to specify the input file.

inpgen -f inpSi.txt

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

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.

Further files generated by inpgen are only temporarily used by the program itself. They are not important to the user and not needed to start fleur or reproduce inpgen behavior.

Visualize a crystal structure

Many different approaches exist to visualize a crystal structure. Especially since the xsf file format is very common, several software packages are capable of visualizing its contents.

For example the following codes might be used: - xcrysden: http://www.xcrysden.org/ - Vesta: https://jp-minerals.org/vesta/en/download.html - ASE: https://wiki.fysik.dtu.dk/ase/

As this tutorial has ASE installed we can use this as a very simple example (note that the next cell uses a python kernel, not the default bash):

from ase.io import read
from ase.visualize import view

atoms=read("inpgen/struct.xsf")
atoms=atoms.repeat((3,3,3)) # repeat the unit cell 3-fold in each direction
view(atoms, viewer="x3d")

Modifying input

By changing into the directory inpgen in the file view to the left of this notebook you can find the input and output files of the last example in which you run the input generator. You now can open an editor view of inpSi.txt to modify this file. As an alternative you could open a terminal and use the nano editor.

For example you could now modify the inpSi.txt by specifying a different exchange-correlation potential and overwritting the default of pbe for the Perdew-Burke-Ernzerhof GGA functional.

To do so, add a line with:

&exco xctyp='vwn' /

at the end of the file to replace the default xc functional by the Vosko-Wilk-Nusair LDA functional vwn.

inpgen -f inpSi.txt

Running the input generator again will lead to an error as inpgen by default will not overwrite existing inp.xml files. You can force the programm to overwrite the file or delete it beforehand.

inpgen -overwrite -f inpSi.txt

The FLEUR input file: inp.xml

Have a closer look at the inp.xml file and identify in it the different cutoff parameters and other numerical parameters used for the FLAPW method and for DFT in general. We will discuss the contents. The proper choice of the parameters is not a topic of this tutorial. Here we will mostly rely on the default values. If you perform real research with FLEUR make sure that you obtain results that are also converged with respect to the parameters.

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 cutoffs. - 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 selected k-point set - an atomSpecies section in which details about different atomic species used in the calculation are defined. In pseudopotential codes a lot of these settings are actually frozen into the generation process of the pseudopotentials. - 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.

Summary of inpgen

In this example we used the input generator inpgen to construct the input for FLEUR, starting from some basic minimal input. Please remember that: - inpgen provides you with defaults that should be appropriate, but in some cases you might have to adjust the default parameters. - In the documentation you will find examples to provide additional input to fine-tune your setup. - inpgen also is the k-point generator for FLEUR.