In this page, we will discuss the calculation modes of PERTURBO related to the interpolation. Here are the values of `calc_mode`

for the interpolation modes:

`'bands'`

: interpolate electronic band structures using Wannier functions.`'phdisp'`

: interpolate phonon dispersion by Fourier transforming real-space interatomic force constants.`'ephmat'`

: interpolate e-ph matrix elements using Wannier functions.

## Electronic bands

*calc_mode = ‘bands’*

**Computes:**Interpolated electronic band structure given an electronic crystal momentum path.

Users specify three variables in the input file (*pert.in*)

- prefix: the same prefix used in
**‘prefix’_epr.h5** - calc_mode: set to
`'bands'`

- fklist: the filename of a file containing the high-symmetry crystal momentum path or k list

Here is the input file or namelist (*pert.in*):

```
&perturbo
prefix = 'si'
calc_mode = 'bands'
fklist = 'si_band.kpt'
/
```

In this example, `fklist='si_band.kpt'`

, the file *si_band.kpt* containing the \(\mathbf{k}\) point list:

```
6
0.500 0.500 0.500 50
0.000 0.000 0.000 50
0.500 0.000 0.500 20
0.500 0.250 0.750 20
0.375 0.375 0.750 50
0.000 0.000 0.000 1
```

The first line specifies how many lines there are below the first line. Columns 1-3 give, respectively, the \(x\), \(y\), and \(z\) coordinates of a crystal momentum **in crystal coordinates**. The last column is the number of points from the current crystal momentum to the next crystal momentum. One can also provide an explicit \(\mathbf{k}\) point list, rather than specifying the path, by providing the number of \(\mathbf{k}\) points in the first line, the coordinates of each \(\mathbf{k}\) point, and setting the values in the last column to 1.

Before running `perturbo.x`

, remember to put *si_epr.h5* in the current directory “pert-band” since `perturbo.x`

needs to read *si_epr.h5*. You may choose to copy the HDF5 file using

`$ cp ../../qe2pert/si_epr.h5 .`

Because the size of the HDF5 file is usually quite large, creating a soft link that point to the original HDF5 file is strongly recommended:

`$ ln -sf ../../qe2pert/si_epr.h5`

Run `perturbo.x`

:

```
$ mpirun -n 1 perturbo.x -npools 1 -i pert.in > pert.out
```

**Note:**The number of pools (-npools) has to be equal to the number of MPI processes (-np or -n), otherwise the code will stop.

It takes just a few seconds to obtain the interpolated band structure. The outputted YAML file, here called *si_bands.yml*, contains the inputs and outputs of the `'bands'`

calculation. The field labeled *bands* contains the information unique to the `'bands'`

calculation, including the interpolated band structure. The remaining sections are common to all Perturbo calculations, and their format is described here.

An example of the *bands* field is given below.

```
bands:
number of bands: 8
k-path coordinate units: arbitrary
k-path coordinates:
- 0.0000000
......
- 3.7802390
k-point coordinate units: crystal
k-point coordinates:
- [ 0.50000, 0.50000, 0.50000, ]
......
- [ 0.00000, 0.00000, 0.00000, ]
band units: eV
band index:
1:
- -3.4658249872
......
- -5.8116812661
......
8:
- 13.6984850767
......
- 9.4608102223
```

We see that there are 8 bands, because we use 8 Wannier functions in the Wannierization procedure in this example. Next, the \(\mathbf{k}\) path information and \(\mathbf{k}\) point information is given. The \(\mathbf{k}\) points, here in crystal coordinates, were inputs to the calculation (each row is a point). The \(\mathbf{k}\) path consists of the one-dimensional coordinates assigned to each \(\mathbf{k}\) point, used as the \(x\) axis a plot of the band structure. Lastly, the field labeled *band index* contains the interpolated band energies in eV units. For each of the 8 bands, the energies of the state at each \(\mathbf{k}\) point are listed under the band index.

We may next use Perturbopy to export the data from the YAML file to Python for postprocessing. For more details, see the Perturbopy tutorial.

*'prefix'.bands*(in this case,

*si.bands*) which contains a copy of the interpolated band structure in the following legacy-format: Note that there are 8 blocks in this example, one for each of the 8 bands. The 1

^{st}column is an irrelevant coordinate used to plot the band structure. The 2

^{nd}to 4

^{th}columns are the x, y, and z coordinates of the crystal momenta

**in crystal coordinates**. The 5

^{th}column is the energy, in eV units, of each electronic state.

## Phonon dispersion

*calc_mode = ‘phdisp’*

**Computes:**Interpolated phonon dispersions along a given crystal momentum path.

Users specify three variables in the input file (*pert.in*):

- prefix: the same prefix used in
**‘prefix’_epr.h5** - calc_mode: set to ‘phdisp’
- fqlist: the filename of a file containing the high-symmetry crystal momentum path or q list

Here is the input file (*pert.in*):

```
&perturbo
prefix = 'si'
calc_mode = 'phdisp'
fqlist = 'si_phdisp.qpt'
/
```

In this example, `fqlist='si_phdisp.qpt'`

, and the file *si_phdisp.qpt* contains a crystal momentum path or list with the same format as the file specified in `fklist`

(in the previous section).

Remember to link (or copy) *si_epr.h5* in the current directory using

`ln -sf ../../qe2pert/si_epr.h5`

.

Run `perturbo.x`

:

```
$ mpirun -n 1 perturbo.x -npools 1 -i pert.in > pert.out
```

It takes a few seconds to obtain the phonon dispersion. The outputted YAML file, here called *si_phdisp.yml*, contains the inputs and outputs of the `'phdisp'`

calculation. The field labeled *phdisp* contains the information unique to the `'phdisp'`

calculation, including the interpolated phonon dispersion. The remaining fields are common to all Perturbo calculations, and their format is described here.

The *phdisp* field is given below.

```
phdisp:
number of modes: 6
q-path coordinate units: arbitrary
q-path coordinates:
- 0.0000000
......
- 3.7802390
q-point coordinate units: crystal
q-point coordinates:
- [ 0.50000, 0.50000, 0.50000, ]
- [ 0.00000, 0.00000, 0.00000, ]
phdisp units: meV
phonon mode:
1:
- 12.9198400723
......
- -0.0000025651
......
6:
- 60.2661349902
......
- 63.1558948005
```

There are 6 phonon modes in silicon, which is reflected in the YAML file. The \(\mathbf{q}\) path coordinates and \(\mathbf{q}\) points are listed. The three-dimensional \(\mathbf{q}\) points, here in crystal coordinates, were inputs to the calculation (each row is a point). The \(\mathbf{q}\) path consists of the one-dimensional coordinates assigned to each \(\mathbf{q}\) point, used for the \(x\) axis on a plot of the phonon dispersion. Lastly, the field labeled *phonon mode* contains the phonon energies in meV units. For each of the 6 phonon modes, the energies of the state at each \(\mathbf{q}\) point are listed under the corresponding phonon mode.

We may next use Perturbopy to export the data from the YAML file to Python for postprocessing. For more details, see the Perturbopy tutorial.

*'prefix'.phdisp*(in this case,

*si.phdisp*) which contains a copy of the interpolated phonon dispersion in the following legacy-format: Note that there are 6 blocks, one for each of the to 6 phonon modes in silicon. The 1

^{st}column is an irrelevant coordinate used to plot the phonon dispersion. The 2

^{nd}to 4

^{th}columns are the

*x*,

*y*, and

*z*coordinates of the crystal momenta, in crystal coordinate. The 5

^{th}column is the phonon energy in meV units.

## E-ph matrix elements

*calc_mode = ‘ephmat’*

**Computes:**The absolute values of the e-ph matrix elements, summed over the number of electronic bands, given two lists of \(\mathbf{k}\) and \(\mathbf{q}\) points. In a typical scenario, one computes the e-ph matrix elements for a chosen \(\mathbf{k}\) point as a function of \(\mathbf{q}\) point.

Requires to specify at least 7 variables:

- prefix: the same prefix as in
*‘prefix’_epr.h5* - calc_mode: set to ‘ephmat’
- fklist: the file containing a list of \(\mathbf{k}\) points (for the format of the list, please see the section on
`calc_mode='bands'`

) - fqlist: the file containing a list of \(\mathbf{q}\) points (for the format of the list, please see the section on
`calc_mode='bands'`

) - band_min, band_max: bands used for the band summation in computing e-ph matrix elements
- phfreq_cutoff: phonon energy (meV) smaller than the cutoff will be ignored

In a typical scenario, the user wants to check if the interpolated e-ph matrix elements match with the density functional perturbation theory (DFPT) result. **Here we assume that users know how to obtain the DFPT e-ph matrix elements from the PHONON package in QE.**

Here is the input file (*pert.in*):

```
&perturbo
prefix = 'si'
calc_mode = 'ephmat'
fklist = 'eph.kpt'
fqlist = 'eph.qpt'
band_min = 2
band_max = 4
phfreq_cutoff = 1 !meV
/
```

In this example, we compute the e-ph matrix elements summed over the bands from 2 to 4. The band index here refers to the band index of the Wannier functions, and it may not be the same as the band index in the DFT output from QE because sometimes bands are excluded in the Wannierization procedure. Make sure you know band range appropriate for your calculation, and provide accordingly band_min and band_max.

The variable phfreq_cutoff is used to avoid numerical instabilities in the phonon calculations, and we recommend using a value between 0.5 and 2 meV (unless you know that phonons in that energy range play a critical role). Do not set phfreq_cutoff to a large value, otherwise too many phonon modes will be excluded from the calculations.

For the format of fklist or fqlist files, please refer to the section on calc_mode=’bands’.

Before running `perturbo.x`

, ensure that three files exist in the current directory *“pert-ephmat”*:

*‘prefix’_epr.h5*: here*si_epr.h5**fklist*: here*eph.kpt**fqlist*: here*eph.qpt*

Run `perturbo.x`

:

```
$ mpirun -n 1 perturbo.x -npools 1 -i pert.in > pert.out
```

The outputted YAML file, here called *si_ephmat.yml*, contains the inputs and outputs of the `'ephmat'`

calculation. The field labeled *ephmat* contains the information unique to the `'ephmat'`

calculation, including the absolute values of the e-ph matrix elements summed over bands from band_min to band_max. The remaining sections are common to all Perturbo calculations, and their format is described here.

The first part of the *ephmat* field, which gives information on the \(\mathbf{k}\) points and \(\mathbf{q}\) points used in the calculation, is given below.

```
ephmat:
phonon energy units: meV
deformation potential units: eV/A
e-ph matrix elements units: meV
number of phonon modes: 6
k-path coordinate units: arbitrary
k-path coordinates:
- 0.0000000
q-path coordinate units: arbitrary
q-path coordinates:
- 0.0000000
......
- 3.7802390
k-point coordinate units: crystal
k-point coordinates:
- [ 0.00000, 0.00000, 0.00000, ]
q-point coordinate units: crystal
q-point coordinates:
- [ 0.50000, 0.50000, 0.50000, ]
......
- [ 0.00000, 0.00000, 0.00000, ]
```

The three-dimensional \(\mathbf{k}\) and \(\mathbf{q}\) points are given in crystal coordinates (each row is a point). The \(\mathbf{k}\) path and \(\mathbf{q}\) path coordinates, which are the one-dimensional coordinates assigned to each \(\mathbf{k}\) or \(\mathbf{q}\) point for plotting purposes, are also given.

The remainder of the *ephmat* field is given below.

```
phonon mode:
1:
phonon energy:
- 12.9198400723
......
- -0.0000027347
deformation potential:
- 0.219927308382E+00
......
- 0.247109681543E-08
e-ph matrix elements:
- 0.118026594146E+02
......
- 0.000000000000E+00
......
6:
phonon energy:
......
deformation potential:
......
e-ph matrix elements:
......
```

In the *phonon mode* field, we find the results of the `'ephmat'`

calculation. There are 6 fields under the *phonon mode* field, reflecting each of the 6 phonon modes in silicon. For a given phonon mode, the following information is given:

- Under the field labeled
*phonon energy*, the phonon energies at each \(\mathbf{q}\) point are given in meV units. This list of energies will have a length equal to the number of q-points. - Under the field labeled
*deformation potential*, the deformation potential, i.e. the expectation value of the phonon perturbation potential with respect to the initial and final electronic states, is given in eV/Å units. - Under the field labeled
*e-ph matrix elements*, the absolute values of the e-ph matrix elements are given for each pair of \(\mathbf{k}\) and and \(\mathbf{q}\) points, summed over bands from band_min to band_max.

**Note:**For scenarios involving multiple \(\mathbf{q}\) points and multiple \(\mathbf{k}\) points, the deformation potential and electron-phonon matrix elements become a 2-dimensional matrix. In this matrix, each row corresponds to a \(\mathbf{k}\) point, and each column corresponds to a \(\mathbf{q}\) point. The 2-dimensional matrix is presented in the

*deformation potential*and

*e-ph matrix elements*field as a flattened list. The rows are concatenated together, i.e. values for the same \(\mathbf{k}\) point appear consecutively in the list.

We may next use Perturbopy to export the data from the YAML file to Python for postprocessing. For more details, see the Perturbopy tutorial.

*'prefix'.ephmat*(in this case,

*si.ephmat*) which contains a copy of absolute values of the e-ph matrix elements summed over bands from band_min to band_max. The data is presented in the following legacy-format: The 1

^{st}column is a dummy index for the

**k**point. The 2

^{nd}column is the

**k**point coordinate used for plotting. The 3

^{rd}and 4

^{th}columns are the dummy index and the

**q**point coordinate used for plotting, respectively. The 5

^{th}column is the phonon mode index. The 6

^{th}column is the phonon energy (in meV). The 7

^{th}column is the deformation potential (in eV/Å units), namely the expectation value of the phonon perturbation potential with respect to the initial and final electronic states. The 8

^{th}column is the absolute values of the e-ph matrix elements (meV units) summed over the number of bands specified by the user.