by Jürgen Spitaler, Lorenzo Pardini, & Pasquale Pavone for exciting neon
(Jupyter notebook by Mara Voiculescu & Martin Kuban)
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 electronic band structure can be calculated.
Read the following paragraphs before starting with the rest of this tutorial!
Before running any Jupyter tutorials, please refer to the 00_before_starting.md
document on how to correctly set up the environment. This only needs to be done once. After which, the venv can be (re)activated from exciting
's root directory:
source tools/excitingjupyter/venv/excitingvenv/bin/activate
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.
The first step of any density-functional calculation is the determination of the ground-state total energy and electron density.
The starting point of a ground-state calculation is the crystal structure, only. At the beginning of a ground-state calculation, an initial electron density is generated, which is obtained from a superposition of atomic densities. Thus, this initial electron density lacks the interaction between atoms and is normally a rather crude approximation of the density.
Then, the calculation iteratively goes through the following steps:
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 iterations. Thus, this kind of calculations is often called self-consistent field (SCF) calculation, and an iteration is often referred to as an SCF cycle.
As a first step, you may create a running directory for the notebook.
%%bash
mkdir -p run_bs_dos
We start by creating an exciting
(xml) input file called input.xml which should appear as the one below.
<input>
<title>Electronic structure of silver</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"
xctype="GGA_PBE_SOL">
</groundstate>
</input>
The next step is writing the complete input as a string and saving it in your working directory as input.xml.
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
%%bash
cd run_bs_dos
python3 -m excitingscripts.setup.excitingroot
cd ..
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 by executing
%%bash
cd run_bs_dos
xcrysden --exciting input.xml >/dev/null 2>&1 &
cd ..
In order to run exciting
from the terminal, you simply need to execute the exciting_smp binary in the running directory. After a few seconds, the calculation should be finished. 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.
%%bash
cd run_bs_dos
time $EXCITINGROOT/bin/exciting_smp input.xml
cd ..
If you wish, you can follow the progress by displaying the output to INFO.OUT with the command
tail -f INFO.OUT
which needs to be killed after exciting
has stopped using Ctrl+C. The calculation should roughly take a few seconds. 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 ground-state calculation are described in How to start an exciting calculation.
After you have completed the ground-state 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):
do="skip"
to the element groundstate
;properties
after the groundstate
element;dos
into the element properties
.dos
as shown below.The corresponding part of the input.xml should now look like this:
...
<groundstate
do="skip"
ngridk="8 8 8"
outputlevel="normal"
xctype="GGA_PBE_SOL">
</groundstate>
<properties>
<dos
nsmdos="2"
nwdos="1000"
winddos="-0.3 0.3"
inttype="tetra">
</dos>
</properties>
...
Here, the attributes of the element dos
have the following meaning (see here) for more details):
nsmdos
indicates the type of smearing for the resulting DOS.nwdos
is number of energy points in the DOS.winddos
indicates the energy window, given in Hartree (Ha), for the DOS plot.inttype
defines the method that is used for evaluating Brillouin-zone integrals.%%bash
cd run_bs_dos
python3 -m excitingscripts.setup.excitingroot
cd ..
Then, execute exciting_smp again:
%%bash
cd run_bs_dos
time $EXCITINGROOT/bin/exciting_smp input.xml
cd ..
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, you can execute the following script:
%%bash
cd run_bs_dos
python3 -m excitingscripts.plot.dos
cd ..
The script excitingscripts.plot.dos
is a useful general tool for plotting electronic and phonon density of states. It allows for a bunch of different arguments which are fully described in The python script "plot.dos". This script produces the PNG file PLOT.png. You can visualize this file with standard tools, the result should look like this:
Please note:
python3 -m excitingscripts.plot.dos -eu Ha
Exercise:
do="skip"
for the element groundstate
for generating the DOS after the ground-state SCF run. Find out why, by searching for the element groundstate in Input Reference and proceeding to its attribute do
.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="1.0 0.0 0.0" label="Gamma"/>
<point coord="0.625 0.375 0.0" label="K"/>
<point coord="0.5 0.5 0.0" label="X"/>
<point coord="0.0 0.0 0.0" label="Gamma"/>
<point coord="0.5 0.0 0.0" label="L"/>
</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
creates 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
.
Here, we choose a simple path containing the directions in reciprocal space with the highest symmetry.
Now, write out the new input as an XML file and run the exciting
code again.
%%bash
cd run_bs_dos
python3 -m excitingscripts.setup.excitingroot
cd ..
%%bash
cd run_bs_dos
time $EXCITINGROOT/bin/exciting_smp input.xml
cd ..
To visualize the band-structure (which is written inside the file BAND.OUT), you can use the following script:
%%bash
cd run_bs_dos
python3 -m excitingscripts.plot.band_structure
cd ..
The script excitingscripts.plot.band_structure
is a useful general tool for plotting electronic and phonon band-structures. It allows for a bunch of different arguments which are fully described in The python script "plot.band_structure". This script produces the PNG file PLOT.png. You can visualize this file with standard tools, the result should look like this:
By looking at the energy units in this plot, you can notice again that, as a default, electronvolts (eV) are used. We stick to this choice in all the tutorials.
If you wish more details on the energy region close to the Fermi Energy $E_F$, you can add a minimum and maximum energy in the command line.
%%bash
cd run_bs_dos
python3 -m excitingscripts.plot.band_structure -e -10 20
This obtains the following image.
Exercises:
When performing electronic-structure calculations, it should be a good practice to include always
For a face-centered cubic crystal, as in the example of this tutorial, the standard path is visualized in the following figure.
In the case of silver, the complete input file input.xml including both the density-of-states and Kohn-Sham electronic band-structure calculation could look like this:
<input>
<title>Electronic structure of silver</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"
xctype="GGA_PBE_SOL">
</groundstate>
<properties>
<dos
nsmdos="2"
nwdos="1000"
winddos="-0.3 0.3"
inttype="tetra">
</dos>
<bandstructure>
<plot1d>
<path steps="100">
<point coord="0.0 0.0 0.0" label="Gamma"/>
<point coord="0.5 0.0 0.5" label="X"/>
<point coord="0.5 0.25 0.75" label="W"/>
<point coord="0.375 0.375 0.75" label="K"/>
<point coord="0.0 0.0 0.0" label="Gamma"/>
<point coord="0.5 0.5 0.5" label="L"/>
<point coord="0.625 0.25 0.625" label="U"/>
<point coord="0.5 0.25 0.75" label="W"/>
<point coord="0.5 0.5 0.5" label="L"/>
<point coord="0.375 0.375 0.75" label="K"/>
</path>
</plot1d>
</bandstructure>
</properties>
</input>
The result for the density-of-states plot should be identical to what is shown in Section 2, while the band-structure plot obtained with
python3 -m excitingscripts.plot.band_structure -e -10 20
should look like the following.