How to Start an exciting Calculation

by Andris Gulans, Jürgen Spitaler, & Pasquale Pavone for exciting oxygen

Purpose: In this tutorial you will learn how to make the first steps with exciting. In addition, we give here a description of the output files produced by an exciting calculation.


0. Installation and definition of the relevant environment variables

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

Before starting, be sure that exciting is already installed according to the procedure reported in Download and compile exciting and that relevant environment variables are already defined as specified in How to set environment variables for tutorials scripts.

Before starting any tutorial, it is a good practice to create a subdirectory for each tutorial you are going to work on. Thus, if your working directory is /home/tutorials, as a first step you may create a subdirectory (which could be called, e.g., my_first_tutorial) and move inside it.

$ cd /home/tutorials
$ mkdir my_first_tutorial
$ cd my_first_tutorial

1. Preparing input

i) Diamond

For the very first exciting run, you will use an already prepared example of an input file that sets up a total-energy calculation of diamond. Input files for exciting are written in the XML format and are typically named input.xml. The XML format allows your data to be written in a structured way. Figuratively speaking, an exciting input is pretty much like an article with its sections and subsections. In case of XML data, sections and subsections are called elements.

<input>
 
   <title>Diamond</title>
 
   <structure speciespath="$EXCITINGROOT/species">
 
      <crystal scale="6.7274">
         <basevect>0.0   0.5   0.5</basevect>
         <basevect>0.5   0.0   0.5</basevect>
         <basevect>0.5   0.5   0.0</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"
      outputlevel="normal"
      xctype="GGA_PBE_SOL">
   </groundstate>
 
</input>

Let us examine this example bit-by-bit. The first thing to be said is that an XML is not sensitive to line indentation. However, for the sake of clarity, line indentation is used in all examples of these Tutorials to illustrate the hierarchy among elements. Now, let's come back to the input.xml shown above. The first and the last line indicate the beginning and the end of the input.

<input>
...
</input>

The element title contains some freely chosen text simply to describe the calculation. Keywords <title> and </title> indicate the beginning and the end of the element (note in the second keyword the presence and position of the slash /).

    <title>Diamond</title>

The next element, structure, describes the geometry and the chemical composition of a studied system. Notice that the declaration of the structure section contains as additional information the parameter speciespath.

    <structure speciespath="$EXCITINGROOT/species/">

Such parameters in the XML language are called attributes, and their values are always given in quotes regardless whether it is numerical, symbolic, or boolean information. In particular, the attribute speciespath defines the location, where the files with the data about chemical elements are stored. In the example above, the speciespath must be changed explicitly by either inserting by hand speciespath = "/home/tutorials/exciting/species" in the input file or executing the following command on the command line.

$ SETUP-excitingroot.sh

Remark on the species files directory in exciting: Starting with the release of exciting boron, it is not possible to define the attribute speciespath (i.e., the directory containing the species files) by linking directly to the exciting-code site.

The element structure contains subelements crystal and species. The element crystal is used for defining the Bravais lattice of the studied system. It contains three lattice vectors (each specified by an element basevect) in units of the attribute scale that is given in Bohr. The element species describes the chemical composition of the studied system. Atomic coordinates are specified by the element atom. The primitive unit cell of diamond contains two carbon atoms, and their positions are given in the basis of the lattice vectors (lattice coordinates).

    <structure ...>
 
      <crystal scale="6.7274">
         <basevect>0.0   0.5   0.5</basevect>
         <basevect>0.5   0.0   0.5</basevect>
         <basevect>0.5   0.5   0.0</basevect>
      </crystal>
 
      <species speciesfile="C.xml">
         <atom coord="0.00 0.00 0.00" />
         <atom coord="0.25 0.25 0.25" />
      </species>
 
   </structure>

The next element, groundstate, contains attributes that define computational parameters. In particular, in calculations of periodic systems it is necessary to define how the Brillouin zone is sampled. It is done using the attribute ngridk. The calculation of some quantities, such as the electron density and the total energy, requires an integration over the Brillouin zone. In practice, the integration is replaced with a sum over equally-spaced points. The number of divisions of the Brillouin zone along each of the three directions of the primitive vectors of the reciprocal lattice is exactly what is specified in the attribute ngridk.

   <groundstate 
      ngridk="4 4 4"
      outputlevel="normal"
      xctype="GGA_PBE_SOL">
   </groundstate>

The attribute outputlevel of the groundstate element specifies the amount of information which is printed to output files. The attribute xctype specifies the type of exchange-correlation functional to be used.

Now, create a work directory diamond, move inside it

$ mkdir diamond
$ cd diamond

Now, save the complete input there as input.xml and run the script SETUP-excitingroot.sh. While for the storage or archiving purposes you may choose any name for the input file, running the exciting code requires that specifically the file input.xml is present.

ii) Visualization of structures

You are ready to start a calculation, but it makes sense to visualize the structure defined in the input before running the code. If XCrySDen is pre-installed, it can be configured for viewing exciting input files. To this purpose, before running XCrySDen, follow the instructions in XCrySDen Setup for exciting. After configuring XcrySDen, try to visualize the prepared input file.

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

If everything is set up properly, this command will open a window as shown below.

xcrysden-snapshot.png

Now you can play a little bit with the visualization program to make sure that you see indeed the diamond structure. Remember that we have supplied the primitive unit cell and not the conventional unit cell. This explains why you do not see something similar to what is normally printed in textbooks for solid-state physics.


2. Running exciting

To run exciting, you simply need to execute the exciting_smp binary. After a few seconds, the calculation should be finished.

$ time exciting_smp

Here we used the time command before exciting_smp in order to get, at the end of the run, the elapsed time explicitly written on the screen.


3. Reading INFO.OUT, the main output file

The execution of exciting will produce a number of output files. More details about these files will be given in the next section. Here, we will focus on the main output file, named INFO.OUT. It contains basic information about the calculation. Below, this file is discussed for the diamond example and for the default value ("normal") of the attribute outputlevel of the groundstate element.

  • The output file starts with a self-explanatory header.
================================================================================
| EXCITING OXYGEN started                                                      =
|                                                                              =
| compiler: ifort (IFORT) 19.0.0.117 20180804                                  =
|                                                                              =
|                                                                              =
| Date (DD-MM-YYYY) : 10-06-2021                                               =
| Time (hh:mm:ss)   : 10:47:58                                                 =
|                                                                              =
| All units are atomic (Hartree, Bohr, etc.)                                   =
================================================================================
  • The next lines give information on the initial density and tell us that the initialization has started.
********************************************************************************
* Ground-state run starting from atomic densities                              *
********************************************************************************

++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+ Starting initialization                                                      +
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  • The next section contains lattice parameters and derived quantities.
 Lattice vectors (cartesian) :
      0.0000000000      3.3637000000      3.3637000000
      3.3637000000      0.0000000000      3.3637000000
      3.3637000000      3.3637000000      0.0000000000

 Reciprocal lattice vectors (cartesian) :
     -0.9339693354      0.9339693354      0.9339693354
      0.9339693354     -0.9339693354      0.9339693354
      0.9339693354      0.9339693354     -0.9339693354

 Unit cell volume                           :      76.1170172117
 Brillouin zone volume                      :       3.2588010215
  • The further bit contains the information about the chemical composition of the crystal.
 Species :    1 (C)
     parameters loaded from                 :    C.xml
     name                                   :    carbon
     nuclear charge                         :      -6.00000000
     electronic charge                      :       6.00000000
     atomic mass                            :   21894.16673000
     muffin-tin radius                      :       1.45000000
     # of radial points in muffin-tin       :     250

     atomic positions (lattice) :
       1 :   0.00000000  0.00000000  0.00000000
       2 :   0.25000000  0.25000000  0.25000000

 Total number of atoms per unit cell        :       2
  • The next section tells whether the calculation is a spin-polarized one.
 Spin treatment                             :    spin-unpolarised
  • The exciting code recognizes crystal symmetries automatically and reports what has been found.
 Number of Bravais lattice symmetries       :      48
 Number of crystal symmetries               :      48

 k-point grid                               :       4    4    4
 Total number of k-points                   :       8
 k-point set is reduced with crystal symmetries
  • The basis set related information is printed in the next section. Note that exciting uses different basis sets for the Kohn-Sham orbitals and the effective potential.
 R^MT_min * |G+k|_max (rgkmax)              :       7.00000000
 Species with R^MT_min                      :       1 (C)
 Maximum |G+k| for APW functions            :       4.82758621
 Maximum |G| for potential and density      :      12.00000000

 G-vector grid sizes                        :      20    20    20
 Total number of G-vectors                  :    2229

 Maximum angular momentum used for
     APW functions                          :       8
     computing H and O matrix elements      :       8
     potential and density                  :       8
     inner part of muffin-tin               :       2
  • Further computational details are printed below. The type of the exchange-correlation functional used in the calculation is among them.
 Total nuclear charge                       :     -12.00000000
 Total electronic charge                    :      12.00000000
 Total core charge                          :       4.00000000
 Total valence charge                       :       8.00000000

 Number of empty states                     :       5
 Total number of valence states             :      10

 Maximum Hamiltonian size                   :     158
 Maximum number of plane-waves              :     150
 Total number of local-orbitals             :       8

 Exchange-correlation type                  :      22
     PBEsol, Phys. Rev. Lett. 100, 136406 (2008)
     Generalised gradient approximation (GGA)

 Smearing scheme                            :    Gaussian
 Smearing width                             :       0.00100000

 Using multisecant Broyden potential mixing
  • Further, intermediate results are printed after each iteration of the SCF (self-consistent field) loop.
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+ SCF iteration number :    1                                                  +
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 Total energy                               :       -76.85604882
 _______________________________________________________________
 Fermi energy                               :         0.47006663
 Kinetic energy                             :        75.01766314
 Coulomb energy                             :      -141.28404909
 Exchange energy                            :       -10.09094088
 Correlation energy                         :        -0.49872199

 DOS at Fermi energy (states/Ha/cell)       :         0.00000000

 Electron charges :
     core                                   :         4.00000000
     core leakage                           :         0.00015896
     valence                                :         8.00000000
     interstitial                           :         2.95818806
     charge in muffin-tin spheres :
                  atom     1     C          :         4.52090597
                  atom     2     C          :         4.52090597
     total charge in muffin-tins            :         9.04181194
     total charge                           :        12.00000000

 Estimated fundamental gap                  :         0.18549484
        valence-band maximum at    1      0.0000  0.0000  0.0000
     conduction-band minimum at    4      0.2500  0.2500  0.0000

 Wall time (seconds)                        :         1.38
  • Actual values of the quantities which are relevant for self-consistency are displayed at each iteration (after the first one) and compared with convergence targets (shown in parentheses). If all self-consistency criteria are matched (values are smaller then targets) for the last 2 iterations the calculation has successfully ended.
 RMS change in effective potential (target) :   1.25384      ( 0.100000E-05)
 Absolute change in total energy   (target) :  0.329777      ( 0.100000E-05)
 Charge distance                   (target) :  0.752460E-02  ( 0.100000E-04)
  • The final answer is reported at the last iteration.
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
| Convergency criteria checked for the last 2 iterations                       +
| Convergence targets achieved. Performing final SCF iteration                 +
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 Total energy                               :       -75.88903685
 _______________________________________________________________
 Fermi energy                               :         0.50878171
 Kinetic energy                             :        75.54873237
 Coulomb energy                             :      -140.90113491
 Exchange energy                            :       -10.03412627
 Correlation energy                         :        -0.50250803

 DOS at Fermi energy (states/Ha/cell)       :         0.00000000

 Electron charges :
     core                                   :         4.00000000
     core leakage                           :         0.00016223
     valence                                :         8.00000000
     interstitial                           :         3.09358006
     charge in muffin-tin spheres :
                  atom     1     C          :         4.45320997
                  atom     2     C          :         4.45320997
     total charge in muffin-tins            :         8.90641994
     total charge                           :        12.00000000

 Estimated fundamental gap                  :         0.15982903
        valence-band maximum at    1      0.0000  0.0000  0.0000
     conduction-band minimum at    4      0.2500  0.2500  0.0000
  • The final lines of INFO.OUT tell how the execution has stopped and report the total time spent in the run.
********************************************************************************
* Groundstate module stopped                                                   *
********************************************************************************

 Total time spent (seconds)                 :         6.11
================================================================================
| EXCITING OXYGEN stopped                                                      =
================================================================================

Notice, that if a CAUTION message is present, it is worth to have a look at the file WARNING.OUT. The CAUTION message could look like the following.

********************************************************************************
* Groundstate module stopped                                                   *
********************************************************************************

 Total time spent (seconds)                 :        11.29

--------------------------------------------------------------------------------
| CAUTION! Warnings have been written in file WARNING.OUT !                    -
--------------------------------------------------------------------------------

================================================================================
| EXCITING OXYGEN stopped                                                    =
================================================================================

4. Output files of an exciting calculation

  • The main output file in exciting is INFO.OUT. A detailed description of the content of this file can be found in the previous section.
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.
  • Both initial (e.g., C.xml) and self-consistent (e.g., C_scf.xml) speciesfiles are also saved, at the end of the run, in the working directory. These files specify which basis functions are used for each element in a calculation performed with exciting.

5. Exercises

i) Create an input file for NaCl to obtain the total energy

Hints: In order to succeed with the task, you need to specify the lattice. Similarly to diamond, NaCl crystallizes in the face-centered cubic structure. The figure below shows the crystallographic (the ball-stick structure) and the primitive (the box drawn with black lines) unit cells of NaCl. Define the primitive unit cell in the input.xml file and test it with XCrySDen. The lattice parameter is $a$=5.64 Å.

nacl2.png



ii) SiC in the zincblende and wurtzite phases

Create the input files of SiC in the cubic (zincblende) and hexagonal (wurtzite) phases. Run exciting to calculate total energies.

Hints: In order to find the structural parameters, you can use the periodic table on the web WebElements and the free Crystallography Open Database.





iii) Outputlevel

Repeat the calculations setting the attribute outputlevel of the groundstate element to "low" and "high". Which are the changes in the file INFO.OUT?

dumdum

iv) Output files

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?
Unless otherwise stated, the content of this page is licensed under Creative Commons Attribution-ShareAlike 3.0 License