Electronic Structure Calculations

by Jürgen Spitaler & Lorenzo Pardini for exciting boron

Purpose: This tutorial gives a basic introduction into electronic-structure calculations. It explains how to set up and execute a simple exciting calculation, using elemental Ag as example. It is described how to prepare the input, how to run the calculation, and how to analyze the output. In addition, it is shown how basic properties like the density of states and the band structure can be calculated.

0. General preparation

Define relevant environment variables

Read the following paragraph before starting with the rest of this tutorial!

Before starting, be sure that the relevant shell variables are defined as specified in How to set environment variables for tutorials scripts.

From now on the symbol $ will indicate the shell prompt.

Units in exciting

By default, all quantities in the exciting code are given in atomic units: Energies in Hartree, lengths in Bohr, etc. (see Input Reference). In case other units are desirable, they can be converted using templates as a post-processing to exciting's standard output.

1. Electronic structure of silver: Groundstate calculation

The first step of any density-functional calculation is the determination of the groundstate total energy and electron density.

The starting point of a groundstate calculation is the crystal structure, only. At the beginning of a groundstate calculation, an initial electron density is generated, which is obtained from a superposition of atomic densities. Thus, this initial electron density lacks of the interaction between atoms and is normally a rather crude approximation of the density.

Then, the calculation iteratively goes through the following steps:

  1. Determine the potential from the electron density.
  2. Solve the Kohn-Sham (KS) equations to get the eigenfunctions and eigenvalues as well as the total energy.
  3. Calculate the electron density from the KS eigenfunctions.
  4. Create a new charge density, mixing the electron density from the current iteration with the ones of previous iteration (to ensure a good convergence behavior).
  5. Start again with (1).

Such a sequence of steps is usually called an iteration. The code will repeat such iterations, until the potential (or total energy, or charge density, …) obtained at the end of the last iteration is consistent with the one of the previous iteration. Thus, this kind of calculations is often called self-consistent field (SCF) calculation, and an iteration is often referred to as an SCF cycle.

To prepare your calculation, create a new, empty directory named Ag somewhere on your filesystem.

$ mkdir Ag
$ cd Ag

In this directory, save the following lines as input.xml.

<input>
 
   <title>Ag</title>
 
   <structure speciespath="$EXCITINGROOT/species">
      <crystal scale="7.7201">
         <basevect>0.5 0.5 0.0</basevect>
         <basevect>0.5 0.0 0.5</basevect>
         <basevect>0.0 0.5 0.5</basevect>
      </crystal>
      <species speciesfile="Ag.xml" chemicalSymbol="Ag">
         <atom coord="0.0  0.0  0.0" />
      </species>
   </structure>
 
   <groundstate 
      ngridk="8  8  8"
      outputlevel="normal">
   </groundstate>
 
</input>

N.B.: Do not forget to replace in the input.xml the string "$EXCITINGROOT" by the actual value of the environment variable $EXCITINGROOT using the command

$ SETUP-excitingroot.sh

If the visualization program XCrySDen is set up appropriately (find here how to do this: XCrySDen Setup for exciting) you can visualize the structure in the exciting input file executing

$ xcrysden --exciting input.xml &

Executing xcrysden this way will write some (non relevant) output on the screen. If you want to skip this output use instead

$ xcrysden --exciting input.xml >/dev/null 2>&1 &

After this, start the groundstate calculation by executing the following command in the Ag directory:

$ time excitingser

The time command here will simply write on the screen the elapsed time at the end of the execution. The calculation should roughly take less than 1 minute. During the calculation, output files are created, which contain all kind of information on your material system and on the calculation. Some of the output files are already created at the beginning of the calculation and will not be changed anymore during the run. Output files created by exciting in a standard groundstate calculation are described in the next section.

2. Output files in exciting.

filename description
INFO.OUT Master output file containing the essential information on the material system, parameters of the calculation, results (total energy, energy contributions, charge contributions, atomic forces, Fermi energy…) of each iteration, and more. The amount of information contained in this file can be triggered using the attribute outputlevel of the element groundstate.
  • Other relevant files which are updated or extended at each iteration contain information about the SCF calculation:
filename description
TOTENERGY.OUT Total energy in [Ha]; each line corresponds to one SCF iteration.
EFERMI.OUT Fermi energy in [Ha] at the last SCF iteration.
RMSDVEFF.OUT Root-mean-square deviation of the effective potential; each line corresponds to one SCF iteration, starting from the 2nd iteration and not considering the last SCF iteration.
DFSCFMAX.OUT Maximum variation of the non IBS part of the atomic forces; each line corresponds to one SCF iteration, starting from the 2nd iteration and not considering the last SCF iteration. Only written if forces are explicitly calculated (e.g., for atomic relaxation).
EIGVAL.OUT Eigenvalues (energies) of the valence bands, for each k-point and band.
EVALCORE.OUT Energy eigenvalues (energy levels) of the core states.
LINENGY.OUT Linearization energies as fixed in the species files (if searchE = "false" for the corresponding linearization energy in the species.xml file) or determined by exciting (if searchE = "true" for the corresponding linearization energy in the species.xml file).
  • Output files containing structural information, symmetries, etc.:
filename description
LATTICE.OUT Information on the lattice: Primitive lattice vectors, unit cell volume, reciprocal lattice vectors, etc.
SYMCRYS.OUT Information on the symmetry operations of the crystal; more symmetry information are found in the files SYMT2.OUT, SYMSITE.OUT, SYMMULT.OUT, SYMLAT.OUT, SYMINV.OUT, and SYMGENR.OUT.
KPOINTS.OUT List of k-points, their coordinates (in units of the reciprocal lattice vectors), weights, matrix size.
BONDLENGTH.OUT Interatomic distances; useful to check the correctness of an input file.
EQATOMS.OUT Information on equivalency of atoms due to the crystal symmetry.
  • Output files in XML format, useful for data storage, databases, etc.
filename description
atoms.xml The results of calculations performed for atoms in order to initialize the electron density.
info.xml The information contained in this file is similar to the one written in INFO.OUT, but displayed in the XML format.
geometry.xml Structural information on the system. This will often be identical to the element structure in your input file, but may differ for certain settings of the attributes in structure, e.g., if primcell = "true" or tshift = "true".
  • Some of the output files are not directly readable, because they are written as binary files. They are used by exciting for current storage of vectors and matrices. They are relevant when restarting or extending an existing calculation.
filename description
EVALFV.OUT First-variational eigenvalues.
EVALSV.OUT Second-variational eigenvalues.
EVECFV.OUT First-variational eigenvectors.
EVECSV.OUT Second-variational eigenvectors.
OCCSV.OUT Occupation of the second-variational states.
STATE.OUT Real-space distribution of the density and the potential.
Exercises

With the table above, find out the following properties of your calculation — to do so, find out first in which output files they are contained:

  • How many iterations did the calculation go through?
  • What is the total energy for the first iteration (which started from the superposition of atomic electron densities), and of the converged calculation (last iteration)?
  • What was the change in total energy between the
    1. first two iterations?
    2. last two iterations?
  • What is the Fermi energy of the system?
  • How many occupied valence bands are there in the system?
  • How much charge is there inside the muffin-tin sphere, and how much is found in the interstitial region?

3. Electronic structure of silver: Density of states

After you have completed the groundstate run and have obtained the corresponding total energy, you can go for more properties of the system. One of the most fundamental ones is the density of states (DOS). The DOS gives you information on the energy levels in your system, or — more precisely — about how many electronic states there are at any given energy.

To calculate it, you need to do the following simple modifications in input.xml (for more details, see Input Reference):

  1. add the attribute do = "skip" to the element groundstate;
  2. add the element properties after the groundstate element;
  3. insert the subelement dos into the element properties;
  4. add the attribute nsmdos = "1" to the element dos.

The corresponding part of the input.xml should now look like this:

...
   <groundstate
      do="skip"
      ngridk="8  8  8">
   </groundstate>
 
   <properties>
      <dos 
         nsmdos="1">
      </dos>
   </properties>
...

Then execute excitingser again on the command line:

$ time excitingser

This time, the program will produce the following files:

filename description
TDOS.OUT Total density of states.
dos.xml Total density of states stored in the XML format.

To visualize the DOS, execute

$ xsltproc $EXCITINGVISUAL/xmldos2grace.xsl dos.xml > Ag_dos.agr

This produces the file Ag_dos.agr for xmgrace. Open it with the command

$ xmgrace Ag_dos.agr &
This will open the plotting tool xmgrace and display the total density of states. Please note that in the DOS plots, energies are relative to the Fermi energy, i.e., EF=0 Ha. The result should look like this:
Ag_dos.png

You can use xmgrace to change the plot appearance in any way you want. For instance, zoom in to see details of the DOS, or produce a figure in any format you like (ps, jpg, png, etc.).

Exercises
  • Do the following modifications inside xmgrace (see Xmgrace: A Quickstart for help …):
    1. Change the x-range of the plot to [-0.4, 0.25].
    2. Autoscale the x axis.
    3. Add axes labels.
    4. Add a title.
    5. Increase the line-width of the DOS curve to 3.
    6. Change the colour of the DOS curve to red.
    7. Add a legend.
    8. Generate the file Ag_dos.png.
  • We were using the attributes do = "skip" for the element groundstate for generating the DOS after the groundstate SCF run. Find out why, by searching for the element groundstate in Input Reference and proceeding to its attribute do.

4. Electronic structure of silver: Band structure

Now, we are ready for a more detailed view on the electronic structure: The band structure. In addition to the energy of each state, the band structure shows the dependence of the energy eigenvalues on the coordinates in k-space.

To calculate the band structure of silver, insert the subelement bandstructure in the element properties with the following specifications:

...
   <properties>
 
      <bandstructure>
         <plot1d>
            <path steps="100">
               <point coord="0.750   0.500   0.250" label="W"    />
               <point coord="0.500   0.500   0.500" label="L"    />
               <point coord="0.000   0.000   0.000" label="GAMMA"/>
               <point coord="0.500   0.500   0.000" label="X"    />
               <point coord="0.750   0.500   0.250" label="W"    />
               <point coord="0.750   0.375   0.375" label="K"    />
            </path>
         </plot1d>
      </bandstructure>
 
   </properties>
...

As you may have realized, we have removed the subelement dos now. The new element bandstructure allows for the calculation of energy eigenvalues as a function of k. Inside this element, the subelement plot1d create a line plot where the abscissa is taken along a path consisting of straight lines joining the points defined by each element point. The coordinates of these points are given in terms of the basis vectors of the reciprocal lattice. The number of points along the full path, for which the ordinate(s) of the line plot (in this case the KS energies) are calculated, is established by the element path. Further details about the visualization of line plots can be found in How to visualize Kohn-Sham states.

Now execute excitingser again on the command line:

$ time excitingser

This makes the code produce the band structure, which is written to bandstructure.xml. To visualize the band structure, execute the following command:

$ xsltproc $EXCITINGVISUAL/xmlband2agr.xsl bandstructure.xml

Now you have produced the xmgrace file Ag_bandstructure.agr, which you can open, visualize and manipulate with xmgrace:

$ xmgrace Ag_bandstructure.agr &
The result should look like this:
Ag_bandstructure.png
Exercises
  • Use the Bilbao Crystallographic Server -> Space Groups Retrieval Tools -> KVEC to find out about the location of the special k-points within the Brillouin zone. The spacegroup of Ag is 225, Fm-3m. Select Choose to choose the corresponding spacegroup, and then click Brillouin zone to see the Brillouin zone with the special k-points.
  • The band structure of our plot is plotted along the path W -> L -> Γ (Gamma) -> X -> W -> K. In which parts of this path do you find strong or weak dispersion, respectively? Try to explain why by using the Brillouin zone plot from above.
  • In xmgrace: Use the autoscale button to see all bands. Look at the dispersion of the bands for low energies and high energies:
    1. What trend do you see relating the band width to the energy?
    2. How can you explain this trend (think about how the "dispersion" of an isolated atom would look like …)?
Unless otherwise stated, the content of this page is licensed under Creative Commons Attribution-ShareAlike 3.0 License