Simple Convergence Tests

by Pablo Garcia Risueno & Pasquale Pavone for exciting boron

Purpose: In this tutorial, you will investigate how the choice of computational parameters can affect the result of an exciting calculation. The procedure which is used in this case is often called convergence study and allows to obtain the best value of such parameters. Explicit examples are presented for the convergence of the total energy of silver and diamond with respect to the choice for the k-points sampling (related to the parameter ngridk) and the dimension of the basis set (related to the parameter rgkmax).

---

0. Define relevant environment variables

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

Before starting, be sure that relevant environment variables are already defined as specified in How to set environment variables for tutorials scripts. Here is a list of the scripts which are relevant for this tutorial with a short description.

• SETUP-convergence-test.py: Python script for generating input files with different values of the main computational parameters.
• EXECUTE-convergence-test.sh: (Bash) shell script for running a series of exciting calculations.
• PLOT-convergence.py: Python script for visualization of convergence results.
• PLOT-3d-convergence.gnu: Gnuplot script for visualization of convergence results.

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

---

1. Convergence of total-energy calculations

A groundstate calculation using a DFT code like exciting fundamentally depends on 2 parameters

• the mesh of k-points (groundstate attribute: ngridk);
• the size of the basis set for expanding the wave function (groundstate attribute: rgkmax).

In order to be able to rely on your calculation, you need to understand what these two parameters mean and what is the effect of a change of their values on the physical quantities which are relevant for you. In this tutorial, we focus on the effect of such changes on the total energy of a crystal only for pedagogical reasons. In the general case, this kind of analysis must be made for all the properties of interest (e.g., lattice parameters, bulk modulus, equation of state, bandgap energies, etc.).

For more informations on these parameters, please expand the links below.

[Read more on the mesh of k-points]

The mesh of k-points

From basic considerations of solid-state theory, it can be shown that the Schrödinger (or, in our case, Kohn-Sham) equation for a periodic system has a bunch of solutions, where each solution is characterized by a vector k in reciprocal space. This k-vector is essentially related to the periodicity of the corresponding solution of the Schrödinger equation: Roughly speaking, the solution will have the same value at coordinates in real space that, along the direction of k, have a distance of 2π/|k|.

Many properties of a solid, including the total energy, are represented as integrals, performed over all possible k-vectors. Obviously, the direct calculation of these integrals is very demanding (one should calculate the solution of the Schrödinger equation for a huge number of k-points). Therefore, the integrals are approximated by sums performed on a set of k-points distributed on a finite grid. The spacing of the points on the grid is a measure of the accuracy of the calculation of the integrals which also depends on how fast the integrand (the solution of the Schrödinger equation) varies by changing k. The challenge is to find a good number of k-points: Large enough to capture the physical properties of your system well, but small enough to keep calculations as fast as possible.

Some qualitative considerations.

• The larger the unit cell, the smaller is the required k-point mesh.
• Systems with longer-range interactions need larger k-point meshes.
• In metals you need a large number of k-points, since the conduction electrons are delocalized over the whole system, i.e. the interactions are very long-ranged. Moreover, for a good description of the system it is important to know exactly where the conduction bands cross the Fermi level, which also requires a dense k mesh.
• In contrast, semiconductors and insulators usually have much more localized electronic states, and a gap between valence and conduction bands. Thus, the number of k-points required for a good calculation is much smaller.

In exciting the parameter which is associated to the choiche of the mesh of k-points is ngridk, see Input Reference for further details.

[Read more on the basis-set size]

The basis-set size

Most of the DFT codes solve the Kohn-Sham equation in reciprocal space, expanding the wavefunctions in terms of suitable periodic basis functions. In our case, the basis functions are the linearized augmented plane waves (LAPW). The larger the size of the basis set, the more accurate is the calculation. The corresponding groundstate attribute in the exciting code is rgkmax (see Input Reference). The default value of rgkmax is 7.0. In some cases, (e.g., for a good description of forces), larger values (8.0 — 9.0) may be necessary to get reliable results. In some other cases, (e.g., for describing very light materials like hydrogen), already smaller values of rgkmax may be sufficient.

[Read more on the scaling of the calculation time]

Scaling of the calculation time…

The calculation time scales

• linearly with respect to the number of k-points;
• as rgkmax to the power of 9.

---

2. Running tests: Silver

In this first example, we investigate the dependence of the total energy on the parameters ngridk and rgkmax for the Ag crystal. To this end, we start by creating a working directory Ag-convergence-test and we move inside it.

$ mkdir Ag-convergence-test
$ cd Ag-convergence-test

Here, we create an exciting (xml) input file called input.xml which should appear as the one below.

<input>
 
   <title>Ag: Convergence test</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">
         <atom coord="0.0  0.0  0.0" />
      </species>
 
   </structure>
 
   <groundstate 
      ngridk="4 4 4" 
      rgkmax="5.0">
   </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

Now you can run exciting by simply typing

$ time excitingser

Using the optional time command, the elapsed time will be displayed on the screen at the end of the execution. After a few seconds, the calculation will be completed. Indeed, the calculation you have just performed uses very rough values for the parameters ngridk and rgkmax. The corresponding total energy (in Hartree) can be found as the last line of the file TOTENERGY.OUT. You can save the value of parameters and total energy at a text file called convergence-test as indicated below (here, only the first value of the parameter ngridk is considered).

4  5.0  -5314.29682386   # ngridk rgkmax  total-energy

In order to improve the calculation, we should change the value of ngridk and rgkmax and repeat the calculation in a systematic way. To this end, we remove all output files from the previous calculation (be always careful when using the command rm).

$ rm *OUT*

Then, we change in the input file the values of one (or both) parameter, e.g.

...
   <groundstate 
      ngridk="6 6 6" 
      rgkmax="5.0">
   </groundstate>
...

and perform a new calculations using the command excitingser.

$ time excitingser

Also this time we extract the value of the calculated total energy and add it to the file convergence-test, which now should appear as

4  5.0  -5314.29682386   # ngridk rgkmax  total-energy
6  5.0  -5314.31785853

Remove once more all output files from the last calculation.

$ rm *OUT*

Then, the same procedure can be repeated for other values of the parameters.

Using scripts for checking convergence

The procedure described above can be easily performed with the help of some useful script. For instance, the script SETUP-convergence-test.py can be used for preparing inputs for a sequence of calculations. You can execute the script, in the directory where you are already, in the following way.

$ SETUP-convergence-test.py 4 20 5 5

where the first 2 arguments are the minimum and maximum values (with a step of 2) for ngridk, respectively. The last 2 (integer!) entries are the minimum and maximum values (with a step of 1) or rgkmax, respectively. This means that, in this example, we are considering the convergence of the total energy as a function of ngridk at the constant value of rgkmax = "5".

The complete run is performed by the script EXECUTE-convergence-test.sh.

$ EXECUTE-convergence-test.sh

The result of all calculations are now stored in a new directory called workdir. Notice that the script SETUP-convergence-test.py always generates a directory called workdir containing the results of the calculation. Very important: The directory workdir will be overwritten each time you execute the script SETUP-convergence-test.py. Therefore, before performing a new run, please rename an already exsisting workdir directory to a different name. Keeping this in mind, you can now move inside the directory workdir for analysing the result.

$ cd workdir

The result of this sequence of calculation is summarized automatically in the file convergence-test, which now should appear as

   4    5.00      -5314.29682386
   6    5.00      -5314.31785853
   8    5.00      -5314.32020985
  10    5.00      -5314.31952010
  12    5.00      -5314.31699599
  14    5.00      -5314.31900073
  16    5.00      -5314.31931613
  18    5.00      -5314.31818501
  20    5.00      -5314.31905365

To visualize these results you can use the command (the line entry k indicates the running on different values of ngridk)

$ PLOT-convergence.py k

This command generate a plot which can be visualized both as a PostScript (PLOT.ps) and a PNG (PLOT.png) file. You can tune the size of the PNG output image by using the command

$ export DPIPNG=70

prior to doing the plot.

The resulting output image should look like this.

If you want to run again the script, move back to the parent directory and move the directory workdir to another name, e.g., test-1.

$ cd ..
$ mv workdir test-1

Then, you can run one or more of the following examples.

• Example 1: Run on ngridk at fixed rgkmax = "9"

$ SETUP-convergence-test.py 4 20 9 9
$ EXECUTE-convergence-test.sh
$ mv workdir example-1
$ cd example-1
$ PLOT-convergence.py k

• Example 2: Run on rgkmax at fixed ngridk = "12 12 12"

$ cd ..
$ SETUP-convergence-test.py 12 12 5 9
$ EXECUTE-convergence-test.sh
$ mv workdir example-2
$ cd example-2
$ PLOT-convergence.py r

• Example 3: Two-dimentional run on both rgkmax and ngridk

$ cd ..
$ SETUP-convergence-test.py 4 20 5 9
$ EXECUTE-convergence-test.sh
$ mv workdir example-3
$ cd example-3
$ PLOT-3d-convergence.gnu Ag 5 9

If examples run correctly, correspondingly, you should obtain the following plots.

• Example 1

• Example 2

• Example 3

Notes on Examples

• Please, notice that the scripts SETUP-convergence-test.py and EXECUTE-convergence-test.sh must be executed in the same directory where the original input file input.xml is located.
• In Example 2 the script PLOT-convergence.py takes the line entry r (run on different values of rgkmax) instead of k (run on different values of ngridk) .
• In Example 3 the script PLOT-3d-convergence.gnu has been used for plotting the convergence behaviour with respect to both rgkmax and ngridk.
• In Example 3 the script PLOT-3d-convergence.gnu takes 3 line entries: a label for the plot (usually, the name of the crystal), the number of used values for rgkmax, and the number of used k-point meshes.

How to quantify convergence

In this subsection we refer to the results of Example 1. In this case the convergence-test file is

   4    9.00      -5314.79400975
   6    9.00      -5314.79814600
   8    9.00      -5314.79964762
  10    9.00      -5314.80025491
  12    9.00      -5314.80060159
  14    9.00      -5314.80081186
  16    9.00      -5314.80084526
  18    9.00      -5314.80090977
  20    9.00      -5314.80092517

Due to the fact that the difference between energies in contiguous rows becomes increasingly small going to large values of ngridk, this difference can be interpreted as a measure of the accuracy in the value of the calculated energy.

3. Running tests: Diamond

Repeat what you have done in the previous section for diamond. In contrast to silver, which is a metal, the diamond an insulator. The corresponding input for exciting (input.xml) could look like the following.

<input>
 
   <title>Diamond: Convergence test</title>
 
   <structure speciespath="$EXCITINGROOT/species"> 
 
      <crystal scale="6.719">
         <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="C.xml">
         <atom coord="0.00 0.00 0.00" />
         <atom coord="0.25 0.25 0.25" />
      </species>
 
   </structure>
 
   <groundstate 
      ngridk="4 4 4" 
      rgkmax="5.0"
      gmaxvr="14">
   </groundstate>
 
</input>

As in the previous section, do not forget to replace in the input.xml the string "$EXCITINGROOT" by the actual value of the environment variable $EXCITINGROOT.

Finally, on the basis of what you learned above, try to reproduce the results for Diamond displayed in the following.

---

Final questions

• Is convergence with respect to the values of ngridk faster for silver or diamond? Why?
• What about the convergence with respect to the values of rgkmax?