How to Start an exciting Calculation¶
by Andris Gulans, Jürgen Spitaler, & Pasquale Pavone for exciting neon
(Jupyter notebook by Mara Voiculescu & Martin Kuban)
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. Before Starting¶
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
Before starting any tutorial, it is a good practice to create a subdirectory for each tutorial you are going to work on. For this tutorial the subdirectory could be called, e.g., run_tutorial_start_exciting_calculation.
%%bash
mkdir -p run_tutorial_start_exciting_calculation
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.
<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 the path for the attribute speciespath by hand in the input file, or by running the script excitingscripts.setup.excitingroot, as shown in the code cells below.
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.
The next step is writing the complete input as a string and saving it as input.xml. While for 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.
Now you can define the attribute speciespath by moving into your running directory and running the following script.
%%bash
cd run_tutorial_start_exciting_calculation
python3 -m excitingscripts.setup.excitingroot
cd ..
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.
%%bash
cd run_tutorial_start_exciting_calculation
xcrysden --exciting input.xml >/dev/null 2>&1 &
cd ..
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.
2. Running Exciting¶
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.
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.
%%bash
cd run_tutorial_start_exciting_calculation
time $EXCITINGROOT/bin/exciting_smp input.xml
cd ..
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.
!head -n 12 run_tutorial_start_exciting_calculation/INFO.OUT
- The next lines give information on the initial density and tell us that the initialization has started.
!head -n 20 run_tutorial_start_exciting_calculation/INFO.OUT | tail -n 7
- The next section contains lattice parameters and derived quantities.
!head -n 33 run_tutorial_start_exciting_calculation/INFO.OUT | tail -n 12
- The further bit contains the information about the chemical composition of the crystal.
!head -n 48 run_tutorial_start_exciting_calculation/INFO.OUT | tail -n 14
- The next section tells whether the calculation is a spin-polarized one.
!head -n 50 run_tutorial_start_exciting_calculation/INFO.OUT | tail -n 1
- The
excitingcode recognizes crystal symmetries automatically and reports what has been found.
!head -n 57 run_tutorial_start_exciting_calculation/INFO.OUT | tail -n 6
- The basis set related information is printed in the next section. Note that
excitinguses different basis sets for the Kohn-Sham orbitals and the effective potential.
!head -n 71 run_tutorial_start_exciting_calculation/INFO.OUT | tail -n 13
- Further computational details are printed below. The type of the exchange-correlation functional used in the calculation is among them.
!head -n 92 run_tutorial_start_exciting_calculation/INFO.OUT | tail -n 20
- Further, intermediate results are printed after each iteration of the SCF (self-consistent field) loop.
!head -n 137 run_tutorial_start_exciting_calculation/INFO.OUT | tail -n 29
- 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.
!head -n 171 run_tutorial_start_exciting_calculation/INFO.OUT | tail -n 3
- The final answer is reported at the last iteration.
!tail -n 42 run_tutorial_start_exciting_calculation/INFO.OUT | head -n 28
- The final lines of INFO.OUT tell how the execution has stopped and report the total time spent in the run.
!tail -n 8 run_tutorial_start_exciting_calculation/INFO.OUT
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 NEON stopped =
================================================================================
4. Output Files of an exciting Calculation¶
- The main output file in
excitingis 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 groundstate element. |
- 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
excitingfor 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.