**by****Pasquale Pavone****for****exciting****boron**

` Purpose:` In this tutorial you will learn how to set up and execute a series of calculations at different volumes for a cubic crystal. Additionally, it will be explained how to fit the energy-vs-volume curves with either polynomial of various degree or other types of equation of state in order to obtain the corresponding equilibrium volume and bulk modulus.

### 0. Define relevant environment variables

**Read the following paragraphs before starting with the rest of this tutorial!**

Before starting, be sure that relevant environment variables are already defined as specified in ` How to set environment variables for tutorials scripts`. Here is a list of the scripts which are relevant for this tutorial with a short description.

: Python script for generating structures at different volumes.**SETUP-volume-optimization.py**: (Bash) shell script for running a series of**EXECUTE-volume-optimization.sh**calculations.**exciting**: Python script for fitting energy-vs-volume curves.**CHECKFIT-energy-vs-volume.py**: Python script for fitting energy-vs-volume curves using a 6th-order polynomial.**PLOT-poly6.py**: Python script for fitting energy-vs-volume curves using the Vinet equation of state.**PLOT-vinet.py**: Python script for fitting energy-vs-volume curves using the Birch-Murnaghan equation of state.**PLOT-birch.py**: Python script for fitting pressure-vs-volume curves using the Birch-Murnaghan equation of state.**PLOT-pbirch.py**: Python script for fitting bulk-modulus-vs-volume curves using the Birch-Murnaghan equation of state.**PLOT-bbirch.py**

From now on the symbol ` $` will indicate the shell prompt.

**Requirements:** Bash shell. Python numpy, lxml, matplotlib.pyplot, and sys libraries.

### 1. Set up the calculations

##### i) Preparation of the input file

The first step is to create a directory for each system that you want to investigate. In this tutorial, we consider as an example the calculation of the energy-vs-volume curves for silver in the fcc cubic structure. Thus, we will create a directory ** silver-volume-optimization** and we move inside it.

```
$ mkdir silver-volume-optimization
$ cd silver-volume-optimization
```

Inside this directory, we create (or copy from a previous calculation) the file ** input.xml** corresponding to a

`calculation at a`

**SCF****reference lattice constant**for silver. A possible choice for this reference value is the

**experimental lattice constant**of

**7.729 Bohr**. The input file could look like the following.

<input> <title>Silver</title> <structure speciespath="$EXCITINGROOT/species"> <crystal scale="7.729"> <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"> <atom coord="0.00 0.00 0.00" /> </species> </structure> <groundstate ngridk="8 8 8" swidth="0.01" rgkmax="7.5"> </groundstate> </input>

Please, remember that the input file for an ` exciting` calculation must always be called

`.`

**input.xml****N.B. (1)**: Do not forget to replace in the ` input.xml` the string "

`" by the actual value of the environment variable`

**$EXCITINGROOT**`using the command`

**$EXCITINGROOT**`$ SETUP-excitingroot.sh`

**N.B. (2)**: If the crystal symmetry allows for the relaxation of the position of the atoms in the unit cell, the complete optimization requires the inclusion in the input file of the element ` relax` just after the element

**groundstate**... <groundstate ... > ... </groundstate> <relax/> ...

(for further details, see ` Simple examples of structure optimization`).

##### ii) Generation of input files for different volumes

In order to generate input files for a series of volumes you have to run the script ` SETUP-volume-optimization.py`.

**Notice**that the script

`always generates a working directory containing input files for different volumes. Results of the current calculations will be also stored in the working directory. The directory name can be specified by adding the name in the command line.`

**SETUP-volume-optimization.py**`$ SETUP-volume-optimization.py DIRECTORYNAME`

If no name is given, the script use the default name ** workdir**.

**Very important**: The working directory is overwritten each time you execute the script

`. Therefore, choose different names for different calculations.`

**SETUP-volume-optimization.py**The script ` SETUP-volume-optimization.py` produces the following output on the screen.

```
$ SETUP-volume-optimization.py vol-opt-1
Enter the number of volume values >>>> 11
$
```

In this example, the working directory is named ` vol-opt-1`, the (on screen) input entry is preceded by the symbol "

`". The entry value must be typed on the screen when requested. This entry (in our example`

**>****>****>****>****11**) is the number of structures which are generated with equally spaced intervals of the lattice constant with a variation of between -5% and +5% from the reference lattice constant.

### 2. Execute the calculations

To execute the series of calculation with input files created by ` SETUP-volume-optimization.py` you have to run the script

`. If a name for the working directory has been specified, then you`

**EXECUTE-volume-optimization.sh****must**give it here, too.

```
$ EXECUTE-volume-optimization.sh vol-opt-1
Running exciting for file input-01.xml ----------------------------------
...
Run completed for file input-11.xml -------------------------------------
$
```

After the complete run, the results of the calculation for the input file ` input-i.xml` are contained in the subdirectory (of the working directory

`)`

**vol-opt-1**`where`

**rundir-***i*`is running from`

*i***01**to the total number of volumes. The data for the energy-vs-volume curve are contained in the file

`inside`

**energy-vs-volume**`.`

**vol-opt-1****Hint:** You can check the status of the calculations by plotting the energies that have been already obtained while other calculations are still running. In order to do this, open a new terminal window, move inside ` vol-opt-1` and run the script

**PLOT-energy.py**`$ PLOT-energy.py`

This way, you obtain both a ` PLOT.ps` and a

`file that you can visualize using the standard tools of your operating system. Here is an example for the first`

**PLOT.png****4**volumes.

### 3. Post-processing: Calculating the optimal volume

In order to analyse the results of the calculations, if you have not done before, you first have to move to the working directory.

`$ cd vol-opt-1`

At this point, you can use the python script ` CHECKFIT-energy-vs-volume.py` for performing the polynomial fit and extracting the equilibrium volume and the bulk modulus.

```
$ CHECKFIT-energy-vs-volume.py
Enter the order of polynomial to be used in the fit >>>> 2
===============================
Lattice symmetry codes
-------------------------------
1 --> Simple cubic (sc)
2 --> Body-centered cubic (bcc)
3 --> Face-centered cubic (fcc)
-------------------------------
0 --> Others
===============================
Enter lattice symmetry code [default 0] >>>> 3
Verification lattice symmetry code >>>> 3
##############################################
Optimal volume = 114.679260 [Bohr^3]
Lattice constant = (fcc) 7.712259 [Bohr]
Bulk modulus = 104.638239 [GPa]
Log(chi) = -3.91
##############################################
$
```

In this example, input entries are preceded by the symbol "` >>>>`". Entry values must be typed on the screen when requested. The first entry (in our example

**2**) represents the order of the polynomial for the fit. The second entry (in our example

**3**) corresponds to the appropriate choice of the lattice symmetry (face-centered cubic in our example). This enables us to extract the value of the lattice constant and of the bulk modulus as reported in the screen output.

The script generates the PostScript output file ` PLOT.ps`, which can be used to visualize the fitting results. An example of the script output is the following.

### 4. Additional exercises

- Improve the accuracy of the fit by adding additional data points.
- If the optimal volume is far from the middle volume in the figure, choose as a new reference lattice constant a value corresponding to the optimal volume.
- Check the accuracy of the calculations by choosing other values for the main computational parameters. An example, corresponding to the choice
=**ngridk**,**"12 12 12"**=**rgkmax**, and using a**"8.0"**polynomial fit, is the following.**4th-order**

- Compare your results with the ones obtained performing a fit using the
equation of state. In order to do this, use the script**Birch-Murnaghan**.**PLOT-birch.py**

```
$ PLOT-birch.py
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
V0 B0 BP a-sc a-bcc a-fcc log(chi)
112.8731 117.242 5.801 4.8328 6.0889 7.6716 -5.11
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
$
```

The output on the screen describes the optimal parameters for the fit, as well as a mesure of the quality of the fit (** log(chi)**, lower values of this quantity mean better fit accuracy). The script generates the output file

`, an example can be found in the following.`

**PLOT.ps**- Compare your results with the ones obtained performing a fit using the
equation of state.**Vinet**

`$ PLOT-vinet.py`

- Compare your results with the ones obtained performing a fit using a sixth order polynomial.

`$ PLOT-poly6.py`

- Use the script
to visualize the comparison between the pressure calculated using the Birch-Murnaghan equation of state and the one obtained from a finite-differentiation of the calculated energies.**PLOT-pbirch.py**

`$ PLOT-pbirch.py`

- Use the script
to visualize the comparison between the bulk modulus calculated using the Birch-Murnaghan equation of state and a second-order finite-differentiation of the calculated energies.**PLOT-bbirch.py**

`$ PLOT-bbirch.py`

- Choose a new cubic material and repeat all the steps.