Purpose: In this tutorial you will learn how to make the first steps with exciting.
Table of Contents
First, you should choose the directory where you want to unpack the current release, exciting beryllium. All examples in this tutorial assume that the source code of exciting is unpacked to /home/exciting-tutorial. From now on the symbol $ will indicate the shell prompt.
$ mkdir /home/exciting-tutorial $ cd /home/exciting-tutorial
Download the current release, exciting beryllium here, and unpack it.
$ tar xvf exciting.beryllium.tar.gz
Before proceeding further, be sure that relevant environment variables are already defined as specified in Tutorial scripts and environment variables. If you choose a different location than /home/exciting-tutorial, replace /home/exciting-tutorial with an appropriate path as indicated in Tutorial scripts and environment variables.
Then, 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 6 (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/make.inc: No such file or directory perl ./setup.pl --------------------------------------------------------- 1 AIX.xlf.poe.essl 2 CrayXT6 3 DUNE 4 g95 5 g95.mac 6 gfortran 7 ifort Enter the number of the platform that suites your system best: 6 You use the makefile from: build/platforms/make.inc.gfortran If the compilation fails, edit "build/make.inc" 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
Finally, create a work directory /home/exciting-tutorial/my_first_tutorial and move inside it
$ mkdir /home/exciting-tutorial/my_first_tutorial $ cd /home/exciting-tutorial/my_first_tutorial
2. Preparing input
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"> </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 /).
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.
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 either inserting by hand speciespath = "/home/exciting-tutorial/exciting/species" in the input file or printing the following command on the command line.
Remark on the species files directory in exciting: Starting with the release of exciting beryllium 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"> </groundstate>
The attribute outputlevel of the groundstate element specifies the amount of information which is printed to output files.
Now, create a work directory diamond, move inside it
$ mkdir diamond $ cd 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 simply need to execute the excitingser binary. After a few seconds, the calculation should be finished.
$ time excitingser
Here we used the time command before excitingser in order to get, at the end of the run, the elapsed time explicitly written on the screen.
4. Reading the main output file
The execution of exciting will produce a number of output files. The main output file is 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 BERYLLIUM started = | version hash id: 6538369d9f6ae6eec0954b7892f64b07f4c18e93 = | = | Date (DD-MM-YYYY) : 12-10-2013 = | Time (hh:mm:ss) : 11:11:06 = | = | All units are atomic (Hartree, Bohr, etc.) = ================================================================================
- The next lines give information on the initial density and tells 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 : 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 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 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 : -77.36807029 _______________________________________________________________ Fermi energy : 0.42682465 Kinetic energy : 74.49623404 Coulomb energy : -141.27395516 Exchange energy : -10.09176468 Correlation energy : -0.49858449 DOS at Fermi energy (states/Ha/cell) : 0.00000000 Electron charges : core : 4.00000000 core leakage : 0.00016012 valence : 8.00000000 interstitial : 2.95335352 charge in muffin-tin spheres : atom 1 C : 4.52332324 atom 2 C : 4.52332324 total charge in muffin-tins : 9.04664648 total charge : 12.00000000 Wall time (seconds) : 1.04
- Actual values of the quantities which are relevant for self-consistency are displayed at each iteration and compared with convergence targets (shown in parentheses). If all self-consistency criteria are matched (values are smaller then targets) the calculation has successfully ended.
RMS change in effective potential (target) : 0.295377E-06 ( 0.100000E-05) Absolute change in total energy (target) : 0.331202E-05 ( 0.100000E-03) Charge distance (target) : 0.848109E-07 ( 0.100000E-04)
- The final answer is reported at the last iteration.
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ | Convergence targets achieved. Performing final SCF iteration + ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Total energy : -75.89058505 _______________________________________________________________ Fermi energy : 0.50873470 Kinetic energy : 75.54952286 Coulomb energy : -140.90306362 Exchange energy : -10.03458863 Correlation energy : -0.50245567 DOS at Fermi energy (states/Ha/cell) : 0.00000000 Electron charges : core : 4.00000000 core leakage : 0.00016227 valence : 8.00000000 interstitial : 3.09101733 charge in muffin-tin spheres : atom 1 C : 4.45449133 atom 2 C : 4.45449133 total charge in muffin-tins : 8.90898267 total charge : 12.00000000
- The final lines of INFO.OUT tell how the execution has stopped and report the total time spent in the run. Notice, that if a CAUTION message is present, it is worth to have a look to the file WARNING.OUT.
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ | Self-consistent loop stopped + ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ STATE.OUT is written ******************************************************************************** | Groundstate module stopped * ******************************************************************************** Total time spent (seconds) : 5.56 -------------------------------------------------------------------------------- | CAUTION! Warnings have been written in file WARNING.OUT ! - -------------------------------------------------------------------------------- ================================================================================ | EXCITING BERYLLIUM stopped = ================================================================================
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 calculate total energies.
Repeat the calculations setting the attribute outputlevel of the groundstate element to "low" and "high". Which are the changes in the file INFO.OUT?