Interpolation of Bands, Phonon Dispersion, and e-ph Matrix Elements

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’

Directory: example02-silicon-perturbo/perturbo/pert-bands/ link

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
500   0.500   0.500   50
000   0.000   0.000   50
500   0.000   0.500   20
500   0.250   0.750   20
375   0.375   0.750   50
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.

Click to show legacy-format ASCII text outputs of the bands calculation

We also obtain an output file called 'prefix'.bands (in this case, si.bands) which contains a copy of the interpolated band structure in the following legacy-format:

 0.0000000      0.50000    0.50000    0.50000     -3.4658249872
 ......
 3.7802390      0.00000    0.00000    0.00000     -5.8116812661
 
 ......
 ......
 
 0.0000000      0.50000    0.50000    0.50000     13.6984850767
 ......
 3.7802390      0.00000    0.00000    0.00000      9.4608102223

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’

Directory: example02-silicon-perturbo/perturbo/pert-phdisp/ link

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.

Click to show legacy-format ASCII text outputs of the phdisp calculation

We also obtain an output file called 'prefix'.phdisp (in this case, si.phdisp) which contains a copy of the interpolated phonon dispersion in the following legacy-format:

  0.0000000      0.50000    0.50000    0.50000     12.9198400723
  ......
  3.7802390      0.00000    0.00000    0.00000     -0.0000024786

  ......
  ......

  0.0000000      0.50000    0.50000    0.50000     45.6922098051
  ......
  3.7802390      0.00000    0.00000    0.00000      0.0000014170

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’

Directory: example02-silicon-perturbo/perturbo/pert-ephmat/ link

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.

Click to show legacy-format ASCII text outputs of the ephmat calculation

We also obtain an output file called '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:

  # ik    xk     iq     xq     imod   omega(meV)    deform. pot.(eV/A)     |g|(meV)
    1   0.00000   1   0.00000  001    12.919840     0.219927308382E+00   0.118026594146E+02
    ......
    ......

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.

Electronic bandscalc_mode = ‘bands’

Phonon dispersioncalc_mode = ‘phdisp’

E-ph matrix elements calc_mode = ‘ephmat’

Electronic bands
calc_mode = ‘bands’

Phonon dispersion
calc_mode = ‘phdisp’

E-ph matrix elements
calc_mode = ‘ephmat’