Bandstructure calculation

Objectives

  • Understand how to construct a k-point set for bandstructure calculations
  • Set input to calculate a bandstructure
  • Visualize the bandstructure

Introduction

To calculate a bandstructure, i.e. a visualization of the energy bands along a path of k-points, we have to start from a self-consistent density. To ease computational effort, we provide such a density.

In addition to a self-consistent density, we also need a different k-point set. In a self-consistency, we have to sample the full Brillouin zone, i.e. we have to use a set of k-points that cover the full reciprocal space, thus typically some kind of k-point grid is used. For the bandstructure, we are usually interested in special k-points and their connecting high-symmetry lines. Thus, we will employ the input generator to create such a path in k-space used in a bandstructure calculation.

Info

To obtain a high quality bandstructure the following steps are needed: 1. Obtain a self-consistent density for your system. Note: You will also need the Fermi energy determined in this step. In a HDF-enabled version of FLEUR this will be be used automatically. 2. Use a proper k-point path for your bandstructure. You can use inpgen to create one. 3. Run FLEUR with proper switches: band="T" 4. Visualize your bandstructure.

## FLEUR steps

We start in the Si directory in which we already have provided the results of a self-consistent calculation.


```sos
cd Si

ls

k-point sets for bandstructures.

For most unit cells the Fleur input generator by default constructs such a k-point path suitable for the calculation of a bandstructure and stores it in the kpts.xml file. To get a list of the names of the k-point sets stored in kpts.xml use the command grep name kpts.xml. The output should be similar to

            <kPointList name="default" count="60" nx="8" ny="8" nz="8" type="mesh">
            <kPointList name="path-2" count="240" type="path">

grep name kpts.xml

In these lines one does not only see the name of each k-point set but also the number of k-points in it (count) and its type. Here we have a k-point path named "path-2" consisting of 240 k-points. For the purpose of the tutorial we want to use a k-point path with less points. To add new k-point sets to the kpts.xml file the input generator has the command line option -kpt. We construct another k-point path along the same high-symmetry points as the default path with only 60 points by invoking inpgen with

inpgen -inp.xml -kpt band=60

The -inp.xml option hereby specifies that inpgen reads in input from an inp.xml file, in contrast to a conventional inpgen input. With these command line options, the input generator will provide the following terminal output on the stored k-point sets:

Stored k-point lists:

                NAME           TYPE      NKPT   COMMENT
 ================================================================================
             default           MESH        60   8 x 8 x 8
              path-2           PATH       240   X - K - g - L - W - X - g
              path-3           PATH        60   X - K - g - L - W - X - g
 ================================================================================

Obviously, we now have an additional k-point path "path-3" with 60 points along $\text{X} - \text{K} - \Gamma - \text{L} - \text{W} - \text{X} - \Gamma$.

!!! note 
One may also want to make other k-point sets available for other reasons, e.g., one wants to converge the density with respect to the size of the k-point set or one wants to use different high-symmetry points to define a k-point path. For a list of options available to create a user-specified k-point set [see the respective section within the inpgen reference](https://www.flapw.de/rel/documentation/inpgen/#k-point-generator).


### Modifications in `inp.xml`

To set up the band structure calculation, two modifications have to be made in the ```inp.xml``` file:

- The desired k-point path has to be selected. For this, we set ```/cell/bzIntegration/kPointListSelection/@listName``` to "path-3".
- The switch activating a band structure calculation (```/output/@band```) has to be set to "T".
- Not in this tutorial, but in general it may also be advisable to explicitly define the number of Kohn-Sham states to be calculated at each k-point. For this ```/calculationSetup/cutoffs/@numbands``` has to be set to a finite value. A value of $0$ tells Fleur to automatically determine a default value large enough to calculate the charge density, but for band structure calculations this may imply only very few unoccupied bands in the band structure.

```{attention}
Open an editor and modify the ```inp.xml``` file as sketched above.

cat inp.xml

Run FLEUR

After performing these changes, we can invoke Fleur to actually perform the band structure calculation.

fleur_MPI

Doing this will yield several new output files:

  • bands.X (X=1 for nonmagnetic calculations, otherwise also X=2 for the two spins): This is a list of the data points to be plotted in the band structure with x-coordinates in the first column and energy eigenvalues in eV in the second column.
  • band.gnu: This is a gnuplot script to plot the data in bands.X.
  • banddos.hdf (only if Fleur is compiled with HDF5 support): In this file also the whole band structure with all needed data is available in an HDF5 file format. Additionally several weights are stored here to indicate, for example, projections onto certain angular momenta within the MT spheres.

One also obtains an important terminal output:

 Fermi energy correction for insulators:
 Fermi energy in bands.* files has been set to the maximal
 value determined in the band structure calculation and
 the calculation of the underlying density, respectively.

This output tells the user what an energy eigenvalue of in the bands.X file means.

To use the gnuplot script we invoke gnuplot < band.gnu > bands.ps postscript file with the band structure. This can be then converted to png and displayed here.

#Use gnuplot to create the plot
gnuplot < band.gnu > bands.ps
#Create a png to display inline
gs -dSAFER -dBATCH -dQUIET -dNOPAUSE -dEPSCrop -r200 -sDEVICE=png256  -sOutputFile=bands.png -c "<</Orientation 3>> setpagedevice" -f bands.ps -c quit  
display <bands.png

AiiDA-FLEUR workflow

To perform the same simulation as above using AiiDA, we will now first perform the SCF calculation explicitly. In order to start from SCRATCH, we will perform the calculations in the separate sub-directory aiida.

Warning

If you use the wrong directory, i.e. an inp.xml file already prepared for the bandstructure as indicated above, your self-consistency will probably fail.

```sos
cd aiida; ls

aiida-fleur launch scf

Simple usage of band workflow

After running the SCF workflow we now can create a bandstructure by invoking the band workflow. To use the results of the SCF run, we have to pass the output file of the SCF workflow using the -P parameter.

aiida-fleur launch band -P scf.json

This workflow now created again some output files. Among them the bandstructure.png image of the bandstructure.

ls
display < bandstructure.png

Modifying the band workflow

The band workflow which we use here has some options controlling its behaviour. These can be set by providing a python dictionary with the 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 a template for this file by using the -wf option with the template.json argument.

aiida-fleur launch band -wf template.json

This creates a template-file called wf_band.json which you can now view and modify:

cat wf_band.json

For example you can set the option "kpath" to "seek" to use the Seek-path library (https://www.materialscloud.org/work/tools/seekpath) to create a path of k-points for your setup. Then you can simply run the workflow again. This time we use the -wf option to provide our settings to the workflow. We also adjust the inp.xml file such that more bands are calculated and displayed in the band structure. 

- Open an editor and modify the ```wf_band.json``` by setting the kpath to "seek".
- Edit the ```inp.xml``` file by setting the numbands parameter to 20.

aiida-fleur launch band -wf wf_band.json -P scf.json

display < bandstructure.png

Using the Masci-tools for more complex plotting

FLEUR generates not only a simple bandstructure but also includes some weights by default into the generated data. In some detail this can be investigated by looking at the structure of the banddos.hdf file.

h5ls -r banddos.hdf

Here you can see that: - there are several groups with metadata like atoms, cell, kpts ... - in the 'Local/BS' group you find the basic data for the bandstructure including some weights.

For example, we could create a bandstructure using the local p character of the first atom (we only have one atom here), we choose the data from the field "MT:1p". (Note that the "1" here corresponds to the atom index, we are not talking about 1p states which do not exist.)

masci-tools plot fleur-bands banddos.hdf --save -w "MT:1p"

display < bandstructure.png

In addition to generating simple png output, the masci-tools also support e.g. a bokeh backend that will generate a html page with an interactive plot.

masci-tools plot fleur-bands banddos.hdf --save -w "MT:1p" --backend=bokeh

%matplotlib
from IPython.display import HTML

HTML(filename="Si/aiida/bands_plot.html")

More advanced plotting using python scripts

Instead of using the command-line interface of the masci tools one can also use these in a python script. The following Python code section will import the relevant parts of the masci tools, then it will open and read the banddos.hdf file and finally it will create 3 plots to display bandstructure projections onto s-, p-, and d-characters:

#Import relevant parts of the masci_tools library
from masci_tools.io.parsers.hdf5 import HDF5Reader
from masci_tools.io.parsers.hdf5.recipes import FleurBands
from masci_tools.vis.fleur import plot_fleur_bands

#Read in data
with HDF5Reader('Si/aiida/banddos.hdf') as h5reader:
   data, attributes = h5reader.read(recipe=FleurBands)

#Plot the data with s projection on the first atom type
#Notice that the axis object of this plot is returned
#if you want to make any special additions
ax = plot_fleur_bands(data, attributes, weight='MT:1s')

# Plot the data with p and d projections
ax = plot_fleur_bands(data, attributes, weight='MT:1p')
ax = plot_fleur_bands(data, attributes, weight='MT:1d')

By inspecting the plots one can directly see the character of the states determining the band gap.

Learn more

To learn more about the possibilities for bandstructure calculations in FLEUR please visit: - https://www.flapw.de/MaX-7.0/documentation/bandstructure/ - https://www.flapw.de/MaX-7.0/documentation/bandUnfolding/ - https://www.flapw.de/MaX-7.0/documentation/banddosPlotting/