How to Start an exciting Calculation

for exciting lithium

Purpose: In this tutorial you will learn how to make the first steps with exciting.

1. Installation

Download the current release, exciting lithium. Unpack it to a directory of your choice. All examples in this tutorial assume that the source code of exciting is unpacked to /home/exciting-tutorial. If you choose a different location, replace /home/exciting-tutorial with an appropriate path (from now on the symbol $ will indicate the shell prompt).

$ mkdir /home/exciting-tutorial 
$ cd /home/exciting-tutorial 
$ wget
$ tar xvf exciting.lithium.tar.gz

Move inside the exciting directory and compile the code!

$ cd exciting
$ make

The compilation script allows you to choose a compiler and other preferences. For the purpose of using exciting within this and the other tutorials, choose gfortran, no k-point parallelization support, and no SMP support. Pay attention that the (yes/No) choice implies typing a full word and not just the first letter.

Makefile:13: build/ No such file or directory
perl ./
1 AIX.xlf.poe.essl
2 CrayXT6
3 g95
4 g95.mac
5 gfortran
6 ifort
7 ifort.XE
8 ifort.mpi.mkl
9 ifort64.mkl

Enter the number of the platform that suites your system best:  5

You use the makefile from:


If the compilation fails, edit "build/" and execute "make" again.

If you have MPI installed you can build exciting with k-point parallelization support.

Build MPI binary ? (yes/No)  No

If you have multithreaded BLAS/LAPACK installed you can build exciting with SMP support.

Build SMP lib binary (yes/No)  No
cd build/serial; make 

If the compilation step was successful, the binary file excitingser should be available in the /home/exciting-tutorial/exciting/bin directory.

$ ls /home/exciting-tutorial/exciting/bin
.  ..  excitingser  spacegroup  species  stateconvert  stateinfo

2. 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. It 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.

    <structure speciespath="">
        <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>
        <species speciesfile="C.xml">
            <atom coord="0.00 0.00 0.00" />
            <atom coord="0.25 0.25 0.25" />
    <groundstate ngridk="4 4 4" >

Let us examine this example bit-by-bit. The first and the last line indicate the beginning and the end of the 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.


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

    <structure speciespath="">

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. The attribute speciespath defines the location, where the files with the data about chemical elements is stored. The example above uses a remote location, which will suffice as long as your workstation has an internet connection. An alternative possibility is to use a local path, for instance, by setting speciespath="/home/exciting-tutorial/exciting/species" (for further details see Tutorial scripts and environment variables).

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 in units of the attribute scale that is given in bohrs. The element species describes the chemical composition of the studied system. The primitive unit cell of diamond contains two carbon atoms, and their positions are given in the basis of the lattice vectors.

    <structure speciespath="">
        <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>
        <species speciesfile="C.xml">
            <atom coord="0.00 0.00 0.00" />
            <atom coord="0.25 0.25 0.25" />

The 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">

Now, create a directory /home/exciting-tutorial/diamond and save the complete input there as input.xml. 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

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


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.

3. Running exciting

To run exciting, you need enter to the /home/exciting-tutorial/diamond/ directory. Then, simply execute the excitingser binary. After a few seconds, the calculation should be finished.

$ cd /home/exciting-tutorial/exciting/diamond
$ excitingser

4. Reading outputs

The execution of exciting will produce a number of output files. Examine INFO.OUT. It contains basic information about the calculation. Below, this file is discussed for the diamond example.

  • The output file starts with a self-explanatory header.
| EXCITING Lithium    (12.08.01) started                     |
| version hash id: b241ef23fa9314e035573330402e9921b86fdebe |

Date (YYYY-MM-DD) : 2012-08-01
Time (hh:mm:ss)   : 16:12:45

All units are atomic (Hartree, Bohr, etc.)
  • The next session contains lattice parameters and derived quantities.
| Ground-state run starting from atomic densities |

Lattice vectors :
   0.000000000       3.363712260       3.363712260    
   3.363712260       0.000000000       3.363712260    
   3.363712260       3.363712260       0.000000000    

Reciprocal lattice vectors :
 -0.9339659315      0.9339659315      0.9339659315    
  0.9339659315     -0.9339659315      0.9339659315    
  0.9339659315      0.9339659315     -0.9339659315    

Unit cell volume      :    76.11784947    
Brillouin zone volume :    3.258765390
  • 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.000000000    
 electronic charge :    6.000000000    
 atomic mass :    21894.16673    
 muffin-tin radius :    1.450000000    
 number of radial points in muffin-tin :    297
 atomic positions (lattice), magnetic fields (Cartesian) :
   1 :   0.00000000  0.00000000  0.00000000       0.00000000  0.00000000  0.00000000
   2 :   0.25000000  0.25000000  0.25000000       0.00000000  0.00000000  0.00000000

Total number of atoms per unit cell :    2
  • The next section tells whether the calculation is a spin-polarized one.
Spin treatment :
  • 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
k-point offset :    0.000000000       0.000000000       0.000000000    
k-point set is reduced with crystal symmetries
Total number of k-points :        8
  • 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.
Smallest muffin-tin radius times maximum |G+k| :    7.000000000    
Species with smallest (or selected) muffin-tin radius :    1 (C)
Maximum |G+k| for APW functions      :    4.827586207    
Maximum |G| for potential and density :    12.00000000    
Polynomial order for pseudocharge density :    9

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

Maximum angular momentum used for
 APW functions                     :   10
 computing H and O matrix elements :    5
 potential and density             :    6
 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. Since it was not supplied in the input, the default option (PBEsol) is used.
Total nuclear charge    :   -12.00000000    
Total core charge       :    4.000000000    
Total valence charge    :    8.000000000    
Total excess charge     :    0.000000000    
Total electronic charge :    12.00000000    

Effective Wigner radius, r_s :    1.148344562    

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

Total number of local-orbitals :   20

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

Smearing scheme :
Smearing width :   0.1000000000E-02

Radial integration step length :    4

Density and potential initialised from atomic data
 Using Multisecant Broyden potential mixing (2)
  • Further, the intermediate and final results are printed after each iteration.
| Self-consistent loop started |

| Iteration number :    1 |

Using advanced method for search of linearization energies

Energies :
 Fermi                       :     0.342173801869    
 sum of eigenvalues          :     -37.5179613378    
 electronic kinetic          :      74.5472397079    
 core electron kinetic       :      62.7455648184    
 Coulomb                     :     -141.296159119    
 Coulomb potential           :     -98.3027575621    
 nuclear-nuclear             :     -24.1177104637    
 electron-nuclear            :     -136.054139748    
 Hartree                     :      18.8756910931    
 Madelung                    :     -92.1447803378    
 xc potential                :     -13.7624434836    
 exchange                    :     -10.0925283364    
 correlation                 :    -0.498636455358    
 total energy                :     -77.3400842027    

Density of states at Fermi energy :   0.6469362104E-11
 (states/Hartree/unit cell)

Charges :
 core                        :    4.000000000    
 core leakage                :   0.1598526408E-03
 valence                     :    8.000000000    
 interstitial                :    2.951077994    
  species :    1 (C)
   atom    1                 :    4.524461003    
   atom    2                 :    4.524461003    
 total in muffin-tins        :    9.048922006    
 total charge                :    12.00000000    

Time (CPU seconds) :         0.99
  • If the calculation has successfully ended, the INFO.OUT contains a message that the self-consistency criteria (shown in parentheses) are matched.
RMS change in effective potential (target) :   0.3270198209E-07 (  0.1000000000E-05)
Absolute change in total energy (target)   :   0.1143303635E-05 (  0.1000000000E-03)
Charge distance (target)                   :   0.1646791623E-07 (  0.1000000000E-02)

Convergence targets achieved
  • The final answer is reported during the last iteration.
| Iteration number :   10 |

Using advanced method for search of linearization energies
REDuction and DMIX in Broyd:    1.1000    0.2000

Energies :
 Fermi                       :     0.433892509056    
 sum of eigenvalues          :     -36.3732205236    
 electronic kinetic          :      75.5554303798    
 core electron kinetic       :      63.4722510105    
 Coulomb                     :     -140.908587257    
 Coulomb potential           :     -98.2376928908    
 nuclear-nuclear             :     -24.1177104637    
 electron-nuclear            :     -135.344060697    
 Hartree                     :      18.5531839029    
 Madelung                    :     -91.7897408120    
 xc potential                :     -13.6909580126    
 exchange                    :     -10.0347499263    
 correlation                 :    -0.502482466446    
 total energy                :     -75.8903892703    

Density of states at Fermi energy :   0.6693362771E-11
 (states/Hartree/unit cell)

Charges :
 core                        :    4.000000000    
 core leakage                :   0.1631881100E-03
 valence                     :    8.000000000    
 interstitial                :    3.089593802    
  species :    1 (C)
   atom    1                 :    4.455203099    
   atom    2                 :    4.455203099    
 total in muffin-tins        :    8.910406198    
 total charge                :    12.00000000
  • Final messages tell how the execution time was distributed over different parts of the exciting code.
| Self-consistent loop stopped |


Timings (CPU seconds) :
 initialisation                        :         0.31
 Hamiltonian and overlap matrix set up :         1.20
 first-variational secular equation    :         1.76
 charge density calculation            :         0.75
 potential calculation                 :         1.67
 total                                 :         5.68

| EXCITING Lithium stopped |

5. Exercises

i) NaCl

Task: Create an input file for NaCl. Run exciting 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 Å.

ii) SiC in the zinc-blende and wurtzite phases

Task: Create the input files of SiC in the cubic (zinc-blende) and hexagonal (wurtzite) phases. Run exciting to obtain the total energies.

Hints: In order to find the structural parameters, you can use the free Crystallography Open Database.

6. Answers

Unless otherwise stated, the content of this page is licensed under Creative Commons Attribution-ShareAlike 3.0 License