for lithium version of Exciting
Purpose: In this tutorial, you will learn how to perform a phonon calculation and to obtain properties like frequencies and eigenvectors, the density of modes (or phonon density of states), thermodynamic properties, and phonondispersion relations. You will work through the example of diamond.
Table of Contents

0. Prerequisites
This tutorial assumes that you have already downloaded all utility scripts and set the relevant environment variables. Otherwise, please have a look at Tutorial scripts and environment variables. Here, is a list of the scripts which are relevant for this tutorial with a short description.
 THERMALcubic.py: Python script for calculating the thermalexpansion coefficient for cubic systems.
 FREEfromdos.py: Python script for calculating thermodynamic properties.
 PLOTphonondos.gnu: Gnuplot visualization tool for the phonon density of states.
 PLOTphonondispersion.gnu: Gnuplot visualization tool for phonondispersion curves.
 PLOTplot.py: Python visualization tool used by some of the other scripts.
Notes: The symbol $ at beginnings of lines in code segments below indicates the shell prompt.
In the following we use the conversion factor 1 Ha $\approx$ 2.194 746 x 10^{5} cm^{1}.
In order to start, create a new working directory, e.g., /home/excitingtutorial/diamondphonons.
1. Set up an input file for a phonon calculation
The setting of the input file can be done in the following steps.
1.1) Define structural parameters
First, the parameter defining your structure should be defined. In this example, we consider carbon in the diamond phase. The structure part of the input file looks then like the following.
... <structure speciespath="$EXCITINGROOT/species"> <crystal scale="6.7468"> <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" rmt="1.25"> <atom coord="0.00 0.00 0.00" /> <atom coord="0.25 0.25 0.25" /> </species> </structure> ...
The chosen lattice parameter of 6.7468 refers to the converged equilibirum parameter for diamond, as obtained with the PBE exchangecorrelation functional.
1.2) Parameters for the groundstate calculation
Then, parameters for performing the SCF have to be specified. In this example, we use the GGA functional of Perdew, Burke, and Ernzerhof (PBE), other choices can be found in the description of the attribute xctype of the element groundstate.
... <groundstate do="fromscratch" ngridk="2 2 2" rgkmax="4.0" xctype="GGAPerdewBurkeErnzerhof"/> ...
Note that this example of input contains values for the parameters ngridk and rgkmax which allow for fast calculations but should not be considered realistic. A detailed description of how to achieve convergence with respect to these parameters can be found in Simple convergence tests.
1.3) Set up the supercell phonon calculation
Simple frozenphonon calculations can be performed only at highsymmetry points in the Brillouin zone (see, e.g., Phonons at Γ in diamondstructure crystals and Phonons at X in diamondstructure crystals). With exciting, we can also perform phonon calculations at any point in the Brillouin zone using the supercell method and phonon interpolation. The input block in which this method is used is the one specified by the element phonon. In supercell phonon calculations, the size of the supercell is specifyed by the periodicity (the wavevector q) of the phonon displacements which are considered. For instance, as mentioned in Phonons at X in diamondstructure crystals, the supercell corresponding to the X point has a size which is twice the one of the unperturbed crystal.
In general, for calculating phonon properties, you must specify the subelement ngridq inside phonon. Setting ngridq="n1 n2 n3", we are asking to exciting to calculate all the phonons corresponding to all the qpoints belonging to a "n1 n2 n3" mesh in reciprocal space. In this case, exciting performs calculation for supercell defined by multiplying the crystal basis vectors of the unit cell by n1, n2, and n3, respectively. The qpoints mesh is defined in the same way as the kpoints grid (specified by ngridk), which is used in calculating the electronic groundstate. However, the choices of the kpoints and qpoints meshes are completely uncorrelated.
In the following example, we choose ngridq="2 2 2", which corresponds to a supercell with all crystal basis vectors doubled with respect to the unit cell of the unperturbed crystal.
... <phonons do="fromscratch" ngridq="2 2 2"> ... </phonons> ...
Further attributes of the element phonons are the following.
 deltaph, that controls the step size for atom displacements (default is 0.03 Bohr).
 reduceq, which uses crystal symmetry to reduce the qpoints (default is true).
Inside the element phonons, you can insert optional elements, requesting various phonon properties. A basic example is the element qpointset.
... <qpointset> <qpoint> 0.0 0.0 0.0 </qpoint> <qpoint> 0.5 0.5 0.0 </qpoint> <qpoint> 0.5 0.5 0.5 </qpoint> </qpointset> ...
This element is needed in order to let exciting calculate phonon eigenvalues (frequencies) and eigenvectors for the qpoints specified in each subelement qpoint. In the example above, calculations will be performed for Γ, X, and L phonons (in the standard notation for highsymmetry points in the Brillouin zone of fcc crystals). Note that qpoints are given in reciprocal lattice coordinates. Additional properties are discussed in Section 2.
1.4) The basic input file for a phonon calculation
We are now ready to run the actual phonon calculation. Jobs of this type are in general a bit lengthy, the present calculation should take about 30 minutes on a recent CPU with the loose parameters specified. Note that they can also be run in parallel.
<input> <title>Diamond: Phonons</title> <structure speciespath="$EXCITINGROOT/species"> <crystal scale="6.7468"> <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" rmt="1.25"> <atom coord="0.00 0.00 0.00" /> <atom coord="0.25 0.25 0.25" /> </species> </structure> <groundstate do="fromscratch" ngridk="2 2 2" rgkmax="4.0" xctype="GGAPerdewBurkeErnzerhof"/> <phonons do="fromscratch" ngridq="2 2 2"> <qpointset> <qpoint> 0.0 0.0 0.0 </qpoint> <qpoint> 0.5 0.5 0.0 </qpoint> <qpoint> 0.5 0.5 0.5 </qpoint> </qpointset> </phonons> </input>
Please, remind that after creating the input file input.xml, the path for the species file must be set using the command
$ SETUPexcitingroot.sh
Now, you can run exciting by using the command
$ excitingser
1.5) Output files of a phonon calculation
In addition to the basic output files already mentioned in Electronicstructure calculations, a typical phonon calculation produces the following files.

Here, fileext means an extension of the filename naming the corresponding qpoint of the grid, species, atom, and polarization.
Exercise
 Have a look to the file PHONON.OUT. What is the frequency of the optical phonon modes at Γ?
 What are the eigenvectors of the optical phonon modes at Γ?
2. Properties from the phonon calculation
To obtain other phonon properties, additional subelements can be inserted inside the element phonons, as explained in the following.
2.1) Phonon density of states (DOS)
The phonon density of states is computed on top of the phonon calculation by adding the element phonondos within the element phonons.
... <phonondos ngrdos="100" nwdos="500" ntemp="200" /> ...
Here, phonon frequencies are computed on a dense grid (ngrdos$\times$ngrdos$\times$ngrdos) and collected to obtain the DOS, which is written to the file PHDOS.OUT. The number of steps between the lowest and highest frequency (N$_{\omega}$) is given by nwdos.
The complete input file in this case is shown below.
<input> <title>Diamond: PhononDOS</title> <structure speciespath="$EXCITINGROOT/species"> <crystal scale="6.7468"> <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" rmt="1.25"> <atom coord="0.00 0.00 0.00" /> <atom coord="0.25 0.25 0.25" /> </species> </structure> <groundstate do="skip" ngridk="2 2 2" rgkmax="4.0" xctype="GGAPerdewBurkeErnzerhof"/> <phonons do="skip" ngridq="2 2 2"> <phonondos ngrdos="100" nwdos="500" ntemp="200" /> </phonons> </input>
Note the precence of the two attributes do="skip" inside the elements phonons and groundstate, respectively. They let exciting skip a new (and lengthy) phonon calculation and read the necessary data from existing files. This requires you, of course, to have already performed the basic phonon calculation with the same parameters (as in Section 1.4) and to work in the same directory. If this is the case, in order to perform the calculation, you type
$ SETUPexcitingroot.sh
$ excitingser
Data in PHDOS.OUT can be plotted directly. You can use the script PLOTphonondos.gnu, which invokes gnuplot, by typing on the command line
$ PLOTphonondos.gnu
A converged result (using an 8$\times$8$\times$8 kgrid, a rgkmax of 7.0 and 4 qpoints in each direction) can be found below.
2.2) Thermodynamic properties
The zeropoint energy, E_{zp}, and further thermodynamic properties can be computed from the phonon DOS g$(\omega)$ (see Input reference for further details).
 the vibrational internal energy E_{vib},
 the vibrational free energy F_{vib},
 the vibrational entropy S_{vib}
 the heat capacity c.
In order to calculate and visualize these thermodynamic properties, you can use the script FREEfromdos.py as follows
$ FREEfromdos.py 0 1600 40

What do you want to calculate?

0 => Zeropoint energy

1 => Vibrational internal energy
2 => Vibrational free energy
3 => Vibrational entropy
4 => Heat capacity

Enter task code >>>> 2
Created PostScript output "PLOT.ps" from file "vibrationalfreeenergy"
$
Note that if the calculation of the zeropoint energy is required, this energy is not plotted, but it is written in output directly on the screen, e.g.,
...
Zeropoint energy is 1.37898903e02 [Ha]
...
The converged plot for the vibrational free energy can be seen here.
2.3) Phonondispersion relations
Phonondispersion relations can also be easily calculated. Phonon eigenvalues are computed along a path through the Brillouin zone and written for later plotting. This path can be specified within the element phonondispplot (reciprocal lattice coordinates) in the following way (a path between the points Γ(K)XΓL is specified in the present example).
... <phonondispplot> <plot1d> <path steps="200"> <point coord="1.0 0.0 0.0" /> <point coord="0.5 0.5 0.0" /> <point coord="0.0 0.0 0.0" /> <point coord="0.5 0.0 0.0" /> </path> </plot1d> </phonondispplot> ...
This codelet is to be included within the element phonons, same as for qpointset and phonondos above. Of course, one can reuse data of a previous phonon calculation by adding do="skip" to the elements phonons and groundstate. This run produces the file PHDISP.OUT that contains the phonon eigenvalues along the path specified in the input and can be plotted directly. The script PLOTphonondispersion.gnu can be used to produce a plot of the phonondispersion relations.
$ PLOTphonondispersion.gnu 0 1600
Converged results as mentioned above can be seen here.
2.4) Other useful features
3. Thermal expansion
Harmonic phonon frequencies do not depend on the crystal volume. As a consequence of this fact, there is no effect of temperature on the equilibrium volume of a perfect harmonic crystal. However, real crystals do change their volume as their temperature is varied. In the next, we show how to calculate with exciting physical quantities which are related to the phenomenon of thermal expansion.
3.1) Mode Grüneisen parameters
Phonon frequencies of a real crystal explicitly depend on the crystal volume. This dependence can be characterized by the mode Grüneisen parameters, $\gamma_j({\bf q})$. The Grüneisen parameter of the mode $j$ at a wavevector ${\bf q}$ is defined as
(1)where $V_0$ is the equilibrium volume. For cubic systems and in terms of the lattice parameter $a$ one can write
(2)where again $a_0$ is the equilibrium parameter.
In order to calculate the mode Grüneisen parameter at some highsymmetry point in the first Brillouin zone of the diamond lattice, create two new working directories, e.g., diamondphononsminus and diamondphononsplus. Copy the input file already used for calculating the phonon dispersion at the (zerotemperature) equilibrium lattice parameter $a_0$ to each of the two directories. In diamondphononsminus change the lattice parameter in the input file to $a_0\Delta$, with $\Delta$=0.05 Bohr. Similarly, change the lattice constant in the input file in diamondphononsplus to $a_0+\Delta$.
Now, repeat the calculation of the phonon frequencies of diamond at Γ and X as above in each of the two new directories. Compute the mode Grüneisen parameters using the above definition (evaluating the derivative numerically from a quadratic interpolation, i.e., from the differences between $\omega_j(a_0 + \Delta)$ and $\omega_j(a_0  \Delta)$). The following values should be obtained (frequencies are given in [cm^{1}]).

Here, $\gamma_{\rm conv}$ is the (almost) converged result, obtained using a 6$\times$6$\times$6 kpoint mesh, rgkmax="7.0", and a grid of 4$\times$4$\times$4 qpoints.
3.2) Thermal expansion coefficient
The thermal expansion of a crystal can be quantified by the linear thermalexpansion coefficient $\alpha(T)$. Within the quasiharmonic approximation, one can write
(3)where $B_0$ is the bulk modulus and
(4)is the derivative of the vibrational free energy with respect to the volume. The derivative is approximated numerically by a quadratic interpolation.
(5)In order to calculate $\alpha(T)$, you can use the following procedure.
 Obtain the phonon DOS and thermodynamical properties for $a_0  \Delta$, $a_0$, and $a_0 + \Delta$ using the same procedure of Section 3.1.
 Create the new directory thermalexpansion.
 Copy the files input.xml and thermo.xml from the directory diamondphonon to the directory thermalexpansion adding the suffix .0. Thus, you will have inside thermalexpansion the two new files input.xml.0 and thermo.xml.0.
 Repeate the previous step from the directory diamondphononplus and the suffix .+.
 Repeate the previous step from the directory diamondphononminus and the suffix ..
Now, inside the directory thermalexpansion you have the following files.
input.xml. thermo.xml.
input.xml.0 thermo.xml.0
input.xml.+ thermo.xml.+
The linear thermalexpansion coefficient can be obtained using the script THERMALcubic.py inside the directory thermalexpansion.
$ THERMALcubic.py 0 1600 40

Linear thermalexpansion coefficient for cubic systems

Enter value for the bulk modulus [GPa] >>>> 452
$
A converged result (using an 6$\times$6$\times$6 kgrid, a rgkmax of 7.0 and 4 qpoints in each direction) can be found here.
All results obtained in this tutorial for diamond can be compared with theoretical and experimental data present in the literature.
Exercise: Silicon in diamond structure
 The calculation presented here for diamond can be repeated for Silicon. Use the PBE exchangecorrelation functional, an equilibrium lattice parameter of 10.34 Bohr, and low values for both k and qpoint grids to accelerate the runs, as above. The experimental bulk modulus is 98 GPa (LandoltBörnstein tables).
 What are the differences to diamond?
 Use the theoretical bulk modulus. Calculate theoretical values of equilibrium parameters as in Volume Optimization for Cubic Systems.
 Compare your results with the "converged" one displayed here.