Yambopy tutorial: electron-phonon coupling

In this tutorial we will cover the handling of electron-phonon coupling matrix elements by Yambopy. The electron-phonon calculation follows two steps:

1. Quantum Espresso calculation of phonon energies, eigenmodes and variations of the self-consistent potential via ph.x.
2. Electron-phonon matrix element calculation, symmetry expansion and conversion by the LetzElPhC.

For more information on the LetzElPhC code and how you should run step 1., please see the related documentation here.

We can use Yambopy to:

• Run LetzElPhC (both preprocessing and main run) without explicitly writing an input file.
• Convert the resulting databases into Yambo format.
• Analyse the electron-phonon coupling both in LetzElPhC or Yambo format.

The scripts of the tutorial, but not the databases, can be found in the yambopy directory:

$cd tutorial/electron_phonon

The full tutorial, including the LetzElPhC and Yambo databases that we will read, can be downloaded and extracted from the yambo website:

$wget https://media.yambo-code.eu/educational/tutorials/files/electron_phonon.tar.gz
$tar -xvzf electron_phonon.tar.gz
$cd electron_phonon

We will work with monolayer molybdenum disulphide electron-phonon data obtained on a 6x6x1 kpoint grid, including spin-orbit interaction (so we deal with electron-phonon coupling and spinorial wavefunctions). Beware that the parameters are most certainly not converged.

Command line: electron-phonon calculation and databases [OPTIONAL]

Note: you can run this step only if you have compiled LetzElPhC on your machine. If not, please skip to the following sections of the tutorial, as the electron-phonon coupling databases are already provided in the .tar.gz file and you don't need to explicitly recalculate them.

If you run this step, please enter the directory

$cd databases

Let us assume that we have run a quantum espresso phonon calculation as per step 1. above. You will find the results in the dvscf directory. We also have done a non-self-consistent calculation to be used in Yambo, and created the relative SAVE directory.

Now, we aim to reconstruct the electron-phonon coupling matrix elements from the phonon energies, modes and potential variations (in dvscf) and the Bloch electronic wavefunctions used by Yambo (in SAVE).

In order to do this, we will run the lelphc executable of the LetzElPhC code. We will run via command line using yambopy, although it will be instructive to have look at the lelphc input files later.

We run in the same directory where the Yambo SAVE is (remember than you can also virtually move it with a symbolic link).

Type:

yambopy l2y

to see the help for the calculation. Have a look at the various flags and their description. For example, if we want to do a serial run of LetzElPhC for bands from [math]\displaystyle{ n_i }[/math] to [math]\displaystyle{ n_f }[/math], we should type:

yambopy l2y -ph path/of/ph_input.in -b n_i n_f

Here [math]\displaystyle{ n_i }[/math] and [math]\displaystyle{ n_f }[/math] are integers representing the initial and final band indices. Please note: in this case, the band index starts from 1 and the the interval of bands read by the code is [math]\displaystyle{ [n_i,n_f] }[/math] including the extrema of the interval.

For our system, we want to do a parallel calculation: 4 MPI tasks on q-point loop (phonon momenta) and 2 MPI tasks on the k-point loop (electron momenta). In addition, we want to explicitly specify the path of the lelphc executable.

We have a final choice to make. We can ask Yambopy to produce the default LetzElPhC electron-phonon databases, or to convert them in Yambo-compatible format. By the default, both will be printed.

• If you don't need the Yambo-style ndb.elph_gkkp* databases you can run yambopy l2y ... with the --no_gkkp option.
• If you don't need the default ndb.elph databases you can run yambopy l2y ... with the --no_lelphc_dbs option.

However, for this tutorial, we will take a look at both databases, so let's run:

yambopy l2y -ph dvscf/mos2.dvscf -b 25 28 -par 4 2 -lelphc path/to/lelphc_exe

We include the last two valence bands of monolayer MoS2 (25 and 26) and the first two conduction bands (27 and 28). If your lelphc executable is in the PATH, you do not need to specify the last flag.

At the end, check your directory: you should find the lelphc.in input file that was run, let's inspect it:

# LetzElPhC input for yambo generated by yambopy
nqpool      = 2
nkpool      = 4
start_bnd   = 25
end_bnd     = 28
save_dir    = ./SAVE
kernel      = dfpt
ph_save_dir = dvscf/ph_save
convention = yambo

Notice the variable convention=yambo: what does it mean? At variance with QE and many other codes, Yambo uses the "backward" momentum transfer convention for electronic scatterings. That is, an electronic transition goes from band [math]\displaystyle{ n }[/math] and momentum [math]\displaystyle{ k-q }[/math] to band [math]\displaystyle{ m }[/math] and momentum [math]\displaystyle{ k }[/math]. In the "forward" momentum transfer convention (the more standard one), the transitions go from [math]\displaystyle{ nk }[/math] to [math]\displaystyle{ mk+q }[/math]. Therefore, this variable ensures that the electron-phonon coupling matrix elements are computed as [math]\displaystyle{ \langle mk|dV|nk-q\rangle }[/math]. However, do not worry: Yambopy can automatically switch between the two conventions when loading the LetzElPhC databases.

You will also find a ndb.elph database that contains the computed electron-phonon matrix elements, in the output format of LetzElPhC.

In addition, if you check the SAVE folder:

ls SAVE/ndb.elph_gkkp*

you will see that yambopy has created the Yambo-compatible electron-phonon databases and placed them inside the SAVE.

If you want to run LetzElPhC directly, without using yambopy, you can refer to its [guide]. Keep in mind that in this case, in order to convert the database to the ndb.elph_gkkp* databases of Yambo, you will then need a couple of lines of python using the Yambopy class ConvertElectronPhononDB in yambopy/letzelph_interface/lelph2y.py.

At the end of this section, you should have produced the same databases that you find in the main electron_phonon folder. You can run the following part either in the directory where you are (by copying the python scripts here), or by going back:

$cd ..

and using the original ones.

Loading electron-phonon matrix elements: Yambo

You may have seen how to calculate and import electron-phonon matrix elements in yambo in the electron-phonon tutorial.

With Yambopy, we can generate a yambo SAVE folder and import the matrix elements with a single command. Typing

$yambopy gkkp

will print the necessary documentation:

Produce a SAVE folder including elph_gkkp databases

Arguments are:
  -nscf, --nscf_dir  -> <Optional> Path to nscf save folder
  -elph, --elph_dir  -> Path to elph_dir folder
  -y, --yambo_dir    -> <Optional> Path to yambo executables
  -e, --expand       -> <Optional> Expand gkkp databases

The necessary quantum espresso databases are stored in ELPH_SAVES/QE_SAVES/hBN.save (nscf calculation) and ELPH_SAVES/QE_SAVES/elph_dir (matrix elements from the dfpt calculation). For this tutorial we also need to expand the electron-phonon matrix elements to the full Brillouin zone. Since this is a different calculation with respect to the previous section, please generate this SAVE in a different directory than the one you used for the previous SAVE, which should be the current directory. For example:

$mkdir yambo-with-elph
$cd yambo-with-elph

Now we can run yambopy as in the instructions:

$yambopy gkkp -nscf ../ELPH_saves/QE_saves/hBN.save -elph ../ELPH_saves/QE_saves/elph_dir --expand

This should generate a yambo SAVE folder which contains the ndb.elph_gkkp_expanded* databases.

Electron-phonon intro old: plots of el-ph matrix elements on k-BZ and q-BZ

In this section we will use the script elph_plot.py and read the electron-phonon databases that you generated in the previous section.

In order to read the ndb.elph_gkkp_expanded* databases in python we use the Yambopy class YamboElectronPhononDB, which can be instanced like this:

yelph = YamboElectronPhononDB(ylat,folder_gkkp='path/to/elph/folder',save='path/to/SAVE')

(notice that it requires a previous instance of YamboLatticeDB).

Now, the yelph object contains phonon frequencies, phonon eigenvectors, qpoint information and, of course, the electron-phonon matrix elements g_{nm\nu}(k,q) where n, m are electron band states, \nu is a phonon branch, and k and q are the electronic and transfer momenta.

We can print the docstring of the YamboElectronPhononDB class with

print(yelph.__doc__)

to get an idea of the information stored and of its capabilities.

Now check the elph_plot.py script. You will see that it performs two plots:

• Plot of |g(k)| in the k-BZ for selected n,m,\nu and q [Kspace_Plot=True].
• Plot of |g(q)| in the q-BZ for selected n,m,\nu and k [Qspace_Plot=True].

You can change the electronic, phononic and momentum indices to see what happens.