The Yambo Project - User contributions [en]

First steps in Yambopy

2026-03-19T13:52:50Z

FulvioPaleari: /* Tutorials */

The yambopy project aims to develop python tools to:

* Read and edit yambo and quantum espresso input files
* Easily perform pre- and post-processing of the simulation data for these two codes - including hard-to-get, database-encoded data beyond standard outputs
* Provide easy visualization and plotting options
* Set up simple automatization workflows (e.g., convergence tests)

=== Setup ===
First of all, make sure that you have a suitable python environment (crated for example with [https://docs.anaconda.com/miniconda/install/ conda] or [https://docs.python.org/3/library/venv.html venv]) with '''python >=3.8'''.

If you are not used with python environments, here two simple commands that you can use
python -m venv MYPATH/yamboenv/
(you can replace `MYPATH` with any path you prefer, e.g. `~/`)
source MYPATH/yamboenv/bin/activate
(for bash users, you can add to your .bashrt the line `. MYPATH/yamboenv/bin/activate`)

Then, you may install yambopy in one of the following ways.

==== Quick installation from PyPI repository ====

* In order to quickly install the officially released version type:

pip install yambopy

==== Installation from tarball ====

* In case you don't want to download from the pip repository and prefer to install a version of yambopy locally, you may download the appropriate tarball from the [https://github.com/yambo-code/yambopy/releases| yambopy github page]. Extract the tarball, enter the yambopy folder and type <code>pip install .</code>

==== Installation of latest patch ====

* In case you want the latest version of the code including new updates and patches that might not be present in the official version, then you can clone the yambopy git repository (a basic knowledge of git may be helpful):

git clone https://github.com/yambo-code/yambopy.git
cd yambopy
pip install .

==== Installation for developers ====
* If you want to install YamboPy in developing mode (to modify or add new functions) you have to download the code from github repository then go in the YamboPy folder and install with the command:

pip install -e .

'''Important:''' if you want your changes to be included into a new patch/version of Yambopy, you need to first create your own personal fork of the git repository, make the changes there, and then create a pull request for the original repository.

==== Dependencies ====

* In principle, <code>pip</code> should take care of the required python dependencies. They are <code>numpy</code>, <code>scipy</code>, <code>matplotlib</code>, <code>netCDF4</code>, <code>h5py</code>, <code>lxml</code>, <code>PyYAML</code>, <code>monty</code>, <code>scikit-learn</code>, <code>tqdm</code>, <code>spglib</code>, <code>spgrep</code>, <code>pykdtree</code>, and <code>numba</code>. In case some dependency-related problem arises, you can install each of them separately beforehand with:

pip install <code>dependency-name</code>

* If you experience errors related to <code>NetCDF4</code> or <code>hdf5</code>, these are usually due to incompatibilities between the python modules the library in your environment. In this case, you can force the python installation to match the system library. For example, if you have an <code>hdf5</code> problem and you are using conda, you could try:

conda install --force-reinstall h5py hdf5

=== Tutorials ===
Now yambopy is ready to use! Just go to the tutorials folder and follow the docs!

cd tutorial/

On this wiki, we provide steps for the following tutorials:

1. Data postprocessing:
* [[Yambopy tutorial: band structures | Database and plotting tutorial for quantum espresso (qepy) and GW '''band structures''']] (Get the databases: [https://media.yambo-code.eu/educational/tutorials/files/databases_qepy.tar.gz databases_qepy], 46.5MB)
* [[Yambopy tutorial: Yambo databases | Database and plotting tutorial for yambo (yambopy) and '''exciton''' analysis ]] (Get the databases: [https://media.yambo-code.eu/educational/tutorials/files/databases_yambopy.tar.gz databases_yambopy], 99MB)
2. Manage QE and Yambo runs: [WARNING: these tutorials are currently under maintenance due to updates to the scheduler class]
* [[GW tutorial. Convergence and approximations (BN)]]
* [[Bethe-Salpeter equation tutorial. Optical absorption (BN)]]
3. Advanced topics:
* [[Yambopy tutorial: electron-phonon coupling|Databases and plotting tutorial for electron-phonon coupling with yambopy]] (Get the databases: [https://media.yambo-code.eu/educational/tutorials/files/yambopy_electron_phonon.tar.gz electron_phonon], 490M)
* [[Exciton-phonon coupling and luminescence]]
* [[Phonon-assisted luminescence by finite atomic displacements]]

=== How to cite ===
If yambopy helped you with your data analysis, workflow management of figure preparation, you can consider citing us.

The way to do so in BibTeX format is the following:
@misc{yambopy,
author = {Paleari, Fulvio and Molina-Sánchez, Alejandro and Nalabothula, Muralidhar and Reho, Riccardo and Bonacci, Miki and Castelo, José M. and Cervantes-Villanueva, Jorge and Pionteck, Mike and Silvetti, Martino and Attaccalite, Claudio and Pereira Coutada Miranda, Henrique},
title = {Yambopy},
month = mar,
year = 2025,
publisher = {Zenodo},
version = {0.4.0},
doi = {10.5281/zenodo.15012962},
url = {[[https://doi.org/10.5281/zenodo.15012962 https://doi.org/10.5281/zenodo.15012962]]}, }

First steps in Yambopy

2026-03-19T13:51:37Z

FulvioPaleari: /* Tutorials */

The yambopy project aims to develop python tools to:

* Read and edit yambo and quantum espresso input files
* Easily perform pre- and post-processing of the simulation data for these two codes - including hard-to-get, database-encoded data beyond standard outputs
* Provide easy visualization and plotting options
* Set up simple automatization workflows (e.g., convergence tests)

=== Setup ===
First of all, make sure that you have a suitable python environment (crated for example with [https://docs.anaconda.com/miniconda/install/ conda] or [https://docs.python.org/3/library/venv.html venv]) with '''python >=3.8'''.

If you are not used with python environments, here two simple commands that you can use
python -m venv MYPATH/yamboenv/
(you can replace `MYPATH` with any path you prefer, e.g. `~/`)
source MYPATH/yamboenv/bin/activate
(for bash users, you can add to your .bashrt the line `. MYPATH/yamboenv/bin/activate`)

Then, you may install yambopy in one of the following ways.

==== Quick installation from PyPI repository ====

* In order to quickly install the officially released version type:

pip install yambopy

==== Installation from tarball ====

* In case you don't want to download from the pip repository and prefer to install a version of yambopy locally, you may download the appropriate tarball from the [https://github.com/yambo-code/yambopy/releases| yambopy github page]. Extract the tarball, enter the yambopy folder and type <code>pip install .</code>

==== Installation of latest patch ====

* In case you want the latest version of the code including new updates and patches that might not be present in the official version, then you can clone the yambopy git repository (a basic knowledge of git may be helpful):

git clone https://github.com/yambo-code/yambopy.git
cd yambopy
pip install .

==== Installation for developers ====
* If you want to install YamboPy in developing mode (to modify or add new functions) you have to download the code from github repository then go in the YamboPy folder and install with the command:

pip install -e .

'''Important:''' if you want your changes to be included into a new patch/version of Yambopy, you need to first create your own personal fork of the git repository, make the changes there, and then create a pull request for the original repository.

==== Dependencies ====

* In principle, <code>pip</code> should take care of the required python dependencies. They are <code>numpy</code>, <code>scipy</code>, <code>matplotlib</code>, <code>netCDF4</code>, <code>h5py</code>, <code>lxml</code>, <code>PyYAML</code>, <code>monty</code>, <code>scikit-learn</code>, <code>tqdm</code>, <code>spglib</code>, <code>spgrep</code>, <code>pykdtree</code>, and <code>numba</code>. In case some dependency-related problem arises, you can install each of them separately beforehand with:

pip install <code>dependency-name</code>

* If you experience errors related to <code>NetCDF4</code> or <code>hdf5</code>, these are usually due to incompatibilities between the python modules the library in your environment. In this case, you can force the python installation to match the system library. For example, if you have an <code>hdf5</code> problem and you are using conda, you could try:

conda install --force-reinstall h5py hdf5

=== Tutorials ===
Now yambopy is ready to use! Just go to the tutorials folder and follow the docs!

cd tutorial/

On this wiki, we provide steps for the following tutorials:

1. Data postprocessing:
* [[Yambopy tutorial: band structures (including GW) | Database and plotting tutorial for quantum espresso (qepy) and GW '''band structures''']] (Get the databases: [https://media.yambo-code.eu/educational/tutorials/files/databases_qepy.tar.gz databases_qepy], 46.5MB)
* [[Yambopy tutorial: Yambo databases and exciton analysis | Database and plotting tutorial for yambo (yambopy) and '''exciton''' analysis ]] (Get the databases: [https://media.yambo-code.eu/educational/tutorials/files/databases_yambopy.tar.gz databases_yambopy], 99MB)
2. Manage QE and Yambo runs: [WARNING: these tutorials are currently under maintenance due to updates to the scheduler class]
* [[GW tutorial. Convergence and approximations (BN)]]
* [[Bethe-Salpeter equation tutorial. Optical absorption (BN)]]
3. Advanced topics:
* [[Yambopy tutorial: electron-phonon coupling|Databases and plotting tutorial for electron-phonon coupling with yambopy]] (Get the databases: [https://media.yambo-code.eu/educational/tutorials/files/yambopy_electron_phonon.tar.gz electron_phonon], 490M)
* [[Exciton-phonon coupling and luminescence]]
* [[Phonon-assisted luminescence by finite atomic displacements]]

=== How to cite ===
If yambopy helped you with your data analysis, workflow management of figure preparation, you can consider citing us.

The way to do so in BibTeX format is the following:
@misc{yambopy,
author = {Paleari, Fulvio and Molina-Sánchez, Alejandro and Nalabothula, Muralidhar and Reho, Riccardo and Bonacci, Miki and Castelo, José M. and Cervantes-Villanueva, Jorge and Pionteck, Mike and Silvetti, Martino and Attaccalite, Claudio and Pereira Coutada Miranda, Henrique},
title = {Yambopy},
month = mar,
year = 2025,
publisher = {Zenodo},
version = {0.4.0},
doi = {10.5281/zenodo.15012962},
url = {[[https://doi.org/10.5281/zenodo.15012962 https://doi.org/10.5281/zenodo.15012962]]}, }

Yambopy tutorial: Yambo databases

2026-03-13T15:28:55Z

FulvioPaleari: /* Exciton intro 1: read and sort data */

In this tutorial we will see some examples on how to read and analyse the data contained in the Yambo netCDF databases, which are not readily available as human readable outputs.

In particular we will take a look at:
* Lattice geometry data (Yambo database: <code>ns.db1</code>, Yambopy class: <code>YamboLatticeDB</code>).
* Dipole matrix elements (Yambo databases: <code>ndb.dipoles</code>, Yambopy class: <code>YamboDipolesDB</code>).
* Exciton energies, symmetries, wavefunctions and spectra (Yambo databases: <code>ndb.BS_diago_Q*</code>, Yambopy class: <code>YamboExcitonDB</code>).

We will also check the command line instructions to quickly generate yambo SAVE folders.

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

The full tutorial, including the Quantum espresso 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/databases_yambopy.tar.gz
$tar -xvzf databases_yambopy.tar.gz
$cd databases_yambopy

We will work with monolayer hexagonal boron nitride electron-phonon and exciton data obtained on a <code>12x12x1</code> kpoint grid. Beware that these are certainly not converged.

=== Command line: generating the Yambo SAVE ===
Yambopy offers a set of command line options. In order to review them, you can type
$yambopy
which will print the output
yambopy v0.7
Available commands are:

plotem1s -> Plot em1s calculation.
analysebse -> Study the convergence of BSE calculations.
analysegw -> Study the convergence of GW calculations by looking at the change in band-gap value.
plotexcitons -> Plot excitons calculation.
addqp -> Add corrections from QP databases.
mergeqp -> Merge QP databases.
save -> Produce a SAVE folder.
gkkp -> Produce a SAVE folder including elph_gkkp databases.
bands -> Script to produce band structure data and visualization from QE.
serial -> Script to update serial numbers of yambo ndb.* databases in order to import them to new calculations.
gwsubspace -> Script to calculate off-diago corrections of yambo ndb.QP databases in order to plot band structure.
phinp -> Script to update the explicit list of q-points in a ph input file (ldisp=.false., qplot=.true.).
convert -> Script to convert RL number in Ry energy units using ndb.gops.
bsesize -> Script to calculate the expected BSE kernel size, in GB, to be loaded by each MPI task.
l2y -> Calculate gauge-invariant electron-phonon matrix elements with LetzElPhC and convert them into Yambo format.
exc-irrep -> Script to get the irreducible representation labels for excitonic states. [-h for help]
exc-wf -> Real space exciton wf for either fixed hole/electron. [-h for help]
exc-sort -> Script to sort excitonic states according to energies and intensities. [-h for help]

For this tutorial, we will need the <code>save</code> and <code>gkkp</code> options.
By typing in one of these, additional information about how to run the commands will be printed, e.g.:
$yambopy save

Produce a SAVE folder

Arguments are:
-nscf, --nscf_dir -> Path to nscf save folder
-y, --yambo_dir -> <Optional> Path to yambo executables

The quantum espresso save for hBN is provided in the directory <code>BSE_saves/QE_saves/hBN.save</code> (you can check the contents of the various folders).
Then, following the instructions printed on screen, we can generate a yambo SAVE from the hBN.save by typing

$yambopy save -nscf BSE_saves/QE_saves/hBN.save

This should produce a SAVE folder in the current directory.

=== Lattice intro: plot k-point coordinates in IBZ/BZ ===
For this section we will use the script <code>bz_plot.py</code>.

By inspecting the SAVE folder we have just generated, we will find the <code>ns.db1</code> database which contains all the geometry and lattice information.
We are now going to read it in python by using the Yambopy class <code>YamboLatticeDB</code>, which can be instanced like this:

from yambopy import YamboLatticeDB
ylat = YamboLatticeDB.from_db_file(filename="PATH/TO/SAVE/ns.db1")
(remember to edit the variable <code>save_path</code> in order to point at your yambo SAVE).

The <code>ylat</code> object now contains many useful information as attributes, such as the k-points in Cartesian or crystal coordinates, the system symmetries, lattice constants and basis vectors in real and reciprocal space, etc.
The k-points are also automatically expanded in the full Brillouin zone from the irreducible one (you can turn this off with the option <code>Expand=False</code>).

Directly printing the object with
print(ylat)
will also give us some general parameters related to the database.

Now check the <code>bz_plot.py</code> script. You will see that it performs three plots:
* Scatterplot of the k-points in Cartesian coordinates with both expanded and unexpanded grids, with annotated indices [<code>Cartesian_Plot=True</code>].
* Scatterplot of the k-points in crystal coordinates [<code>Crystal_Plot=True</code>].
* Manual transformation of a chosen k-point from irreducible to full Brillouin zone (you can change the index <code>i_k</code> in the script to check different cases) [<code>Symmetry_Plot=True</code>].

Below, the result of the first plot.

[[File:Car kpoints hbn.jpg|YamboLatticeDB plot from yambopy tutorial| 500px]]

'''What about the units?'''

Below we report the relation between units used in Yambo, Quantum Espresso, and Yambopy.

* bohr^-1 (atomic units): <code>YamboLatticeDB.car_kpoints*2.*pi</code>. Divide by the bohr-to-angstrom conversion factor to obtain angs^-1
* Yambo cartesian units (<code>[cc]</code> in Yambo outputs): <code>YamboLatticeDB.car_kpoints*2.*pi</code> (same as above).
* QE cartesian units (<code>[cart. coord. in units 2pi/alat]</code> in QE outputs): <code>YamboLatticeDB.car_kpoints*YamboLatticeDB.alat[0]</code>.
* Internal yambo units (<code>[iku]</code> in yambo outputs): <code>YamboLatticeDB.iku_kpoints</code>
* Fractional coordinates (<code>[rlu]</code> in yambo, <code>cryst. coord.</code> in QE): <code>YamboLatticeDB.red_kpoints</code>.

=== Dipoles intro: plots of dipoles on BZ, plot of IP absorption ===
In this section we will use the script <code>dipoles_plot.py</code> and read the dipole databases generated in an optical absorption calculation by yambo. Keep in mind that from now on we will use the "BSE" yambo SAVE generated in the [[#Command line: generating the Yambo SAVE|first section]].

The databases written after a calculation of optical properties with yambo (dipoles, static screening, excitons) are in the directory <code>BSE_saves/BSE_databases</code>. Here we will also find <code>ndb.dipoles</code> which is needed now, since it contains the matrix elements d_{vck}(\alpha) where vk and ck are the valence and electron states involved in the transition and \alpha the polarisation direction of the external electric field.

In order to read it in python we use the Yambopy class <code>YamboDipolesDB</code>, which can be instanced like this:
ydip = YamboDipolesDB(ylat,save='path/to/BSE/databases',filename='ndb.dipoles')
(notice that it requires a previous instance of <code>YamboLatticeDB</code>).

In addition, in order to read the Kohn-Sham energies, we can also instance the <code>YamboElectronsDB</code> as
yel = YamboElectronsDB.from_db_file(folder='path/to/SAVE')

The object <code>ydip</code> now has a method that permits to retrieve the independent-particle absorption spectrum with customly chosen energy range, steps, and broadening:
w, eps2 = ydip.ip_eps2(yel)

In order to see all this in action, take a look at the <code>dipoles_plot.py</code> script. You will see that it performs two plots:
* Plot of |d(k)| in the BZ for selected v,c and \alpha (we choose the layer plane 'xy') [<code>Kspace_Plot=True</code>]. From this plot you can appreciate which sections of the BZ contribute the most to the absorption rate.
* Plot of the independent-particles absorption spectrum [<code>Absorption_Plot=True</code>].

You can play with the indices and the plot parameters to check what happens.

[[File:Dipoles hbn2.png|YamboDipolesDB plot from yambopy tutorial|500px]]

=== Exciton intro 1: read and sort data ===
In this section we will use both the script <code>exc_read.py</code> and the command line in order to read the exciton data resulting from a BSE calculation to familiarise with their structure. This time we are going to read the <code>ndb.BS_diago_Q*</code> databases which correspond to BSE calculations at various momenta Q (Q=1 being the zero-momentum optical absorption limit - notice that python indexing starts from 0, while the databases are counted starting from 1).

In order to read them in python we use the Yambopy class <code>YamboExcitonDB</code>, which can be instanced like this:
yexc = YamboExcitonDB.from_db_file(ylat,filename=f'path/to/BSE/databases/ndb.BS_diago_Q{i}')
(where i is the number of BS_diago_Qi file. Notice that it requires a previous instance of <code>YamboLatticeDB</code>).

Now the <code>yexc</code> object contains information about the exciton energies (<code>yexc.eigenvalues</code>), wave functions (<code>yexc.eigenvectors</code>) and intensities (<code>yexc.l_residuals</code>, <code>yexc.r_residuals</code>) for Qpoint i_Q. You can start by keeping <code>Q1</code> which is the optical limit and then check other momenta.

The exciton wave function components A_{vck}^{\lambda Q} (\lambda being the exciton index) are stored as A_{t}^{\lambda} in each Q-dependent database, with t being the transition index grouping the single-particle indices vck. Therefore, <code>yexc.eigenvectors</code> is an array with (N_excitons,N_transitions) dimension. In order to make the connection t->kcv, the table <code>yexc.table</code> provides k,v,c and spin indices corresponding to each transition.

In order to get a clearer picture, take a look at the script <code>exc_read.py</code>. Run it and try to understand the outputs.
$ python exc_read.py

Actually, we can produce output files with the sorted exciton energies in a much more convenient way by using the command line instruction <code>exc-sort</code>. Check its syntax via:
$ yambopy exc-sort -h

Then, we run it for our specific calculation with:
$ yambopy exc-sort --save BSE_saves/YAMBO_saves/SAVE -J BSE_saves/BSE_databases --iqpt 1

Recall that that the path given to <code>--save</code> must be the directory that contains the <code>ns.db1</code> yambo database (usually called... <code>SAVE</code>). The path given to <code>-J</code> must be the directory that contains the results of the BSE calculation, namely the <code>ndb.BS_diago_Q1</code> file. The final argument is the center-of-mass momentum of the exciton. In a standard absorption calculation, you only need the first Q-point which describes vertical electronic transitions. However, if you calculate the exciton dispersion, you will produce a <code>ndb.BS_diago_QN</code> at each momentum index N that you selected for the yambo BSE calculation.

This command should produce the <code>o-BSE_databases.exc_qpt1_sorted_E.dat</code> and <code>o-BSE_databases.exc_qpt1_sorted_I.dat</code> output files for you to inspect. These are very useful as they allow for identification of degenerate states and degree of optical activity. You will see that in our system most states are doubly degenerate, a byproduct of crystal symmetry. This is an updated version of the ypp exciton analysis that you can find [[How to analyse excitons#Sort the excitonic eigenvalues|here]].

=== Exciton intro 2: symmetry analysis and wavefunction plot in real space ===

==== Symmetries of excitons====
We can analyse the symmetries of the excitonic wavefunctions in terms of irreducible representation of the point group of the system (if at Q=0) or the Q little group. For more information, the methodology is explained in Ref. <ref>Symmetries of excitons, M. Nalabothula et al., [https://arxiv.org/abs/2511.21540 preprint arXiv]</ref>.

We use the <code>exc-irrep</code> command line option, check the arguments with:
$ yambopy exc-irrep -h

We know from the previous section (by inspecting the sorted energies) that the first four BSE eigenvalues correspond to two doubly-degenerate bright states. Let us analyse their symmetry by running
$ yambopy exc-irrep --path BSE_saves/YAMBO_saves -J BSE_saves/BSE_databases --iqpt 1 --nstates 4

This command first loads the electronic wave functions and calculated the electronic representation matrices (called <code>Dmats</code> in the code). As a second step, they are used to compute the '''excitonic''' representation matrices.

We obtain the following output:

========================================
Group theory analysis for Q point : (0.000000, 0.000000, 0.000000)
****************************************
Little group : D3h
Little group symmetries : [ 1 2 3 4 5 6 7 8 9 10 11 12]
Classes (symmetry indices in each class):
E : [1]
2S_3 : [2 6]
2C_3 : [3 5]
sigma_h : [4]
3C_2 : [ 7 9 11]
3sigma_v : [ 8 10 12]

====== Exciton representations ======
Energy (eV), degeneracy : representation
----------------------------------------
1.9139 2 : E'
2.5988 2 : E'
****************************************

This is similar to the group theory analysis done by Quantum Espresso on the electronic states, and is actually analogous to the one performed for the phonon modes of crystals. We see that the first two states transform as the E' representation of the D3h point group of the crystal. By optical selection rules, only states with this symmetry can form absorption peaks in monolayer BN when light is polarized along the layer plane.

We could go further and calculate the total crystal angular momentum of these states, while also rotate the degenerate exciton states so that they are both eigenvectors of the BSE Hamiltonian and the total crystal angular momentum operator. This is very useful for analyses involving selection rules, exciton-boson couplings, chirality, etc. This is an advanced topic and will not be covered, nonetheless an example script is provided in the tutorial folder called <code>total_crystal_angular_momentum_exciton.py</code>.

''' What to do when symmetry analysis does not seem to work well '''

* Check for warnings during execution. If the BSE calculation was done with a response function that breaks the symmetries (such as the longitudinal response in place of the transverse one at q=0), that may explain the issues.

* If the exciton density of states is very high (such as for a bulk 3D system or for a 2D system at higher energies in the optical spectrum), the analyser may fail to resolve degenerate states, and incorporate a bunch of states together. The symmetry analysis will still be performed but the representation labels will appear as summed. In severe cases, the code may crash. You can try to get a better result by carefully selecting the degeneracy tolerance with <code>degen_tol</code> and restricting the number of states with <code>nstates</code> in the command line options.

====Exciton wave functions in real space====
We can also plot the wave functions of the exciton states on the crystal lattice. In practice, what we do is set the position of the hole at a "physical" point, and then visualize the resulting electronic distribution:

<math>I^{e}_{\lambda \mathbf{Q}}(\mathbf{r}_e)= |\Psi_{\alpha \mathbf{Q}}(\mathbf{r}_e,\mathbf{r}_h=\mathbf{r}_0)|^2</math>

Let us focus on the lowest exciton state, which gives rise to the largest peak in absorption (see the last part of the tutorial). We will set the hole position on top of a nitrogen atom, since that's where the <math>p_z</math> orbitals where the hole comes from are mostly localized.

If we don't know the correct coordinates, we can modify the <code>bz_plot.py</code> script by adding (after instancing the lattice object):
for iat in range(len(ylat.atomic_numbers)): print(ylat.atomic_numbers[iat],ylat.red_atomic_positions[iat])
which will print
5 [0.6666667 0.3333333 0. ]
7 [-0.6666667 -0.3333333 0. ]

In order to make the plot, we have to give yambopy the same inputs that are used in the equivalent [[How to analyse excitons#Plot the exciton spatial distribution| ypp calculation]]. First, let's check all the options via
$ yambopy exc-wf -h

Then, we can run our calculation (by selecting a 9x9x1 supercell and a 30 Ry cutoff) as
$ yambopy exc-wf --path BSE_saves/YAMBO_saves -J BSE_saves/BSE_databases --iqpt 1 --iexe 1 --supercell 9 9 1 --wfc_cutoff 30 --hole 0.33333333 0.66666667 0.03

Yambopy will produce a *.cube file that can be visualized with VESTA, xcrysden or the like, producing a figure similar to the one below.

The example script <code>exc_real_wf.py</code>, which runs the same calculation by explicitly calling the necessary functions, will give you more info about what is happening behind the scenes.

[[File:Exc BN yambopy.png|YamboExcitonDB exciton wave function|400px]]

We see that electron is localised in <math>p_z</math>-like distributions on top of boron atoms around the nitrogen where the hole is set.

=== Exciton intro 3: plot exciton weights on k-BZ and (interpolated) band structure ===
In this section we will use the script <code>exc_kspace_plot.py</code> and work with the quantities defined in the previous section.

For now, only the i_Q=0 case is implemented in this section.
We want to check the relative importance of the various (vk->ck) electronic transitions in forming a certain excitonic state.

Since many excitonic states are degenerate, we first need to tell Yambopy which states we want to check. For example, in monolayer hexagonal boron nitride, the lowest-bound exciton - forming the main peak in the BSE absorption spectrum - is doubly degenerate. In order to analyse it, in the <code>exc_kspace_plot.py</code> script we set
states = [1,2]
(we can also set [3,4] to check the second excitonic state, and then [5] for the non-degenerate third state, and so on; we can check degeneracies by printing the energies using the script <code>exc_read.py</code>).

In order to make a band structure plot, it is necessary to read the band energies, for example with the <code>YamboSaveDB</code> class
yel = YamboSaveDB.from_db_file(folder='path/to/SAVE')
and specify the path in the BZ using crystal coordinates via the <code>Path</code> function:
npoints = 20
path = Path([ [[ 0.0, 0.0, 0.0],'$\Gamma$'],
[[ 0.5, 0.0, 0.0],'M'],
[[1./3.,1./3., 0.0],'K'],
[[ 0.0, 0.0, 0.0],'$\Gamma$']],
[int(npoints*2),int(npoints),int(sqrt(5)*npoints)] )

Now let's take a closer look at the <code>exc_kspace_plot.py</code> script. You will see that it performs three plots:
* Plot of |A(k)| in the k-BZ for the selected exciton state. You can see how most contributions come from the area around K and the MK direction [<code>Kspace_Plot=True</code>].
* Plot of |A(v,c,k)| on the electronic band structure for the selected exciton state. Here you can better see how the top valence and bottom conduction around MK are mostly involved [<code>Bands_Plot=True</code>].
* Plot of interpolated |A(v,c,k)| on the interpolated electronic band structure for the selected exciton state [<code>Bands_Plot_Interpolated=True</code>].

As always, try to play with the parameters, for example by changing the excitonic states to analyse.

[[File:Exc bands1 hbn.jpg|YamboExcitonDB plot from yambopy tutorial|300px| Uninterpolated exciton weights on top of band structure]][[File:Exc bands2 hbn.jpg|YamboExcitonDB plot from yambopy tutorial|300px]]

=== Exciton intro 4: plot BSE optical absorption with custom options ===
In this section we will use the script <code>exc_abs_plot.py</code> and work with the quantities defined in the previous sections.

The class <code>YamboExcitonDB</code> also enables us, of course, to read the dielectric function eps(w) and print absorption and related spectra in python.

The advantages over using the standard human-readable yambo outputs are mainly two:
# We can freely select energy ranges, energy steps, peak broadenings and number of excitonic states included without having to rerun the <code>yambo</code> executable every time. This reduces the chance of mistakenly editing the yambo input and allows for greater freedom since these plots can now be done in your local machine without having to transfer the output data from a remote cluster.
# The dielectric function constructed from netCDF database variables has a much higher precision (number of significant digits) than the human readable output, which may be important if you want to perform additional operations in python (e.g., computing refractive index, reflectivity and other optical spectra from it, performing finite-difference derivatives, etc).

We can read eps(w) as a <code>numpy</code> array with the specified options as (energy values are in eV):
w, eps = yexc.get_chi(nexcitons='all',emin=0,emax=7,estep=0.005,broad=0.04)
Or, you can directly prepare a plot of its imaginary part with
w, chi = yexc.plot_chi_ax(ax,nexcitons='all',emin=0,emax=7,estep=0.005,broad=0.04)
where <code>ax</code> is a previously defined <code>Axes</code> object from <code>matplotlib</code>.

In order to see how this works, let's take a look at the <code>exc_abs_plot.py</code> script.
You will see that it performs the two operations described above:
* Plotting the BSE absorption spectrum [<code>Absorption_Plot=True</code>].
* Reading the complex dielectric function.

Try to customise the plots by changing the <code>nexcitons</code>, <code>emin</code>, <code>emax</code>, <code>estep</code>, <code>broad</code> parameters.

[[File:Absalpha.png|Yambo alpha_2D tutorial plot|700px]]

==Links==
* Back to [[Rome 2023#Tutorials]]
* Back to [[ICTP 2022#Tutorials]]

==References==

Yambopy tutorial: Yambo databases

2026-03-13T15:25:59Z

FulvioPaleari: /* Exciton intro 1: read and sort data */

In this tutorial we will see some examples on how to read and analyse the data contained in the Yambo netCDF databases, which are not readily available as human readable outputs.

In particular we will take a look at:
* Lattice geometry data (Yambo database: <code>ns.db1</code>, Yambopy class: <code>YamboLatticeDB</code>).
* Dipole matrix elements (Yambo databases: <code>ndb.dipoles</code>, Yambopy class: <code>YamboDipolesDB</code>).
* Exciton energies, symmetries, wavefunctions and spectra (Yambo databases: <code>ndb.BS_diago_Q*</code>, Yambopy class: <code>YamboExcitonDB</code>).

We will also check the command line instructions to quickly generate yambo SAVE folders.

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

The full tutorial, including the Quantum espresso 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/databases_yambopy.tar.gz
$tar -xvzf databases_yambopy.tar.gz
$cd databases_yambopy

We will work with monolayer hexagonal boron nitride electron-phonon and exciton data obtained on a <code>12x12x1</code> kpoint grid. Beware that these are certainly not converged.

=== Command line: generating the Yambo SAVE ===
Yambopy offers a set of command line options. In order to review them, you can type
$yambopy
which will print the output
yambopy v0.7
Available commands are:

plotem1s -> Plot em1s calculation.
analysebse -> Study the convergence of BSE calculations.
analysegw -> Study the convergence of GW calculations by looking at the change in band-gap value.
plotexcitons -> Plot excitons calculation.
addqp -> Add corrections from QP databases.
mergeqp -> Merge QP databases.
save -> Produce a SAVE folder.
gkkp -> Produce a SAVE folder including elph_gkkp databases.
bands -> Script to produce band structure data and visualization from QE.
serial -> Script to update serial numbers of yambo ndb.* databases in order to import them to new calculations.
gwsubspace -> Script to calculate off-diago corrections of yambo ndb.QP databases in order to plot band structure.
phinp -> Script to update the explicit list of q-points in a ph input file (ldisp=.false., qplot=.true.).
convert -> Script to convert RL number in Ry energy units using ndb.gops.
bsesize -> Script to calculate the expected BSE kernel size, in GB, to be loaded by each MPI task.
l2y -> Calculate gauge-invariant electron-phonon matrix elements with LetzElPhC and convert them into Yambo format.
exc-irrep -> Script to get the irreducible representation labels for excitonic states. [-h for help]
exc-wf -> Real space exciton wf for either fixed hole/electron. [-h for help]
exc-sort -> Script to sort excitonic states according to energies and intensities. [-h for help]

For this tutorial, we will need the <code>save</code> and <code>gkkp</code> options.
By typing in one of these, additional information about how to run the commands will be printed, e.g.:
$yambopy save

Produce a SAVE folder

Arguments are:
-nscf, --nscf_dir -> Path to nscf save folder
-y, --yambo_dir -> <Optional> Path to yambo executables

The quantum espresso save for hBN is provided in the directory <code>BSE_saves/QE_saves/hBN.save</code> (you can check the contents of the various folders).
Then, following the instructions printed on screen, we can generate a yambo SAVE from the hBN.save by typing

$yambopy save -nscf BSE_saves/QE_saves/hBN.save

This should produce a SAVE folder in the current directory.

=== Lattice intro: plot k-point coordinates in IBZ/BZ ===
For this section we will use the script <code>bz_plot.py</code>.

By inspecting the SAVE folder we have just generated, we will find the <code>ns.db1</code> database which contains all the geometry and lattice information.
We are now going to read it in python by using the Yambopy class <code>YamboLatticeDB</code>, which can be instanced like this:

from yambopy import YamboLatticeDB
ylat = YamboLatticeDB.from_db_file(filename="PATH/TO/SAVE/ns.db1")
(remember to edit the variable <code>save_path</code> in order to point at your yambo SAVE).

The <code>ylat</code> object now contains many useful information as attributes, such as the k-points in Cartesian or crystal coordinates, the system symmetries, lattice constants and basis vectors in real and reciprocal space, etc.
The k-points are also automatically expanded in the full Brillouin zone from the irreducible one (you can turn this off with the option <code>Expand=False</code>).

Directly printing the object with
print(ylat)
will also give us some general parameters related to the database.

Now check the <code>bz_plot.py</code> script. You will see that it performs three plots:
* Scatterplot of the k-points in Cartesian coordinates with both expanded and unexpanded grids, with annotated indices [<code>Cartesian_Plot=True</code>].
* Scatterplot of the k-points in crystal coordinates [<code>Crystal_Plot=True</code>].
* Manual transformation of a chosen k-point from irreducible to full Brillouin zone (you can change the index <code>i_k</code> in the script to check different cases) [<code>Symmetry_Plot=True</code>].

Below, the result of the first plot.

[[File:Car kpoints hbn.jpg|YamboLatticeDB plot from yambopy tutorial| 500px]]

'''What about the units?'''

Below we report the relation between units used in Yambo, Quantum Espresso, and Yambopy.

* bohr^-1 (atomic units): <code>YamboLatticeDB.car_kpoints*2.*pi</code>. Divide by the bohr-to-angstrom conversion factor to obtain angs^-1
* Yambo cartesian units (<code>[cc]</code> in Yambo outputs): <code>YamboLatticeDB.car_kpoints*2.*pi</code> (same as above).
* QE cartesian units (<code>[cart. coord. in units 2pi/alat]</code> in QE outputs): <code>YamboLatticeDB.car_kpoints*YamboLatticeDB.alat[0]</code>.
* Internal yambo units (<code>[iku]</code> in yambo outputs): <code>YamboLatticeDB.iku_kpoints</code>
* Fractional coordinates (<code>[rlu]</code> in yambo, <code>cryst. coord.</code> in QE): <code>YamboLatticeDB.red_kpoints</code>.

=== Dipoles intro: plots of dipoles on BZ, plot of IP absorption ===
In this section we will use the script <code>dipoles_plot.py</code> and read the dipole databases generated in an optical absorption calculation by yambo. Keep in mind that from now on we will use the "BSE" yambo SAVE generated in the [[#Command line: generating the Yambo SAVE|first section]].

The databases written after a calculation of optical properties with yambo (dipoles, static screening, excitons) are in the directory <code>BSE_saves/BSE_databases</code>. Here we will also find <code>ndb.dipoles</code> which is needed now, since it contains the matrix elements d_{vck}(\alpha) where vk and ck are the valence and electron states involved in the transition and \alpha the polarisation direction of the external electric field.

In order to read it in python we use the Yambopy class <code>YamboDipolesDB</code>, which can be instanced like this:
ydip = YamboDipolesDB(ylat,save='path/to/BSE/databases',filename='ndb.dipoles')
(notice that it requires a previous instance of <code>YamboLatticeDB</code>).

In addition, in order to read the Kohn-Sham energies, we can also instance the <code>YamboElectronsDB</code> as
yel = YamboElectronsDB.from_db_file(folder='path/to/SAVE')

The object <code>ydip</code> now has a method that permits to retrieve the independent-particle absorption spectrum with customly chosen energy range, steps, and broadening:
w, eps2 = ydip.ip_eps2(yel)

In order to see all this in action, take a look at the <code>dipoles_plot.py</code> script. You will see that it performs two plots:
* Plot of |d(k)| in the BZ for selected v,c and \alpha (we choose the layer plane 'xy') [<code>Kspace_Plot=True</code>]. From this plot you can appreciate which sections of the BZ contribute the most to the absorption rate.
* Plot of the independent-particles absorption spectrum [<code>Absorption_Plot=True</code>].

You can play with the indices and the plot parameters to check what happens.

[[File:Dipoles hbn2.png|YamboDipolesDB plot from yambopy tutorial|500px]]

=== Exciton intro 1: read and sort data ===
In this section we will use both the script <code>exc_read.py</code> and the command line in order to read the exciton data resulting from a BSE calculation to familiarise with their structure. This time we are going to read the <code>ndb.BS_diago_Q*</code> databases which correspond to BSE calculations at various momenta Q (Q=1 being the zero-momentum optical absorption limit - notice that python indexing starts from 0, while the databases are counted starting from 1).

In order to read them in python we use the Yambopy class <code>YamboExcitonDB</code>, which can be instanced like this:
yexc = YamboExcitonDB.from_db_file(ylat,filename=f'path/to/BSE/databases/ndb.BS_diago_Q{i}')
(where i is the number of BS_diago_Qi file. Notice that it requires a previous instance of <code>YamboLatticeDB</code>).

Now the <code>yexc</code> object contains information about the exciton energies (<code>yexc.eigenvalues</code>), wave functions (<code>yexc.eigenvectors</code>) and intensities (<code>yexc.l_residuals</code>, <code>yexc.r_residuals</code>) for Qpoint i_Q. You can start by keeping <code>Q1</code> which is the optical limit and then check other momenta.

The exciton wave function components A_{vck}^{\lambda Q} (\lambda being the exciton index) are stored as A_{t}^{\lambda} in each Q-dependent database, with t being the transition index grouping the single-particle indices vck. Therefore, <code>yexc.eigenvectors</code> is an array with (N_excitons,N_transitions) dimension. In order to make the connection t->kcv, the table <code>yexc.table</code> provides k,v,c and spin indices corresponding to each transition.

In order to get a clearer picture, take a look at the script <code>exc_read.py</code>. Run it and try to understand the outputs.
$ python exc_read.py

Actually, we can produce output files with the sorted exciton energies in a much more convenient way by using the command line instruction <code>exc-sort</code>. Check its syntax via:
$ yambopy exc-sort -h

Then, we run it for our specific calculation with:
$ yambopy exc-sort --save BSE_saves/YAMBO_saves/SAVE -J BSE_saves/BSE_databases --iqpt 1

Recall that that the path given <code>--save</code> must be the directory that contains the <code>ns.db1</code> yambo database (usually called... <code>SAVE</code>). The path given to <code>-J</code> must be the directory that cotains the results of the BSE calculation, namely the <code>ndb.BS_diago_Q1</code> file.
This should produce the <code>o-BSE_databases.exc_qpt1_sorted_E.dat</code> and <code>o-BSE_databases.exc_qpt1_sorted_I.dat</code> output files for you to inspect. These are very useful as they allow for identification of degenerate states and degree of optical activity. You will see that in our system most states are doubly degenerate, a byproduct of crystal symmetry. This is an updated version of the ypp exciton analysis that you can find [[How to analyse excitons#Sort the excitonic eigenvalues|here]].

=== Exciton intro 2: symmetry analysis and wavefunction plot in real space ===

==== Symmetries of excitons====
We can analyse the symmetries of the excitonic wavefunctions in terms of irreducible representation of the point group of the system (if at Q=0) or the Q little group. For more information, the methodology is explained in Ref. <ref>Symmetries of excitons, M. Nalabothula et al., [https://arxiv.org/abs/2511.21540 preprint arXiv]</ref>.

We use the <code>exc-irrep</code> command line option, check the arguments with:
$ yambopy exc-irrep -h

We know from the previous section (by inspecting the sorted energies) that the first four BSE eigenvalues correspond to two doubly-degenerate bright states. Let us analyse their symmetry by running
$ yambopy exc-irrep --path BSE_saves/YAMBO_saves -J BSE_saves/BSE_databases --iqpt 1 --nstates 4

This command first loads the electronic wave functions and calculated the electronic representation matrices (called <code>Dmats</code> in the code). As a second step, they are used to compute the '''excitonic''' representation matrices.

We obtain the following output:

========================================
Group theory analysis for Q point : (0.000000, 0.000000, 0.000000)
****************************************
Little group : D3h
Little group symmetries : [ 1 2 3 4 5 6 7 8 9 10 11 12]
Classes (symmetry indices in each class):
E : [1]
2S_3 : [2 6]
2C_3 : [3 5]
sigma_h : [4]
3C_2 : [ 7 9 11]
3sigma_v : [ 8 10 12]

====== Exciton representations ======
Energy (eV), degeneracy : representation
----------------------------------------
1.9139 2 : E'
2.5988 2 : E'
****************************************

This is similar to the group theory analysis done by Quantum Espresso on the electronic states, and is actually analogous to the one performed for the phonon modes of crystals. We see that the first two states transform as the E' representation of the D3h point group of the crystal. By optical selection rules, only states with this symmetry can form absorption peaks in monolayer BN when light is polarized along the layer plane.

We could go further and calculate the total crystal angular momentum of these states, while also rotate the degenerate exciton states so that they are both eigenvectors of the BSE Hamiltonian and the total crystal angular momentum operator. This is very useful for analyses involving selection rules, exciton-boson couplings, chirality, etc. This is an advanced topic and will not be covered, nonetheless an example script is provided in the tutorial folder called <code>total_crystal_angular_momentum_exciton.py</code>.

''' What to do when symmetry analysis does not seem to work well '''

* Check for warnings during execution. If the BSE calculation was done with a response function that breaks the symmetries (such as the longitudinal response in place of the transverse one at q=0), that may explain the issues.

* If the exciton density of states is very high (such as for a bulk 3D system or for a 2D system at higher energies in the optical spectrum), the analyser may fail to resolve degenerate states, and incorporate a bunch of states together. The symmetry analysis will still be performed but the representation labels will appear as summed. In severe cases, the code may crash. You can try to get a better result by carefully selecting the degeneracy tolerance with <code>degen_tol</code> and restricting the number of states with <code>nstates</code> in the command line options.

====Exciton wave functions in real space====
We can also plot the wave functions of the exciton states on the crystal lattice. In practice, what we do is set the position of the hole at a "physical" point, and then visualize the resulting electronic distribution:

<math>I^{e}_{\lambda \mathbf{Q}}(\mathbf{r}_e)= |\Psi_{\alpha \mathbf{Q}}(\mathbf{r}_e,\mathbf{r}_h=\mathbf{r}_0)|^2</math>

Let us focus on the lowest exciton state, which gives rise to the largest peak in absorption (see the last part of the tutorial). We will set the hole position on top of a nitrogen atom, since that's where the <math>p_z</math> orbitals where the hole comes from are mostly localized.

If we don't know the correct coordinates, we can modify the <code>bz_plot.py</code> script by adding (after instancing the lattice object):
for iat in range(len(ylat.atomic_numbers)): print(ylat.atomic_numbers[iat],ylat.red_atomic_positions[iat])
which will print
5 [0.6666667 0.3333333 0. ]
7 [-0.6666667 -0.3333333 0. ]

In order to make the plot, we have to give yambopy the same inputs that are used in the equivalent [[How to analyse excitons#Plot the exciton spatial distribution| ypp calculation]]. First, let's check all the options via
$ yambopy exc-wf -h

Then, we can run our calculation (by selecting a 9x9x1 supercell and a 30 Ry cutoff) as
$ yambopy exc-wf --path BSE_saves/YAMBO_saves -J BSE_saves/BSE_databases --iqpt 1 --iexe 1 --supercell 9 9 1 --wfc_cutoff 30 --hole 0.33333333 0.66666667 0.03

Yambopy will produce a *.cube file that can be visualized with VESTA, xcrysden or the like, producing a figure similar to the one below.

The example script <code>exc_real_wf.py</code>, which runs the same calculation by explicitly calling the necessary functions, will give you more info about what is happening behind the scenes.

[[File:Exc BN yambopy.png|YamboExcitonDB exciton wave function|400px]]

We see that electron is localised in <math>p_z</math>-like distributions on top of boron atoms around the nitrogen where the hole is set.

=== Exciton intro 3: plot exciton weights on k-BZ and (interpolated) band structure ===
In this section we will use the script <code>exc_kspace_plot.py</code> and work with the quantities defined in the previous section.

For now, only the i_Q=0 case is implemented in this section.
We want to check the relative importance of the various (vk->ck) electronic transitions in forming a certain excitonic state.

Since many excitonic states are degenerate, we first need to tell Yambopy which states we want to check. For example, in monolayer hexagonal boron nitride, the lowest-bound exciton - forming the main peak in the BSE absorption spectrum - is doubly degenerate. In order to analyse it, in the <code>exc_kspace_plot.py</code> script we set
states = [1,2]
(we can also set [3,4] to check the second excitonic state, and then [5] for the non-degenerate third state, and so on; we can check degeneracies by printing the energies using the script <code>exc_read.py</code>).

In order to make a band structure plot, it is necessary to read the band energies, for example with the <code>YamboSaveDB</code> class
yel = YamboSaveDB.from_db_file(folder='path/to/SAVE')
and specify the path in the BZ using crystal coordinates via the <code>Path</code> function:
npoints = 20
path = Path([ [[ 0.0, 0.0, 0.0],'$\Gamma$'],
[[ 0.5, 0.0, 0.0],'M'],
[[1./3.,1./3., 0.0],'K'],
[[ 0.0, 0.0, 0.0],'$\Gamma$']],
[int(npoints*2),int(npoints),int(sqrt(5)*npoints)] )

Now let's take a closer look at the <code>exc_kspace_plot.py</code> script. You will see that it performs three plots:
* Plot of |A(k)| in the k-BZ for the selected exciton state. You can see how most contributions come from the area around K and the MK direction [<code>Kspace_Plot=True</code>].
* Plot of |A(v,c,k)| on the electronic band structure for the selected exciton state. Here you can better see how the top valence and bottom conduction around MK are mostly involved [<code>Bands_Plot=True</code>].
* Plot of interpolated |A(v,c,k)| on the interpolated electronic band structure for the selected exciton state [<code>Bands_Plot_Interpolated=True</code>].

As always, try to play with the parameters, for example by changing the excitonic states to analyse.

[[File:Exc bands1 hbn.jpg|YamboExcitonDB plot from yambopy tutorial|300px| Uninterpolated exciton weights on top of band structure]][[File:Exc bands2 hbn.jpg|YamboExcitonDB plot from yambopy tutorial|300px]]

=== Exciton intro 4: plot BSE optical absorption with custom options ===
In this section we will use the script <code>exc_abs_plot.py</code> and work with the quantities defined in the previous sections.

The class <code>YamboExcitonDB</code> also enables us, of course, to read the dielectric function eps(w) and print absorption and related spectra in python.

The advantages over using the standard human-readable yambo outputs are mainly two:
# We can freely select energy ranges, energy steps, peak broadenings and number of excitonic states included without having to rerun the <code>yambo</code> executable every time. This reduces the chance of mistakenly editing the yambo input and allows for greater freedom since these plots can now be done in your local machine without having to transfer the output data from a remote cluster.
# The dielectric function constructed from netCDF database variables has a much higher precision (number of significant digits) than the human readable output, which may be important if you want to perform additional operations in python (e.g., computing refractive index, reflectivity and other optical spectra from it, performing finite-difference derivatives, etc).

We can read eps(w) as a <code>numpy</code> array with the specified options as (energy values are in eV):
w, eps = yexc.get_chi(nexcitons='all',emin=0,emax=7,estep=0.005,broad=0.04)
Or, you can directly prepare a plot of its imaginary part with
w, chi = yexc.plot_chi_ax(ax,nexcitons='all',emin=0,emax=7,estep=0.005,broad=0.04)
where <code>ax</code> is a previously defined <code>Axes</code> object from <code>matplotlib</code>.

In order to see how this works, let's take a look at the <code>exc_abs_plot.py</code> script.
You will see that it performs the two operations described above:
* Plotting the BSE absorption spectrum [<code>Absorption_Plot=True</code>].
* Reading the complex dielectric function.

Try to customise the plots by changing the <code>nexcitons</code>, <code>emin</code>, <code>emax</code>, <code>estep</code>, <code>broad</code> parameters.

[[File:Absalpha.png|Yambo alpha_2D tutorial plot|700px]]

==Links==
* Back to [[Rome 2023#Tutorials]]
* Back to [[ICTP 2022#Tutorials]]

==References==

Exciton-phonon coupling and luminescence

2026-03-13T14:56:00Z

FulvioPaleari: /* Step 6: obtain the electron-phonon matrix elements */

[[File:Tdgw-phonon-usc-01-1024x829.jpg|thumb|right|400px|(c) Zhenglu Li, University of Southern California]]

In this advanced tutorial, we will calculate exciton-phonon interactions from first principles by interfacing DFPT (for phonon calculations) and BSE (for exciton calculations).

The DFTP calculations are run with Quantum ESPRESSO, while the many-body GW-BSE calculations are run with Yambo. Finally, the exciton-phonon interaction will be obtained by combining and postprocessing the databases computed in the two previous runs. The great advantage of this workflow is that the calculations can be run in the irreducible Brillouin zones both for the electronic momenta ('''k''') and the transfer momenta ('''Q''', '''q''') of excitons and phonons, thus speeding up considerably the jobs while reducing the IO and memory load.

We will first compute the exciton-phonon coupling matrix elements: these are the building blocks needed to construct experimental observables such as phonon-assisted optical spectra (such as luminescence), Raman spectra and exciton lifetimes. We will do this in the case of monolayer MoS2, a 2D system with large spin-orbit interaction.

As an example of application, we will consider the case of phonon-assisted luminescence. We will do this in the case of bulk hBN, a layered indirect insulator with strong electron-phonon coupling.

'''Note:''' this tutorial will be updated when new exc-ph tools become available in Yambopy (including full-python postprocessing, Raman spectra, interpolated lifetimes, etc).

== Requirements ==

This is an advanced topic: we assume that you already know something about the theory<ref name="toyozawa2003" /><ref name="antonius2017" /><ref name="cudazzo2020" /><ref name="paleari2019_PhD" /><ref name="paleari2022" /><ref name="lechifflart2023_PhD" /> and applications<ref name="paleari2019" /><ref name="cannuccia2019" /><ref name="chen2020" /><ref name="zanfrognini2023" /><ref name="lechifflart2023" /><ref name="chan2023" /><ref name="marini2024" /><ref name="murali2025" /> of exciton-phonon physics.

Also, we assume that you already know how to run both a basic '''Yambo''' GW-BSE calculation and a DFPT phonon calculation with '''Quantum ESPRESSO'''.

Besides the QE executables <code>pw.x</code> and <code>ph.x</code>, we also use the yambo phonon-specific executable <code>yambo_ph</code> and the python utility '''Yambopy'''. The auxiliary code '''LetzElPhC''' (executable <code>lelphc</code>) will be used to obtain the electron-phonon matrix elements by reading the same electronic wavefunctions used by Yambo (and stored in the <code>SAVE</code> directory), while also making full use of crystal symmetries. [https://github.com/yambo-code/LetzElPhC LetzElPhC] will be run by Yambopy, but it must nonetheless be installed. Finally, the exciton-phonon properties can be computed either using <code>yambo_ph</code> or using Yambopy itself. Both cases will be covered in this tutorial.

[[File:Workflow scheme.png|800px|center]]

== Step 0: Pseudopotentials, equilibrium structure and convergence ==

In a real calculation, it is important to ensure that both the pseudopotential and the lattice parameters that we are using are compatible and perform well for the electronic excited states and for the lattice vibrations simultaneously. Furthermore, you have to make sure that the wave function cutoff <code>ecutwfc</code> is converged with respect to the DFPT step and not just to the DFT one. This is in addition to the other customary convergence tests for DFT, DFPT, GW and BSE calculations.

This is often the most time-demanding step when starting on a new system.

For the sake of this tutorial, we assume that we have already done all these tests and we are starting the final workflow to get the exciton-phonon properties.

== Step 1: scf calculation ==

First of all, we run a standard scf calculation with <code>pw.x</code> for Yambo. We stick with non-symmorphic symmetries. At the end, we will have the QE <code>save</code> directory.

This is the input <code>mos2.scf</code>:

&control
wf_collect = .true.,
calculation = "scf",
verbosity = 'high',
pseudo_dir = '$PSEUDO_DIR',
prefix = "mos2",
outdir = '.',
/&end
&system
ecutwfc = 100.0,
occupations = 'fixed',
ibrav = 4,
celldm(1) = 5.9000811881,
celldm(3) = 6.7795677253,
nat = 3,
ntyp = 2,
lspinorb = .true.
noncolin = .true.
assume_isolated = '2D'
force_symmorphic = .true.
/&end
&electrons
electron_maxstep = 200,
mixing_beta = 0.7,
conv_thr = 1.d-08,
/&end
ATOMIC_SPECIES
Mo 95.940 Mo_ONCV_PBE_FR-1.0.upf
S 32.065 S_ONCV_PBE_FR-1.1.upf
ATOMIC_POSITIONS { crystal }
Mo 0.333333333 0.666666667 0.000000000
S 0.666666667 0.333333333 0.073413577
S 0.666666667 0.333333333 -0.073413577
K_POINTS { automatic }
6 6 1 0 0 0

Here we are using full relativistic pseudopotentials from the SG-15 database.

We can run it on our machine (for example using 4 MPI tasks) as:

mpirun -np 4 pw.x -inp mos2.scf > scf.out

== Step 2: nscf calculation for Yambo ==

Copy the QE <code>save</code> directory from the scf calculation and run the nscf calculation for any number of empty states, with the correct <code>k</code>-grid we want to use in Yambo. Here we are using a badly underconverged grid of 6x6x1.

This reciprocal-space grid will also match the momentum transfer <code>q</code> grid on which excitons and phonons will be defined!

The electronic wavefunctions computed at this step and stored in the new nscf <code>save</code> directory will be used both by Yambo and by the electron-phonon code: this is important because using different sets of wavefunctions would lead to a phase mismatch issue in the exciton-phonon matrix elements.

The nscf input <code>mos2.nscf</code> is
&control
wf_collect = .true.,
calculation = "nscf",
verbosity = 'high',
pseudo_dir = '$PSEUDO_DIR',
prefix = "mos2",
outdir = '.',
/&end
&system
ecutwfc = 100.0,
occupations = 'fixed',
ibrav = 4,
celldm(1) = 5.9000811881,
celldm(3) = 6.7795677253,
nat = 3,
ntyp = 2,
lspinorb = .true.
noncolin = .true.
nbnd = 250
assume_isolated = '2D'
force_symmorphic = .true.
/&end
&electrons
electron_maxstep = 200,
mixing_beta = 0.7,
conv_thr = 1.d-08,
/&end
ATOMIC_SPECIES
Mo 95.940 Mo_ONCV_PBE_FR-1.0.upf
S 32.065 S_ONCV_PBE_FR-1.1.upf
ATOMIC_POSITIONS { crystal }
Mo 0.333333333 0.666666667 0.000000000
S 0.666666667 0.333333333 0.073413577
S 0.666666667 0.333333333 -0.073413577
K_POINTS { automatic }
6 6 1 0 0 0

Again, we run the calculation

mpirun -np 4 pw.x -inp mos2.nscf > nscf.out

== Step 3: dvscf phonon calculation ==

Now we run the phonon calculation.

Copy the <code>save</code> directory from the '''scf''' calculation and run <code>ph.x</code> for a dvscf calculation with a standard <code>q</code>-grid matching the <code>k</code>-grid we wanna use in Yambo.

At the end, we will have the <code>_ph0</code> directory containing the variation of the self-consistent potential, <math>\Delta V_{SCF}(q)</math>, and the <code>*.dyn</code> files with the phonon energies and eigenvectors.

NB: one could further refine the phonon energies by enforcing the acoustic sum rule, including non-analytic long-range contributions, interpolating to finer grids... all of this can be done within Quantum ESPRESSO and will not be covered in this version of the tutorial.

The input is <code>mos2.dvscf</code>:

mos2_dvscf
&inputph
tr2_ph=1.0d-12,
verbosity='high'
prefix='mos2',
fildvscf = 'mos2-dvscf',
electron_phonon = 'dvscf',
fildyn='mos2.dyn',
epsil=.false.,
ldisp=.true.,
recover=.true.,
nq1=6,
nq2=6,
nq3=1
/

And now we run as

nohup mpirun -np 8 ph.x -inp mos2.dvscf > dvscf.out &

This time we use nohup and more processes because this calculation may take some time. It is a good idea to set <code>recover=.true.</code> as in a real calculation you will easily breach walltime, and in this way you can safely restart.

== Step 4: create Yambo <code>SAVE</code> directory ==

This is just the standard Yambo initialization: run

p2y

and then

yambo

in the '''nscf''' <code>save</code> folder and then move the newly generated <code>SAVE</code> directory to a convenient place.

== Step 5: run a BSE calculation ==

Now we switch from QE to Yambo. Here, we forgo the GW step for simplicity (we can use a scissor operator to open the band gap).

This calculation has a couple of differences with respect to a standard BSE calculation for optical absorption. We can look at the input file <code>bse.in</code>:

# Runlevels
optics # [R OPT] Optics
rim_cut # [R RIM CUT] Coulomb potential
bss # [R BSS] Bethe Salpeter Equation solver
em1s # [R Xs] Static Inverse Dielectric Matrix
bse # [R BSE] Bethe Salpeter Equation.
bsk # [R BSK] Bethe Salpeter Equation kernel
# RIM and cutoff settings
RandQpts=1000000 # [RIM] Number of random q-points in the BZ
RandGvec= 100 RL # [RIM] Coulomb interaction RS components
CUTGeo= "slab z" # [CUT] Coulomb Cutoff geometry: box/cylinder/sphere X/Y/Z/XY..
# Static screening
X_and_IO_CPU= "1 1 4 2 1" # [PARALLEL] CPUs for each role
X_and_IO_ROLEs= "q g k c v" # [PARALLEL] CPUs roles (q,g,k,c,v)
X_and_IO_nCPU_LinAlg_INV=-1 # [PARALLEL] CPUs for Linear Algebra (if -1 it is automatically set)
Chimod= "hartree" # [X] IP/Hartree/ALDA/LRC/BSfxc
% BndsRnXs
1 | 200 | # [Xs] Polarization function bands
%
% LongDrXs
1.000000 | 1.000000 | 1.000000 | # [Xs] [cc] Electric Field
%
NGsBlkXs= 8000 mRy # [Xs] Response block size
# BSE
BS_CPU= "4.1.2" # [PARALLEL] CPUs for each role
BS_ROLEs= "k.eh.t" # [PARALLEL] CPUs roles (k,eh,t)
BS_nCPU_diago=4 # [PARALLEL] CPUs for matrix diagonalization
BSEmod= "causal" # [BSE] resonant/causal/coupling
BSKmod= "SEX" # [BSE] IP/Hartree/HF/ALDA/SEX/BSfxc
BSSmod= "d" # [BSS] (h)aydock/(d)iagonalization/(s)lepc/(i)nversion/(t)ddft`
BSENGexx= 40000 mRy # [BSK] Exchange components
ALLGexx # [BSS] Force the use use all RL vectors for the exchange part
BSENGBlk= 8000 mRy # [BSK] Screened interaction block size
Lkind="full" #[BSE,X] bar(default)/full/tilde
% KfnQP_E
1.000000 | 1.000000 | 1.000000 | # [EXTQP BSK BSS] E parameters (c/v) eV|adim|adim
%
% BEnRange
0.00000 | 4.00000 | eV # [BSS] Energy range
%
% BDmRange
0.05000 | 0.05000 | eV # [BSS] Damping range
%
BEnSteps= 2000 # [BSS] Energy steps
% BLongDir
1.000000 | 0.000000 | 0.000000 | # [BSS] [cc] Electric Field
%
% BSEQptR
 1 | 7 | # [BSK] Transferred momenta range
%
% BSEBands
25 | 28 | # [BSK] Bands range
%
WRbsWF # [BSS] Write to disk excitonic the FWs

This file was generated using the command: <code> yambo -X s -o b -k sex -y d -r</code> 

First of all, we compute the excitons for all the momenta in the irreducible Brillouin zone for our discrete grid via the <code>BSEQptR</code> variable. This will be a '''finite-momentum''' BSE calculation, analogous to the phonon one.

Second, we change the variable <code>Lkind</code> from <code>bar</code> to <code>full</code>. In Yambo, <code>Lkind="bar"</code>, which is the default for optical absorption, means that we are computing the excitonic response function without the long-range component of the exchange interaction. This cannot be used when computing the exciton momentum dependence, where the long-range exchange interaction can play a role, therefore we have to include it with <code>Lkind="full"</code>. This allows for the calculation of the excitonic longitudinal-transverse splitting (in 3D systems) as well.

We can now run the code:

nohup mpirun -np 8 yambo -F bse.in -J bse_Lfull -C bse_Lfull &

At the end of the calculation, we have obtained the <code>ndb.BS_diago_Q*</code> databases inside the directory <code>bse_Lfull</code>. They contain information on the exciton energies and wavefunctions at each momentum. Do not forget to check the report and logs of your calculation in the same directory to make sure that the code is doing what you want.

== Step 6: obtain the electron-phonon matrix elements ==

We have finished the heavy simulations. Now it's time for the postprocessing. The first order of business is the reconstruction of the electron-phonon coupling matrix elements from the dvscf results and the electronic wavefunctions.

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

We run in the same directory where the Yambo <code>SAVE</code> 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>n_i</math> to <math>n_f</math>, we should type:

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

Here <math>n_i</math> and <math>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>[n_i,n_f]</math> including the extrema of the interval.

These should coincide with those used for the Bethe-Salpeter kernel, i.e. those specified in the <code>BSEBands</code> variable of the BSE input file (this is not strictly necessary, but certainly efficient since these calculations use a lot of disk space).

For our system, we want to do a parallel calculation with 4 qpools and 2 kpools. In addition, we want to explicitly specify the path of the <code>lelphc</code> executable and avoid automatically deleting the LetzElPhC data. So we type:

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

At the end, check your directory: you should find the <code>lelphc.in</code> 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 <code>convention=yambo</code>: 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>n</math> and momentum <math>k-q</math> to band <math>m</math> and momentum <math>k</math>. In the "forward" momentum transfer convention (the more standard one), the transitions go from <math>nk</math> to <math>mk+q</math>. Therefore, this variable ensures that the electron-phonon coupling matrix elements are computed as <math>\langle mk|dV|nk-q\rangle</math>. This will have consequences also in the formulation of the ''exciton''-phonon coupling matrix element.

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

In addition, if you check the <code>SAVE</code> folder:

ls SAVE/ndb.elph_gkkp*

you will see that yambopy has created the Yambo-compatible electron-phonon databases.

If you want to run LetzElPhC directly, without using yambopy, you can refer to its [https://github.com/yambo-code/LetzElPhC/blob/main/docs/tex_doc/main.pdf|user guide].
Keep in mind that in this case, in order to convert the database to the <code>ndb.elph_gkkp*</code> databases of Yambo, you will then need a couple of lines of python using the Yambopy class <code>ConvertElectronPhononDB</code> in <code>yambopy/letzelph_interface/lelph2y.py</code>.

If you don't need the <code>ndb.elph_gkkp*</code> databases -- e.g., because you are doing the exc-ph postprocessing with yambopy -- you can run <code>yambopy l2y ...</code> with the <code>--no_gkkp</code> option.

If you don't need the <code>ndb.elph</code> databases -- e.g., because you are using <code>yambo_ph</code> for the exc-ph part -- you can run <code>yambopy l2y ...</code> with the <code>--no_lelphc_dbs</code> option.

== Step 7: Obtain the exciton-phonon coupling ==

Now, we can finally access our basic building block for exciton-phonon physics. This could be done entirely in python (using '''Yambopy'''), or by running '''Yambo'''.

* For the '''Yambo postprocessing''' case (running yambo inputs with the <code>yambo_ph</code> executable), '''follow the alternative route to Steps 7-8 [[Exciton-phonon coupling and luminescence - Yambo postprocessing|at this link]]'''.
* For the '''Yambopy postprocessing''' case (using flexible python scripting), '''keep following Steps 7-8 on this page'''.

Our objective is obtaining the following quantity:

<math>\mathcal{G}^\mu_{\alpha\lambda}(0,q)=\sum_{vv^\prime c k} A^{\alpha, *}_{cv^\prime} (k, q) g_{vv^\prime}^\mu (k,q) A^{\lambda}_{cv}(k,0) - \sum_{cc^\prime vk} A^{\alpha, *}_{c^\prime v} (k+q, q) g_{c^\prime c}^\mu (k+q,q) A^{\lambda}_{cv}(k, 0)</math>

Here, <math>A^{\alpha}_{cv}(k,q)</math> are the exciton coefficients extracted from the eigenvector of the two-particles Hamiltonian during the BSE calculation in step 5, while <math>g_{nm}^\mu (k,q)</math> are the electron-phonon coupling matrix elements obtained in step 6. As you can see, the exciton <math>\lambda</math> undergoes phonon-mediated scattering to state <math>\alpha</math> via phonon mode <math>\mu</math>. The scattering can happen for the hole (valence, <math>v</math>) or for the electron (conduction, <math>c</math>).

NB:

(1) This is written in the "backward" momentum transfer convention used by Yambo. The momentum dependence is different in the "forward" transfer convention.

(2) For simplicity, this is written for zero initial exciton momentum. This means that one of the two states involved in the phonon-mediated scattering process will be in the optical limit (and possibly an optically generated exciton), while the other state can have any momentum: this momentum will be the same as the phonon one. This matrix element can be used to describe phonon-assisted absorption and emission spectra.

In order to calculate this quantity using python, we need the <code>ndb.elph</code> databases natively generated by the <code>LetzElPhC</code> code, as well as the BSE databases <code>ndb.BS_diago_Q*</code> containing the information on exciton wavefunctions and energies.

Next, we write a python user script importing the yambopy exciton-phonon tools. You can find a version of this script in <code>yambopy/tutorials/exciton-phonon/calculate_excph.py</code>.

import numpy as np
from yambopy import YamboLatticeDB,YamboWFDB,LetzElphElectronPhononDB #Specific Yambopy dbs loading classes
from yambopy.exciton_phonon.excph_matrix_elements import exciton_phonon_matelem #Specific exc-ph functions

path = '1L_MoS2'
bands_range=[24,28] # 2 valence bands, 2 conduction bands
nexc = 12 # number of excitonic states

bsepath = f'{path}/bse-allq_full' # Path to BSE calculation (Lin=Lout)
savepath = f'{path}/SAVE' # Yambo SAVE
ndb_elph = f'{path}/ndb.elph' # LetzElPhC electron-phonon database (any convention)

# Read lattice
lattice = YamboLatticeDB.from_db_file(filename=f'{savepath}/ns.db1')
# Read electron-phonon
elph = LetzElphElectronPhononDB(ndb_elph,read_all=False)
# Read wave functions
wfcs = YamboWFDB(filename='ns.wf',save=savepath,latdb=lattice,bands_range=bands_range)
# Calculate exciton-phonon matrix elements
exph = exciton_phonon_matelem(lattice,elph,wfcs,BSE_dir=bsepath,nexc_in=nexc,nexc_out=nexc,dmat_mode='save',exph_file='MoS2_Ex-ph.npy')

In this script, we can select the number exciton states <math>\lambda</math> with <code>nexc</code>, the single-particle bands range with <code>bands_range</code>. '''Please note''': in this case, the band index starts from 0 (python indexing) and the the interval of bands read by the code is <math>[n_i,n_f)</math>, therefore the last value (28 in the example) is excluded. That is, in the example we are selecting the 25th, 26th, 27th and 28th bands. Those bands have to be present in both the electron-phonon and BSE calculations.

Here we calculate the couplings of the first twelve states at each finite-<math>q</math> point including <math>q=0</math>. We also include all the nine phonon modes of monolayer MoS2. We also need access to the Yambo <code>SAVE</code> directory in order to read the electronic wavefunctions: they are used to compute the electronic representation matrices (<code>dmat</code> in the code). The argument <code>dmat_mode</code> can be set to <code>'load'</code> for subsequent calculations.

When we are satisfied with the input, we run the code:

python calculate_excph.py

If you check the output, you should find the <code>MoS2_Ex-ph.npy</code> binary file in the directory where you ran.

=== Analysis of the couplings ===

It is a good idea to have a look at what we computed up to now in order to make sure nothing has gone wrong.

It is not easy to know what to expect (apart from symmetry and gauge compliance of the matrix elements), but one can work out the exciton-phonon selection rules in advance, check that the magnitude is reasonable, etc.

It is also not easy to meaningfully plot this quantity. We have to make sure that we are not breaking degenerate states, otherwise the plots will not be invariant.

First of all, we have to know our system: in monolayer MoS2, the first four excitons are all doubly degenerate. The first exciton responsible for a bright peak in the absorption spectrum (the '''A''' peak), is the second state, corresponding to state indices <code>(3,4)</code> in fortran indexing or <code>(2,3)</code> in python indexing.

All these information can be obtained by analyzing the BSE results (this stuff is explained in the BSE tutorials) and by knowledge of the system or class of systems from the literature.

Thus, a good quantity to plot may be the norm of the matrix elements, summed over the degenerate subspace of exciton A, for a certain number of scattered final states mediated by certain phonon modes:

<math>F_A(q)= \sqrt{ \sum_{\alpha \in A,\lambda,\mu} |\mathcal{G}_{\alpha\lambda}^\mu (0,q)|^2 }</math>

In order to do this, we create a python script <code>analyse_excph.py</code> in which we first load the excph dabatases.
You can find a version of this script in the yambopy directory, in <code>tutorials/exciton-phonon</code>.
First, we select the exciton and phonon states to be included in <code>F_A</code>, together with the path of databases and plot details:

# Exciton "in" states
exc_in = [2,3] # First bright peak (A: 2,3 -- B: 6,7)
exc_out = [0,1,2,3] # first 4 states (dispersion of dark triplet state and A)
ph_in = 'all'
# Paths of databases
ns_db1 =f'{path}/SAVE/ns.db1'
ns_ypy = 'MoS2_Ex-ph.npy'

...

Then, we load the data:

# Read lattice and k-space info
ylat = YamboLatticeDB.from_db_file(filename=ns_db1)
print(ylat)

# Load exc-ph database
X_py = np.load(ns_ypy)
G_squared = np.abs(X_py)**2.

The quantity <math>F_A(q)</math> is obtained from a dedicated function as:

if exc_in == 'all': exc_in = range(G_squared.shape[2])
if exc_out == 'all': exc_out = range(G_squared.shape[3])
if ph_in == 'all': ph_in = range(G_squared.shape[1])

G_squared = G_squared[:, ph_in, :, :].sum(axis=(1))
G_squared = G_squared[:, exc_in, :].sum(axis=(1))
G_squared = G_squared[:, exc_out].sum(axis=(1))

F_q = np.sqrt( G_squared )*ha2ev # Switch from Ha to eV

And finally, we have to make a plotting function. For this tutorial we will use a custom scatterplot employing some of the plotting tools provided by yambopy (but you can do whatever you want).

plot_2D_excph(qgrid,G2_to_plot,rlat=ylat.rlat,plt_cbar=True,\
marker='H',s=700,cmap='magma')
...

You can get more experience on using Yambopy for these kinds of visualization by following the [https://wiki.yambo-code.eu/wiki/index.php?title=First_steps_in_Yambopy Yambopy tutorials]. In fact, remember that these scripts and all the other Yambopy tutorial scripts are just suggestions, not source code written in stone: if you know <code>numpy</code> and <code>matplotlib</code> you can do your own analysis and your own plots, you just need to import the required Yambopy modules to load the data.

In our case, the resulting plot is the following.

[[File:1L MoS2 MoS2 Ex-ph.png|500px|center]]

This can be checked against Fig. 2(d) of reference <ref name="chan2023" />, although you have to keep in mind that our results are badly undersampled in terms of the reciprocal-space grid, as can be easily seen, and the quantity plotted is not exactly the same. However, the main features are already there since they are dictated mostly by crystal symmetries.

Now that we have the exciton-phonon matrix elements, we can use them to build several kinds of observables. Below, we give an example related to phonon-assisted luminescence, but we may update this tutorial in the future to include more cases.

== Step 8: Compute phonon-assisted luminescence ==

[[File:Luminescence scheme.png|250px|right]]

We want to compute the experimental optical signature due to the phonon-assisted recombination of an exciton (as sketched in the figure).

The signal from the phonon replicas can be modeled as a second-order scattering process involving one phonon and one photon:

<math>I^{Sat}(\omega)=\frac{1}{ N_q} \frac{1}{3} \sum_{\epsilon s\beta \mu q} \frac{1}{E_{\beta q}-s\Omega_{\mu q}}\left|\sum_\alpha\frac{ D^{\epsilon}_\alpha \mathcal{G}_{\beta \alpha}^{\mu,*}(q)}{E_\alpha -E_{\beta q} +s\Omega_{\mu q}+\mathrm{i}\eta}\right|^2 \frac{N^{exc}_{\beta q}(T_{exc})[\frac{1+s}{2}+n_{\mu q}(T)]}{\omega -[E_{\beta q}-s\Omega_{\mu q}]+\mathrm{i}\eta}</math>

In this equation, the oscillator strength of the peak is given by the exciton-phonon coupling matrix elements <math>\mathcal{G}</math> multiplied by the exciton dipoles <math>D</math> (they are called "residuals" in Yambo). Here <math>E_\lambda</math> and <math>E_{\alpha q}</math> are the energies of the optical and finite-momentum excitons, respectively, while <math>\Omega_{\mu q}</math> are the phonon energies.

Here, <math>n_{\mu q}(T)</math> is the temperature-dependent phonon Bose-Einstein occupation function. As it can be seen, <math>s=1</math> corresponds to processes of phonon ''emission'' (<math>\propto n(T)+1</math>), while <math>s=-1</math> corresponds to processes of phonon ''absorption'' (<math>\propto n(T)</math>). Therefore, <math>I^{Sat}_{PL}(\omega;T)</math> describes ''light'' emission by recombining excitons mediated by either ''phonon'' absorption or emission.

The quantity <math> N_{\alpha q}(T_{exc})</math> is the exciton occupation function. Luminescence is technically an out-of-equilibrium process, but we can assume that for very low density of excitations and in steady-state conditions, the exciton population can be approximately described by an equilibrium distribution evaluated at an effective temperature. Here, we use the Boltzmann distribution. Experimentally, <math>T_{exc}</math> tends to coincide with the lattice temperature <math>T</math> more or less above 100 K, while at very low temperature (< 10 K), <math>T_{exc}</math> may vary between 10-50 K. It goes without saying that this needs to carefully be checked in your realistic calculations.

Finally, the spectrum is averaged over the polarization directions of the emitted photons (<math>\epsilon=x,y,z</math> representing the respective dipole components).

=== Running the jobs ===

In order to study luminescence in a paradigmatic system, we switch to bulk hexagonal boron nitride and we repeat the workflow. As you can easily see, one can think about automatizing the execution of all these calculations via scripting or more advanced tools. However, in the case of very large simulations (memory-limited or disk-space limited) or for systems whose electronic and lattice properties are fragile with respect to tiny calculation details, one must be very careful and run many basic tests.

Fortunately, we are running a fast underconverged example. We use LDA pseudopotentials from the pseudo-dojo library and the following are the calculations steps.

1. Input <code>hbn.scf</code>:

&control
calculation='scf',
prefix='hBN',
restart_mode='from_scratch'
pseudo_dir = '$PSEUDO_DIR',
outdir = './tmp'
verbosity = 'high'
wf_collect=.true.
/
&system
ibrav = 4,
celldm(1) = 4.703675849
celldm(3) = 2.603711434
nat= 4,
ntyp= 2,
force_symmorphic=.true.
ecutwfc = 100,
/
&electrons
diago_david_ndim = 2
diago_full_acc=.true.
diago_thr_init=5.0e-6
mixing_mode = 'plain'
mixing_beta = 0.7
conv_thr = 1.0d-16
/
ATOMIC_SPECIES
B 10.81100 B_LDA_dojo.UPF
N 14.00674 N_LDA_dojo.UPF
ATOMIC_POSITIONS {crystal}
N 0.6666666670 0.3333333330 -0.250000000000
B 0.3333333330 0.6666666670 -0.250000000000
B 0.6666666670 0.3333333330 0.25000000000
N 0.3333333330 0.6666666670 0.25000000000
K_POINTS {automatic}
6 6 2 0 0 0

mpirun -np 4 pw.x -inp hbn.scf > scf.out

2. Input <code>hbn.nscf</code>:

&control
calculation='nscf',
prefix='hBN',
restart_mode='from_scratch'
pseudo_dir = '$PSEUDO_DIR'
outdir = './'
verbosity = 'high'
wf_collect=.true.
/
&system
ibrav = 4,
celldm(1) = 4.703675849
celldm(3) = 2.603711434
nat= 4,
ntyp= 2,
force_symmorphic=.true.
ecutwfc = 100,
nbnd = 120
/
&electrons
diago_david_ndim = 2
diago_full_acc=.true.
diago_thr_init=5.0e-6
mixing_mode = 'plain'
mixing_beta = 0.7
conv_thr = 1.0d-16
/
ATOMIC_SPECIES
B 10.81100 B_LDA_dojo.UPF
N 14.00674 N_LDA_dojo.UPF
ATOMIC_POSITIONS {crystal}
N 0.6666666670 0.3333333330 -0.250000000000
B 0.3333333330 0.6666666670 -0.250000000000
B 0.6666666670 0.3333333330 0.25000000000
N 0.3333333330 0.6666666670 0.25000000000
K_POINTS {automatic}
6 6 2 0 0 0

mpirun -np 4 pw.x -inp hbn.nscf > nscf.out

3. Input <code>hbn.dvscf</code>:

hbn_dvscf
&inputph
tr2_ph=1.0d-12,
verbosity='high'
prefix='hBN',
fildvscf = 'hBN-dvscf',
electron_phonon = 'dvscf',
fildyn='hBN.dyn',
epsil=.false.,
ldisp=.true.,
recover=.true.,
nq1=6,
nq2=6,
nq3=2
/

nohup mpirun -np 8 pw.x -inp hbn.dvscf > dvscf.out &

4. Input <code>bse.in</code> (we include 2 valence and 2 conduction bands):

optics # [R] Linear Response optical properties
bss # [R] BSE solver
bse # [R][BSE] Bethe Salpeter Equation.
dipoles # [R] Oscillator strenghts (or dipoles)
em1s
DIP_CPU= "1 8 1" # [PARALLEL] CPUs for each role
DIP_ROLEs= "k c v" # [PARALLEL] CPUs roles (k,c,v)
DIP_Threads=0 # [OPENMP/X] Number of threads for dipoles
X_and_IO_CPU= "1 1 1 8 1" # [PARALLEL] CPUs for each role
X_and_IO_ROLEs= "q g k c v" # [PARALLEL] CPUs roles (q,g,k,c,v)
X_and_IO_nCPU_LinAlg_INV=-1 # [PARALLEL] CPUs for Linear Algebra (if -1 it is automatically set)
X_Threads=0 # [OPENMP/X] Number of threads for response functions
BS_CPU= "8 1 1" # [PARALLEL] CPUs for each role
BS_ROLEs= "k eh t" # [PARALLEL] CPUs roles (k,eh,t)
BS_nCPU_LinAlg_INV=-1 # [PARALLEL] CPUs for Linear Algebra (if -1 it is automatically set)
BS_nCPU_LinAlg_DIAGO=-1 # [PARALLEL] CPUs for Linear Algebra (if -1 it is automatically set)
X_Threads=0 # [OPENMP/X] Number of threads for response functions
K_Threads=0 # [OPENMP/BSK] Number of threads for response functions
% QpntsRXs
1 | 14 | # [Xs] Transferred momenta
%
% BndsRnXs
1 | 120 | # [Xs] Polarization function bands
%
NGsBlkXs= 10 Ry # [Xs] Response block size
% LongDrXs
1.000000 | 1.000000 | 1.000000 | # [Xs] [cc] Electric Field
%
BSEmod= "resonant" # [BSE] resonant/retarded/coupling
BSKmod= "SEX" # [BSE] IP/Hartree/HF/ALDA/SEX/BSfxc
Lkind= "Lfull" # [BSE] Lbar (default) / full
BSSmod= "d" # [BSS] (h)aydock/(d)iagonalization/(s)lepc/(i)nversion/(t)ddft`
% DipBands
1 | 120 | # [DIP] Bands range for dipoles
%
DipApproach= "G-space v" # [DIP] [G-space v/R-space x/Covariant/Shifted grids]
DipComputed= "R V P" # [DIP] [default R P V; extra P2 Spin Orb]
BSENGexx= 30000 Ry # [BSK] Exchange components
#ALLGexx # [BSS] Force the use use all RL vectors for the exchange part
BSENGBlk= 9000 Ry # [BSK] Screened interaction block size [if -1 uses all the G-vectors of W(q,G,Gp)]
% KfnQP_E
1.25997 | 1.08816 | 1.12683 | # [EXTQP BSK BSS] E parameters (c/v) eV|adim|adim
%
% BSEQptR
 1 | 14 | # [BSK] Transferred momenta range
%
% BSEBands
 7 | 10 | # [BSK] Bands range
%
% BEnRange
0.50000 | 8.00000 | eV # [BSS] Energy range
%
% BDmRange
0.050000 | 0.050000 | eV # [BSS] Damping range
%
BEnSteps= 1000 # [BSS] Energy steps
% BLongDir
1.000000 | 1.000000 | 0.000000 | # [BSS] [cc] Electric Field
%
WRbsWF # [BSS] Write to disk excitonic the WFs

nohup mpirun -np 8 yambo -F bse.in -J bse_Lfull -C bse_Lfull &

Importantly, since we want to describe the phonon-assisted recombination process of an *optical* exciton (i.e., emitting a transverse photon), this time we also run an additional calculation at `Q=0` omitting the nonanalytic long-range Coulomb exchange. Make a second input <code>bse_Lbar.in</code> with the following changes:

Lkind= "Lbar" # [BSE] Lbar (default) / full
% BSEQptR
 1 | 1 | # [BSK] Transferred momenta range
%

4b. So now we make a second BSE run in a different directory specified by <code>-J</code>. Here, we also pass to yambo the directory of the previous run as it includes the important screening databases <code>ndb.em1s*</code> that we do not want to recompute from scratch.

mpirun -np 8 yambo -F bse_Lbar.in -J bse_Lbar,bse_Lfull -C bse_Lbar

5. Now we run <code>lelphc</code> (with or without yambopy: in the latter case remember the option <code>-D</code>) to get the el-ph matrix elements, particularly the <code>ndb.elph</code> databases:

yambopy l2y -ph path/of/dvscf/hbn.dvscf -b 7 10 -par 4 2 -D

=== Luminescence calculation ===

6. And finally we calculate exciton-phonon matrix elements and the luminescence spectrum in one go using a python script importing the Yambopy exciton-phonon tools: in order to do this, we need to take a look at all the necessary input variables for the formula written above.

We can start from the script <code>luminescence.py</code> available in <code>tutorials/exciton-phonon</code>.

import numpy as np
import matplotlib.pyplot as plt
from yambopy.exciton_phonon.excph_luminescence import exc_ph_luminescence
from yambopy.exciton_phonon.excph_input_data import exc_ph_get_inputs

We import the necessary tools...

path = '3D_hBN'
# Path to BSE calculation (Lout--> response is Lfull)
bsepath = f'{path}/bse_Lfull' # ndb.BS_diago_Q* databases are needed
# Path to BSE calculation for optically active exciton (Lin --> response is Lbar)
bseBARpath = f'{path}/bse_Lbar' # ndb.BS_diago_Q1 database is needed
# Path to electron-phonon calculation
elphpath = path # ndb.elph is needed
# Path to unprojected dipoles matrix elements (optional)
dipolespath = bsepath # ndb.dipoles is needed (optional)
# Path to lattice and k-space info
savepath = f'{path}/SAVE' # ns.db1 database is needed

... and we specify the paths to the necessary databases. Note that, if we want to perform polarization averaging, we have to recompute the excitonic dipoles in python as seen here.

What about <code>bseBARpath</code>? This variable points to the directory where the databases for the optical (zero-momentum) excitons <math>\alpha</math> (which may be computed with <code>Lkind='Lbar'</code>) is located, which can be different from the directory with the full indirect exciton dispersion <math>\beta</math> (usually computed with <code>Lkind='Lfull'</code>, however <code>Lkind='Ltilde'</code> can also be used if one is interested in "irreducible" excitons). This makes it possible to compute the coupling between different exciton kinds.

bands_range=[6,10] # 2 valence, 2 conduction bands
phonons_range=[0,12] # All phonons
nexc_out = 12 # 12 excitonic states at each momentum (Lout)
nexc_in = 12 # 12 excitonic states at Q=0 (Lin)
T_ph = 10 # Lattice temperature
T_exc = 10 # Effective excitonic temperature

emin=4.4 # Energy range and plot details (in eV)
emax=4.7
estep=0.0002
broad = 0.005 # Broadening parameter for peak width (in eV)

Next, we specify the parameters for the calculation. We include valence bands from 7 to 10 (6 to 9 in python index) and the contribution of all 12 phonon modes. We consider 12 excitonic states for the coupling matrix elements.

Here <code>T_ph</code> and <code>T_exc</code> are the lattice and excitonic temperatures, respectively.

# We calculate and load all the inputs:
# * Exciton-phonon matrix elements
# * Excitonic dipole matrix elements
# * Exciton energies
# * Phonon energies
# * We specify bse_path2=bseBARpath meaning we use Lbar calculation for Q=0 excitons
input_data = exc_ph_get_inputs(savepath,elphpath,bsepath,\
bse_path2=bseBARpath,dipoles_path=dipolespath,\
nexc_in=12,nexc_out=12,\
bands_range=[6,10],phonons_range=[0,12])

ph_energies, exc_energies, exc_energies_in, G, exc_dipoles = input_data

The function <code>exc_ph_get_inputs</code> gives us all the input data for luminescence in the correct format: phonon energies, exciton energies, optical exciton energies (if needed), exciton-phonon matrix elements (calculated on the fly and printed to file), unprojected exciton dipoles (optional, calculated on the fly and printed to file).
The exc-ph matrix element calculation is just a wrapper of the same tools that we have tested in the above section on MoS2.

Finally, there is the calculation of the luminescence spectrum via the function <code>exc_ph_luminescence</code>:
# We calculate the luminescence spectrum including the input data from before
w,PL = exc_ph_luminescence(T_ph,ph_energies,exc_energies,exc_dipoles,G,\
exc_energies_in=exc_energies_in,exc_temp=T_exc,\
nexc_out=nexc_out,nexc_in=nexc_in,emin=emin,emax=emax,\
estep=estep,broad=broad)

If you want to print the luminescence data for later plotting, you can also add the following line to the script:
# Save to file
data = np.column_stack((w, PL))
np.savetxt("hBN_luminescence_12x12x1.dat", data, fmt="%.8f")

It is now time to run the whole script:

python luminescence.py

NB: By using Yambopy for Step 6, we have limited the use of the Yambo code to just step 4 in the entire workflow. This option is more flexible, as it allows for a greater degree of control by the user. On the other hand the Yambo postprocessing route features a Yambo-style input that doesn't require python knowledge and the calculation is currently faster in fortran. However, the luminescence expression computed in Yambo is a slightly different than this one: it is more approximated in the description of the satellite oscillator strengths, but it explicitly includes the renormalization of the direct exciton peak. You can check the differences [[Exciton-phonon coupling and luminescence - Yambo postprocessing|here]].

=== Results ===
We can plot the results of the step 6 calculation. If we do it in the same script we can add something like this:
fig = plt.figure()
ax = fig.add_subplot(1,1,1)
ax.set_xlim(emin,emax)
ax.set_ylim(0,np.max(PL)*1.1)
ax.get_yaxis().set_visible(False)

ax.plot(w, PL, '-',c='red', label="AA' hBN luminescence")

plt.legend()
plt.savefig('hBN_luminescence.png')
plt.show()

[[File:HBN luminescence satellites.png|500px|center]]

Here, the signal corresponds to a finite-momentum exciton that recombines with the help of several different phonon modes, both optical and acoustic. Each phonon mode whose coupling with the exciton is allowed can generate a peak, and the energy shifts of these peaks with respect to the initial exciton energy correspond to the phonon energies. This result is underconverged, but the main features are all there. In the plot, we show a more converged example using a 12x12x4 grid (all the other parameters being equal). These plots can be compared with Fig. 4(a) of reference <ref name="zanfrognini2023" />.

== References ==

<references>
<ref name="toyozawa2003" >Toyozawa, Yutaka, and Chris Oxlade, ''Optical processes in solids'', [https://m.booksee.org/book/1121964?force_lang=en Cambridge University Press, (2003)]. </ref>
<ref name='lechifflart2023'>P. Lechifflart, F. Paleari, D. Sangalli, C. Attaccalite, ''First-principles study of luminescence in hexagonal boron nitride single layer: Exciton-phonon coupling and the role of substrate'',
[https://doi.org/10.1103/PhysRevMaterials.7.024006 Phys. Rev. M, '''7''' (2), 024006 (2023)]; [https://arxiv.org/abs/2212.10407 arXiv2212.1047]</ref>
<ref name='cannuccia2019'>E. Cannuccia, B. Monserrat and C. Attaccalite, ''Theory of phonon-assisted luminescence in solids: Application to hexagonal boron nitride'', [https://doi.org/10.1103/PhysRevB.99.081109 Phys. Rev. B '''99''', 081109(R) (2019)]; [https://arxiv.org/abs/1807.11797 arXiv1807.11797]</ref>
<ref name='paleari2019'>F. Paleari et al., ''Exciton-Phonon Coupling in the Ultraviolet Absorption and Emission Spectra of Bulk Hexagonal Boron Nitride'', [https://doi.org/10.1103/PhysRevLett.122.187401 Phys. Rev. Lett. '''122''', 187401 (2019)]; [https://arxiv.org/abs/1810.08976 arXiv1810.089776] </ref>
<ref name='chen2020'>''Exciton-Phonon Interaction and Relaxation Times from First Principles'',
Hsiao-Yi Chen, Davide Sangalli, and Marco Bernardi, [https://doi.org/10.1103/PhysRevLett.125.107401 Phys. Rev. Lett. '''125''', 107401 (2020)]; [https://arxiv.org/abs/2002.08913 arXiv 2002.08913 (2020)]</ref>
<ref name="lechifflart2023_PhD">P. Lechifflart, ''Exciton-phonon coupling and phonon-assisted luminescence in hexagonal Boron Nitride nanostructures'', [https://hal.science/tel-04266805v1 PhD Thesis, University of Marseille (2023)]; [https://www.yambo-code.eu/wiki/images/5/54/These_final.pdf From the yambo website]</ref>
<ref name='paleari2019_PhD'>F. Paleari, ''First-principles approaches to the description of indirect absorption and luminescence spectroscopy: exciton-phonon coupling in hexagonal boron nitride'', [https://wwwen.uni.lu/research/fstm/dphyms/people/fulvio_paleari PhD thesis, University of Luxembourg (2019)]</ref>
<ref name='zanfrognini2023'>M. Zanfrognini et al., ''Distinguishing different stackings in layered materials via luminescence spectroscopy'', [https://doi.org/10.1103/PhysRevLett.131.206902 Phys. Rev. Lett. '''131''', 206902 (2023)]; [https://arxiv.org/abs/2305.17554 arXiv 2305.17554] </ref>
<ref name='marini2024'>G. Marini, M. Calandra, P. Cudazzo, ''Optical absorption and photoluminescence of single layer boron nitride from a first principles cumulant approach'', [https://doi.org/10.1021/acs.nanolett.4c00669 Nano Lett., '''24''', 20, 6017 (2024)]; [https://arxiv.org/abs/2402.03826 arXiv 2402.03826 (2024)]</ref>
<ref name='antonius2017'>G. Antonius, S. G. Louie, ''Theory of exciton-phonon coupling'', [https://doi.org/10.1103/PhysRevB.105.085111 Phys. Rev. B, '''105''', 085111 (2022)]; [https://arxiv.org/abs/1705.04245 arXiv1705.04245 (2017)]</ref>
<ref name='paleari2022'> F. Paleari, and A. Marini, ''Exciton-phonon interaction calls for a revision of the “exciton” concept'', [https://doi.org/10.1103/PhysRevB.106.125403 Phys. Rev. B, '''106''', 125403 (2022)]; [https://arxiv.org/abs/2205.02783 arXiv 2205.02783]</ref>
<ref name='cudazzo2020'> P. Cudazzo, ''First-principles description of the exciton-phonon interaction: A cumulant approach'', [https://doi.org/10.1103/PhysRevB.102.045136 Phys. Rev. B, '''102''', 045136 (2020)]; [https://orbilu.uni.lu/bitstream/10993/44769/1/main.pdf Open access pdf from Luxembourg University]</ref>
<ref name='chan2023'>Y-h Chan, J. B. Haber, M. H. Naik, J. B. Neaton, D. Y. Qiu, F. H. da Jornada, S. G. Louie, ''Exciton Lifetime and Optical Line Width Profile via Exciton–Phonon Interactions: Theory and First-Principles Calculations for Monolayer MoS2'', [https://doi.org/10.1021/acs.nanolett.3c00732 Nano Lett., '''23''', 9 (2023)]; [https://arxiv.org/abs/2212.08451 arXiv 2212.08451 (2023)]</ref>
<ref name='murali2025'>M. Nalabothula, S. Reichardt, L. Wirtz, ''Origin of Interlayer Exciton–Phonon Coupling in 2D Heterostructures'', [https://doi.org/10.1021/acs.nanolett.5c00355 Nano Lett., '''25''', 15 (2025)], [https://arxiv.org/abs/2407.16111 arXiv 2407.16111 (2025)]</ref>
</references>

Exciton-phonon coupling and luminescence

2026-03-13T14:47:46Z

FulvioPaleari:

[[File:Tdgw-phonon-usc-01-1024x829.jpg|thumb|right|400px|(c) Zhenglu Li, University of Southern California]]

In this advanced tutorial, we will calculate exciton-phonon interactions from first principles by interfacing DFPT (for phonon calculations) and BSE (for exciton calculations).

The DFTP calculations are run with Quantum ESPRESSO, while the many-body GW-BSE calculations are run with Yambo. Finally, the exciton-phonon interaction will be obtained by combining and postprocessing the databases computed in the two previous runs. The great advantage of this workflow is that the calculations can be run in the irreducible Brillouin zones both for the electronic momenta ('''k''') and the transfer momenta ('''Q''', '''q''') of excitons and phonons, thus speeding up considerably the jobs while reducing the IO and memory load.

We will first compute the exciton-phonon coupling matrix elements: these are the building blocks needed to construct experimental observables such as phonon-assisted optical spectra (such as luminescence), Raman spectra and exciton lifetimes. We will do this in the case of monolayer MoS2, a 2D system with large spin-orbit interaction.

As an example of application, we will consider the case of phonon-assisted luminescence. We will do this in the case of bulk hBN, a layered indirect insulator with strong electron-phonon coupling.

'''Note:''' this tutorial will be updated when new exc-ph tools become available in Yambopy (including full-python postprocessing, Raman spectra, interpolated lifetimes, etc).

== Requirements ==

This is an advanced topic: we assume that you already know something about the theory<ref name="toyozawa2003" /><ref name="antonius2017" /><ref name="cudazzo2020" /><ref name="paleari2019_PhD" /><ref name="paleari2022" /><ref name="lechifflart2023_PhD" /> and applications<ref name="paleari2019" /><ref name="cannuccia2019" /><ref name="chen2020" /><ref name="zanfrognini2023" /><ref name="lechifflart2023" /><ref name="chan2023" /><ref name="marini2024" /><ref name="murali2025" /> of exciton-phonon physics.

Also, we assume that you already know how to run both a basic '''Yambo''' GW-BSE calculation and a DFPT phonon calculation with '''Quantum ESPRESSO'''.

Besides the QE executables <code>pw.x</code> and <code>ph.x</code>, we also use the yambo phonon-specific executable <code>yambo_ph</code> and the python utility '''Yambopy'''. The auxiliary code '''LetzElPhC''' (executable <code>lelphc</code>) will be used to obtain the electron-phonon matrix elements by reading the same electronic wavefunctions used by Yambo (and stored in the <code>SAVE</code> directory), while also making full use of crystal symmetries. [https://github.com/yambo-code/LetzElPhC LetzElPhC] will be run by Yambopy, but it must nonetheless be installed. Finally, the exciton-phonon properties can be computed either using <code>yambo_ph</code> or using Yambopy itself. Both cases will be covered in this tutorial.

[[File:Workflow scheme.png|800px|center]]

== Step 0: Pseudopotentials, equilibrium structure and convergence ==

In a real calculation, it is important to ensure that both the pseudopotential and the lattice parameters that we are using are compatible and perform well for the electronic excited states and for the lattice vibrations simultaneously. Furthermore, you have to make sure that the wave function cutoff <code>ecutwfc</code> is converged with respect to the DFPT step and not just to the DFT one. This is in addition to the other customary convergence tests for DFT, DFPT, GW and BSE calculations.

This is often the most time-demanding step when starting on a new system.

For the sake of this tutorial, we assume that we have already done all these tests and we are starting the final workflow to get the exciton-phonon properties.

== Step 1: scf calculation ==

First of all, we run a standard scf calculation with <code>pw.x</code> for Yambo. We stick with non-symmorphic symmetries. At the end, we will have the QE <code>save</code> directory.

This is the input <code>mos2.scf</code>:

&control
wf_collect = .true.,
calculation = "scf",
verbosity = 'high',
pseudo_dir = '$PSEUDO_DIR',
prefix = "mos2",
outdir = '.',
/&end
&system
ecutwfc = 100.0,
occupations = 'fixed',
ibrav = 4,
celldm(1) = 5.9000811881,
celldm(3) = 6.7795677253,
nat = 3,
ntyp = 2,
lspinorb = .true.
noncolin = .true.
assume_isolated = '2D'
force_symmorphic = .true.
/&end
&electrons
electron_maxstep = 200,
mixing_beta = 0.7,
conv_thr = 1.d-08,
/&end
ATOMIC_SPECIES
Mo 95.940 Mo_ONCV_PBE_FR-1.0.upf
S 32.065 S_ONCV_PBE_FR-1.1.upf
ATOMIC_POSITIONS { crystal }
Mo 0.333333333 0.666666667 0.000000000
S 0.666666667 0.333333333 0.073413577
S 0.666666667 0.333333333 -0.073413577
K_POINTS { automatic }
6 6 1 0 0 0

Here we are using full relativistic pseudopotentials from the SG-15 database.

We can run it on our machine (for example using 4 MPI tasks) as:

mpirun -np 4 pw.x -inp mos2.scf > scf.out

== Step 2: nscf calculation for Yambo ==

Copy the QE <code>save</code> directory from the scf calculation and run the nscf calculation for any number of empty states, with the correct <code>k</code>-grid we want to use in Yambo. Here we are using a badly underconverged grid of 6x6x1.

This reciprocal-space grid will also match the momentum transfer <code>q</code> grid on which excitons and phonons will be defined!

The electronic wavefunctions computed at this step and stored in the new nscf <code>save</code> directory will be used both by Yambo and by the electron-phonon code: this is important because using different sets of wavefunctions would lead to a phase mismatch issue in the exciton-phonon matrix elements.

The nscf input <code>mos2.nscf</code> is
&control
wf_collect = .true.,
calculation = "nscf",
verbosity = 'high',
pseudo_dir = '$PSEUDO_DIR',
prefix = "mos2",
outdir = '.',
/&end
&system
ecutwfc = 100.0,
occupations = 'fixed',
ibrav = 4,
celldm(1) = 5.9000811881,
celldm(3) = 6.7795677253,
nat = 3,
ntyp = 2,
lspinorb = .true.
noncolin = .true.
nbnd = 250
assume_isolated = '2D'
force_symmorphic = .true.
/&end
&electrons
electron_maxstep = 200,
mixing_beta = 0.7,
conv_thr = 1.d-08,
/&end
ATOMIC_SPECIES
Mo 95.940 Mo_ONCV_PBE_FR-1.0.upf
S 32.065 S_ONCV_PBE_FR-1.1.upf
ATOMIC_POSITIONS { crystal }
Mo 0.333333333 0.666666667 0.000000000
S 0.666666667 0.333333333 0.073413577
S 0.666666667 0.333333333 -0.073413577
K_POINTS { automatic }
6 6 1 0 0 0

Again, we run the calculation

mpirun -np 4 pw.x -inp mos2.nscf > nscf.out

== Step 3: dvscf phonon calculation ==

Now we run the phonon calculation.

Copy the <code>save</code> directory from the '''scf''' calculation and run <code>ph.x</code> for a dvscf calculation with a standard <code>q</code>-grid matching the <code>k</code>-grid we wanna use in Yambo.

At the end, we will have the <code>_ph0</code> directory containing the variation of the self-consistent potential, <math>\Delta V_{SCF}(q)</math>, and the <code>*.dyn</code> files with the phonon energies and eigenvectors.

NB: one could further refine the phonon energies by enforcing the acoustic sum rule, including non-analytic long-range contributions, interpolating to finer grids... all of this can be done within Quantum ESPRESSO and will not be covered in this version of the tutorial.

The input is <code>mos2.dvscf</code>:

mos2_dvscf
&inputph
tr2_ph=1.0d-12,
verbosity='high'
prefix='mos2',
fildvscf = 'mos2-dvscf',
electron_phonon = 'dvscf',
fildyn='mos2.dyn',
epsil=.false.,
ldisp=.true.,
recover=.true.,
nq1=6,
nq2=6,
nq3=1
/

And now we run as

nohup mpirun -np 8 ph.x -inp mos2.dvscf > dvscf.out &

This time we use nohup and more processes because this calculation may take some time. It is a good idea to set <code>recover=.true.</code> as in a real calculation you will easily breach walltime, and in this way you can safely restart.

== Step 4: create Yambo <code>SAVE</code> directory ==

This is just the standard Yambo initialization: run

p2y

and then

yambo

in the '''nscf''' <code>save</code> folder and then move the newly generated <code>SAVE</code> directory to a convenient place.

== Step 5: run a BSE calculation ==

Now we switch from QE to Yambo. Here, we forgo the GW step for simplicity (we can use a scissor operator to open the band gap).

This calculation has a couple of differences with respect to a standard BSE calculation for optical absorption. We can look at the input file <code>bse.in</code>:

# Runlevels
optics # [R OPT] Optics
rim_cut # [R RIM CUT] Coulomb potential
bss # [R BSS] Bethe Salpeter Equation solver
em1s # [R Xs] Static Inverse Dielectric Matrix
bse # [R BSE] Bethe Salpeter Equation.
bsk # [R BSK] Bethe Salpeter Equation kernel
# RIM and cutoff settings
RandQpts=1000000 # [RIM] Number of random q-points in the BZ
RandGvec= 100 RL # [RIM] Coulomb interaction RS components
CUTGeo= "slab z" # [CUT] Coulomb Cutoff geometry: box/cylinder/sphere X/Y/Z/XY..
# Static screening
X_and_IO_CPU= "1 1 4 2 1" # [PARALLEL] CPUs for each role
X_and_IO_ROLEs= "q g k c v" # [PARALLEL] CPUs roles (q,g,k,c,v)
X_and_IO_nCPU_LinAlg_INV=-1 # [PARALLEL] CPUs for Linear Algebra (if -1 it is automatically set)
Chimod= "hartree" # [X] IP/Hartree/ALDA/LRC/BSfxc
% BndsRnXs
1 | 200 | # [Xs] Polarization function bands
%
% LongDrXs
1.000000 | 1.000000 | 1.000000 | # [Xs] [cc] Electric Field
%
NGsBlkXs= 8000 mRy # [Xs] Response block size
# BSE
BS_CPU= "4.1.2" # [PARALLEL] CPUs for each role
BS_ROLEs= "k.eh.t" # [PARALLEL] CPUs roles (k,eh,t)
BS_nCPU_diago=4 # [PARALLEL] CPUs for matrix diagonalization
BSEmod= "causal" # [BSE] resonant/causal/coupling
BSKmod= "SEX" # [BSE] IP/Hartree/HF/ALDA/SEX/BSfxc
BSSmod= "d" # [BSS] (h)aydock/(d)iagonalization/(s)lepc/(i)nversion/(t)ddft`
BSENGexx= 40000 mRy # [BSK] Exchange components
ALLGexx # [BSS] Force the use use all RL vectors for the exchange part
BSENGBlk= 8000 mRy # [BSK] Screened interaction block size
Lkind="full" #[BSE,X] bar(default)/full/tilde
% KfnQP_E
1.000000 | 1.000000 | 1.000000 | # [EXTQP BSK BSS] E parameters (c/v) eV|adim|adim
%
% BEnRange
0.00000 | 4.00000 | eV # [BSS] Energy range
%
% BDmRange
0.05000 | 0.05000 | eV # [BSS] Damping range
%
BEnSteps= 2000 # [BSS] Energy steps
% BLongDir
1.000000 | 0.000000 | 0.000000 | # [BSS] [cc] Electric Field
%
% BSEQptR
 1 | 7 | # [BSK] Transferred momenta range
%
% BSEBands
25 | 28 | # [BSK] Bands range
%
WRbsWF # [BSS] Write to disk excitonic the FWs

This file was generated using the command: <code> yambo -X s -o b -k sex -y d -r</code> 

First of all, we compute the excitons for all the momenta in the irreducible Brillouin zone for our discrete grid via the <code>BSEQptR</code> variable. This will be a '''finite-momentum''' BSE calculation, analogous to the phonon one.

Second, we change the variable <code>Lkind</code> from <code>bar</code> to <code>full</code>. In Yambo, <code>Lkind="bar"</code>, which is the default for optical absorption, means that we are computing the excitonic response function without the long-range component of the exchange interaction. This cannot be used when computing the exciton momentum dependence, where the long-range exchange interaction can play a role, therefore we have to include it with <code>Lkind="full"</code>. This allows for the calculation of the excitonic longitudinal-transverse splitting (in 3D systems) as well.

We can now run the code:

nohup mpirun -np 8 yambo -F bse.in -J bse_Lfull -C bse_Lfull &

At the end of the calculation, we have obtained the <code>ndb.BS_diago_Q*</code> databases inside the directory <code>bse_Lfull</code>. They contain information on the exciton energies and wavefunctions at each momentum. Do not forget to check the report and logs of your calculation in the same directory to make sure that the code is doing what you want.

== Step 6: obtain the electron-phonon matrix elements ==

We have finished the heavy simulations. Now it's time for the postprocessing. The first order of business is the reconstruction of the electron-phonon coupling matrix elements from the dvscf results and the electronic wavefunctions.

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

We run in the same directory where the Yambo <code>SAVE</code> 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>n_i</math> to <math>n_f</math>, we should type:

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

Here <math>n_i</math> and <math>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>[n_i,n_f]</math> including the extrema of the interval.

These should coincide with those used for the Bethe-Salpeter kernel, i.e. those specified in the <code>BSEBands</code> variable of the BSE input file (this is not strictly necessary, but certainly efficient since these calculations use a lot of disk space).

For our system, we want to do a parallel calculation with 4 qpools and 2 kpools. In addition, we want to explicitly specify the path of the <code>lelphc</code> executable and avoid automatically deleting the LetzElPhC data. So we type:

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

At the end, check your directory: you should find the <code>lelphc.in</code> 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 <code>convention=yambo</code>: 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>n</math> and momentum <math>k-q</math> to band <math>m</math> and momentum <math>k</math>. In the "forward" momentum transfer convention (the more standard one), the transitions go from <math>nk</math> to <math>mk+q</math>. Therefore, this variable ensures that the electron-phonon coupling matrix elements are computed as <math>\langle mk|dV|nk-q\rangle</math>. This will have consequences also in the formulation of the ''exciton''-phonon coupling matrix element.

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

In addition, if you check the <code>SAVE</code> folder:

ls SAVE/ndb.elph_gkkp*

you will see that yambopy has created the Yambo-compatible electron-phonon databases.

If you want to run LetzElPhC directly, without using yambopy, you can refer to its [[https://gitlab.com/lumen-code/LetzElPhC/-/blob/main/docs/main.pdf?ref_type=heads|user guide]].
Keep in mind that in this case, in order to convert the database to the <code>ndb.elph_gkkp*</code> databases of Yambo, you will then need a couple of lines of python using the Yambopy class <code>ConvertElectronPhononDB</code> in <code>yambopy/letzelph_interface/lelph2y.py</code>.

If you don't need the <code>ndb.elph_gkkp*</code> databases -- e.g., because you are doing the exc-ph postprocessing with yambopy -- you can run <code>yambopy l2y ...</code> with the <code>--no_gkkp</code> option.

If you don't need the <code>ndb.elph</code> databases -- e.g., because you are using <code>yambo_ph</code> for the exc-ph part -- you can run <code>yambopy l2y ...</code> with the <code>--no_lelphc_dbs</code> option.

== Step 7: Obtain the exciton-phonon coupling ==

Now, we can finally access our basic building block for exciton-phonon physics. This could be done entirely in python (using '''Yambopy'''), or by running '''Yambo'''.

* For the '''Yambo postprocessing''' case (running yambo inputs with the <code>yambo_ph</code> executable), '''follow the alternative route to Steps 7-8 [[Exciton-phonon coupling and luminescence - Yambo postprocessing|at this link]]'''.
* For the '''Yambopy postprocessing''' case (using flexible python scripting), '''keep following Steps 7-8 on this page'''.

Our objective is obtaining the following quantity:

<math>\mathcal{G}^\mu_{\alpha\lambda}(0,q)=\sum_{vv^\prime c k} A^{\alpha, *}_{cv^\prime} (k, q) g_{vv^\prime}^\mu (k,q) A^{\lambda}_{cv}(k,0) - \sum_{cc^\prime vk} A^{\alpha, *}_{c^\prime v} (k+q, q) g_{c^\prime c}^\mu (k+q,q) A^{\lambda}_{cv}(k, 0)</math>

Here, <math>A^{\alpha}_{cv}(k,q)</math> are the exciton coefficients extracted from the eigenvector of the two-particles Hamiltonian during the BSE calculation in step 5, while <math>g_{nm}^\mu (k,q)</math> are the electron-phonon coupling matrix elements obtained in step 6. As you can see, the exciton <math>\lambda</math> undergoes phonon-mediated scattering to state <math>\alpha</math> via phonon mode <math>\mu</math>. The scattering can happen for the hole (valence, <math>v</math>) or for the electron (conduction, <math>c</math>).

NB:

(1) This is written in the "backward" momentum transfer convention used by Yambo. The momentum dependence is different in the "forward" transfer convention.

(2) For simplicity, this is written for zero initial exciton momentum. This means that one of the two states involved in the phonon-mediated scattering process will be in the optical limit (and possibly an optically generated exciton), while the other state can have any momentum: this momentum will be the same as the phonon one. This matrix element can be used to describe phonon-assisted absorption and emission spectra.

In order to calculate this quantity using python, we need the <code>ndb.elph</code> databases natively generated by the <code>LetzElPhC</code> code, as well as the BSE databases <code>ndb.BS_diago_Q*</code> containing the information on exciton wavefunctions and energies.

Next, we write a python user script importing the yambopy exciton-phonon tools. You can find a version of this script in <code>yambopy/tutorials/exciton-phonon/calculate_excph.py</code>.

import numpy as np
from yambopy import YamboLatticeDB,YamboWFDB,LetzElphElectronPhononDB #Specific Yambopy dbs loading classes
from yambopy.exciton_phonon.excph_matrix_elements import exciton_phonon_matelem #Specific exc-ph functions

path = '1L_MoS2'
bands_range=[24,28] # 2 valence bands, 2 conduction bands
nexc = 12 # number of excitonic states

bsepath = f'{path}/bse-allq_full' # Path to BSE calculation (Lin=Lout)
savepath = f'{path}/SAVE' # Yambo SAVE
ndb_elph = f'{path}/ndb.elph' # LetzElPhC electron-phonon database (any convention)

# Read lattice
lattice = YamboLatticeDB.from_db_file(filename=f'{savepath}/ns.db1')
# Read electron-phonon
elph = LetzElphElectronPhononDB(ndb_elph,read_all=False)
# Read wave functions
wfcs = YamboWFDB(filename='ns.wf',save=savepath,latdb=lattice,bands_range=bands_range)
# Calculate exciton-phonon matrix elements
exph = exciton_phonon_matelem(lattice,elph,wfcs,BSE_dir=bsepath,nexc_in=nexc,nexc_out=nexc,dmat_mode='save',exph_file='MoS2_Ex-ph.npy')

In this script, we can select the number exciton states <math>\lambda</math> with <code>nexc</code>, the single-particle bands range with <code>bands_range</code>. '''Please note''': in this case, the band index starts from 0 (python indexing) and the the interval of bands read by the code is <math>[n_i,n_f)</math>, therefore the last value (28 in the example) is excluded. That is, in the example we are selecting the 25th, 26th, 27th and 28th bands. Those bands have to be present in both the electron-phonon and BSE calculations.

Here we calculate the couplings of the first twelve states at each finite-<math>q</math> point including <math>q=0</math>. We also include all the nine phonon modes of monolayer MoS2. We also need access to the Yambo <code>SAVE</code> directory in order to read the electronic wavefunctions: they are used to compute the electronic representation matrices (<code>dmat</code> in the code). The argument <code>dmat_mode</code> can be set to <code>'load'</code> for subsequent calculations.

When we are satisfied with the input, we run the code:

python calculate_excph.py

If you check the output, you should find the <code>MoS2_Ex-ph.npy</code> binary file in the directory where you ran.

=== Analysis of the couplings ===

It is a good idea to have a look at what we computed up to now in order to make sure nothing has gone wrong.

It is not easy to know what to expect (apart from symmetry and gauge compliance of the matrix elements), but one can work out the exciton-phonon selection rules in advance, check that the magnitude is reasonable, etc.

It is also not easy to meaningfully plot this quantity. We have to make sure that we are not breaking degenerate states, otherwise the plots will not be invariant.

First of all, we have to know our system: in monolayer MoS2, the first four excitons are all doubly degenerate. The first exciton responsible for a bright peak in the absorption spectrum (the '''A''' peak), is the second state, corresponding to state indices <code>(3,4)</code> in fortran indexing or <code>(2,3)</code> in python indexing.

All these information can be obtained by analyzing the BSE results (this stuff is explained in the BSE tutorials) and by knowledge of the system or class of systems from the literature.

Thus, a good quantity to plot may be the norm of the matrix elements, summed over the degenerate subspace of exciton A, for a certain number of scattered final states mediated by certain phonon modes:

<math>F_A(q)= \sqrt{ \sum_{\alpha \in A,\lambda,\mu} |\mathcal{G}_{\alpha\lambda}^\mu (0,q)|^2 }</math>

In order to do this, we create a python script <code>analyse_excph.py</code> in which we first load the excph dabatases.
You can find a version of this script in the yambopy directory, in <code>tutorials/exciton-phonon</code>.
First, we select the exciton and phonon states to be included in <code>F_A</code>, together with the path of databases and plot details:

# Exciton "in" states
exc_in = [2,3] # First bright peak (A: 2,3 -- B: 6,7)
exc_out = [0,1,2,3] # first 4 states (dispersion of dark triplet state and A)
ph_in = 'all'
# Paths of databases
ns_db1 =f'{path}/SAVE/ns.db1'
ns_ypy = 'MoS2_Ex-ph.npy'

...

Then, we load the data:

# Read lattice and k-space info
ylat = YamboLatticeDB.from_db_file(filename=ns_db1)
print(ylat)

# Load exc-ph database
X_py = np.load(ns_ypy)
G_squared = np.abs(X_py)**2.

The quantity <math>F_A(q)</math> is obtained from a dedicated function as:

if exc_in == 'all': exc_in = range(G_squared.shape[2])
if exc_out == 'all': exc_out = range(G_squared.shape[3])
if ph_in == 'all': ph_in = range(G_squared.shape[1])

G_squared = G_squared[:, ph_in, :, :].sum(axis=(1))
G_squared = G_squared[:, exc_in, :].sum(axis=(1))
G_squared = G_squared[:, exc_out].sum(axis=(1))

F_q = np.sqrt( G_squared )*ha2ev # Switch from Ha to eV

And finally, we have to make a plotting function. For this tutorial we will use a custom scatterplot employing some of the plotting tools provided by yambopy (but you can do whatever you want).

plot_2D_excph(qgrid,G2_to_plot,rlat=ylat.rlat,plt_cbar=True,\
marker='H',s=700,cmap='magma')
...

You can get more experience on using Yambopy for these kinds of visualization by following the [https://wiki.yambo-code.eu/wiki/index.php?title=First_steps_in_Yambopy Yambopy tutorials]. In fact, remember that these scripts and all the other Yambopy tutorial scripts are just suggestions, not source code written in stone: if you know <code>numpy</code> and <code>matplotlib</code> you can do your own analysis and your own plots, you just need to import the required Yambopy modules to load the data.

In our case, the resulting plot is the following.

[[File:1L MoS2 MoS2 Ex-ph.png|500px|center]]

This can be checked against Fig. 2(d) of reference <ref name="chan2023" />, although you have to keep in mind that our results are badly undersampled in terms of the reciprocal-space grid, as can be easily seen, and the quantity plotted is not exactly the same. However, the main features are already there since they are dictated mostly by crystal symmetries.

Now that we have the exciton-phonon matrix elements, we can use them to build several kinds of observables. Below, we give an example related to phonon-assisted luminescence, but we may update this tutorial in the future to include more cases.

== Step 8: Compute phonon-assisted luminescence ==

[[File:Luminescence scheme.png|250px|right]]

We want to compute the experimental optical signature due to the phonon-assisted recombination of an exciton (as sketched in the figure).

The signal from the phonon replicas can be modeled as a second-order scattering process involving one phonon and one photon:

<math>I^{Sat}(\omega)=\frac{1}{ N_q} \frac{1}{3} \sum_{\epsilon s\beta \mu q} \frac{1}{E_{\beta q}-s\Omega_{\mu q}}\left|\sum_\alpha\frac{ D^{\epsilon}_\alpha \mathcal{G}_{\beta \alpha}^{\mu,*}(q)}{E_\alpha -E_{\beta q} +s\Omega_{\mu q}+\mathrm{i}\eta}\right|^2 \frac{N^{exc}_{\beta q}(T_{exc})[\frac{1+s}{2}+n_{\mu q}(T)]}{\omega -[E_{\beta q}-s\Omega_{\mu q}]+\mathrm{i}\eta}</math>

In this equation, the oscillator strength of the peak is given by the exciton-phonon coupling matrix elements <math>\mathcal{G}</math> multiplied by the exciton dipoles <math>D</math> (they are called "residuals" in Yambo). Here <math>E_\lambda</math> and <math>E_{\alpha q}</math> are the energies of the optical and finite-momentum excitons, respectively, while <math>\Omega_{\mu q}</math> are the phonon energies.

Here, <math>n_{\mu q}(T)</math> is the temperature-dependent phonon Bose-Einstein occupation function. As it can be seen, <math>s=1</math> corresponds to processes of phonon ''emission'' (<math>\propto n(T)+1</math>), while <math>s=-1</math> corresponds to processes of phonon ''absorption'' (<math>\propto n(T)</math>). Therefore, <math>I^{Sat}_{PL}(\omega;T)</math> describes ''light'' emission by recombining excitons mediated by either ''phonon'' absorption or emission.

The quantity <math> N_{\alpha q}(T_{exc})</math> is the exciton occupation function. Luminescence is technically an out-of-equilibrium process, but we can assume that for very low density of excitations and in steady-state conditions, the exciton population can be approximately described by an equilibrium distribution evaluated at an effective temperature. Here, we use the Boltzmann distribution. Experimentally, <math>T_{exc}</math> tends to coincide with the lattice temperature <math>T</math> more or less above 100 K, while at very low temperature (< 10 K), <math>T_{exc}</math> may vary between 10-50 K. It goes without saying that this needs to carefully be checked in your realistic calculations.

Finally, the spectrum is averaged over the polarization directions of the emitted photons (<math>\epsilon=x,y,z</math> representing the respective dipole components).

=== Running the jobs ===

In order to study luminescence in a paradigmatic system, we switch to bulk hexagonal boron nitride and we repeat the workflow. As you can easily see, one can think about automatizing the execution of all these calculations via scripting or more advanced tools. However, in the case of very large simulations (memory-limited or disk-space limited) or for systems whose electronic and lattice properties are fragile with respect to tiny calculation details, one must be very careful and run many basic tests.

Fortunately, we are running a fast underconverged example. We use LDA pseudopotentials from the pseudo-dojo library and the following are the calculations steps.

1. Input <code>hbn.scf</code>:

&control
calculation='scf',
prefix='hBN',
restart_mode='from_scratch'
pseudo_dir = '$PSEUDO_DIR',
outdir = './tmp'
verbosity = 'high'
wf_collect=.true.
/
&system
ibrav = 4,
celldm(1) = 4.703675849
celldm(3) = 2.603711434
nat= 4,
ntyp= 2,
force_symmorphic=.true.
ecutwfc = 100,
/
&electrons
diago_david_ndim = 2
diago_full_acc=.true.
diago_thr_init=5.0e-6
mixing_mode = 'plain'
mixing_beta = 0.7
conv_thr = 1.0d-16
/
ATOMIC_SPECIES
B 10.81100 B_LDA_dojo.UPF
N 14.00674 N_LDA_dojo.UPF
ATOMIC_POSITIONS {crystal}
N 0.6666666670 0.3333333330 -0.250000000000
B 0.3333333330 0.6666666670 -0.250000000000
B 0.6666666670 0.3333333330 0.25000000000
N 0.3333333330 0.6666666670 0.25000000000
K_POINTS {automatic}
6 6 2 0 0 0

mpirun -np 4 pw.x -inp hbn.scf > scf.out

2. Input <code>hbn.nscf</code>:

&control
calculation='nscf',
prefix='hBN',
restart_mode='from_scratch'
pseudo_dir = '$PSEUDO_DIR'
outdir = './'
verbosity = 'high'
wf_collect=.true.
/
&system
ibrav = 4,
celldm(1) = 4.703675849
celldm(3) = 2.603711434
nat= 4,
ntyp= 2,
force_symmorphic=.true.
ecutwfc = 100,
nbnd = 120
/
&electrons
diago_david_ndim = 2
diago_full_acc=.true.
diago_thr_init=5.0e-6
mixing_mode = 'plain'
mixing_beta = 0.7
conv_thr = 1.0d-16
/
ATOMIC_SPECIES
B 10.81100 B_LDA_dojo.UPF
N 14.00674 N_LDA_dojo.UPF
ATOMIC_POSITIONS {crystal}
N 0.6666666670 0.3333333330 -0.250000000000
B 0.3333333330 0.6666666670 -0.250000000000
B 0.6666666670 0.3333333330 0.25000000000
N 0.3333333330 0.6666666670 0.25000000000
K_POINTS {automatic}
6 6 2 0 0 0

mpirun -np 4 pw.x -inp hbn.nscf > nscf.out

3. Input <code>hbn.dvscf</code>:

hbn_dvscf
&inputph
tr2_ph=1.0d-12,
verbosity='high'
prefix='hBN',
fildvscf = 'hBN-dvscf',
electron_phonon = 'dvscf',
fildyn='hBN.dyn',
epsil=.false.,
ldisp=.true.,
recover=.true.,
nq1=6,
nq2=6,
nq3=2
/

nohup mpirun -np 8 pw.x -inp hbn.dvscf > dvscf.out &

4. Input <code>bse.in</code> (we include 2 valence and 2 conduction bands):

optics # [R] Linear Response optical properties
bss # [R] BSE solver
bse # [R][BSE] Bethe Salpeter Equation.
dipoles # [R] Oscillator strenghts (or dipoles)
em1s
DIP_CPU= "1 8 1" # [PARALLEL] CPUs for each role
DIP_ROLEs= "k c v" # [PARALLEL] CPUs roles (k,c,v)
DIP_Threads=0 # [OPENMP/X] Number of threads for dipoles
X_and_IO_CPU= "1 1 1 8 1" # [PARALLEL] CPUs for each role
X_and_IO_ROLEs= "q g k c v" # [PARALLEL] CPUs roles (q,g,k,c,v)
X_and_IO_nCPU_LinAlg_INV=-1 # [PARALLEL] CPUs for Linear Algebra (if -1 it is automatically set)
X_Threads=0 # [OPENMP/X] Number of threads for response functions
BS_CPU= "8 1 1" # [PARALLEL] CPUs for each role
BS_ROLEs= "k eh t" # [PARALLEL] CPUs roles (k,eh,t)
BS_nCPU_LinAlg_INV=-1 # [PARALLEL] CPUs for Linear Algebra (if -1 it is automatically set)
BS_nCPU_LinAlg_DIAGO=-1 # [PARALLEL] CPUs for Linear Algebra (if -1 it is automatically set)
X_Threads=0 # [OPENMP/X] Number of threads for response functions
K_Threads=0 # [OPENMP/BSK] Number of threads for response functions
% QpntsRXs
1 | 14 | # [Xs] Transferred momenta
%
% BndsRnXs
1 | 120 | # [Xs] Polarization function bands
%
NGsBlkXs= 10 Ry # [Xs] Response block size
% LongDrXs
1.000000 | 1.000000 | 1.000000 | # [Xs] [cc] Electric Field
%
BSEmod= "resonant" # [BSE] resonant/retarded/coupling
BSKmod= "SEX" # [BSE] IP/Hartree/HF/ALDA/SEX/BSfxc
Lkind= "Lfull" # [BSE] Lbar (default) / full
BSSmod= "d" # [BSS] (h)aydock/(d)iagonalization/(s)lepc/(i)nversion/(t)ddft`
% DipBands
1 | 120 | # [DIP] Bands range for dipoles
%
DipApproach= "G-space v" # [DIP] [G-space v/R-space x/Covariant/Shifted grids]
DipComputed= "R V P" # [DIP] [default R P V; extra P2 Spin Orb]
BSENGexx= 30000 Ry # [BSK] Exchange components
#ALLGexx # [BSS] Force the use use all RL vectors for the exchange part
BSENGBlk= 9000 Ry # [BSK] Screened interaction block size [if -1 uses all the G-vectors of W(q,G,Gp)]
% KfnQP_E
1.25997 | 1.08816 | 1.12683 | # [EXTQP BSK BSS] E parameters (c/v) eV|adim|adim
%
% BSEQptR
 1 | 14 | # [BSK] Transferred momenta range
%
% BSEBands
 7 | 10 | # [BSK] Bands range
%
% BEnRange
0.50000 | 8.00000 | eV # [BSS] Energy range
%
% BDmRange
0.050000 | 0.050000 | eV # [BSS] Damping range
%
BEnSteps= 1000 # [BSS] Energy steps
% BLongDir
1.000000 | 1.000000 | 0.000000 | # [BSS] [cc] Electric Field
%
WRbsWF # [BSS] Write to disk excitonic the WFs

nohup mpirun -np 8 yambo -F bse.in -J bse_Lfull -C bse_Lfull &

Importantly, since we want to describe the phonon-assisted recombination process of an *optical* exciton (i.e., emitting a transverse photon), this time we also run an additional calculation at `Q=0` omitting the nonanalytic long-range Coulomb exchange. Make a second input <code>bse_Lbar.in</code> with the following changes:

Lkind= "Lbar" # [BSE] Lbar (default) / full
% BSEQptR
 1 | 1 | # [BSK] Transferred momenta range
%

4b. So now we make a second BSE run in a different directory specified by <code>-J</code>. Here, we also pass to yambo the directory of the previous run as it includes the important screening databases <code>ndb.em1s*</code> that we do not want to recompute from scratch.

mpirun -np 8 yambo -F bse_Lbar.in -J bse_Lbar,bse_Lfull -C bse_Lbar

5. Now we run <code>lelphc</code> (with or without yambopy: in the latter case remember the option <code>-D</code>) to get the el-ph matrix elements, particularly the <code>ndb.elph</code> databases:

yambopy l2y -ph path/of/dvscf/hbn.dvscf -b 7 10 -par 4 2 -D

=== Luminescence calculation ===

6. And finally we calculate exciton-phonon matrix elements and the luminescence spectrum in one go using a python script importing the Yambopy exciton-phonon tools: in order to do this, we need to take a look at all the necessary input variables for the formula written above.

We can start from the script <code>luminescence.py</code> available in <code>tutorials/exciton-phonon</code>.

import numpy as np
import matplotlib.pyplot as plt
from yambopy.exciton_phonon.excph_luminescence import exc_ph_luminescence
from yambopy.exciton_phonon.excph_input_data import exc_ph_get_inputs

We import the necessary tools...

path = '3D_hBN'
# Path to BSE calculation (Lout--> response is Lfull)
bsepath = f'{path}/bse_Lfull' # ndb.BS_diago_Q* databases are needed
# Path to BSE calculation for optically active exciton (Lin --> response is Lbar)
bseBARpath = f'{path}/bse_Lbar' # ndb.BS_diago_Q1 database is needed
# Path to electron-phonon calculation
elphpath = path # ndb.elph is needed
# Path to unprojected dipoles matrix elements (optional)
dipolespath = bsepath # ndb.dipoles is needed (optional)
# Path to lattice and k-space info
savepath = f'{path}/SAVE' # ns.db1 database is needed

... and we specify the paths to the necessary databases. Note that, if we want to perform polarization averaging, we have to recompute the excitonic dipoles in python as seen here.

What about <code>bseBARpath</code>? This variable points to the directory where the databases for the optical (zero-momentum) excitons <math>\alpha</math> (which may be computed with <code>Lkind='Lbar'</code>) is located, which can be different from the directory with the full indirect exciton dispersion <math>\beta</math> (usually computed with <code>Lkind='Lfull'</code>, however <code>Lkind='Ltilde'</code> can also be used if one is interested in "irreducible" excitons). This makes it possible to compute the coupling between different exciton kinds.

bands_range=[6,10] # 2 valence, 2 conduction bands
phonons_range=[0,12] # All phonons
nexc_out = 12 # 12 excitonic states at each momentum (Lout)
nexc_in = 12 # 12 excitonic states at Q=0 (Lin)
T_ph = 10 # Lattice temperature
T_exc = 10 # Effective excitonic temperature

emin=4.4 # Energy range and plot details (in eV)
emax=4.7
estep=0.0002
broad = 0.005 # Broadening parameter for peak width (in eV)

Next, we specify the parameters for the calculation. We include valence bands from 7 to 10 (6 to 9 in python index) and the contribution of all 12 phonon modes. We consider 12 excitonic states for the coupling matrix elements.

Here <code>T_ph</code> and <code>T_exc</code> are the lattice and excitonic temperatures, respectively.

# We calculate and load all the inputs:
# * Exciton-phonon matrix elements
# * Excitonic dipole matrix elements
# * Exciton energies
# * Phonon energies
# * We specify bse_path2=bseBARpath meaning we use Lbar calculation for Q=0 excitons
input_data = exc_ph_get_inputs(savepath,elphpath,bsepath,\
bse_path2=bseBARpath,dipoles_path=dipolespath,\
nexc_in=12,nexc_out=12,\
bands_range=[6,10],phonons_range=[0,12])

ph_energies, exc_energies, exc_energies_in, G, exc_dipoles = input_data

The function <code>exc_ph_get_inputs</code> gives us all the input data for luminescence in the correct format: phonon energies, exciton energies, optical exciton energies (if needed), exciton-phonon matrix elements (calculated on the fly and printed to file), unprojected exciton dipoles (optional, calculated on the fly and printed to file).
The exc-ph matrix element calculation is just a wrapper of the same tools that we have tested in the above section on MoS2.

Finally, there is the calculation of the luminescence spectrum via the function <code>exc_ph_luminescence</code>:
# We calculate the luminescence spectrum including the input data from before
w,PL = exc_ph_luminescence(T_ph,ph_energies,exc_energies,exc_dipoles,G,\
exc_energies_in=exc_energies_in,exc_temp=T_exc,\
nexc_out=nexc_out,nexc_in=nexc_in,emin=emin,emax=emax,\
estep=estep,broad=broad)

If you want to print the luminescence data for later plotting, you can also add the following line to the script:
# Save to file
data = np.column_stack((w, PL))
np.savetxt("hBN_luminescence_12x12x1.dat", data, fmt="%.8f")

It is now time to run the whole script:

python luminescence.py

NB: By using Yambopy for Step 6, we have limited the use of the Yambo code to just step 4 in the entire workflow. This option is more flexible, as it allows for a greater degree of control by the user. On the other hand the Yambo postprocessing route features a Yambo-style input that doesn't require python knowledge and the calculation is currently faster in fortran. However, the luminescence expression computed in Yambo is a slightly different than this one: it is more approximated in the description of the satellite oscillator strengths, but it explicitly includes the renormalization of the direct exciton peak. You can check the differences [[Exciton-phonon coupling and luminescence - Yambo postprocessing|here]].

=== Results ===
We can plot the results of the step 6 calculation. If we do it in the same script we can add something like this:
fig = plt.figure()
ax = fig.add_subplot(1,1,1)
ax.set_xlim(emin,emax)
ax.set_ylim(0,np.max(PL)*1.1)
ax.get_yaxis().set_visible(False)

ax.plot(w, PL, '-',c='red', label="AA' hBN luminescence")

plt.legend()
plt.savefig('hBN_luminescence.png')
plt.show()

[[File:HBN luminescence satellites.png|500px|center]]

Here, the signal corresponds to a finite-momentum exciton that recombines with the help of several different phonon modes, both optical and acoustic. Each phonon mode whose coupling with the exciton is allowed can generate a peak, and the energy shifts of these peaks with respect to the initial exciton energy correspond to the phonon energies. This result is underconverged, but the main features are all there. In the plot, we show a more converged example using a 12x12x4 grid (all the other parameters being equal). These plots can be compared with Fig. 4(a) of reference <ref name="zanfrognini2023" />.

== References ==

<references>
<ref name="toyozawa2003" >Toyozawa, Yutaka, and Chris Oxlade, ''Optical processes in solids'', [https://m.booksee.org/book/1121964?force_lang=en Cambridge University Press, (2003)]. </ref>
<ref name='lechifflart2023'>P. Lechifflart, F. Paleari, D. Sangalli, C. Attaccalite, ''First-principles study of luminescence in hexagonal boron nitride single layer: Exciton-phonon coupling and the role of substrate'',
[https://doi.org/10.1103/PhysRevMaterials.7.024006 Phys. Rev. M, '''7''' (2), 024006 (2023)]; [https://arxiv.org/abs/2212.10407 arXiv2212.1047]</ref>
<ref name='cannuccia2019'>E. Cannuccia, B. Monserrat and C. Attaccalite, ''Theory of phonon-assisted luminescence in solids: Application to hexagonal boron nitride'', [https://doi.org/10.1103/PhysRevB.99.081109 Phys. Rev. B '''99''', 081109(R) (2019)]; [https://arxiv.org/abs/1807.11797 arXiv1807.11797]</ref>
<ref name='paleari2019'>F. Paleari et al., ''Exciton-Phonon Coupling in the Ultraviolet Absorption and Emission Spectra of Bulk Hexagonal Boron Nitride'', [https://doi.org/10.1103/PhysRevLett.122.187401 Phys. Rev. Lett. '''122''', 187401 (2019)]; [https://arxiv.org/abs/1810.08976 arXiv1810.089776] </ref>
<ref name='chen2020'>''Exciton-Phonon Interaction and Relaxation Times from First Principles'',
Hsiao-Yi Chen, Davide Sangalli, and Marco Bernardi, [https://doi.org/10.1103/PhysRevLett.125.107401 Phys. Rev. Lett. '''125''', 107401 (2020)]; [https://arxiv.org/abs/2002.08913 arXiv 2002.08913 (2020)]</ref>
<ref name="lechifflart2023_PhD">P. Lechifflart, ''Exciton-phonon coupling and phonon-assisted luminescence in hexagonal Boron Nitride nanostructures'', [https://hal.science/tel-04266805v1 PhD Thesis, University of Marseille (2023)]; [https://www.yambo-code.eu/wiki/images/5/54/These_final.pdf From the yambo website]</ref>
<ref name='paleari2019_PhD'>F. Paleari, ''First-principles approaches to the description of indirect absorption and luminescence spectroscopy: exciton-phonon coupling in hexagonal boron nitride'', [https://wwwen.uni.lu/research/fstm/dphyms/people/fulvio_paleari PhD thesis, University of Luxembourg (2019)]</ref>
<ref name='zanfrognini2023'>M. Zanfrognini et al., ''Distinguishing different stackings in layered materials via luminescence spectroscopy'', [https://doi.org/10.1103/PhysRevLett.131.206902 Phys. Rev. Lett. '''131''', 206902 (2023)]; [https://arxiv.org/abs/2305.17554 arXiv 2305.17554] </ref>
<ref name='marini2024'>G. Marini, M. Calandra, P. Cudazzo, ''Optical absorption and photoluminescence of single layer boron nitride from a first principles cumulant approach'', [https://doi.org/10.1021/acs.nanolett.4c00669 Nano Lett., '''24''', 20, 6017 (2024)]; [https://arxiv.org/abs/2402.03826 arXiv 2402.03826 (2024)]</ref>
<ref name='antonius2017'>G. Antonius, S. G. Louie, ''Theory of exciton-phonon coupling'', [https://doi.org/10.1103/PhysRevB.105.085111 Phys. Rev. B, '''105''', 085111 (2022)]; [https://arxiv.org/abs/1705.04245 arXiv1705.04245 (2017)]</ref>
<ref name='paleari2022'> F. Paleari, and A. Marini, ''Exciton-phonon interaction calls for a revision of the “exciton” concept'', [https://doi.org/10.1103/PhysRevB.106.125403 Phys. Rev. B, '''106''', 125403 (2022)]; [https://arxiv.org/abs/2205.02783 arXiv 2205.02783]</ref>
<ref name='cudazzo2020'> P. Cudazzo, ''First-principles description of the exciton-phonon interaction: A cumulant approach'', [https://doi.org/10.1103/PhysRevB.102.045136 Phys. Rev. B, '''102''', 045136 (2020)]; [https://orbilu.uni.lu/bitstream/10993/44769/1/main.pdf Open access pdf from Luxembourg University]</ref>
<ref name='chan2023'>Y-h Chan, J. B. Haber, M. H. Naik, J. B. Neaton, D. Y. Qiu, F. H. da Jornada, S. G. Louie, ''Exciton Lifetime and Optical Line Width Profile via Exciton–Phonon Interactions: Theory and First-Principles Calculations for Monolayer MoS2'', [https://doi.org/10.1021/acs.nanolett.3c00732 Nano Lett., '''23''', 9 (2023)]; [https://arxiv.org/abs/2212.08451 arXiv 2212.08451 (2023)]</ref>
<ref name='murali2025'>M. Nalabothula, S. Reichardt, L. Wirtz, ''Origin of Interlayer Exciton–Phonon Coupling in 2D Heterostructures'', [https://doi.org/10.1021/acs.nanolett.5c00355 Nano Lett., '''25''', 15 (2025)], [https://arxiv.org/abs/2407.16111 arXiv 2407.16111 (2025)]</ref>
</references>

Exciton-phonon coupling and luminescence

2026-03-13T14:45:50Z

FulvioPaleari:

[[exc-ph scheme| Tdgw-phonon-usc-01-1024x829.jpg| (c) Zhenglu Li, University of Southern California |400px | right ]]

In this advanced tutorial, we will calculate exciton-phonon interactions from first principles by interfacing DFPT (for phonon calculations) and BSE (for exciton calculations).

The DFTP calculations are run with Quantum ESPRESSO, while the many-body GW-BSE calculations are run with Yambo. Finally, the exciton-phonon interaction will be obtained by combining and postprocessing the databases computed in the two previous runs. The great advantage of this workflow is that the calculations can be run in the irreducible Brillouin zones both for the electronic momenta ('''k''') and the transfer momenta ('''Q''', '''q''') of excitons and phonons, thus speeding up considerably the jobs while reducing the IO and memory load.

We will first compute the exciton-phonon coupling matrix elements: these are the building blocks needed to construct experimental observables such as phonon-assisted optical spectra (such as luminescence), Raman spectra and exciton lifetimes. We will do this in the case of monolayer MoS2, a 2D system with large spin-orbit interaction.

As an example of application, we will consider the case of phonon-assisted luminescence. We will do this in the case of bulk hBN, a layered indirect insulator with strong electron-phonon coupling.

'''Note:''' this tutorial will be updated when new exc-ph tools become available in Yambopy (including full-python postprocessing, Raman spectra, interpolated lifetimes, etc).

== Requirements ==

This is an advanced topic: we assume that you already know something about the theory<ref name="toyozawa2003" /><ref name="antonius2017" /><ref name="cudazzo2020" /><ref name="paleari2019_PhD" /><ref name="paleari2022" /><ref name="lechifflart2023_PhD" /> and applications<ref name="paleari2019" /><ref name="cannuccia2019" /><ref name="chen2020" /><ref name="zanfrognini2023" /><ref name="lechifflart2023" /><ref name="chan2023" /><ref name="marini2024" /><ref name="murali2025" /> of exciton-phonon physics.

Also, we assume that you already know how to run both a basic '''Yambo''' GW-BSE calculation and a DFPT phonon calculation with '''Quantum ESPRESSO'''.

Besides the QE executables <code>pw.x</code> and <code>ph.x</code>, we also use the yambo phonon-specific executable <code>yambo_ph</code> and the python utility '''Yambopy'''. The auxiliary code '''LetzElPhC''' (executable <code>lelphc</code>) will be used to obtain the electron-phonon matrix elements by reading the same electronic wavefunctions used by Yambo (and stored in the <code>SAVE</code> directory), while also making full use of crystal symmetries. [https://github.com/yambo-code/LetzElPhC LetzElPhC] will be run by Yambopy, but it must nonetheless be installed. Finally, the exciton-phonon properties can be computed either using <code>yambo_ph</code> or using Yambopy itself. Both cases will be covered in this tutorial.

[[File:Workflow scheme.png|800px|center]]

== Step 0: Pseudopotentials, equilibrium structure and convergence ==

In a real calculation, it is important to ensure that both the pseudopotential and the lattice parameters that we are using are compatible and perform well for the electronic excited states and for the lattice vibrations simultaneously. Furthermore, you have to make sure that the wave function cutoff <code>ecutwfc</code> is converged with respect to the DFPT step and not just to the DFT one. This is in addition to the other customary convergence tests for DFT, DFPT, GW and BSE calculations.

This is often the most time-demanding step when starting on a new system.

For the sake of this tutorial, we assume that we have already done all these tests and we are starting the final workflow to get the exciton-phonon properties.

== Step 1: scf calculation ==

First of all, we run a standard scf calculation with <code>pw.x</code> for Yambo. We stick with non-symmorphic symmetries. At the end, we will have the QE <code>save</code> directory.

This is the input <code>mos2.scf</code>:

&control
wf_collect = .true.,
calculation = "scf",
verbosity = 'high',
pseudo_dir = '$PSEUDO_DIR',
prefix = "mos2",
outdir = '.',
/&end
&system
ecutwfc = 100.0,
occupations = 'fixed',
ibrav = 4,
celldm(1) = 5.9000811881,
celldm(3) = 6.7795677253,
nat = 3,
ntyp = 2,
lspinorb = .true.
noncolin = .true.
assume_isolated = '2D'
force_symmorphic = .true.
/&end
&electrons
electron_maxstep = 200,
mixing_beta = 0.7,
conv_thr = 1.d-08,
/&end
ATOMIC_SPECIES
Mo 95.940 Mo_ONCV_PBE_FR-1.0.upf
S 32.065 S_ONCV_PBE_FR-1.1.upf
ATOMIC_POSITIONS { crystal }
Mo 0.333333333 0.666666667 0.000000000
S 0.666666667 0.333333333 0.073413577
S 0.666666667 0.333333333 -0.073413577
K_POINTS { automatic }
6 6 1 0 0 0

Here we are using full relativistic pseudopotentials from the SG-15 database.

We can run it on our machine (for example using 4 MPI tasks) as:

mpirun -np 4 pw.x -inp mos2.scf > scf.out

== Step 2: nscf calculation for Yambo ==

Copy the QE <code>save</code> directory from the scf calculation and run the nscf calculation for any number of empty states, with the correct <code>k</code>-grid we want to use in Yambo. Here we are using a badly underconverged grid of 6x6x1.

This reciprocal-space grid will also match the momentum transfer <code>q</code> grid on which excitons and phonons will be defined!

The electronic wavefunctions computed at this step and stored in the new nscf <code>save</code> directory will be used both by Yambo and by the electron-phonon code: this is important because using different sets of wavefunctions would lead to a phase mismatch issue in the exciton-phonon matrix elements.

The nscf input <code>mos2.nscf</code> is
&control
wf_collect = .true.,
calculation = "nscf",
verbosity = 'high',
pseudo_dir = '$PSEUDO_DIR',
prefix = "mos2",
outdir = '.',
/&end
&system
ecutwfc = 100.0,
occupations = 'fixed',
ibrav = 4,
celldm(1) = 5.9000811881,
celldm(3) = 6.7795677253,
nat = 3,
ntyp = 2,
lspinorb = .true.
noncolin = .true.
nbnd = 250
assume_isolated = '2D'
force_symmorphic = .true.
/&end
&electrons
electron_maxstep = 200,
mixing_beta = 0.7,
conv_thr = 1.d-08,
/&end
ATOMIC_SPECIES
Mo 95.940 Mo_ONCV_PBE_FR-1.0.upf
S 32.065 S_ONCV_PBE_FR-1.1.upf
ATOMIC_POSITIONS { crystal }
Mo 0.333333333 0.666666667 0.000000000
S 0.666666667 0.333333333 0.073413577
S 0.666666667 0.333333333 -0.073413577
K_POINTS { automatic }
6 6 1 0 0 0

Again, we run the calculation

mpirun -np 4 pw.x -inp mos2.nscf > nscf.out

== Step 3: dvscf phonon calculation ==

Now we run the phonon calculation.

Copy the <code>save</code> directory from the '''scf''' calculation and run <code>ph.x</code> for a dvscf calculation with a standard <code>q</code>-grid matching the <code>k</code>-grid we wanna use in Yambo.

At the end, we will have the <code>_ph0</code> directory containing the variation of the self-consistent potential, <math>\Delta V_{SCF}(q)</math>, and the <code>*.dyn</code> files with the phonon energies and eigenvectors.

NB: one could further refine the phonon energies by enforcing the acoustic sum rule, including non-analytic long-range contributions, interpolating to finer grids... all of this can be done within Quantum ESPRESSO and will not be covered in this version of the tutorial.

The input is <code>mos2.dvscf</code>:

mos2_dvscf
&inputph
tr2_ph=1.0d-12,
verbosity='high'
prefix='mos2',
fildvscf = 'mos2-dvscf',
electron_phonon = 'dvscf',
fildyn='mos2.dyn',
epsil=.false.,
ldisp=.true.,
recover=.true.,
nq1=6,
nq2=6,
nq3=1
/

And now we run as

nohup mpirun -np 8 ph.x -inp mos2.dvscf > dvscf.out &

This time we use nohup and more processes because this calculation may take some time. It is a good idea to set <code>recover=.true.</code> as in a real calculation you will easily breach walltime, and in this way you can safely restart.

== Step 4: create Yambo <code>SAVE</code> directory ==

This is just the standard Yambo initialization: run

p2y

and then

yambo

in the '''nscf''' <code>save</code> folder and then move the newly generated <code>SAVE</code> directory to a convenient place.

== Step 5: run a BSE calculation ==

Now we switch from QE to Yambo. Here, we forgo the GW step for simplicity (we can use a scissor operator to open the band gap).

This calculation has a couple of differences with respect to a standard BSE calculation for optical absorption. We can look at the input file <code>bse.in</code>:

# Runlevels
optics # [R OPT] Optics
rim_cut # [R RIM CUT] Coulomb potential
bss # [R BSS] Bethe Salpeter Equation solver
em1s # [R Xs] Static Inverse Dielectric Matrix
bse # [R BSE] Bethe Salpeter Equation.
bsk # [R BSK] Bethe Salpeter Equation kernel
# RIM and cutoff settings
RandQpts=1000000 # [RIM] Number of random q-points in the BZ
RandGvec= 100 RL # [RIM] Coulomb interaction RS components
CUTGeo= "slab z" # [CUT] Coulomb Cutoff geometry: box/cylinder/sphere X/Y/Z/XY..
# Static screening
X_and_IO_CPU= "1 1 4 2 1" # [PARALLEL] CPUs for each role
X_and_IO_ROLEs= "q g k c v" # [PARALLEL] CPUs roles (q,g,k,c,v)
X_and_IO_nCPU_LinAlg_INV=-1 # [PARALLEL] CPUs for Linear Algebra (if -1 it is automatically set)
Chimod= "hartree" # [X] IP/Hartree/ALDA/LRC/BSfxc
% BndsRnXs
1 | 200 | # [Xs] Polarization function bands
%
% LongDrXs
1.000000 | 1.000000 | 1.000000 | # [Xs] [cc] Electric Field
%
NGsBlkXs= 8000 mRy # [Xs] Response block size
# BSE
BS_CPU= "4.1.2" # [PARALLEL] CPUs for each role
BS_ROLEs= "k.eh.t" # [PARALLEL] CPUs roles (k,eh,t)
BS_nCPU_diago=4 # [PARALLEL] CPUs for matrix diagonalization
BSEmod= "causal" # [BSE] resonant/causal/coupling
BSKmod= "SEX" # [BSE] IP/Hartree/HF/ALDA/SEX/BSfxc
BSSmod= "d" # [BSS] (h)aydock/(d)iagonalization/(s)lepc/(i)nversion/(t)ddft`
BSENGexx= 40000 mRy # [BSK] Exchange components
ALLGexx # [BSS] Force the use use all RL vectors for the exchange part
BSENGBlk= 8000 mRy # [BSK] Screened interaction block size
Lkind="full" #[BSE,X] bar(default)/full/tilde
% KfnQP_E
1.000000 | 1.000000 | 1.000000 | # [EXTQP BSK BSS] E parameters (c/v) eV|adim|adim
%
% BEnRange
0.00000 | 4.00000 | eV # [BSS] Energy range
%
% BDmRange
0.05000 | 0.05000 | eV # [BSS] Damping range
%
BEnSteps= 2000 # [BSS] Energy steps
% BLongDir
1.000000 | 0.000000 | 0.000000 | # [BSS] [cc] Electric Field
%
% BSEQptR
 1 | 7 | # [BSK] Transferred momenta range
%
% BSEBands
25 | 28 | # [BSK] Bands range
%
WRbsWF # [BSS] Write to disk excitonic the FWs

This file was generated using the command: <code> yambo -X s -o b -k sex -y d -r</code> 

First of all, we compute the excitons for all the momenta in the irreducible Brillouin zone for our discrete grid via the <code>BSEQptR</code> variable. This will be a '''finite-momentum''' BSE calculation, analogous to the phonon one.

Second, we change the variable <code>Lkind</code> from <code>bar</code> to <code>full</code>. In Yambo, <code>Lkind="bar"</code>, which is the default for optical absorption, means that we are computing the excitonic response function without the long-range component of the exchange interaction. This cannot be used when computing the exciton momentum dependence, where the long-range exchange interaction can play a role, therefore we have to include it with <code>Lkind="full"</code>. This allows for the calculation of the excitonic longitudinal-transverse splitting (in 3D systems) as well.

We can now run the code:

nohup mpirun -np 8 yambo -F bse.in -J bse_Lfull -C bse_Lfull &

At the end of the calculation, we have obtained the <code>ndb.BS_diago_Q*</code> databases inside the directory <code>bse_Lfull</code>. They contain information on the exciton energies and wavefunctions at each momentum. Do not forget to check the report and logs of your calculation in the same directory to make sure that the code is doing what you want.

== Step 6: obtain the electron-phonon matrix elements ==

We have finished the heavy simulations. Now it's time for the postprocessing. The first order of business is the reconstruction of the electron-phonon coupling matrix elements from the dvscf results and the electronic wavefunctions.

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

We run in the same directory where the Yambo <code>SAVE</code> 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>n_i</math> to <math>n_f</math>, we should type:

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

Here <math>n_i</math> and <math>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>[n_i,n_f]</math> including the extrema of the interval.

These should coincide with those used for the Bethe-Salpeter kernel, i.e. those specified in the <code>BSEBands</code> variable of the BSE input file (this is not strictly necessary, but certainly efficient since these calculations use a lot of disk space).

For our system, we want to do a parallel calculation with 4 qpools and 2 kpools. In addition, we want to explicitly specify the path of the <code>lelphc</code> executable and avoid automatically deleting the LetzElPhC data. So we type:

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

At the end, check your directory: you should find the <code>lelphc.in</code> 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 <code>convention=yambo</code>: 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>n</math> and momentum <math>k-q</math> to band <math>m</math> and momentum <math>k</math>. In the "forward" momentum transfer convention (the more standard one), the transitions go from <math>nk</math> to <math>mk+q</math>. Therefore, this variable ensures that the electron-phonon coupling matrix elements are computed as <math>\langle mk|dV|nk-q\rangle</math>. This will have consequences also in the formulation of the ''exciton''-phonon coupling matrix element.

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

In addition, if you check the <code>SAVE</code> folder:

ls SAVE/ndb.elph_gkkp*

you will see that yambopy has created the Yambo-compatible electron-phonon databases.

If you want to run LetzElPhC directly, without using yambopy, you can refer to its [[https://gitlab.com/lumen-code/LetzElPhC/-/blob/main/docs/main.pdf?ref_type=heads|user guide]].
Keep in mind that in this case, in order to convert the database to the <code>ndb.elph_gkkp*</code> databases of Yambo, you will then need a couple of lines of python using the Yambopy class <code>ConvertElectronPhononDB</code> in <code>yambopy/letzelph_interface/lelph2y.py</code>.

If you don't need the <code>ndb.elph_gkkp*</code> databases -- e.g., because you are doing the exc-ph postprocessing with yambopy -- you can run <code>yambopy l2y ...</code> with the <code>--no_gkkp</code> option.

If you don't need the <code>ndb.elph</code> databases -- e.g., because you are using <code>yambo_ph</code> for the exc-ph part -- you can run <code>yambopy l2y ...</code> with the <code>--no_lelphc_dbs</code> option.

== Step 7: Obtain the exciton-phonon coupling ==

Now, we can finally access our basic building block for exciton-phonon physics. This could be done entirely in python (using '''Yambopy'''), or by running '''Yambo'''.

* For the '''Yambo postprocessing''' case (running yambo inputs with the <code>yambo_ph</code> executable), '''follow the alternative route to Steps 7-8 [[Exciton-phonon coupling and luminescence - Yambo postprocessing|at this link]]'''.
* For the '''Yambopy postprocessing''' case (using flexible python scripting), '''keep following Steps 7-8 on this page'''.

Our objective is obtaining the following quantity:

<math>\mathcal{G}^\mu_{\alpha\lambda}(0,q)=\sum_{vv^\prime c k} A^{\alpha, *}_{cv^\prime} (k, q) g_{vv^\prime}^\mu (k,q) A^{\lambda}_{cv}(k,0) - \sum_{cc^\prime vk} A^{\alpha, *}_{c^\prime v} (k+q, q) g_{c^\prime c}^\mu (k+q,q) A^{\lambda}_{cv}(k, 0)</math>

Here, <math>A^{\alpha}_{cv}(k,q)</math> are the exciton coefficients extracted from the eigenvector of the two-particles Hamiltonian during the BSE calculation in step 5, while <math>g_{nm}^\mu (k,q)</math> are the electron-phonon coupling matrix elements obtained in step 6. As you can see, the exciton <math>\lambda</math> undergoes phonon-mediated scattering to state <math>\alpha</math> via phonon mode <math>\mu</math>. The scattering can happen for the hole (valence, <math>v</math>) or for the electron (conduction, <math>c</math>).

NB:

(1) This is written in the "backward" momentum transfer convention used by Yambo. The momentum dependence is different in the "forward" transfer convention.

(2) For simplicity, this is written for zero initial exciton momentum. This means that one of the two states involved in the phonon-mediated scattering process will be in the optical limit (and possibly an optically generated exciton), while the other state can have any momentum: this momentum will be the same as the phonon one. This matrix element can be used to describe phonon-assisted absorption and emission spectra.

In order to calculate this quantity using python, we need the <code>ndb.elph</code> databases natively generated by the <code>LetzElPhC</code> code, as well as the BSE databases <code>ndb.BS_diago_Q*</code> containing the information on exciton wavefunctions and energies.

Next, we write a python user script importing the yambopy exciton-phonon tools. You can find a version of this script in <code>yambopy/tutorials/exciton-phonon/calculate_excph.py</code>.

import numpy as np
from yambopy import YamboLatticeDB,YamboWFDB,LetzElphElectronPhononDB #Specific Yambopy dbs loading classes
from yambopy.exciton_phonon.excph_matrix_elements import exciton_phonon_matelem #Specific exc-ph functions

path = '1L_MoS2'
bands_range=[24,28] # 2 valence bands, 2 conduction bands
nexc = 12 # number of excitonic states

bsepath = f'{path}/bse-allq_full' # Path to BSE calculation (Lin=Lout)
savepath = f'{path}/SAVE' # Yambo SAVE
ndb_elph = f'{path}/ndb.elph' # LetzElPhC electron-phonon database (any convention)

# Read lattice
lattice = YamboLatticeDB.from_db_file(filename=f'{savepath}/ns.db1')
# Read electron-phonon
elph = LetzElphElectronPhononDB(ndb_elph,read_all=False)
# Read wave functions
wfcs = YamboWFDB(filename='ns.wf',save=savepath,latdb=lattice,bands_range=bands_range)
# Calculate exciton-phonon matrix elements
exph = exciton_phonon_matelem(lattice,elph,wfcs,BSE_dir=bsepath,nexc_in=nexc,nexc_out=nexc,dmat_mode='save',exph_file='MoS2_Ex-ph.npy')

In this script, we can select the number exciton states <math>\lambda</math> with <code>nexc</code>, the single-particle bands range with <code>bands_range</code>. '''Please note''': in this case, the band index starts from 0 (python indexing) and the the interval of bands read by the code is <math>[n_i,n_f)</math>, therefore the last value (28 in the example) is excluded. That is, in the example we are selecting the 25th, 26th, 27th and 28th bands. Those bands have to be present in both the electron-phonon and BSE calculations.

Here we calculate the couplings of the first twelve states at each finite-<math>q</math> point including <math>q=0</math>. We also include all the nine phonon modes of monolayer MoS2. We also need access to the Yambo <code>SAVE</code> directory in order to read the electronic wavefunctions: they are used to compute the electronic representation matrices (<code>dmat</code> in the code). The argument <code>dmat_mode</code> can be set to <code>'load'</code> for subsequent calculations.

When we are satisfied with the input, we run the code:

python calculate_excph.py

If you check the output, you should find the <code>MoS2_Ex-ph.npy</code> binary file in the directory where you ran.

=== Analysis of the couplings ===

It is a good idea to have a look at what we computed up to now in order to make sure nothing has gone wrong.

It is not easy to know what to expect (apart from symmetry and gauge compliance of the matrix elements), but one can work out the exciton-phonon selection rules in advance, check that the magnitude is reasonable, etc.

It is also not easy to meaningfully plot this quantity. We have to make sure that we are not breaking degenerate states, otherwise the plots will not be invariant.

First of all, we have to know our system: in monolayer MoS2, the first four excitons are all doubly degenerate. The first exciton responsible for a bright peak in the absorption spectrum (the '''A''' peak), is the second state, corresponding to state indices <code>(3,4)</code> in fortran indexing or <code>(2,3)</code> in python indexing.

All these information can be obtained by analyzing the BSE results (this stuff is explained in the BSE tutorials) and by knowledge of the system or class of systems from the literature.

Thus, a good quantity to plot may be the norm of the matrix elements, summed over the degenerate subspace of exciton A, for a certain number of scattered final states mediated by certain phonon modes:

<math>F_A(q)= \sqrt{ \sum_{\alpha \in A,\lambda,\mu} |\mathcal{G}_{\alpha\lambda}^\mu (0,q)|^2 }</math>

In order to do this, we create a python script <code>analyse_excph.py</code> in which we first load the excph dabatases.
You can find a version of this script in the yambopy directory, in <code>tutorials/exciton-phonon</code>.
First, we select the exciton and phonon states to be included in <code>F_A</code>, together with the path of databases and plot details:

# Exciton "in" states
exc_in = [2,3] # First bright peak (A: 2,3 -- B: 6,7)
exc_out = [0,1,2,3] # first 4 states (dispersion of dark triplet state and A)
ph_in = 'all'
# Paths of databases
ns_db1 =f'{path}/SAVE/ns.db1'
ns_ypy = 'MoS2_Ex-ph.npy'

...

Then, we load the data:

# Read lattice and k-space info
ylat = YamboLatticeDB.from_db_file(filename=ns_db1)
print(ylat)

# Load exc-ph database
X_py = np.load(ns_ypy)
G_squared = np.abs(X_py)**2.

The quantity <math>F_A(q)</math> is obtained from a dedicated function as:

if exc_in == 'all': exc_in = range(G_squared.shape[2])
if exc_out == 'all': exc_out = range(G_squared.shape[3])
if ph_in == 'all': ph_in = range(G_squared.shape[1])

G_squared = G_squared[:, ph_in, :, :].sum(axis=(1))
G_squared = G_squared[:, exc_in, :].sum(axis=(1))
G_squared = G_squared[:, exc_out].sum(axis=(1))

F_q = np.sqrt( G_squared )*ha2ev # Switch from Ha to eV

And finally, we have to make a plotting function. For this tutorial we will use a custom scatterplot employing some of the plotting tools provided by yambopy (but you can do whatever you want).

plot_2D_excph(qgrid,G2_to_plot,rlat=ylat.rlat,plt_cbar=True,\
marker='H',s=700,cmap='magma')
...

You can get more experience on using Yambopy for these kinds of visualization by following the [https://wiki.yambo-code.eu/wiki/index.php?title=First_steps_in_Yambopy Yambopy tutorials]. In fact, remember that these scripts and all the other Yambopy tutorial scripts are just suggestions, not source code written in stone: if you know <code>numpy</code> and <code>matplotlib</code> you can do your own analysis and your own plots, you just need to import the required Yambopy modules to load the data.

In our case, the resulting plot is the following.

[[File:1L MoS2 MoS2 Ex-ph.png|500px|center]]

This can be checked against Fig. 2(d) of reference <ref name="chan2023" />, although you have to keep in mind that our results are badly undersampled in terms of the reciprocal-space grid, as can be easily seen, and the quantity plotted is not exactly the same. However, the main features are already there since they are dictated mostly by crystal symmetries.

Now that we have the exciton-phonon matrix elements, we can use them to build several kinds of observables. Below, we give an example related to phonon-assisted luminescence, but we may update this tutorial in the future to include more cases.

== Step 8: Compute phonon-assisted luminescence ==

[[File:Luminescence scheme.png|250px|right]]

We want to compute the experimental optical signature due to the phonon-assisted recombination of an exciton (as sketched in the figure).

The signal from the phonon replicas can be modeled as a second-order scattering process involving one phonon and one photon:

<math>I^{Sat}(\omega)=\frac{1}{ N_q} \frac{1}{3} \sum_{\epsilon s\beta \mu q} \frac{1}{E_{\beta q}-s\Omega_{\mu q}}\left|\sum_\alpha\frac{ D^{\epsilon}_\alpha \mathcal{G}_{\beta \alpha}^{\mu,*}(q)}{E_\alpha -E_{\beta q} +s\Omega_{\mu q}+\mathrm{i}\eta}\right|^2 \frac{N^{exc}_{\beta q}(T_{exc})[\frac{1+s}{2}+n_{\mu q}(T)]}{\omega -[E_{\beta q}-s\Omega_{\mu q}]+\mathrm{i}\eta}</math>

In this equation, the oscillator strength of the peak is given by the exciton-phonon coupling matrix elements <math>\mathcal{G}</math> multiplied by the exciton dipoles <math>D</math> (they are called "residuals" in Yambo). Here <math>E_\lambda</math> and <math>E_{\alpha q}</math> are the energies of the optical and finite-momentum excitons, respectively, while <math>\Omega_{\mu q}</math> are the phonon energies.

Here, <math>n_{\mu q}(T)</math> is the temperature-dependent phonon Bose-Einstein occupation function. As it can be seen, <math>s=1</math> corresponds to processes of phonon ''emission'' (<math>\propto n(T)+1</math>), while <math>s=-1</math> corresponds to processes of phonon ''absorption'' (<math>\propto n(T)</math>). Therefore, <math>I^{Sat}_{PL}(\omega;T)</math> describes ''light'' emission by recombining excitons mediated by either ''phonon'' absorption or emission.

The quantity <math> N_{\alpha q}(T_{exc})</math> is the exciton occupation function. Luminescence is technically an out-of-equilibrium process, but we can assume that for very low density of excitations and in steady-state conditions, the exciton population can be approximately described by an equilibrium distribution evaluated at an effective temperature. Here, we use the Boltzmann distribution. Experimentally, <math>T_{exc}</math> tends to coincide with the lattice temperature <math>T</math> more or less above 100 K, while at very low temperature (< 10 K), <math>T_{exc}</math> may vary between 10-50 K. It goes without saying that this needs to carefully be checked in your realistic calculations.

Finally, the spectrum is averaged over the polarization directions of the emitted photons (<math>\epsilon=x,y,z</math> representing the respective dipole components).

=== Running the jobs ===

In order to study luminescence in a paradigmatic system, we switch to bulk hexagonal boron nitride and we repeat the workflow. As you can easily see, one can think about automatizing the execution of all these calculations via scripting or more advanced tools. However, in the case of very large simulations (memory-limited or disk-space limited) or for systems whose electronic and lattice properties are fragile with respect to tiny calculation details, one must be very careful and run many basic tests.

Fortunately, we are running a fast underconverged example. We use LDA pseudopotentials from the pseudo-dojo library and the following are the calculations steps.

1. Input <code>hbn.scf</code>:

&control
calculation='scf',
prefix='hBN',
restart_mode='from_scratch'
pseudo_dir = '$PSEUDO_DIR',
outdir = './tmp'
verbosity = 'high'
wf_collect=.true.
/
&system
ibrav = 4,
celldm(1) = 4.703675849
celldm(3) = 2.603711434
nat= 4,
ntyp= 2,
force_symmorphic=.true.
ecutwfc = 100,
/
&electrons
diago_david_ndim = 2
diago_full_acc=.true.
diago_thr_init=5.0e-6
mixing_mode = 'plain'
mixing_beta = 0.7
conv_thr = 1.0d-16
/
ATOMIC_SPECIES
B 10.81100 B_LDA_dojo.UPF
N 14.00674 N_LDA_dojo.UPF
ATOMIC_POSITIONS {crystal}
N 0.6666666670 0.3333333330 -0.250000000000
B 0.3333333330 0.6666666670 -0.250000000000
B 0.6666666670 0.3333333330 0.25000000000
N 0.3333333330 0.6666666670 0.25000000000
K_POINTS {automatic}
6 6 2 0 0 0

mpirun -np 4 pw.x -inp hbn.scf > scf.out

2. Input <code>hbn.nscf</code>:

&control
calculation='nscf',
prefix='hBN',
restart_mode='from_scratch'
pseudo_dir = '$PSEUDO_DIR'
outdir = './'
verbosity = 'high'
wf_collect=.true.
/
&system
ibrav = 4,
celldm(1) = 4.703675849
celldm(3) = 2.603711434
nat= 4,
ntyp= 2,
force_symmorphic=.true.
ecutwfc = 100,
nbnd = 120
/
&electrons
diago_david_ndim = 2
diago_full_acc=.true.
diago_thr_init=5.0e-6
mixing_mode = 'plain'
mixing_beta = 0.7
conv_thr = 1.0d-16
/
ATOMIC_SPECIES
B 10.81100 B_LDA_dojo.UPF
N 14.00674 N_LDA_dojo.UPF
ATOMIC_POSITIONS {crystal}
N 0.6666666670 0.3333333330 -0.250000000000
B 0.3333333330 0.6666666670 -0.250000000000
B 0.6666666670 0.3333333330 0.25000000000
N 0.3333333330 0.6666666670 0.25000000000
K_POINTS {automatic}
6 6 2 0 0 0

mpirun -np 4 pw.x -inp hbn.nscf > nscf.out

3. Input <code>hbn.dvscf</code>:

hbn_dvscf
&inputph
tr2_ph=1.0d-12,
verbosity='high'
prefix='hBN',
fildvscf = 'hBN-dvscf',
electron_phonon = 'dvscf',
fildyn='hBN.dyn',
epsil=.false.,
ldisp=.true.,
recover=.true.,
nq1=6,
nq2=6,
nq3=2
/

nohup mpirun -np 8 pw.x -inp hbn.dvscf > dvscf.out &

4. Input <code>bse.in</code> (we include 2 valence and 2 conduction bands):

optics # [R] Linear Response optical properties
bss # [R] BSE solver
bse # [R][BSE] Bethe Salpeter Equation.
dipoles # [R] Oscillator strenghts (or dipoles)
em1s
DIP_CPU= "1 8 1" # [PARALLEL] CPUs for each role
DIP_ROLEs= "k c v" # [PARALLEL] CPUs roles (k,c,v)
DIP_Threads=0 # [OPENMP/X] Number of threads for dipoles
X_and_IO_CPU= "1 1 1 8 1" # [PARALLEL] CPUs for each role
X_and_IO_ROLEs= "q g k c v" # [PARALLEL] CPUs roles (q,g,k,c,v)
X_and_IO_nCPU_LinAlg_INV=-1 # [PARALLEL] CPUs for Linear Algebra (if -1 it is automatically set)
X_Threads=0 # [OPENMP/X] Number of threads for response functions
BS_CPU= "8 1 1" # [PARALLEL] CPUs for each role
BS_ROLEs= "k eh t" # [PARALLEL] CPUs roles (k,eh,t)
BS_nCPU_LinAlg_INV=-1 # [PARALLEL] CPUs for Linear Algebra (if -1 it is automatically set)
BS_nCPU_LinAlg_DIAGO=-1 # [PARALLEL] CPUs for Linear Algebra (if -1 it is automatically set)
X_Threads=0 # [OPENMP/X] Number of threads for response functions
K_Threads=0 # [OPENMP/BSK] Number of threads for response functions
% QpntsRXs
1 | 14 | # [Xs] Transferred momenta
%
% BndsRnXs
1 | 120 | # [Xs] Polarization function bands
%
NGsBlkXs= 10 Ry # [Xs] Response block size
% LongDrXs
1.000000 | 1.000000 | 1.000000 | # [Xs] [cc] Electric Field
%
BSEmod= "resonant" # [BSE] resonant/retarded/coupling
BSKmod= "SEX" # [BSE] IP/Hartree/HF/ALDA/SEX/BSfxc
Lkind= "Lfull" # [BSE] Lbar (default) / full
BSSmod= "d" # [BSS] (h)aydock/(d)iagonalization/(s)lepc/(i)nversion/(t)ddft`
% DipBands
1 | 120 | # [DIP] Bands range for dipoles
%
DipApproach= "G-space v" # [DIP] [G-space v/R-space x/Covariant/Shifted grids]
DipComputed= "R V P" # [DIP] [default R P V; extra P2 Spin Orb]
BSENGexx= 30000 Ry # [BSK] Exchange components
#ALLGexx # [BSS] Force the use use all RL vectors for the exchange part
BSENGBlk= 9000 Ry # [BSK] Screened interaction block size [if -1 uses all the G-vectors of W(q,G,Gp)]
% KfnQP_E
1.25997 | 1.08816 | 1.12683 | # [EXTQP BSK BSS] E parameters (c/v) eV|adim|adim
%
% BSEQptR
 1 | 14 | # [BSK] Transferred momenta range
%
% BSEBands
 7 | 10 | # [BSK] Bands range
%
% BEnRange
0.50000 | 8.00000 | eV # [BSS] Energy range
%
% BDmRange
0.050000 | 0.050000 | eV # [BSS] Damping range
%
BEnSteps= 1000 # [BSS] Energy steps
% BLongDir
1.000000 | 1.000000 | 0.000000 | # [BSS] [cc] Electric Field
%
WRbsWF # [BSS] Write to disk excitonic the WFs

nohup mpirun -np 8 yambo -F bse.in -J bse_Lfull -C bse_Lfull &

Importantly, since we want to describe the phonon-assisted recombination process of an *optical* exciton (i.e., emitting a transverse photon), this time we also run an additional calculation at `Q=0` omitting the nonanalytic long-range Coulomb exchange. Make a second input <code>bse_Lbar.in</code> with the following changes:

Lkind= "Lbar" # [BSE] Lbar (default) / full
% BSEQptR
 1 | 1 | # [BSK] Transferred momenta range
%

4b. So now we make a second BSE run in a different directory specified by <code>-J</code>. Here, we also pass to yambo the directory of the previous run as it includes the important screening databases <code>ndb.em1s*</code> that we do not want to recompute from scratch.

mpirun -np 8 yambo -F bse_Lbar.in -J bse_Lbar,bse_Lfull -C bse_Lbar

5. Now we run <code>lelphc</code> (with or without yambopy: in the latter case remember the option <code>-D</code>) to get the el-ph matrix elements, particularly the <code>ndb.elph</code> databases:

yambopy l2y -ph path/of/dvscf/hbn.dvscf -b 7 10 -par 4 2 -D

=== Luminescence calculation ===

6. And finally we calculate exciton-phonon matrix elements and the luminescence spectrum in one go using a python script importing the Yambopy exciton-phonon tools: in order to do this, we need to take a look at all the necessary input variables for the formula written above.

We can start from the script <code>luminescence.py</code> available in <code>tutorials/exciton-phonon</code>.

import numpy as np
import matplotlib.pyplot as plt
from yambopy.exciton_phonon.excph_luminescence import exc_ph_luminescence
from yambopy.exciton_phonon.excph_input_data import exc_ph_get_inputs

We import the necessary tools...

path = '3D_hBN'
# Path to BSE calculation (Lout--> response is Lfull)
bsepath = f'{path}/bse_Lfull' # ndb.BS_diago_Q* databases are needed
# Path to BSE calculation for optically active exciton (Lin --> response is Lbar)
bseBARpath = f'{path}/bse_Lbar' # ndb.BS_diago_Q1 database is needed
# Path to electron-phonon calculation
elphpath = path # ndb.elph is needed
# Path to unprojected dipoles matrix elements (optional)
dipolespath = bsepath # ndb.dipoles is needed (optional)
# Path to lattice and k-space info
savepath = f'{path}/SAVE' # ns.db1 database is needed

... and we specify the paths to the necessary databases. Note that, if we want to perform polarization averaging, we have to recompute the excitonic dipoles in python as seen here.

What about <code>bseBARpath</code>? This variable points to the directory where the databases for the optical (zero-momentum) excitons <math>\alpha</math> (which may be computed with <code>Lkind='Lbar'</code>) is located, which can be different from the directory with the full indirect exciton dispersion <math>\beta</math> (usually computed with <code>Lkind='Lfull'</code>, however <code>Lkind='Ltilde'</code> can also be used if one is interested in "irreducible" excitons). This makes it possible to compute the coupling between different exciton kinds.

bands_range=[6,10] # 2 valence, 2 conduction bands
phonons_range=[0,12] # All phonons
nexc_out = 12 # 12 excitonic states at each momentum (Lout)
nexc_in = 12 # 12 excitonic states at Q=0 (Lin)
T_ph = 10 # Lattice temperature
T_exc = 10 # Effective excitonic temperature

emin=4.4 # Energy range and plot details (in eV)
emax=4.7
estep=0.0002
broad = 0.005 # Broadening parameter for peak width (in eV)

Next, we specify the parameters for the calculation. We include valence bands from 7 to 10 (6 to 9 in python index) and the contribution of all 12 phonon modes. We consider 12 excitonic states for the coupling matrix elements.

Here <code>T_ph</code> and <code>T_exc</code> are the lattice and excitonic temperatures, respectively.

# We calculate and load all the inputs:
# * Exciton-phonon matrix elements
# * Excitonic dipole matrix elements
# * Exciton energies
# * Phonon energies
# * We specify bse_path2=bseBARpath meaning we use Lbar calculation for Q=0 excitons
input_data = exc_ph_get_inputs(savepath,elphpath,bsepath,\
bse_path2=bseBARpath,dipoles_path=dipolespath,\
nexc_in=12,nexc_out=12,\
bands_range=[6,10],phonons_range=[0,12])

ph_energies, exc_energies, exc_energies_in, G, exc_dipoles = input_data

The function <code>exc_ph_get_inputs</code> gives us all the input data for luminescence in the correct format: phonon energies, exciton energies, optical exciton energies (if needed), exciton-phonon matrix elements (calculated on the fly and printed to file), unprojected exciton dipoles (optional, calculated on the fly and printed to file).
The exc-ph matrix element calculation is just a wrapper of the same tools that we have tested in the above section on MoS2.

Finally, there is the calculation of the luminescence spectrum via the function <code>exc_ph_luminescence</code>:
# We calculate the luminescence spectrum including the input data from before
w,PL = exc_ph_luminescence(T_ph,ph_energies,exc_energies,exc_dipoles,G,\
exc_energies_in=exc_energies_in,exc_temp=T_exc,\
nexc_out=nexc_out,nexc_in=nexc_in,emin=emin,emax=emax,\
estep=estep,broad=broad)

If you want to print the luminescence data for later plotting, you can also add the following line to the script:
# Save to file
data = np.column_stack((w, PL))
np.savetxt("hBN_luminescence_12x12x1.dat", data, fmt="%.8f")

It is now time to run the whole script:

python luminescence.py

NB: By using Yambopy for Step 6, we have limited the use of the Yambo code to just step 4 in the entire workflow. This option is more flexible, as it allows for a greater degree of control by the user. On the other hand the Yambo postprocessing route features a Yambo-style input that doesn't require python knowledge and the calculation is currently faster in fortran. However, the luminescence expression computed in Yambo is a slightly different than this one: it is more approximated in the description of the satellite oscillator strengths, but it explicitly includes the renormalization of the direct exciton peak. You can check the differences [[Exciton-phonon coupling and luminescence - Yambo postprocessing|here]].

=== Results ===
We can plot the results of the step 6 calculation. If we do it in the same script we can add something like this:
fig = plt.figure()
ax = fig.add_subplot(1,1,1)
ax.set_xlim(emin,emax)
ax.set_ylim(0,np.max(PL)*1.1)
ax.get_yaxis().set_visible(False)

ax.plot(w, PL, '-',c='red', label="AA' hBN luminescence")

plt.legend()
plt.savefig('hBN_luminescence.png')
plt.show()

[[File:HBN luminescence satellites.png|500px|center]]

Here, the signal corresponds to a finite-momentum exciton that recombines with the help of several different phonon modes, both optical and acoustic. Each phonon mode whose coupling with the exciton is allowed can generate a peak, and the energy shifts of these peaks with respect to the initial exciton energy correspond to the phonon energies. This result is underconverged, but the main features are all there. In the plot, we show a more converged example using a 12x12x4 grid (all the other parameters being equal). These plots can be compared with Fig. 4(a) of reference <ref name="zanfrognini2023" />.

== References ==

<references>
<ref name="toyozawa2003" >Toyozawa, Yutaka, and Chris Oxlade, ''Optical processes in solids'', [https://m.booksee.org/book/1121964?force_lang=en Cambridge University Press, (2003)]. </ref>
<ref name='lechifflart2023'>P. Lechifflart, F. Paleari, D. Sangalli, C. Attaccalite, ''First-principles study of luminescence in hexagonal boron nitride single layer: Exciton-phonon coupling and the role of substrate'',
[https://doi.org/10.1103/PhysRevMaterials.7.024006 Phys. Rev. M, '''7''' (2), 024006 (2023)]; [https://arxiv.org/abs/2212.10407 arXiv2212.1047]</ref>
<ref name='cannuccia2019'>E. Cannuccia, B. Monserrat and C. Attaccalite, ''Theory of phonon-assisted luminescence in solids: Application to hexagonal boron nitride'', [https://doi.org/10.1103/PhysRevB.99.081109 Phys. Rev. B '''99''', 081109(R) (2019)]; [https://arxiv.org/abs/1807.11797 arXiv1807.11797]</ref>
<ref name='paleari2019'>F. Paleari et al., ''Exciton-Phonon Coupling in the Ultraviolet Absorption and Emission Spectra of Bulk Hexagonal Boron Nitride'', [https://doi.org/10.1103/PhysRevLett.122.187401 Phys. Rev. Lett. '''122''', 187401 (2019)]; [https://arxiv.org/abs/1810.08976 arXiv1810.089776] </ref>
<ref name='chen2020'>''Exciton-Phonon Interaction and Relaxation Times from First Principles'',
Hsiao-Yi Chen, Davide Sangalli, and Marco Bernardi, [https://doi.org/10.1103/PhysRevLett.125.107401 Phys. Rev. Lett. '''125''', 107401 (2020)]; [https://arxiv.org/abs/2002.08913 arXiv 2002.08913 (2020)]</ref>
<ref name="lechifflart2023_PhD">P. Lechifflart, ''Exciton-phonon coupling and phonon-assisted luminescence in hexagonal Boron Nitride nanostructures'', [https://hal.science/tel-04266805v1 PhD Thesis, University of Marseille (2023)]; [https://www.yambo-code.eu/wiki/images/5/54/These_final.pdf From the yambo website]</ref>
<ref name='paleari2019_PhD'>F. Paleari, ''First-principles approaches to the description of indirect absorption and luminescence spectroscopy: exciton-phonon coupling in hexagonal boron nitride'', [https://wwwen.uni.lu/research/fstm/dphyms/people/fulvio_paleari PhD thesis, University of Luxembourg (2019)]</ref>
<ref name='zanfrognini2023'>M. Zanfrognini et al., ''Distinguishing different stackings in layered materials via luminescence spectroscopy'', [https://doi.org/10.1103/PhysRevLett.131.206902 Phys. Rev. Lett. '''131''', 206902 (2023)]; [https://arxiv.org/abs/2305.17554 arXiv 2305.17554] </ref>
<ref name='marini2024'>G. Marini, M. Calandra, P. Cudazzo, ''Optical absorption and photoluminescence of single layer boron nitride from a first principles cumulant approach'', [https://doi.org/10.1021/acs.nanolett.4c00669 Nano Lett., '''24''', 20, 6017 (2024)]; [https://arxiv.org/abs/2402.03826 arXiv 2402.03826 (2024)]</ref>
<ref name='antonius2017'>G. Antonius, S. G. Louie, ''Theory of exciton-phonon coupling'', [https://doi.org/10.1103/PhysRevB.105.085111 Phys. Rev. B, '''105''', 085111 (2022)]; [https://arxiv.org/abs/1705.04245 arXiv1705.04245 (2017)]</ref>
<ref name='paleari2022'> F. Paleari, and A. Marini, ''Exciton-phonon interaction calls for a revision of the “exciton” concept'', [https://doi.org/10.1103/PhysRevB.106.125403 Phys. Rev. B, '''106''', 125403 (2022)]; [https://arxiv.org/abs/2205.02783 arXiv 2205.02783]</ref>
<ref name='cudazzo2020'> P. Cudazzo, ''First-principles description of the exciton-phonon interaction: A cumulant approach'', [https://doi.org/10.1103/PhysRevB.102.045136 Phys. Rev. B, '''102''', 045136 (2020)]; [https://orbilu.uni.lu/bitstream/10993/44769/1/main.pdf Open access pdf from Luxembourg University]</ref>
<ref name='chan2023'>Y-h Chan, J. B. Haber, M. H. Naik, J. B. Neaton, D. Y. Qiu, F. H. da Jornada, S. G. Louie, ''Exciton Lifetime and Optical Line Width Profile via Exciton–Phonon Interactions: Theory and First-Principles Calculations for Monolayer MoS2'', [https://doi.org/10.1021/acs.nanolett.3c00732 Nano Lett., '''23''', 9 (2023)]; [https://arxiv.org/abs/2212.08451 arXiv 2212.08451 (2023)]</ref>
<ref name='murali2025'>M. Nalabothula, S. Reichardt, L. Wirtz, ''Origin of Interlayer Exciton–Phonon Coupling in 2D Heterostructures'', [https://doi.org/10.1021/acs.nanolett.5c00355 Nano Lett., '''25''', 15 (2025)], [https://arxiv.org/abs/2407.16111 arXiv 2407.16111 (2025)]</ref>
</references>

Exciton-phonon coupling and luminescence

2026-03-13T14:45:40Z

FulvioPaleari:

[[exc-ph scheme| File:Tdgw-phonon-usc-01-1024x829.jpg| (c) Zhenglu Li, University of Southern California |400px | right ]]

In this advanced tutorial, we will calculate exciton-phonon interactions from first principles by interfacing DFPT (for phonon calculations) and BSE (for exciton calculations).

The DFTP calculations are run with Quantum ESPRESSO, while the many-body GW-BSE calculations are run with Yambo. Finally, the exciton-phonon interaction will be obtained by combining and postprocessing the databases computed in the two previous runs. The great advantage of this workflow is that the calculations can be run in the irreducible Brillouin zones both for the electronic momenta ('''k''') and the transfer momenta ('''Q''', '''q''') of excitons and phonons, thus speeding up considerably the jobs while reducing the IO and memory load.

We will first compute the exciton-phonon coupling matrix elements: these are the building blocks needed to construct experimental observables such as phonon-assisted optical spectra (such as luminescence), Raman spectra and exciton lifetimes. We will do this in the case of monolayer MoS2, a 2D system with large spin-orbit interaction.

As an example of application, we will consider the case of phonon-assisted luminescence. We will do this in the case of bulk hBN, a layered indirect insulator with strong electron-phonon coupling.

'''Note:''' this tutorial will be updated when new exc-ph tools become available in Yambopy (including full-python postprocessing, Raman spectra, interpolated lifetimes, etc).

== Requirements ==

This is an advanced topic: we assume that you already know something about the theory<ref name="toyozawa2003" /><ref name="antonius2017" /><ref name="cudazzo2020" /><ref name="paleari2019_PhD" /><ref name="paleari2022" /><ref name="lechifflart2023_PhD" /> and applications<ref name="paleari2019" /><ref name="cannuccia2019" /><ref name="chen2020" /><ref name="zanfrognini2023" /><ref name="lechifflart2023" /><ref name="chan2023" /><ref name="marini2024" /><ref name="murali2025" /> of exciton-phonon physics.

Also, we assume that you already know how to run both a basic '''Yambo''' GW-BSE calculation and a DFPT phonon calculation with '''Quantum ESPRESSO'''.

Besides the QE executables <code>pw.x</code> and <code>ph.x</code>, we also use the yambo phonon-specific executable <code>yambo_ph</code> and the python utility '''Yambopy'''. The auxiliary code '''LetzElPhC''' (executable <code>lelphc</code>) will be used to obtain the electron-phonon matrix elements by reading the same electronic wavefunctions used by Yambo (and stored in the <code>SAVE</code> directory), while also making full use of crystal symmetries. [https://github.com/yambo-code/LetzElPhC LetzElPhC] will be run by Yambopy, but it must nonetheless be installed. Finally, the exciton-phonon properties can be computed either using <code>yambo_ph</code> or using Yambopy itself. Both cases will be covered in this tutorial.

[[File:Workflow scheme.png|800px|center]]

== Step 0: Pseudopotentials, equilibrium structure and convergence ==

In a real calculation, it is important to ensure that both the pseudopotential and the lattice parameters that we are using are compatible and perform well for the electronic excited states and for the lattice vibrations simultaneously. Furthermore, you have to make sure that the wave function cutoff <code>ecutwfc</code> is converged with respect to the DFPT step and not just to the DFT one. This is in addition to the other customary convergence tests for DFT, DFPT, GW and BSE calculations.

This is often the most time-demanding step when starting on a new system.

For the sake of this tutorial, we assume that we have already done all these tests and we are starting the final workflow to get the exciton-phonon properties.

== Step 1: scf calculation ==

First of all, we run a standard scf calculation with <code>pw.x</code> for Yambo. We stick with non-symmorphic symmetries. At the end, we will have the QE <code>save</code> directory.

This is the input <code>mos2.scf</code>:

&control
wf_collect = .true.,
calculation = "scf",
verbosity = 'high',
pseudo_dir = '$PSEUDO_DIR',
prefix = "mos2",
outdir = '.',
/&end
&system
ecutwfc = 100.0,
occupations = 'fixed',
ibrav = 4,
celldm(1) = 5.9000811881,
celldm(3) = 6.7795677253,
nat = 3,
ntyp = 2,
lspinorb = .true.
noncolin = .true.
assume_isolated = '2D'
force_symmorphic = .true.
/&end
&electrons
electron_maxstep = 200,
mixing_beta = 0.7,
conv_thr = 1.d-08,
/&end
ATOMIC_SPECIES
Mo 95.940 Mo_ONCV_PBE_FR-1.0.upf
S 32.065 S_ONCV_PBE_FR-1.1.upf
ATOMIC_POSITIONS { crystal }
Mo 0.333333333 0.666666667 0.000000000
S 0.666666667 0.333333333 0.073413577
S 0.666666667 0.333333333 -0.073413577
K_POINTS { automatic }
6 6 1 0 0 0

Here we are using full relativistic pseudopotentials from the SG-15 database.

We can run it on our machine (for example using 4 MPI tasks) as:

mpirun -np 4 pw.x -inp mos2.scf > scf.out

== Step 2: nscf calculation for Yambo ==

Copy the QE <code>save</code> directory from the scf calculation and run the nscf calculation for any number of empty states, with the correct <code>k</code>-grid we want to use in Yambo. Here we are using a badly underconverged grid of 6x6x1.

This reciprocal-space grid will also match the momentum transfer <code>q</code> grid on which excitons and phonons will be defined!

The electronic wavefunctions computed at this step and stored in the new nscf <code>save</code> directory will be used both by Yambo and by the electron-phonon code: this is important because using different sets of wavefunctions would lead to a phase mismatch issue in the exciton-phonon matrix elements.

The nscf input <code>mos2.nscf</code> is
&control
wf_collect = .true.,
calculation = "nscf",
verbosity = 'high',
pseudo_dir = '$PSEUDO_DIR',
prefix = "mos2",
outdir = '.',
/&end
&system
ecutwfc = 100.0,
occupations = 'fixed',
ibrav = 4,
celldm(1) = 5.9000811881,
celldm(3) = 6.7795677253,
nat = 3,
ntyp = 2,
lspinorb = .true.
noncolin = .true.
nbnd = 250
assume_isolated = '2D'
force_symmorphic = .true.
/&end
&electrons
electron_maxstep = 200,
mixing_beta = 0.7,
conv_thr = 1.d-08,
/&end
ATOMIC_SPECIES
Mo 95.940 Mo_ONCV_PBE_FR-1.0.upf
S 32.065 S_ONCV_PBE_FR-1.1.upf
ATOMIC_POSITIONS { crystal }
Mo 0.333333333 0.666666667 0.000000000
S 0.666666667 0.333333333 0.073413577
S 0.666666667 0.333333333 -0.073413577
K_POINTS { automatic }
6 6 1 0 0 0

Again, we run the calculation

mpirun -np 4 pw.x -inp mos2.nscf > nscf.out

== Step 3: dvscf phonon calculation ==

Now we run the phonon calculation.

Copy the <code>save</code> directory from the '''scf''' calculation and run <code>ph.x</code> for a dvscf calculation with a standard <code>q</code>-grid matching the <code>k</code>-grid we wanna use in Yambo.

At the end, we will have the <code>_ph0</code> directory containing the variation of the self-consistent potential, <math>\Delta V_{SCF}(q)</math>, and the <code>*.dyn</code> files with the phonon energies and eigenvectors.

NB: one could further refine the phonon energies by enforcing the acoustic sum rule, including non-analytic long-range contributions, interpolating to finer grids... all of this can be done within Quantum ESPRESSO and will not be covered in this version of the tutorial.

The input is <code>mos2.dvscf</code>:

mos2_dvscf
&inputph
tr2_ph=1.0d-12,
verbosity='high'
prefix='mos2',
fildvscf = 'mos2-dvscf',
electron_phonon = 'dvscf',
fildyn='mos2.dyn',
epsil=.false.,
ldisp=.true.,
recover=.true.,
nq1=6,
nq2=6,
nq3=1
/

And now we run as

nohup mpirun -np 8 ph.x -inp mos2.dvscf > dvscf.out &

This time we use nohup and more processes because this calculation may take some time. It is a good idea to set <code>recover=.true.</code> as in a real calculation you will easily breach walltime, and in this way you can safely restart.

== Step 4: create Yambo <code>SAVE</code> directory ==

This is just the standard Yambo initialization: run

p2y

and then

yambo

in the '''nscf''' <code>save</code> folder and then move the newly generated <code>SAVE</code> directory to a convenient place.

== Step 5: run a BSE calculation ==

Now we switch from QE to Yambo. Here, we forgo the GW step for simplicity (we can use a scissor operator to open the band gap).

This calculation has a couple of differences with respect to a standard BSE calculation for optical absorption. We can look at the input file <code>bse.in</code>:

# Runlevels
optics # [R OPT] Optics
rim_cut # [R RIM CUT] Coulomb potential
bss # [R BSS] Bethe Salpeter Equation solver
em1s # [R Xs] Static Inverse Dielectric Matrix
bse # [R BSE] Bethe Salpeter Equation.
bsk # [R BSK] Bethe Salpeter Equation kernel
# RIM and cutoff settings
RandQpts=1000000 # [RIM] Number of random q-points in the BZ
RandGvec= 100 RL # [RIM] Coulomb interaction RS components
CUTGeo= "slab z" # [CUT] Coulomb Cutoff geometry: box/cylinder/sphere X/Y/Z/XY..
# Static screening
X_and_IO_CPU= "1 1 4 2 1" # [PARALLEL] CPUs for each role
X_and_IO_ROLEs= "q g k c v" # [PARALLEL] CPUs roles (q,g,k,c,v)
X_and_IO_nCPU_LinAlg_INV=-1 # [PARALLEL] CPUs for Linear Algebra (if -1 it is automatically set)
Chimod= "hartree" # [X] IP/Hartree/ALDA/LRC/BSfxc
% BndsRnXs
1 | 200 | # [Xs] Polarization function bands
%
% LongDrXs
1.000000 | 1.000000 | 1.000000 | # [Xs] [cc] Electric Field
%
NGsBlkXs= 8000 mRy # [Xs] Response block size
# BSE
BS_CPU= "4.1.2" # [PARALLEL] CPUs for each role
BS_ROLEs= "k.eh.t" # [PARALLEL] CPUs roles (k,eh,t)
BS_nCPU_diago=4 # [PARALLEL] CPUs for matrix diagonalization
BSEmod= "causal" # [BSE] resonant/causal/coupling
BSKmod= "SEX" # [BSE] IP/Hartree/HF/ALDA/SEX/BSfxc
BSSmod= "d" # [BSS] (h)aydock/(d)iagonalization/(s)lepc/(i)nversion/(t)ddft`
BSENGexx= 40000 mRy # [BSK] Exchange components
ALLGexx # [BSS] Force the use use all RL vectors for the exchange part
BSENGBlk= 8000 mRy # [BSK] Screened interaction block size
Lkind="full" #[BSE,X] bar(default)/full/tilde
% KfnQP_E
1.000000 | 1.000000 | 1.000000 | # [EXTQP BSK BSS] E parameters (c/v) eV|adim|adim
%
% BEnRange
0.00000 | 4.00000 | eV # [BSS] Energy range
%
% BDmRange
0.05000 | 0.05000 | eV # [BSS] Damping range
%
BEnSteps= 2000 # [BSS] Energy steps
% BLongDir
1.000000 | 0.000000 | 0.000000 | # [BSS] [cc] Electric Field
%
% BSEQptR
 1 | 7 | # [BSK] Transferred momenta range
%
% BSEBands
25 | 28 | # [BSK] Bands range
%
WRbsWF # [BSS] Write to disk excitonic the FWs

This file was generated using the command: <code> yambo -X s -o b -k sex -y d -r</code> 

First of all, we compute the excitons for all the momenta in the irreducible Brillouin zone for our discrete grid via the <code>BSEQptR</code> variable. This will be a '''finite-momentum''' BSE calculation, analogous to the phonon one.

Second, we change the variable <code>Lkind</code> from <code>bar</code> to <code>full</code>. In Yambo, <code>Lkind="bar"</code>, which is the default for optical absorption, means that we are computing the excitonic response function without the long-range component of the exchange interaction. This cannot be used when computing the exciton momentum dependence, where the long-range exchange interaction can play a role, therefore we have to include it with <code>Lkind="full"</code>. This allows for the calculation of the excitonic longitudinal-transverse splitting (in 3D systems) as well.

We can now run the code:

nohup mpirun -np 8 yambo -F bse.in -J bse_Lfull -C bse_Lfull &

At the end of the calculation, we have obtained the <code>ndb.BS_diago_Q*</code> databases inside the directory <code>bse_Lfull</code>. They contain information on the exciton energies and wavefunctions at each momentum. Do not forget to check the report and logs of your calculation in the same directory to make sure that the code is doing what you want.

== Step 6: obtain the electron-phonon matrix elements ==

We have finished the heavy simulations. Now it's time for the postprocessing. The first order of business is the reconstruction of the electron-phonon coupling matrix elements from the dvscf results and the electronic wavefunctions.

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

We run in the same directory where the Yambo <code>SAVE</code> 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>n_i</math> to <math>n_f</math>, we should type:

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

Here <math>n_i</math> and <math>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>[n_i,n_f]</math> including the extrema of the interval.

These should coincide with those used for the Bethe-Salpeter kernel, i.e. those specified in the <code>BSEBands</code> variable of the BSE input file (this is not strictly necessary, but certainly efficient since these calculations use a lot of disk space).

For our system, we want to do a parallel calculation with 4 qpools and 2 kpools. In addition, we want to explicitly specify the path of the <code>lelphc</code> executable and avoid automatically deleting the LetzElPhC data. So we type:

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

At the end, check your directory: you should find the <code>lelphc.in</code> 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 <code>convention=yambo</code>: 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>n</math> and momentum <math>k-q</math> to band <math>m</math> and momentum <math>k</math>. In the "forward" momentum transfer convention (the more standard one), the transitions go from <math>nk</math> to <math>mk+q</math>. Therefore, this variable ensures that the electron-phonon coupling matrix elements are computed as <math>\langle mk|dV|nk-q\rangle</math>. This will have consequences also in the formulation of the ''exciton''-phonon coupling matrix element.

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

In addition, if you check the <code>SAVE</code> folder:

ls SAVE/ndb.elph_gkkp*

you will see that yambopy has created the Yambo-compatible electron-phonon databases.

If you want to run LetzElPhC directly, without using yambopy, you can refer to its [[https://gitlab.com/lumen-code/LetzElPhC/-/blob/main/docs/main.pdf?ref_type=heads|user guide]].
Keep in mind that in this case, in order to convert the database to the <code>ndb.elph_gkkp*</code> databases of Yambo, you will then need a couple of lines of python using the Yambopy class <code>ConvertElectronPhononDB</code> in <code>yambopy/letzelph_interface/lelph2y.py</code>.

If you don't need the <code>ndb.elph_gkkp*</code> databases -- e.g., because you are doing the exc-ph postprocessing with yambopy -- you can run <code>yambopy l2y ...</code> with the <code>--no_gkkp</code> option.

If you don't need the <code>ndb.elph</code> databases -- e.g., because you are using <code>yambo_ph</code> for the exc-ph part -- you can run <code>yambopy l2y ...</code> with the <code>--no_lelphc_dbs</code> option.

== Step 7: Obtain the exciton-phonon coupling ==

Now, we can finally access our basic building block for exciton-phonon physics. This could be done entirely in python (using '''Yambopy'''), or by running '''Yambo'''.

* For the '''Yambo postprocessing''' case (running yambo inputs with the <code>yambo_ph</code> executable), '''follow the alternative route to Steps 7-8 [[Exciton-phonon coupling and luminescence - Yambo postprocessing|at this link]]'''.
* For the '''Yambopy postprocessing''' case (using flexible python scripting), '''keep following Steps 7-8 on this page'''.

Our objective is obtaining the following quantity:

<math>\mathcal{G}^\mu_{\alpha\lambda}(0,q)=\sum_{vv^\prime c k} A^{\alpha, *}_{cv^\prime} (k, q) g_{vv^\prime}^\mu (k,q) A^{\lambda}_{cv}(k,0) - \sum_{cc^\prime vk} A^{\alpha, *}_{c^\prime v} (k+q, q) g_{c^\prime c}^\mu (k+q,q) A^{\lambda}_{cv}(k, 0)</math>

Here, <math>A^{\alpha}_{cv}(k,q)</math> are the exciton coefficients extracted from the eigenvector of the two-particles Hamiltonian during the BSE calculation in step 5, while <math>g_{nm}^\mu (k,q)</math> are the electron-phonon coupling matrix elements obtained in step 6. As you can see, the exciton <math>\lambda</math> undergoes phonon-mediated scattering to state <math>\alpha</math> via phonon mode <math>\mu</math>. The scattering can happen for the hole (valence, <math>v</math>) or for the electron (conduction, <math>c</math>).

NB:

(1) This is written in the "backward" momentum transfer convention used by Yambo. The momentum dependence is different in the "forward" transfer convention.

(2) For simplicity, this is written for zero initial exciton momentum. This means that one of the two states involved in the phonon-mediated scattering process will be in the optical limit (and possibly an optically generated exciton), while the other state can have any momentum: this momentum will be the same as the phonon one. This matrix element can be used to describe phonon-assisted absorption and emission spectra.

In order to calculate this quantity using python, we need the <code>ndb.elph</code> databases natively generated by the <code>LetzElPhC</code> code, as well as the BSE databases <code>ndb.BS_diago_Q*</code> containing the information on exciton wavefunctions and energies.

Next, we write a python user script importing the yambopy exciton-phonon tools. You can find a version of this script in <code>yambopy/tutorials/exciton-phonon/calculate_excph.py</code>.

import numpy as np
from yambopy import YamboLatticeDB,YamboWFDB,LetzElphElectronPhononDB #Specific Yambopy dbs loading classes
from yambopy.exciton_phonon.excph_matrix_elements import exciton_phonon_matelem #Specific exc-ph functions

path = '1L_MoS2'
bands_range=[24,28] # 2 valence bands, 2 conduction bands
nexc = 12 # number of excitonic states

bsepath = f'{path}/bse-allq_full' # Path to BSE calculation (Lin=Lout)
savepath = f'{path}/SAVE' # Yambo SAVE
ndb_elph = f'{path}/ndb.elph' # LetzElPhC electron-phonon database (any convention)

# Read lattice
lattice = YamboLatticeDB.from_db_file(filename=f'{savepath}/ns.db1')
# Read electron-phonon
elph = LetzElphElectronPhononDB(ndb_elph,read_all=False)
# Read wave functions
wfcs = YamboWFDB(filename='ns.wf',save=savepath,latdb=lattice,bands_range=bands_range)
# Calculate exciton-phonon matrix elements
exph = exciton_phonon_matelem(lattice,elph,wfcs,BSE_dir=bsepath,nexc_in=nexc,nexc_out=nexc,dmat_mode='save',exph_file='MoS2_Ex-ph.npy')

In this script, we can select the number exciton states <math>\lambda</math> with <code>nexc</code>, the single-particle bands range with <code>bands_range</code>. '''Please note''': in this case, the band index starts from 0 (python indexing) and the the interval of bands read by the code is <math>[n_i,n_f)</math>, therefore the last value (28 in the example) is excluded. That is, in the example we are selecting the 25th, 26th, 27th and 28th bands. Those bands have to be present in both the electron-phonon and BSE calculations.

Here we calculate the couplings of the first twelve states at each finite-<math>q</math> point including <math>q=0</math>. We also include all the nine phonon modes of monolayer MoS2. We also need access to the Yambo <code>SAVE</code> directory in order to read the electronic wavefunctions: they are used to compute the electronic representation matrices (<code>dmat</code> in the code). The argument <code>dmat_mode</code> can be set to <code>'load'</code> for subsequent calculations.

When we are satisfied with the input, we run the code:

python calculate_excph.py

If you check the output, you should find the <code>MoS2_Ex-ph.npy</code> binary file in the directory where you ran.

=== Analysis of the couplings ===

It is a good idea to have a look at what we computed up to now in order to make sure nothing has gone wrong.

It is not easy to know what to expect (apart from symmetry and gauge compliance of the matrix elements), but one can work out the exciton-phonon selection rules in advance, check that the magnitude is reasonable, etc.

It is also not easy to meaningfully plot this quantity. We have to make sure that we are not breaking degenerate states, otherwise the plots will not be invariant.

First of all, we have to know our system: in monolayer MoS2, the first four excitons are all doubly degenerate. The first exciton responsible for a bright peak in the absorption spectrum (the '''A''' peak), is the second state, corresponding to state indices <code>(3,4)</code> in fortran indexing or <code>(2,3)</code> in python indexing.

All these information can be obtained by analyzing the BSE results (this stuff is explained in the BSE tutorials) and by knowledge of the system or class of systems from the literature.

Thus, a good quantity to plot may be the norm of the matrix elements, summed over the degenerate subspace of exciton A, for a certain number of scattered final states mediated by certain phonon modes:

<math>F_A(q)= \sqrt{ \sum_{\alpha \in A,\lambda,\mu} |\mathcal{G}_{\alpha\lambda}^\mu (0,q)|^2 }</math>

In order to do this, we create a python script <code>analyse_excph.py</code> in which we first load the excph dabatases.
You can find a version of this script in the yambopy directory, in <code>tutorials/exciton-phonon</code>.
First, we select the exciton and phonon states to be included in <code>F_A</code>, together with the path of databases and plot details:

# Exciton "in" states
exc_in = [2,3] # First bright peak (A: 2,3 -- B: 6,7)
exc_out = [0,1,2,3] # first 4 states (dispersion of dark triplet state and A)
ph_in = 'all'
# Paths of databases
ns_db1 =f'{path}/SAVE/ns.db1'
ns_ypy = 'MoS2_Ex-ph.npy'

...

Then, we load the data:

# Read lattice and k-space info
ylat = YamboLatticeDB.from_db_file(filename=ns_db1)
print(ylat)

# Load exc-ph database
X_py = np.load(ns_ypy)
G_squared = np.abs(X_py)**2.

The quantity <math>F_A(q)</math> is obtained from a dedicated function as:

if exc_in == 'all': exc_in = range(G_squared.shape[2])
if exc_out == 'all': exc_out = range(G_squared.shape[3])
if ph_in == 'all': ph_in = range(G_squared.shape[1])

G_squared = G_squared[:, ph_in, :, :].sum(axis=(1))
G_squared = G_squared[:, exc_in, :].sum(axis=(1))
G_squared = G_squared[:, exc_out].sum(axis=(1))

F_q = np.sqrt( G_squared )*ha2ev # Switch from Ha to eV

And finally, we have to make a plotting function. For this tutorial we will use a custom scatterplot employing some of the plotting tools provided by yambopy (but you can do whatever you want).

plot_2D_excph(qgrid,G2_to_plot,rlat=ylat.rlat,plt_cbar=True,\
marker='H',s=700,cmap='magma')
...

You can get more experience on using Yambopy for these kinds of visualization by following the [https://wiki.yambo-code.eu/wiki/index.php?title=First_steps_in_Yambopy Yambopy tutorials]. In fact, remember that these scripts and all the other Yambopy tutorial scripts are just suggestions, not source code written in stone: if you know <code>numpy</code> and <code>matplotlib</code> you can do your own analysis and your own plots, you just need to import the required Yambopy modules to load the data.

In our case, the resulting plot is the following.

[[File:1L MoS2 MoS2 Ex-ph.png|500px|center]]

This can be checked against Fig. 2(d) of reference <ref name="chan2023" />, although you have to keep in mind that our results are badly undersampled in terms of the reciprocal-space grid, as can be easily seen, and the quantity plotted is not exactly the same. However, the main features are already there since they are dictated mostly by crystal symmetries.

Now that we have the exciton-phonon matrix elements, we can use them to build several kinds of observables. Below, we give an example related to phonon-assisted luminescence, but we may update this tutorial in the future to include more cases.

== Step 8: Compute phonon-assisted luminescence ==

[[File:Luminescence scheme.png|250px|right]]

We want to compute the experimental optical signature due to the phonon-assisted recombination of an exciton (as sketched in the figure).

The signal from the phonon replicas can be modeled as a second-order scattering process involving one phonon and one photon:

<math>I^{Sat}(\omega)=\frac{1}{ N_q} \frac{1}{3} \sum_{\epsilon s\beta \mu q} \frac{1}{E_{\beta q}-s\Omega_{\mu q}}\left|\sum_\alpha\frac{ D^{\epsilon}_\alpha \mathcal{G}_{\beta \alpha}^{\mu,*}(q)}{E_\alpha -E_{\beta q} +s\Omega_{\mu q}+\mathrm{i}\eta}\right|^2 \frac{N^{exc}_{\beta q}(T_{exc})[\frac{1+s}{2}+n_{\mu q}(T)]}{\omega -[E_{\beta q}-s\Omega_{\mu q}]+\mathrm{i}\eta}</math>

In this equation, the oscillator strength of the peak is given by the exciton-phonon coupling matrix elements <math>\mathcal{G}</math> multiplied by the exciton dipoles <math>D</math> (they are called "residuals" in Yambo). Here <math>E_\lambda</math> and <math>E_{\alpha q}</math> are the energies of the optical and finite-momentum excitons, respectively, while <math>\Omega_{\mu q}</math> are the phonon energies.

Here, <math>n_{\mu q}(T)</math> is the temperature-dependent phonon Bose-Einstein occupation function. As it can be seen, <math>s=1</math> corresponds to processes of phonon ''emission'' (<math>\propto n(T)+1</math>), while <math>s=-1</math> corresponds to processes of phonon ''absorption'' (<math>\propto n(T)</math>). Therefore, <math>I^{Sat}_{PL}(\omega;T)</math> describes ''light'' emission by recombining excitons mediated by either ''phonon'' absorption or emission.

The quantity <math> N_{\alpha q}(T_{exc})</math> is the exciton occupation function. Luminescence is technically an out-of-equilibrium process, but we can assume that for very low density of excitations and in steady-state conditions, the exciton population can be approximately described by an equilibrium distribution evaluated at an effective temperature. Here, we use the Boltzmann distribution. Experimentally, <math>T_{exc}</math> tends to coincide with the lattice temperature <math>T</math> more or less above 100 K, while at very low temperature (< 10 K), <math>T_{exc}</math> may vary between 10-50 K. It goes without saying that this needs to carefully be checked in your realistic calculations.

Finally, the spectrum is averaged over the polarization directions of the emitted photons (<math>\epsilon=x,y,z</math> representing the respective dipole components).

=== Running the jobs ===

In order to study luminescence in a paradigmatic system, we switch to bulk hexagonal boron nitride and we repeat the workflow. As you can easily see, one can think about automatizing the execution of all these calculations via scripting or more advanced tools. However, in the case of very large simulations (memory-limited or disk-space limited) or for systems whose electronic and lattice properties are fragile with respect to tiny calculation details, one must be very careful and run many basic tests.

Fortunately, we are running a fast underconverged example. We use LDA pseudopotentials from the pseudo-dojo library and the following are the calculations steps.

1. Input <code>hbn.scf</code>:

&control
calculation='scf',
prefix='hBN',
restart_mode='from_scratch'
pseudo_dir = '$PSEUDO_DIR',
outdir = './tmp'
verbosity = 'high'
wf_collect=.true.
/
&system
ibrav = 4,
celldm(1) = 4.703675849
celldm(3) = 2.603711434
nat= 4,
ntyp= 2,
force_symmorphic=.true.
ecutwfc = 100,
/
&electrons
diago_david_ndim = 2
diago_full_acc=.true.
diago_thr_init=5.0e-6
mixing_mode = 'plain'
mixing_beta = 0.7
conv_thr = 1.0d-16
/
ATOMIC_SPECIES
B 10.81100 B_LDA_dojo.UPF
N 14.00674 N_LDA_dojo.UPF
ATOMIC_POSITIONS {crystal}
N 0.6666666670 0.3333333330 -0.250000000000
B 0.3333333330 0.6666666670 -0.250000000000
B 0.6666666670 0.3333333330 0.25000000000
N 0.3333333330 0.6666666670 0.25000000000
K_POINTS {automatic}
6 6 2 0 0 0

mpirun -np 4 pw.x -inp hbn.scf > scf.out

2. Input <code>hbn.nscf</code>:

&control
calculation='nscf',
prefix='hBN',
restart_mode='from_scratch'
pseudo_dir = '$PSEUDO_DIR'
outdir = './'
verbosity = 'high'
wf_collect=.true.
/
&system
ibrav = 4,
celldm(1) = 4.703675849
celldm(3) = 2.603711434
nat= 4,
ntyp= 2,
force_symmorphic=.true.
ecutwfc = 100,
nbnd = 120
/
&electrons
diago_david_ndim = 2
diago_full_acc=.true.
diago_thr_init=5.0e-6
mixing_mode = 'plain'
mixing_beta = 0.7
conv_thr = 1.0d-16
/
ATOMIC_SPECIES
B 10.81100 B_LDA_dojo.UPF
N 14.00674 N_LDA_dojo.UPF
ATOMIC_POSITIONS {crystal}
N 0.6666666670 0.3333333330 -0.250000000000
B 0.3333333330 0.6666666670 -0.250000000000
B 0.6666666670 0.3333333330 0.25000000000
N 0.3333333330 0.6666666670 0.25000000000
K_POINTS {automatic}
6 6 2 0 0 0

mpirun -np 4 pw.x -inp hbn.nscf > nscf.out

3. Input <code>hbn.dvscf</code>:

hbn_dvscf
&inputph
tr2_ph=1.0d-12,
verbosity='high'
prefix='hBN',
fildvscf = 'hBN-dvscf',
electron_phonon = 'dvscf',
fildyn='hBN.dyn',
epsil=.false.,
ldisp=.true.,
recover=.true.,
nq1=6,
nq2=6,
nq3=2
/

nohup mpirun -np 8 pw.x -inp hbn.dvscf > dvscf.out &

4. Input <code>bse.in</code> (we include 2 valence and 2 conduction bands):

optics # [R] Linear Response optical properties
bss # [R] BSE solver
bse # [R][BSE] Bethe Salpeter Equation.
dipoles # [R] Oscillator strenghts (or dipoles)
em1s
DIP_CPU= "1 8 1" # [PARALLEL] CPUs for each role
DIP_ROLEs= "k c v" # [PARALLEL] CPUs roles (k,c,v)
DIP_Threads=0 # [OPENMP/X] Number of threads for dipoles
X_and_IO_CPU= "1 1 1 8 1" # [PARALLEL] CPUs for each role
X_and_IO_ROLEs= "q g k c v" # [PARALLEL] CPUs roles (q,g,k,c,v)
X_and_IO_nCPU_LinAlg_INV=-1 # [PARALLEL] CPUs for Linear Algebra (if -1 it is automatically set)
X_Threads=0 # [OPENMP/X] Number of threads for response functions
BS_CPU= "8 1 1" # [PARALLEL] CPUs for each role
BS_ROLEs= "k eh t" # [PARALLEL] CPUs roles (k,eh,t)
BS_nCPU_LinAlg_INV=-1 # [PARALLEL] CPUs for Linear Algebra (if -1 it is automatically set)
BS_nCPU_LinAlg_DIAGO=-1 # [PARALLEL] CPUs for Linear Algebra (if -1 it is automatically set)
X_Threads=0 # [OPENMP/X] Number of threads for response functions
K_Threads=0 # [OPENMP/BSK] Number of threads for response functions
% QpntsRXs
1 | 14 | # [Xs] Transferred momenta
%
% BndsRnXs
1 | 120 | # [Xs] Polarization function bands
%
NGsBlkXs= 10 Ry # [Xs] Response block size
% LongDrXs
1.000000 | 1.000000 | 1.000000 | # [Xs] [cc] Electric Field
%
BSEmod= "resonant" # [BSE] resonant/retarded/coupling
BSKmod= "SEX" # [BSE] IP/Hartree/HF/ALDA/SEX/BSfxc
Lkind= "Lfull" # [BSE] Lbar (default) / full
BSSmod= "d" # [BSS] (h)aydock/(d)iagonalization/(s)lepc/(i)nversion/(t)ddft`
% DipBands
1 | 120 | # [DIP] Bands range for dipoles
%
DipApproach= "G-space v" # [DIP] [G-space v/R-space x/Covariant/Shifted grids]
DipComputed= "R V P" # [DIP] [default R P V; extra P2 Spin Orb]
BSENGexx= 30000 Ry # [BSK] Exchange components
#ALLGexx # [BSS] Force the use use all RL vectors for the exchange part
BSENGBlk= 9000 Ry # [BSK] Screened interaction block size [if -1 uses all the G-vectors of W(q,G,Gp)]
% KfnQP_E
1.25997 | 1.08816 | 1.12683 | # [EXTQP BSK BSS] E parameters (c/v) eV|adim|adim
%
% BSEQptR
 1 | 14 | # [BSK] Transferred momenta range
%
% BSEBands
 7 | 10 | # [BSK] Bands range
%
% BEnRange
0.50000 | 8.00000 | eV # [BSS] Energy range
%
% BDmRange
0.050000 | 0.050000 | eV # [BSS] Damping range
%
BEnSteps= 1000 # [BSS] Energy steps
% BLongDir
1.000000 | 1.000000 | 0.000000 | # [BSS] [cc] Electric Field
%
WRbsWF # [BSS] Write to disk excitonic the WFs

nohup mpirun -np 8 yambo -F bse.in -J bse_Lfull -C bse_Lfull &

Importantly, since we want to describe the phonon-assisted recombination process of an *optical* exciton (i.e., emitting a transverse photon), this time we also run an additional calculation at `Q=0` omitting the nonanalytic long-range Coulomb exchange. Make a second input <code>bse_Lbar.in</code> with the following changes:

Lkind= "Lbar" # [BSE] Lbar (default) / full
% BSEQptR
 1 | 1 | # [BSK] Transferred momenta range
%

4b. So now we make a second BSE run in a different directory specified by <code>-J</code>. Here, we also pass to yambo the directory of the previous run as it includes the important screening databases <code>ndb.em1s*</code> that we do not want to recompute from scratch.

mpirun -np 8 yambo -F bse_Lbar.in -J bse_Lbar,bse_Lfull -C bse_Lbar

5. Now we run <code>lelphc</code> (with or without yambopy: in the latter case remember the option <code>-D</code>) to get the el-ph matrix elements, particularly the <code>ndb.elph</code> databases:

yambopy l2y -ph path/of/dvscf/hbn.dvscf -b 7 10 -par 4 2 -D

=== Luminescence calculation ===

6. And finally we calculate exciton-phonon matrix elements and the luminescence spectrum in one go using a python script importing the Yambopy exciton-phonon tools: in order to do this, we need to take a look at all the necessary input variables for the formula written above.

We can start from the script <code>luminescence.py</code> available in <code>tutorials/exciton-phonon</code>.

import numpy as np
import matplotlib.pyplot as plt
from yambopy.exciton_phonon.excph_luminescence import exc_ph_luminescence
from yambopy.exciton_phonon.excph_input_data import exc_ph_get_inputs

We import the necessary tools...

path = '3D_hBN'
# Path to BSE calculation (Lout--> response is Lfull)
bsepath = f'{path}/bse_Lfull' # ndb.BS_diago_Q* databases are needed
# Path to BSE calculation for optically active exciton (Lin --> response is Lbar)
bseBARpath = f'{path}/bse_Lbar' # ndb.BS_diago_Q1 database is needed
# Path to electron-phonon calculation
elphpath = path # ndb.elph is needed
# Path to unprojected dipoles matrix elements (optional)
dipolespath = bsepath # ndb.dipoles is needed (optional)
# Path to lattice and k-space info
savepath = f'{path}/SAVE' # ns.db1 database is needed

... and we specify the paths to the necessary databases. Note that, if we want to perform polarization averaging, we have to recompute the excitonic dipoles in python as seen here.

What about <code>bseBARpath</code>? This variable points to the directory where the databases for the optical (zero-momentum) excitons <math>\alpha</math> (which may be computed with <code>Lkind='Lbar'</code>) is located, which can be different from the directory with the full indirect exciton dispersion <math>\beta</math> (usually computed with <code>Lkind='Lfull'</code>, however <code>Lkind='Ltilde'</code> can also be used if one is interested in "irreducible" excitons). This makes it possible to compute the coupling between different exciton kinds.

bands_range=[6,10] # 2 valence, 2 conduction bands
phonons_range=[0,12] # All phonons
nexc_out = 12 # 12 excitonic states at each momentum (Lout)
nexc_in = 12 # 12 excitonic states at Q=0 (Lin)
T_ph = 10 # Lattice temperature
T_exc = 10 # Effective excitonic temperature

emin=4.4 # Energy range and plot details (in eV)
emax=4.7
estep=0.0002
broad = 0.005 # Broadening parameter for peak width (in eV)

Next, we specify the parameters for the calculation. We include valence bands from 7 to 10 (6 to 9 in python index) and the contribution of all 12 phonon modes. We consider 12 excitonic states for the coupling matrix elements.

Here <code>T_ph</code> and <code>T_exc</code> are the lattice and excitonic temperatures, respectively.

# We calculate and load all the inputs:
# * Exciton-phonon matrix elements
# * Excitonic dipole matrix elements
# * Exciton energies
# * Phonon energies
# * We specify bse_path2=bseBARpath meaning we use Lbar calculation for Q=0 excitons
input_data = exc_ph_get_inputs(savepath,elphpath,bsepath,\
bse_path2=bseBARpath,dipoles_path=dipolespath,\
nexc_in=12,nexc_out=12,\
bands_range=[6,10],phonons_range=[0,12])

ph_energies, exc_energies, exc_energies_in, G, exc_dipoles = input_data

The function <code>exc_ph_get_inputs</code> gives us all the input data for luminescence in the correct format: phonon energies, exciton energies, optical exciton energies (if needed), exciton-phonon matrix elements (calculated on the fly and printed to file), unprojected exciton dipoles (optional, calculated on the fly and printed to file).
The exc-ph matrix element calculation is just a wrapper of the same tools that we have tested in the above section on MoS2.

Finally, there is the calculation of the luminescence spectrum via the function <code>exc_ph_luminescence</code>:
# We calculate the luminescence spectrum including the input data from before
w,PL = exc_ph_luminescence(T_ph,ph_energies,exc_energies,exc_dipoles,G,\
exc_energies_in=exc_energies_in,exc_temp=T_exc,\
nexc_out=nexc_out,nexc_in=nexc_in,emin=emin,emax=emax,\
estep=estep,broad=broad)

If you want to print the luminescence data for later plotting, you can also add the following line to the script:
# Save to file
data = np.column_stack((w, PL))
np.savetxt("hBN_luminescence_12x12x1.dat", data, fmt="%.8f")

It is now time to run the whole script:

python luminescence.py

NB: By using Yambopy for Step 6, we have limited the use of the Yambo code to just step 4 in the entire workflow. This option is more flexible, as it allows for a greater degree of control by the user. On the other hand the Yambo postprocessing route features a Yambo-style input that doesn't require python knowledge and the calculation is currently faster in fortran. However, the luminescence expression computed in Yambo is a slightly different than this one: it is more approximated in the description of the satellite oscillator strengths, but it explicitly includes the renormalization of the direct exciton peak. You can check the differences [[Exciton-phonon coupling and luminescence - Yambo postprocessing|here]].

=== Results ===
We can plot the results of the step 6 calculation. If we do it in the same script we can add something like this:
fig = plt.figure()
ax = fig.add_subplot(1,1,1)
ax.set_xlim(emin,emax)
ax.set_ylim(0,np.max(PL)*1.1)
ax.get_yaxis().set_visible(False)

ax.plot(w, PL, '-',c='red', label="AA' hBN luminescence")

plt.legend()
plt.savefig('hBN_luminescence.png')
plt.show()

[[File:HBN luminescence satellites.png|500px|center]]

Here, the signal corresponds to a finite-momentum exciton that recombines with the help of several different phonon modes, both optical and acoustic. Each phonon mode whose coupling with the exciton is allowed can generate a peak, and the energy shifts of these peaks with respect to the initial exciton energy correspond to the phonon energies. This result is underconverged, but the main features are all there. In the plot, we show a more converged example using a 12x12x4 grid (all the other parameters being equal). These plots can be compared with Fig. 4(a) of reference <ref name="zanfrognini2023" />.

== References ==

<references>
<ref name="toyozawa2003" >Toyozawa, Yutaka, and Chris Oxlade, ''Optical processes in solids'', [https://m.booksee.org/book/1121964?force_lang=en Cambridge University Press, (2003)]. </ref>
<ref name='lechifflart2023'>P. Lechifflart, F. Paleari, D. Sangalli, C. Attaccalite, ''First-principles study of luminescence in hexagonal boron nitride single layer: Exciton-phonon coupling and the role of substrate'',
[https://doi.org/10.1103/PhysRevMaterials.7.024006 Phys. Rev. M, '''7''' (2), 024006 (2023)]; [https://arxiv.org/abs/2212.10407 arXiv2212.1047]</ref>
<ref name='cannuccia2019'>E. Cannuccia, B. Monserrat and C. Attaccalite, ''Theory of phonon-assisted luminescence in solids: Application to hexagonal boron nitride'', [https://doi.org/10.1103/PhysRevB.99.081109 Phys. Rev. B '''99''', 081109(R) (2019)]; [https://arxiv.org/abs/1807.11797 arXiv1807.11797]</ref>
<ref name='paleari2019'>F. Paleari et al., ''Exciton-Phonon Coupling in the Ultraviolet Absorption and Emission Spectra of Bulk Hexagonal Boron Nitride'', [https://doi.org/10.1103/PhysRevLett.122.187401 Phys. Rev. Lett. '''122''', 187401 (2019)]; [https://arxiv.org/abs/1810.08976 arXiv1810.089776] </ref>
<ref name='chen2020'>''Exciton-Phonon Interaction and Relaxation Times from First Principles'',
Hsiao-Yi Chen, Davide Sangalli, and Marco Bernardi, [https://doi.org/10.1103/PhysRevLett.125.107401 Phys. Rev. Lett. '''125''', 107401 (2020)]; [https://arxiv.org/abs/2002.08913 arXiv 2002.08913 (2020)]</ref>
<ref name="lechifflart2023_PhD">P. Lechifflart, ''Exciton-phonon coupling and phonon-assisted luminescence in hexagonal Boron Nitride nanostructures'', [https://hal.science/tel-04266805v1 PhD Thesis, University of Marseille (2023)]; [https://www.yambo-code.eu/wiki/images/5/54/These_final.pdf From the yambo website]</ref>
<ref name='paleari2019_PhD'>F. Paleari, ''First-principles approaches to the description of indirect absorption and luminescence spectroscopy: exciton-phonon coupling in hexagonal boron nitride'', [https://wwwen.uni.lu/research/fstm/dphyms/people/fulvio_paleari PhD thesis, University of Luxembourg (2019)]</ref>
<ref name='zanfrognini2023'>M. Zanfrognini et al., ''Distinguishing different stackings in layered materials via luminescence spectroscopy'', [https://doi.org/10.1103/PhysRevLett.131.206902 Phys. Rev. Lett. '''131''', 206902 (2023)]; [https://arxiv.org/abs/2305.17554 arXiv 2305.17554] </ref>
<ref name='marini2024'>G. Marini, M. Calandra, P. Cudazzo, ''Optical absorption and photoluminescence of single layer boron nitride from a first principles cumulant approach'', [https://doi.org/10.1021/acs.nanolett.4c00669 Nano Lett., '''24''', 20, 6017 (2024)]; [https://arxiv.org/abs/2402.03826 arXiv 2402.03826 (2024)]</ref>
<ref name='antonius2017'>G. Antonius, S. G. Louie, ''Theory of exciton-phonon coupling'', [https://doi.org/10.1103/PhysRevB.105.085111 Phys. Rev. B, '''105''', 085111 (2022)]; [https://arxiv.org/abs/1705.04245 arXiv1705.04245 (2017)]</ref>
<ref name='paleari2022'> F. Paleari, and A. Marini, ''Exciton-phonon interaction calls for a revision of the “exciton” concept'', [https://doi.org/10.1103/PhysRevB.106.125403 Phys. Rev. B, '''106''', 125403 (2022)]; [https://arxiv.org/abs/2205.02783 arXiv 2205.02783]</ref>
<ref name='cudazzo2020'> P. Cudazzo, ''First-principles description of the exciton-phonon interaction: A cumulant approach'', [https://doi.org/10.1103/PhysRevB.102.045136 Phys. Rev. B, '''102''', 045136 (2020)]; [https://orbilu.uni.lu/bitstream/10993/44769/1/main.pdf Open access pdf from Luxembourg University]</ref>
<ref name='chan2023'>Y-h Chan, J. B. Haber, M. H. Naik, J. B. Neaton, D. Y. Qiu, F. H. da Jornada, S. G. Louie, ''Exciton Lifetime and Optical Line Width Profile via Exciton–Phonon Interactions: Theory and First-Principles Calculations for Monolayer MoS2'', [https://doi.org/10.1021/acs.nanolett.3c00732 Nano Lett., '''23''', 9 (2023)]; [https://arxiv.org/abs/2212.08451 arXiv 2212.08451 (2023)]</ref>
<ref name='murali2025'>M. Nalabothula, S. Reichardt, L. Wirtz, ''Origin of Interlayer Exciton–Phonon Coupling in 2D Heterostructures'', [https://doi.org/10.1021/acs.nanolett.5c00355 Nano Lett., '''25''', 15 (2025)], [https://arxiv.org/abs/2407.16111 arXiv 2407.16111 (2025)]</ref>
</references>

Exciton-phonon coupling and luminescence

2026-03-13T14:44:44Z

FulvioPaleari:

[[File:Tdgw-phonon-usc-01-1024x829.jpg| 400px | right | caption=(c) Zhenglu Li, University of Southern California]]

In this advanced tutorial, we will calculate exciton-phonon interactions from first principles by interfacing DFPT (for phonon calculations) and BSE (for exciton calculations).

The DFTP calculations are run with Quantum ESPRESSO, while the many-body GW-BSE calculations are run with Yambo. Finally, the exciton-phonon interaction will be obtained by combining and postprocessing the databases computed in the two previous runs. The great advantage of this workflow is that the calculations can be run in the irreducible Brillouin zones both for the electronic momenta ('''k''') and the transfer momenta ('''Q''', '''q''') of excitons and phonons, thus speeding up considerably the jobs while reducing the IO and memory load.

We will first compute the exciton-phonon coupling matrix elements: these are the building blocks needed to construct experimental observables such as phonon-assisted optical spectra (such as luminescence), Raman spectra and exciton lifetimes. We will do this in the case of monolayer MoS2, a 2D system with large spin-orbit interaction.

As an example of application, we will consider the case of phonon-assisted luminescence. We will do this in the case of bulk hBN, a layered indirect insulator with strong electron-phonon coupling.

'''Note:''' this tutorial will be updated when new exc-ph tools become available in Yambopy (including full-python postprocessing, Raman spectra, interpolated lifetimes, etc).

== Requirements ==

This is an advanced topic: we assume that you already know something about the theory<ref name="toyozawa2003" /><ref name="antonius2017" /><ref name="cudazzo2020" /><ref name="paleari2019_PhD" /><ref name="paleari2022" /><ref name="lechifflart2023_PhD" /> and applications<ref name="paleari2019" /><ref name="cannuccia2019" /><ref name="chen2020" /><ref name="zanfrognini2023" /><ref name="lechifflart2023" /><ref name="chan2023" /><ref name="marini2024" /><ref name="murali2025" /> of exciton-phonon physics.

Also, we assume that you already know how to run both a basic '''Yambo''' GW-BSE calculation and a DFPT phonon calculation with '''Quantum ESPRESSO'''.

Besides the QE executables <code>pw.x</code> and <code>ph.x</code>, we also use the yambo phonon-specific executable <code>yambo_ph</code> and the python utility '''Yambopy'''. The auxiliary code '''LetzElPhC''' (executable <code>lelphc</code>) will be used to obtain the electron-phonon matrix elements by reading the same electronic wavefunctions used by Yambo (and stored in the <code>SAVE</code> directory), while also making full use of crystal symmetries. [https://github.com/yambo-code/LetzElPhC LetzElPhC] will be run by Yambopy, but it must nonetheless be installed. Finally, the exciton-phonon properties can be computed either using <code>yambo_ph</code> or using Yambopy itself. Both cases will be covered in this tutorial.

[[File:Workflow scheme.png|800px|center]]

== Step 0: Pseudopotentials, equilibrium structure and convergence ==

In a real calculation, it is important to ensure that both the pseudopotential and the lattice parameters that we are using are compatible and perform well for the electronic excited states and for the lattice vibrations simultaneously. Furthermore, you have to make sure that the wave function cutoff <code>ecutwfc</code> is converged with respect to the DFPT step and not just to the DFT one. This is in addition to the other customary convergence tests for DFT, DFPT, GW and BSE calculations.

This is often the most time-demanding step when starting on a new system.

For the sake of this tutorial, we assume that we have already done all these tests and we are starting the final workflow to get the exciton-phonon properties.

== Step 1: scf calculation ==

First of all, we run a standard scf calculation with <code>pw.x</code> for Yambo. We stick with non-symmorphic symmetries. At the end, we will have the QE <code>save</code> directory.

This is the input <code>mos2.scf</code>:

&control
wf_collect = .true.,
calculation = "scf",
verbosity = 'high',
pseudo_dir = '$PSEUDO_DIR',
prefix = "mos2",
outdir = '.',
/&end
&system
ecutwfc = 100.0,
occupations = 'fixed',
ibrav = 4,
celldm(1) = 5.9000811881,
celldm(3) = 6.7795677253,
nat = 3,
ntyp = 2,
lspinorb = .true.
noncolin = .true.
assume_isolated = '2D'
force_symmorphic = .true.
/&end
&electrons
electron_maxstep = 200,
mixing_beta = 0.7,
conv_thr = 1.d-08,
/&end
ATOMIC_SPECIES
Mo 95.940 Mo_ONCV_PBE_FR-1.0.upf
S 32.065 S_ONCV_PBE_FR-1.1.upf
ATOMIC_POSITIONS { crystal }
Mo 0.333333333 0.666666667 0.000000000
S 0.666666667 0.333333333 0.073413577
S 0.666666667 0.333333333 -0.073413577
K_POINTS { automatic }
6 6 1 0 0 0

Here we are using full relativistic pseudopotentials from the SG-15 database.

We can run it on our machine (for example using 4 MPI tasks) as:

mpirun -np 4 pw.x -inp mos2.scf > scf.out

== Step 2: nscf calculation for Yambo ==

Copy the QE <code>save</code> directory from the scf calculation and run the nscf calculation for any number of empty states, with the correct <code>k</code>-grid we want to use in Yambo. Here we are using a badly underconverged grid of 6x6x1.

This reciprocal-space grid will also match the momentum transfer <code>q</code> grid on which excitons and phonons will be defined!

The electronic wavefunctions computed at this step and stored in the new nscf <code>save</code> directory will be used both by Yambo and by the electron-phonon code: this is important because using different sets of wavefunctions would lead to a phase mismatch issue in the exciton-phonon matrix elements.

The nscf input <code>mos2.nscf</code> is
&control
wf_collect = .true.,
calculation = "nscf",
verbosity = 'high',
pseudo_dir = '$PSEUDO_DIR',
prefix = "mos2",
outdir = '.',
/&end
&system
ecutwfc = 100.0,
occupations = 'fixed',
ibrav = 4,
celldm(1) = 5.9000811881,
celldm(3) = 6.7795677253,
nat = 3,
ntyp = 2,
lspinorb = .true.
noncolin = .true.
nbnd = 250
assume_isolated = '2D'
force_symmorphic = .true.
/&end
&electrons
electron_maxstep = 200,
mixing_beta = 0.7,
conv_thr = 1.d-08,
/&end
ATOMIC_SPECIES
Mo 95.940 Mo_ONCV_PBE_FR-1.0.upf
S 32.065 S_ONCV_PBE_FR-1.1.upf
ATOMIC_POSITIONS { crystal }
Mo 0.333333333 0.666666667 0.000000000
S 0.666666667 0.333333333 0.073413577
S 0.666666667 0.333333333 -0.073413577
K_POINTS { automatic }
6 6 1 0 0 0

Again, we run the calculation

mpirun -np 4 pw.x -inp mos2.nscf > nscf.out

== Step 3: dvscf phonon calculation ==

Now we run the phonon calculation.

Copy the <code>save</code> directory from the '''scf''' calculation and run <code>ph.x</code> for a dvscf calculation with a standard <code>q</code>-grid matching the <code>k</code>-grid we wanna use in Yambo.

At the end, we will have the <code>_ph0</code> directory containing the variation of the self-consistent potential, <math>\Delta V_{SCF}(q)</math>, and the <code>*.dyn</code> files with the phonon energies and eigenvectors.

NB: one could further refine the phonon energies by enforcing the acoustic sum rule, including non-analytic long-range contributions, interpolating to finer grids... all of this can be done within Quantum ESPRESSO and will not be covered in this version of the tutorial.

The input is <code>mos2.dvscf</code>:

mos2_dvscf
&inputph
tr2_ph=1.0d-12,
verbosity='high'
prefix='mos2',
fildvscf = 'mos2-dvscf',
electron_phonon = 'dvscf',
fildyn='mos2.dyn',
epsil=.false.,
ldisp=.true.,
recover=.true.,
nq1=6,
nq2=6,
nq3=1
/

And now we run as

nohup mpirun -np 8 ph.x -inp mos2.dvscf > dvscf.out &

This time we use nohup and more processes because this calculation may take some time. It is a good idea to set <code>recover=.true.</code> as in a real calculation you will easily breach walltime, and in this way you can safely restart.

== Step 4: create Yambo <code>SAVE</code> directory ==

This is just the standard Yambo initialization: run

p2y

and then

yambo

in the '''nscf''' <code>save</code> folder and then move the newly generated <code>SAVE</code> directory to a convenient place.

== Step 5: run a BSE calculation ==

Now we switch from QE to Yambo. Here, we forgo the GW step for simplicity (we can use a scissor operator to open the band gap).

This calculation has a couple of differences with respect to a standard BSE calculation for optical absorption. We can look at the input file <code>bse.in</code>:

# Runlevels
optics # [R OPT] Optics
rim_cut # [R RIM CUT] Coulomb potential
bss # [R BSS] Bethe Salpeter Equation solver
em1s # [R Xs] Static Inverse Dielectric Matrix
bse # [R BSE] Bethe Salpeter Equation.
bsk # [R BSK] Bethe Salpeter Equation kernel
# RIM and cutoff settings
RandQpts=1000000 # [RIM] Number of random q-points in the BZ
RandGvec= 100 RL # [RIM] Coulomb interaction RS components
CUTGeo= "slab z" # [CUT] Coulomb Cutoff geometry: box/cylinder/sphere X/Y/Z/XY..
# Static screening
X_and_IO_CPU= "1 1 4 2 1" # [PARALLEL] CPUs for each role
X_and_IO_ROLEs= "q g k c v" # [PARALLEL] CPUs roles (q,g,k,c,v)
X_and_IO_nCPU_LinAlg_INV=-1 # [PARALLEL] CPUs for Linear Algebra (if -1 it is automatically set)
Chimod= "hartree" # [X] IP/Hartree/ALDA/LRC/BSfxc
% BndsRnXs
1 | 200 | # [Xs] Polarization function bands
%
% LongDrXs
1.000000 | 1.000000 | 1.000000 | # [Xs] [cc] Electric Field
%
NGsBlkXs= 8000 mRy # [Xs] Response block size
# BSE
BS_CPU= "4.1.2" # [PARALLEL] CPUs for each role
BS_ROLEs= "k.eh.t" # [PARALLEL] CPUs roles (k,eh,t)
BS_nCPU_diago=4 # [PARALLEL] CPUs for matrix diagonalization
BSEmod= "causal" # [BSE] resonant/causal/coupling
BSKmod= "SEX" # [BSE] IP/Hartree/HF/ALDA/SEX/BSfxc
BSSmod= "d" # [BSS] (h)aydock/(d)iagonalization/(s)lepc/(i)nversion/(t)ddft`
BSENGexx= 40000 mRy # [BSK] Exchange components
ALLGexx # [BSS] Force the use use all RL vectors for the exchange part
BSENGBlk= 8000 mRy # [BSK] Screened interaction block size
Lkind="full" #[BSE,X] bar(default)/full/tilde
% KfnQP_E
1.000000 | 1.000000 | 1.000000 | # [EXTQP BSK BSS] E parameters (c/v) eV|adim|adim
%
% BEnRange
0.00000 | 4.00000 | eV # [BSS] Energy range
%
% BDmRange
0.05000 | 0.05000 | eV # [BSS] Damping range
%
BEnSteps= 2000 # [BSS] Energy steps
% BLongDir
1.000000 | 0.000000 | 0.000000 | # [BSS] [cc] Electric Field
%
% BSEQptR
 1 | 7 | # [BSK] Transferred momenta range
%
% BSEBands
25 | 28 | # [BSK] Bands range
%
WRbsWF # [BSS] Write to disk excitonic the FWs

This file was generated using the command: <code> yambo -X s -o b -k sex -y d -r</code> 

First of all, we compute the excitons for all the momenta in the irreducible Brillouin zone for our discrete grid via the <code>BSEQptR</code> variable. This will be a '''finite-momentum''' BSE calculation, analogous to the phonon one.

Second, we change the variable <code>Lkind</code> from <code>bar</code> to <code>full</code>. In Yambo, <code>Lkind="bar"</code>, which is the default for optical absorption, means that we are computing the excitonic response function without the long-range component of the exchange interaction. This cannot be used when computing the exciton momentum dependence, where the long-range exchange interaction can play a role, therefore we have to include it with <code>Lkind="full"</code>. This allows for the calculation of the excitonic longitudinal-transverse splitting (in 3D systems) as well.

We can now run the code:

nohup mpirun -np 8 yambo -F bse.in -J bse_Lfull -C bse_Lfull &

At the end of the calculation, we have obtained the <code>ndb.BS_diago_Q*</code> databases inside the directory <code>bse_Lfull</code>. They contain information on the exciton energies and wavefunctions at each momentum. Do not forget to check the report and logs of your calculation in the same directory to make sure that the code is doing what you want.

== Step 6: obtain the electron-phonon matrix elements ==

We have finished the heavy simulations. Now it's time for the postprocessing. The first order of business is the reconstruction of the electron-phonon coupling matrix elements from the dvscf results and the electronic wavefunctions.

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

We run in the same directory where the Yambo <code>SAVE</code> 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>n_i</math> to <math>n_f</math>, we should type:

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

Here <math>n_i</math> and <math>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>[n_i,n_f]</math> including the extrema of the interval.

These should coincide with those used for the Bethe-Salpeter kernel, i.e. those specified in the <code>BSEBands</code> variable of the BSE input file (this is not strictly necessary, but certainly efficient since these calculations use a lot of disk space).

For our system, we want to do a parallel calculation with 4 qpools and 2 kpools. In addition, we want to explicitly specify the path of the <code>lelphc</code> executable and avoid automatically deleting the LetzElPhC data. So we type:

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

At the end, check your directory: you should find the <code>lelphc.in</code> 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 <code>convention=yambo</code>: 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>n</math> and momentum <math>k-q</math> to band <math>m</math> and momentum <math>k</math>. In the "forward" momentum transfer convention (the more standard one), the transitions go from <math>nk</math> to <math>mk+q</math>. Therefore, this variable ensures that the electron-phonon coupling matrix elements are computed as <math>\langle mk|dV|nk-q\rangle</math>. This will have consequences also in the formulation of the ''exciton''-phonon coupling matrix element.

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

In addition, if you check the <code>SAVE</code> folder:

ls SAVE/ndb.elph_gkkp*

you will see that yambopy has created the Yambo-compatible electron-phonon databases.

If you want to run LetzElPhC directly, without using yambopy, you can refer to its [[https://gitlab.com/lumen-code/LetzElPhC/-/blob/main/docs/main.pdf?ref_type=heads|user guide]].
Keep in mind that in this case, in order to convert the database to the <code>ndb.elph_gkkp*</code> databases of Yambo, you will then need a couple of lines of python using the Yambopy class <code>ConvertElectronPhononDB</code> in <code>yambopy/letzelph_interface/lelph2y.py</code>.

If you don't need the <code>ndb.elph_gkkp*</code> databases -- e.g., because you are doing the exc-ph postprocessing with yambopy -- you can run <code>yambopy l2y ...</code> with the <code>--no_gkkp</code> option.

If you don't need the <code>ndb.elph</code> databases -- e.g., because you are using <code>yambo_ph</code> for the exc-ph part -- you can run <code>yambopy l2y ...</code> with the <code>--no_lelphc_dbs</code> option.

== Step 7: Obtain the exciton-phonon coupling ==

Now, we can finally access our basic building block for exciton-phonon physics. This could be done entirely in python (using '''Yambopy'''), or by running '''Yambo'''.

* For the '''Yambo postprocessing''' case (running yambo inputs with the <code>yambo_ph</code> executable), '''follow the alternative route to Steps 7-8 [[Exciton-phonon coupling and luminescence - Yambo postprocessing|at this link]]'''.
* For the '''Yambopy postprocessing''' case (using flexible python scripting), '''keep following Steps 7-8 on this page'''.

Our objective is obtaining the following quantity:

<math>\mathcal{G}^\mu_{\alpha\lambda}(0,q)=\sum_{vv^\prime c k} A^{\alpha, *}_{cv^\prime} (k, q) g_{vv^\prime}^\mu (k,q) A^{\lambda}_{cv}(k,0) - \sum_{cc^\prime vk} A^{\alpha, *}_{c^\prime v} (k+q, q) g_{c^\prime c}^\mu (k+q,q) A^{\lambda}_{cv}(k, 0)</math>

Here, <math>A^{\alpha}_{cv}(k,q)</math> are the exciton coefficients extracted from the eigenvector of the two-particles Hamiltonian during the BSE calculation in step 5, while <math>g_{nm}^\mu (k,q)</math> are the electron-phonon coupling matrix elements obtained in step 6. As you can see, the exciton <math>\lambda</math> undergoes phonon-mediated scattering to state <math>\alpha</math> via phonon mode <math>\mu</math>. The scattering can happen for the hole (valence, <math>v</math>) or for the electron (conduction, <math>c</math>).

NB:

(1) This is written in the "backward" momentum transfer convention used by Yambo. The momentum dependence is different in the "forward" transfer convention.

(2) For simplicity, this is written for zero initial exciton momentum. This means that one of the two states involved in the phonon-mediated scattering process will be in the optical limit (and possibly an optically generated exciton), while the other state can have any momentum: this momentum will be the same as the phonon one. This matrix element can be used to describe phonon-assisted absorption and emission spectra.

In order to calculate this quantity using python, we need the <code>ndb.elph</code> databases natively generated by the <code>LetzElPhC</code> code, as well as the BSE databases <code>ndb.BS_diago_Q*</code> containing the information on exciton wavefunctions and energies.

Next, we write a python user script importing the yambopy exciton-phonon tools. You can find a version of this script in <code>yambopy/tutorials/exciton-phonon/calculate_excph.py</code>.

import numpy as np
from yambopy import YamboLatticeDB,YamboWFDB,LetzElphElectronPhononDB #Specific Yambopy dbs loading classes
from yambopy.exciton_phonon.excph_matrix_elements import exciton_phonon_matelem #Specific exc-ph functions

path = '1L_MoS2'
bands_range=[24,28] # 2 valence bands, 2 conduction bands
nexc = 12 # number of excitonic states

bsepath = f'{path}/bse-allq_full' # Path to BSE calculation (Lin=Lout)
savepath = f'{path}/SAVE' # Yambo SAVE
ndb_elph = f'{path}/ndb.elph' # LetzElPhC electron-phonon database (any convention)

# Read lattice
lattice = YamboLatticeDB.from_db_file(filename=f'{savepath}/ns.db1')
# Read electron-phonon
elph = LetzElphElectronPhononDB(ndb_elph,read_all=False)
# Read wave functions
wfcs = YamboWFDB(filename='ns.wf',save=savepath,latdb=lattice,bands_range=bands_range)
# Calculate exciton-phonon matrix elements
exph = exciton_phonon_matelem(lattice,elph,wfcs,BSE_dir=bsepath,nexc_in=nexc,nexc_out=nexc,dmat_mode='save',exph_file='MoS2_Ex-ph.npy')

In this script, we can select the number exciton states <math>\lambda</math> with <code>nexc</code>, the single-particle bands range with <code>bands_range</code>. '''Please note''': in this case, the band index starts from 0 (python indexing) and the the interval of bands read by the code is <math>[n_i,n_f)</math>, therefore the last value (28 in the example) is excluded. That is, in the example we are selecting the 25th, 26th, 27th and 28th bands. Those bands have to be present in both the electron-phonon and BSE calculations.

Here we calculate the couplings of the first twelve states at each finite-<math>q</math> point including <math>q=0</math>. We also include all the nine phonon modes of monolayer MoS2. We also need access to the Yambo <code>SAVE</code> directory in order to read the electronic wavefunctions: they are used to compute the electronic representation matrices (<code>dmat</code> in the code). The argument <code>dmat_mode</code> can be set to <code>'load'</code> for subsequent calculations.

When we are satisfied with the input, we run the code:

python calculate_excph.py

If you check the output, you should find the <code>MoS2_Ex-ph.npy</code> binary file in the directory where you ran.

=== Analysis of the couplings ===

It is a good idea to have a look at what we computed up to now in order to make sure nothing has gone wrong.

It is not easy to know what to expect (apart from symmetry and gauge compliance of the matrix elements), but one can work out the exciton-phonon selection rules in advance, check that the magnitude is reasonable, etc.

It is also not easy to meaningfully plot this quantity. We have to make sure that we are not breaking degenerate states, otherwise the plots will not be invariant.

First of all, we have to know our system: in monolayer MoS2, the first four excitons are all doubly degenerate. The first exciton responsible for a bright peak in the absorption spectrum (the '''A''' peak), is the second state, corresponding to state indices <code>(3,4)</code> in fortran indexing or <code>(2,3)</code> in python indexing.

All these information can be obtained by analyzing the BSE results (this stuff is explained in the BSE tutorials) and by knowledge of the system or class of systems from the literature.

Thus, a good quantity to plot may be the norm of the matrix elements, summed over the degenerate subspace of exciton A, for a certain number of scattered final states mediated by certain phonon modes:

<math>F_A(q)= \sqrt{ \sum_{\alpha \in A,\lambda,\mu} |\mathcal{G}_{\alpha\lambda}^\mu (0,q)|^2 }</math>

In order to do this, we create a python script <code>analyse_excph.py</code> in which we first load the excph dabatases.
You can find a version of this script in the yambopy directory, in <code>tutorials/exciton-phonon</code>.
First, we select the exciton and phonon states to be included in <code>F_A</code>, together with the path of databases and plot details:

# Exciton "in" states
exc_in = [2,3] # First bright peak (A: 2,3 -- B: 6,7)
exc_out = [0,1,2,3] # first 4 states (dispersion of dark triplet state and A)
ph_in = 'all'
# Paths of databases
ns_db1 =f'{path}/SAVE/ns.db1'
ns_ypy = 'MoS2_Ex-ph.npy'

...

Then, we load the data:

# Read lattice and k-space info
ylat = YamboLatticeDB.from_db_file(filename=ns_db1)
print(ylat)

# Load exc-ph database
X_py = np.load(ns_ypy)
G_squared = np.abs(X_py)**2.

The quantity <math>F_A(q)</math> is obtained from a dedicated function as:

if exc_in == 'all': exc_in = range(G_squared.shape[2])
if exc_out == 'all': exc_out = range(G_squared.shape[3])
if ph_in == 'all': ph_in = range(G_squared.shape[1])

G_squared = G_squared[:, ph_in, :, :].sum(axis=(1))
G_squared = G_squared[:, exc_in, :].sum(axis=(1))
G_squared = G_squared[:, exc_out].sum(axis=(1))

F_q = np.sqrt( G_squared )*ha2ev # Switch from Ha to eV

And finally, we have to make a plotting function. For this tutorial we will use a custom scatterplot employing some of the plotting tools provided by yambopy (but you can do whatever you want).

plot_2D_excph(qgrid,G2_to_plot,rlat=ylat.rlat,plt_cbar=True,\
marker='H',s=700,cmap='magma')
...

You can get more experience on using Yambopy for these kinds of visualization by following the [https://wiki.yambo-code.eu/wiki/index.php?title=First_steps_in_Yambopy Yambopy tutorials]. In fact, remember that these scripts and all the other Yambopy tutorial scripts are just suggestions, not source code written in stone: if you know <code>numpy</code> and <code>matplotlib</code> you can do your own analysis and your own plots, you just need to import the required Yambopy modules to load the data.

In our case, the resulting plot is the following.

[[File:1L MoS2 MoS2 Ex-ph.png|500px|center]]

This can be checked against Fig. 2(d) of reference <ref name="chan2023" />, although you have to keep in mind that our results are badly undersampled in terms of the reciprocal-space grid, as can be easily seen, and the quantity plotted is not exactly the same. However, the main features are already there since they are dictated mostly by crystal symmetries.

Now that we have the exciton-phonon matrix elements, we can use them to build several kinds of observables. Below, we give an example related to phonon-assisted luminescence, but we may update this tutorial in the future to include more cases.

== Step 8: Compute phonon-assisted luminescence ==

[[File:Luminescence scheme.png|250px|right]]

We want to compute the experimental optical signature due to the phonon-assisted recombination of an exciton (as sketched in the figure).

The signal from the phonon replicas can be modeled as a second-order scattering process involving one phonon and one photon:

<math>I^{Sat}(\omega)=\frac{1}{ N_q} \frac{1}{3} \sum_{\epsilon s\beta \mu q} \frac{1}{E_{\beta q}-s\Omega_{\mu q}}\left|\sum_\alpha\frac{ D^{\epsilon}_\alpha \mathcal{G}_{\beta \alpha}^{\mu,*}(q)}{E_\alpha -E_{\beta q} +s\Omega_{\mu q}+\mathrm{i}\eta}\right|^2 \frac{N^{exc}_{\beta q}(T_{exc})[\frac{1+s}{2}+n_{\mu q}(T)]}{\omega -[E_{\beta q}-s\Omega_{\mu q}]+\mathrm{i}\eta}</math>

In this equation, the oscillator strength of the peak is given by the exciton-phonon coupling matrix elements <math>\mathcal{G}</math> multiplied by the exciton dipoles <math>D</math> (they are called "residuals" in Yambo). Here <math>E_\lambda</math> and <math>E_{\alpha q}</math> are the energies of the optical and finite-momentum excitons, respectively, while <math>\Omega_{\mu q}</math> are the phonon energies.

Here, <math>n_{\mu q}(T)</math> is the temperature-dependent phonon Bose-Einstein occupation function. As it can be seen, <math>s=1</math> corresponds to processes of phonon ''emission'' (<math>\propto n(T)+1</math>), while <math>s=-1</math> corresponds to processes of phonon ''absorption'' (<math>\propto n(T)</math>). Therefore, <math>I^{Sat}_{PL}(\omega;T)</math> describes ''light'' emission by recombining excitons mediated by either ''phonon'' absorption or emission.

The quantity <math> N_{\alpha q}(T_{exc})</math> is the exciton occupation function. Luminescence is technically an out-of-equilibrium process, but we can assume that for very low density of excitations and in steady-state conditions, the exciton population can be approximately described by an equilibrium distribution evaluated at an effective temperature. Here, we use the Boltzmann distribution. Experimentally, <math>T_{exc}</math> tends to coincide with the lattice temperature <math>T</math> more or less above 100 K, while at very low temperature (< 10 K), <math>T_{exc}</math> may vary between 10-50 K. It goes without saying that this needs to carefully be checked in your realistic calculations.

Finally, the spectrum is averaged over the polarization directions of the emitted photons (<math>\epsilon=x,y,z</math> representing the respective dipole components).

=== Running the jobs ===

In order to study luminescence in a paradigmatic system, we switch to bulk hexagonal boron nitride and we repeat the workflow. As you can easily see, one can think about automatizing the execution of all these calculations via scripting or more advanced tools. However, in the case of very large simulations (memory-limited or disk-space limited) or for systems whose electronic and lattice properties are fragile with respect to tiny calculation details, one must be very careful and run many basic tests.

Fortunately, we are running a fast underconverged example. We use LDA pseudopotentials from the pseudo-dojo library and the following are the calculations steps.

1. Input <code>hbn.scf</code>:

&control
calculation='scf',
prefix='hBN',
restart_mode='from_scratch'
pseudo_dir = '$PSEUDO_DIR',
outdir = './tmp'
verbosity = 'high'
wf_collect=.true.
/
&system
ibrav = 4,
celldm(1) = 4.703675849
celldm(3) = 2.603711434
nat= 4,
ntyp= 2,
force_symmorphic=.true.
ecutwfc = 100,
/
&electrons
diago_david_ndim = 2
diago_full_acc=.true.
diago_thr_init=5.0e-6
mixing_mode = 'plain'
mixing_beta = 0.7
conv_thr = 1.0d-16
/
ATOMIC_SPECIES
B 10.81100 B_LDA_dojo.UPF
N 14.00674 N_LDA_dojo.UPF
ATOMIC_POSITIONS {crystal}
N 0.6666666670 0.3333333330 -0.250000000000
B 0.3333333330 0.6666666670 -0.250000000000
B 0.6666666670 0.3333333330 0.25000000000
N 0.3333333330 0.6666666670 0.25000000000
K_POINTS {automatic}
6 6 2 0 0 0

mpirun -np 4 pw.x -inp hbn.scf > scf.out

2. Input <code>hbn.nscf</code>:

&control
calculation='nscf',
prefix='hBN',
restart_mode='from_scratch'
pseudo_dir = '$PSEUDO_DIR'
outdir = './'
verbosity = 'high'
wf_collect=.true.
/
&system
ibrav = 4,
celldm(1) = 4.703675849
celldm(3) = 2.603711434
nat= 4,
ntyp= 2,
force_symmorphic=.true.
ecutwfc = 100,
nbnd = 120
/
&electrons
diago_david_ndim = 2
diago_full_acc=.true.
diago_thr_init=5.0e-6
mixing_mode = 'plain'
mixing_beta = 0.7
conv_thr = 1.0d-16
/
ATOMIC_SPECIES
B 10.81100 B_LDA_dojo.UPF
N 14.00674 N_LDA_dojo.UPF
ATOMIC_POSITIONS {crystal}
N 0.6666666670 0.3333333330 -0.250000000000
B 0.3333333330 0.6666666670 -0.250000000000
B 0.6666666670 0.3333333330 0.25000000000
N 0.3333333330 0.6666666670 0.25000000000
K_POINTS {automatic}
6 6 2 0 0 0

mpirun -np 4 pw.x -inp hbn.nscf > nscf.out

3. Input <code>hbn.dvscf</code>:

hbn_dvscf
&inputph
tr2_ph=1.0d-12,
verbosity='high'
prefix='hBN',
fildvscf = 'hBN-dvscf',
electron_phonon = 'dvscf',
fildyn='hBN.dyn',
epsil=.false.,
ldisp=.true.,
recover=.true.,
nq1=6,
nq2=6,
nq3=2
/

nohup mpirun -np 8 pw.x -inp hbn.dvscf > dvscf.out &

4. Input <code>bse.in</code> (we include 2 valence and 2 conduction bands):

optics # [R] Linear Response optical properties
bss # [R] BSE solver
bse # [R][BSE] Bethe Salpeter Equation.
dipoles # [R] Oscillator strenghts (or dipoles)
em1s
DIP_CPU= "1 8 1" # [PARALLEL] CPUs for each role
DIP_ROLEs= "k c v" # [PARALLEL] CPUs roles (k,c,v)
DIP_Threads=0 # [OPENMP/X] Number of threads for dipoles
X_and_IO_CPU= "1 1 1 8 1" # [PARALLEL] CPUs for each role
X_and_IO_ROLEs= "q g k c v" # [PARALLEL] CPUs roles (q,g,k,c,v)
X_and_IO_nCPU_LinAlg_INV=-1 # [PARALLEL] CPUs for Linear Algebra (if -1 it is automatically set)
X_Threads=0 # [OPENMP/X] Number of threads for response functions
BS_CPU= "8 1 1" # [PARALLEL] CPUs for each role
BS_ROLEs= "k eh t" # [PARALLEL] CPUs roles (k,eh,t)
BS_nCPU_LinAlg_INV=-1 # [PARALLEL] CPUs for Linear Algebra (if -1 it is automatically set)
BS_nCPU_LinAlg_DIAGO=-1 # [PARALLEL] CPUs for Linear Algebra (if -1 it is automatically set)
X_Threads=0 # [OPENMP/X] Number of threads for response functions
K_Threads=0 # [OPENMP/BSK] Number of threads for response functions
% QpntsRXs
1 | 14 | # [Xs] Transferred momenta
%
% BndsRnXs
1 | 120 | # [Xs] Polarization function bands
%
NGsBlkXs= 10 Ry # [Xs] Response block size
% LongDrXs
1.000000 | 1.000000 | 1.000000 | # [Xs] [cc] Electric Field
%
BSEmod= "resonant" # [BSE] resonant/retarded/coupling
BSKmod= "SEX" # [BSE] IP/Hartree/HF/ALDA/SEX/BSfxc
Lkind= "Lfull" # [BSE] Lbar (default) / full
BSSmod= "d" # [BSS] (h)aydock/(d)iagonalization/(s)lepc/(i)nversion/(t)ddft`
% DipBands
1 | 120 | # [DIP] Bands range for dipoles
%
DipApproach= "G-space v" # [DIP] [G-space v/R-space x/Covariant/Shifted grids]
DipComputed= "R V P" # [DIP] [default R P V; extra P2 Spin Orb]
BSENGexx= 30000 Ry # [BSK] Exchange components
#ALLGexx # [BSS] Force the use use all RL vectors for the exchange part
BSENGBlk= 9000 Ry # [BSK] Screened interaction block size [if -1 uses all the G-vectors of W(q,G,Gp)]
% KfnQP_E
1.25997 | 1.08816 | 1.12683 | # [EXTQP BSK BSS] E parameters (c/v) eV|adim|adim
%
% BSEQptR
 1 | 14 | # [BSK] Transferred momenta range
%
% BSEBands
 7 | 10 | # [BSK] Bands range
%
% BEnRange
0.50000 | 8.00000 | eV # [BSS] Energy range
%
% BDmRange
0.050000 | 0.050000 | eV # [BSS] Damping range
%
BEnSteps= 1000 # [BSS] Energy steps
% BLongDir
1.000000 | 1.000000 | 0.000000 | # [BSS] [cc] Electric Field
%
WRbsWF # [BSS] Write to disk excitonic the WFs

nohup mpirun -np 8 yambo -F bse.in -J bse_Lfull -C bse_Lfull &

Importantly, since we want to describe the phonon-assisted recombination process of an *optical* exciton (i.e., emitting a transverse photon), this time we also run an additional calculation at `Q=0` omitting the nonanalytic long-range Coulomb exchange. Make a second input <code>bse_Lbar.in</code> with the following changes:

Lkind= "Lbar" # [BSE] Lbar (default) / full
% BSEQptR
 1 | 1 | # [BSK] Transferred momenta range
%

4b. So now we make a second BSE run in a different directory specified by <code>-J</code>. Here, we also pass to yambo the directory of the previous run as it includes the important screening databases <code>ndb.em1s*</code> that we do not want to recompute from scratch.

mpirun -np 8 yambo -F bse_Lbar.in -J bse_Lbar,bse_Lfull -C bse_Lbar

5. Now we run <code>lelphc</code> (with or without yambopy: in the latter case remember the option <code>-D</code>) to get the el-ph matrix elements, particularly the <code>ndb.elph</code> databases:

yambopy l2y -ph path/of/dvscf/hbn.dvscf -b 7 10 -par 4 2 -D

=== Luminescence calculation ===

6. And finally we calculate exciton-phonon matrix elements and the luminescence spectrum in one go using a python script importing the Yambopy exciton-phonon tools: in order to do this, we need to take a look at all the necessary input variables for the formula written above.

We can start from the script <code>luminescence.py</code> available in <code>tutorials/exciton-phonon</code>.

import numpy as np
import matplotlib.pyplot as plt
from yambopy.exciton_phonon.excph_luminescence import exc_ph_luminescence
from yambopy.exciton_phonon.excph_input_data import exc_ph_get_inputs

We import the necessary tools...

path = '3D_hBN'
# Path to BSE calculation (Lout--> response is Lfull)
bsepath = f'{path}/bse_Lfull' # ndb.BS_diago_Q* databases are needed
# Path to BSE calculation for optically active exciton (Lin --> response is Lbar)
bseBARpath = f'{path}/bse_Lbar' # ndb.BS_diago_Q1 database is needed
# Path to electron-phonon calculation
elphpath = path # ndb.elph is needed
# Path to unprojected dipoles matrix elements (optional)
dipolespath = bsepath # ndb.dipoles is needed (optional)
# Path to lattice and k-space info
savepath = f'{path}/SAVE' # ns.db1 database is needed

... and we specify the paths to the necessary databases. Note that, if we want to perform polarization averaging, we have to recompute the excitonic dipoles in python as seen here.

What about <code>bseBARpath</code>? This variable points to the directory where the databases for the optical (zero-momentum) excitons <math>\alpha</math> (which may be computed with <code>Lkind='Lbar'</code>) is located, which can be different from the directory with the full indirect exciton dispersion <math>\beta</math> (usually computed with <code>Lkind='Lfull'</code>, however <code>Lkind='Ltilde'</code> can also be used if one is interested in "irreducible" excitons). This makes it possible to compute the coupling between different exciton kinds.

bands_range=[6,10] # 2 valence, 2 conduction bands
phonons_range=[0,12] # All phonons
nexc_out = 12 # 12 excitonic states at each momentum (Lout)
nexc_in = 12 # 12 excitonic states at Q=0 (Lin)
T_ph = 10 # Lattice temperature
T_exc = 10 # Effective excitonic temperature

emin=4.4 # Energy range and plot details (in eV)
emax=4.7
estep=0.0002
broad = 0.005 # Broadening parameter for peak width (in eV)

Next, we specify the parameters for the calculation. We include valence bands from 7 to 10 (6 to 9 in python index) and the contribution of all 12 phonon modes. We consider 12 excitonic states for the coupling matrix elements.

Here <code>T_ph</code> and <code>T_exc</code> are the lattice and excitonic temperatures, respectively.

# We calculate and load all the inputs:
# * Exciton-phonon matrix elements
# * Excitonic dipole matrix elements
# * Exciton energies
# * Phonon energies
# * We specify bse_path2=bseBARpath meaning we use Lbar calculation for Q=0 excitons
input_data = exc_ph_get_inputs(savepath,elphpath,bsepath,\
bse_path2=bseBARpath,dipoles_path=dipolespath,\
nexc_in=12,nexc_out=12,\
bands_range=[6,10],phonons_range=[0,12])

ph_energies, exc_energies, exc_energies_in, G, exc_dipoles = input_data

The function <code>exc_ph_get_inputs</code> gives us all the input data for luminescence in the correct format: phonon energies, exciton energies, optical exciton energies (if needed), exciton-phonon matrix elements (calculated on the fly and printed to file), unprojected exciton dipoles (optional, calculated on the fly and printed to file).
The exc-ph matrix element calculation is just a wrapper of the same tools that we have tested in the above section on MoS2.

Finally, there is the calculation of the luminescence spectrum via the function <code>exc_ph_luminescence</code>:
# We calculate the luminescence spectrum including the input data from before
w,PL = exc_ph_luminescence(T_ph,ph_energies,exc_energies,exc_dipoles,G,\
exc_energies_in=exc_energies_in,exc_temp=T_exc,\
nexc_out=nexc_out,nexc_in=nexc_in,emin=emin,emax=emax,\
estep=estep,broad=broad)

If you want to print the luminescence data for later plotting, you can also add the following line to the script:
# Save to file
data = np.column_stack((w, PL))
np.savetxt("hBN_luminescence_12x12x1.dat", data, fmt="%.8f")

It is now time to run the whole script:

python luminescence.py

NB: By using Yambopy for Step 6, we have limited the use of the Yambo code to just step 4 in the entire workflow. This option is more flexible, as it allows for a greater degree of control by the user. On the other hand the Yambo postprocessing route features a Yambo-style input that doesn't require python knowledge and the calculation is currently faster in fortran. However, the luminescence expression computed in Yambo is a slightly different than this one: it is more approximated in the description of the satellite oscillator strengths, but it explicitly includes the renormalization of the direct exciton peak. You can check the differences [[Exciton-phonon coupling and luminescence - Yambo postprocessing|here]].

=== Results ===
We can plot the results of the step 6 calculation. If we do it in the same script we can add something like this:
fig = plt.figure()
ax = fig.add_subplot(1,1,1)
ax.set_xlim(emin,emax)
ax.set_ylim(0,np.max(PL)*1.1)
ax.get_yaxis().set_visible(False)

ax.plot(w, PL, '-',c='red', label="AA' hBN luminescence")

plt.legend()
plt.savefig('hBN_luminescence.png')
plt.show()

[[File:HBN luminescence satellites.png|500px|center]]

Here, the signal corresponds to a finite-momentum exciton that recombines with the help of several different phonon modes, both optical and acoustic. Each phonon mode whose coupling with the exciton is allowed can generate a peak, and the energy shifts of these peaks with respect to the initial exciton energy correspond to the phonon energies. This result is underconverged, but the main features are all there. In the plot, we show a more converged example using a 12x12x4 grid (all the other parameters being equal). These plots can be compared with Fig. 4(a) of reference <ref name="zanfrognini2023" />.

== References ==

<references>
<ref name="toyozawa2003" >Toyozawa, Yutaka, and Chris Oxlade, ''Optical processes in solids'', [https://m.booksee.org/book/1121964?force_lang=en Cambridge University Press, (2003)]. </ref>
<ref name='lechifflart2023'>P. Lechifflart, F. Paleari, D. Sangalli, C. Attaccalite, ''First-principles study of luminescence in hexagonal boron nitride single layer: Exciton-phonon coupling and the role of substrate'',
[https://doi.org/10.1103/PhysRevMaterials.7.024006 Phys. Rev. M, '''7''' (2), 024006 (2023)]; [https://arxiv.org/abs/2212.10407 arXiv2212.1047]</ref>
<ref name='cannuccia2019'>E. Cannuccia, B. Monserrat and C. Attaccalite, ''Theory of phonon-assisted luminescence in solids: Application to hexagonal boron nitride'', [https://doi.org/10.1103/PhysRevB.99.081109 Phys. Rev. B '''99''', 081109(R) (2019)]; [https://arxiv.org/abs/1807.11797 arXiv1807.11797]</ref>
<ref name='paleari2019'>F. Paleari et al., ''Exciton-Phonon Coupling in the Ultraviolet Absorption and Emission Spectra of Bulk Hexagonal Boron Nitride'', [https://doi.org/10.1103/PhysRevLett.122.187401 Phys. Rev. Lett. '''122''', 187401 (2019)]; [https://arxiv.org/abs/1810.08976 arXiv1810.089776] </ref>
<ref name='chen2020'>''Exciton-Phonon Interaction and Relaxation Times from First Principles'',
Hsiao-Yi Chen, Davide Sangalli, and Marco Bernardi, [https://doi.org/10.1103/PhysRevLett.125.107401 Phys. Rev. Lett. '''125''', 107401 (2020)]; [https://arxiv.org/abs/2002.08913 arXiv 2002.08913 (2020)]</ref>
<ref name="lechifflart2023_PhD">P. Lechifflart, ''Exciton-phonon coupling and phonon-assisted luminescence in hexagonal Boron Nitride nanostructures'', [https://hal.science/tel-04266805v1 PhD Thesis, University of Marseille (2023)]; [https://www.yambo-code.eu/wiki/images/5/54/These_final.pdf From the yambo website]</ref>
<ref name='paleari2019_PhD'>F. Paleari, ''First-principles approaches to the description of indirect absorption and luminescence spectroscopy: exciton-phonon coupling in hexagonal boron nitride'', [https://wwwen.uni.lu/research/fstm/dphyms/people/fulvio_paleari PhD thesis, University of Luxembourg (2019)]</ref>
<ref name='zanfrognini2023'>M. Zanfrognini et al., ''Distinguishing different stackings in layered materials via luminescence spectroscopy'', [https://doi.org/10.1103/PhysRevLett.131.206902 Phys. Rev. Lett. '''131''', 206902 (2023)]; [https://arxiv.org/abs/2305.17554 arXiv 2305.17554] </ref>
<ref name='marini2024'>G. Marini, M. Calandra, P. Cudazzo, ''Optical absorption and photoluminescence of single layer boron nitride from a first principles cumulant approach'', [https://doi.org/10.1021/acs.nanolett.4c00669 Nano Lett., '''24''', 20, 6017 (2024)]; [https://arxiv.org/abs/2402.03826 arXiv 2402.03826 (2024)]</ref>
<ref name='antonius2017'>G. Antonius, S. G. Louie, ''Theory of exciton-phonon coupling'', [https://doi.org/10.1103/PhysRevB.105.085111 Phys. Rev. B, '''105''', 085111 (2022)]; [https://arxiv.org/abs/1705.04245 arXiv1705.04245 (2017)]</ref>
<ref name='paleari2022'> F. Paleari, and A. Marini, ''Exciton-phonon interaction calls for a revision of the “exciton” concept'', [https://doi.org/10.1103/PhysRevB.106.125403 Phys. Rev. B, '''106''', 125403 (2022)]; [https://arxiv.org/abs/2205.02783 arXiv 2205.02783]</ref>
<ref name='cudazzo2020'> P. Cudazzo, ''First-principles description of the exciton-phonon interaction: A cumulant approach'', [https://doi.org/10.1103/PhysRevB.102.045136 Phys. Rev. B, '''102''', 045136 (2020)]; [https://orbilu.uni.lu/bitstream/10993/44769/1/main.pdf Open access pdf from Luxembourg University]</ref>
<ref name='chan2023'>Y-h Chan, J. B. Haber, M. H. Naik, J. B. Neaton, D. Y. Qiu, F. H. da Jornada, S. G. Louie, ''Exciton Lifetime and Optical Line Width Profile via Exciton–Phonon Interactions: Theory and First-Principles Calculations for Monolayer MoS2'', [https://doi.org/10.1021/acs.nanolett.3c00732 Nano Lett., '''23''', 9 (2023)]; [https://arxiv.org/abs/2212.08451 arXiv 2212.08451 (2023)]</ref>
<ref name='murali2025'>M. Nalabothula, S. Reichardt, L. Wirtz, ''Origin of Interlayer Exciton–Phonon Coupling in 2D Heterostructures'', [https://doi.org/10.1021/acs.nanolett.5c00355 Nano Lett., '''25''', 15 (2025)], [https://arxiv.org/abs/2407.16111 arXiv 2407.16111 (2025)]</ref>
</references>

Exciton-phonon coupling and luminescence

2026-03-13T14:44:28Z

FulvioPaleari:

[[File:Tdgw-phonon-usc-01-1024x829.jpg| 400px | right | Caption=(c) Zhenglu Li, University of Southern California]]

In this advanced tutorial, we will calculate exciton-phonon interactions from first principles by interfacing DFPT (for phonon calculations) and BSE (for exciton calculations).

The DFTP calculations are run with Quantum ESPRESSO, while the many-body GW-BSE calculations are run with Yambo. Finally, the exciton-phonon interaction will be obtained by combining and postprocessing the databases computed in the two previous runs. The great advantage of this workflow is that the calculations can be run in the irreducible Brillouin zones both for the electronic momenta ('''k''') and the transfer momenta ('''Q''', '''q''') of excitons and phonons, thus speeding up considerably the jobs while reducing the IO and memory load.

We will first compute the exciton-phonon coupling matrix elements: these are the building blocks needed to construct experimental observables such as phonon-assisted optical spectra (such as luminescence), Raman spectra and exciton lifetimes. We will do this in the case of monolayer MoS2, a 2D system with large spin-orbit interaction.

As an example of application, we will consider the case of phonon-assisted luminescence. We will do this in the case of bulk hBN, a layered indirect insulator with strong electron-phonon coupling.

'''Note:''' this tutorial will be updated when new exc-ph tools become available in Yambopy (including full-python postprocessing, Raman spectra, interpolated lifetimes, etc).

== Requirements ==

This is an advanced topic: we assume that you already know something about the theory<ref name="toyozawa2003" /><ref name="antonius2017" /><ref name="cudazzo2020" /><ref name="paleari2019_PhD" /><ref name="paleari2022" /><ref name="lechifflart2023_PhD" /> and applications<ref name="paleari2019" /><ref name="cannuccia2019" /><ref name="chen2020" /><ref name="zanfrognini2023" /><ref name="lechifflart2023" /><ref name="chan2023" /><ref name="marini2024" /><ref name="murali2025" /> of exciton-phonon physics.

Also, we assume that you already know how to run both a basic '''Yambo''' GW-BSE calculation and a DFPT phonon calculation with '''Quantum ESPRESSO'''.

Besides the QE executables <code>pw.x</code> and <code>ph.x</code>, we also use the yambo phonon-specific executable <code>yambo_ph</code> and the python utility '''Yambopy'''. The auxiliary code '''LetzElPhC''' (executable <code>lelphc</code>) will be used to obtain the electron-phonon matrix elements by reading the same electronic wavefunctions used by Yambo (and stored in the <code>SAVE</code> directory), while also making full use of crystal symmetries. [https://github.com/yambo-code/LetzElPhC LetzElPhC] will be run by Yambopy, but it must nonetheless be installed. Finally, the exciton-phonon properties can be computed either using <code>yambo_ph</code> or using Yambopy itself. Both cases will be covered in this tutorial.

[[File:Workflow scheme.png|800px|center]]

== Step 0: Pseudopotentials, equilibrium structure and convergence ==

In a real calculation, it is important to ensure that both the pseudopotential and the lattice parameters that we are using are compatible and perform well for the electronic excited states and for the lattice vibrations simultaneously. Furthermore, you have to make sure that the wave function cutoff <code>ecutwfc</code> is converged with respect to the DFPT step and not just to the DFT one. This is in addition to the other customary convergence tests for DFT, DFPT, GW and BSE calculations.

This is often the most time-demanding step when starting on a new system.

For the sake of this tutorial, we assume that we have already done all these tests and we are starting the final workflow to get the exciton-phonon properties.

== Step 1: scf calculation ==

First of all, we run a standard scf calculation with <code>pw.x</code> for Yambo. We stick with non-symmorphic symmetries. At the end, we will have the QE <code>save</code> directory.

This is the input <code>mos2.scf</code>:

&control
wf_collect = .true.,
calculation = "scf",
verbosity = 'high',
pseudo_dir = '$PSEUDO_DIR',
prefix = "mos2",
outdir = '.',
/&end
&system
ecutwfc = 100.0,
occupations = 'fixed',
ibrav = 4,
celldm(1) = 5.9000811881,
celldm(3) = 6.7795677253,
nat = 3,
ntyp = 2,
lspinorb = .true.
noncolin = .true.
assume_isolated = '2D'
force_symmorphic = .true.
/&end
&electrons
electron_maxstep = 200,
mixing_beta = 0.7,
conv_thr = 1.d-08,
/&end
ATOMIC_SPECIES
Mo 95.940 Mo_ONCV_PBE_FR-1.0.upf
S 32.065 S_ONCV_PBE_FR-1.1.upf
ATOMIC_POSITIONS { crystal }
Mo 0.333333333 0.666666667 0.000000000
S 0.666666667 0.333333333 0.073413577
S 0.666666667 0.333333333 -0.073413577
K_POINTS { automatic }
6 6 1 0 0 0

Here we are using full relativistic pseudopotentials from the SG-15 database.

We can run it on our machine (for example using 4 MPI tasks) as:

mpirun -np 4 pw.x -inp mos2.scf > scf.out

== Step 2: nscf calculation for Yambo ==

Copy the QE <code>save</code> directory from the scf calculation and run the nscf calculation for any number of empty states, with the correct <code>k</code>-grid we want to use in Yambo. Here we are using a badly underconverged grid of 6x6x1.

This reciprocal-space grid will also match the momentum transfer <code>q</code> grid on which excitons and phonons will be defined!

The electronic wavefunctions computed at this step and stored in the new nscf <code>save</code> directory will be used both by Yambo and by the electron-phonon code: this is important because using different sets of wavefunctions would lead to a phase mismatch issue in the exciton-phonon matrix elements.

The nscf input <code>mos2.nscf</code> is
&control
wf_collect = .true.,
calculation = "nscf",
verbosity = 'high',
pseudo_dir = '$PSEUDO_DIR',
prefix = "mos2",
outdir = '.',
/&end
&system
ecutwfc = 100.0,
occupations = 'fixed',
ibrav = 4,
celldm(1) = 5.9000811881,
celldm(3) = 6.7795677253,
nat = 3,
ntyp = 2,
lspinorb = .true.
noncolin = .true.
nbnd = 250
assume_isolated = '2D'
force_symmorphic = .true.
/&end
&electrons
electron_maxstep = 200,
mixing_beta = 0.7,
conv_thr = 1.d-08,
/&end
ATOMIC_SPECIES
Mo 95.940 Mo_ONCV_PBE_FR-1.0.upf
S 32.065 S_ONCV_PBE_FR-1.1.upf
ATOMIC_POSITIONS { crystal }
Mo 0.333333333 0.666666667 0.000000000
S 0.666666667 0.333333333 0.073413577
S 0.666666667 0.333333333 -0.073413577
K_POINTS { automatic }
6 6 1 0 0 0

Again, we run the calculation

mpirun -np 4 pw.x -inp mos2.nscf > nscf.out

== Step 3: dvscf phonon calculation ==

Now we run the phonon calculation.

Copy the <code>save</code> directory from the '''scf''' calculation and run <code>ph.x</code> for a dvscf calculation with a standard <code>q</code>-grid matching the <code>k</code>-grid we wanna use in Yambo.

At the end, we will have the <code>_ph0</code> directory containing the variation of the self-consistent potential, <math>\Delta V_{SCF}(q)</math>, and the <code>*.dyn</code> files with the phonon energies and eigenvectors.

NB: one could further refine the phonon energies by enforcing the acoustic sum rule, including non-analytic long-range contributions, interpolating to finer grids... all of this can be done within Quantum ESPRESSO and will not be covered in this version of the tutorial.

The input is <code>mos2.dvscf</code>:

mos2_dvscf
&inputph
tr2_ph=1.0d-12,
verbosity='high'
prefix='mos2',
fildvscf = 'mos2-dvscf',
electron_phonon = 'dvscf',
fildyn='mos2.dyn',
epsil=.false.,
ldisp=.true.,
recover=.true.,
nq1=6,
nq2=6,
nq3=1
/

And now we run as

nohup mpirun -np 8 ph.x -inp mos2.dvscf > dvscf.out &

This time we use nohup and more processes because this calculation may take some time. It is a good idea to set <code>recover=.true.</code> as in a real calculation you will easily breach walltime, and in this way you can safely restart.

== Step 4: create Yambo <code>SAVE</code> directory ==

This is just the standard Yambo initialization: run

p2y

and then

yambo

in the '''nscf''' <code>save</code> folder and then move the newly generated <code>SAVE</code> directory to a convenient place.

== Step 5: run a BSE calculation ==

Now we switch from QE to Yambo. Here, we forgo the GW step for simplicity (we can use a scissor operator to open the band gap).

This calculation has a couple of differences with respect to a standard BSE calculation for optical absorption. We can look at the input file <code>bse.in</code>:

# Runlevels
optics # [R OPT] Optics
rim_cut # [R RIM CUT] Coulomb potential
bss # [R BSS] Bethe Salpeter Equation solver
em1s # [R Xs] Static Inverse Dielectric Matrix
bse # [R BSE] Bethe Salpeter Equation.
bsk # [R BSK] Bethe Salpeter Equation kernel
# RIM and cutoff settings
RandQpts=1000000 # [RIM] Number of random q-points in the BZ
RandGvec= 100 RL # [RIM] Coulomb interaction RS components
CUTGeo= "slab z" # [CUT] Coulomb Cutoff geometry: box/cylinder/sphere X/Y/Z/XY..
# Static screening
X_and_IO_CPU= "1 1 4 2 1" # [PARALLEL] CPUs for each role
X_and_IO_ROLEs= "q g k c v" # [PARALLEL] CPUs roles (q,g,k,c,v)
X_and_IO_nCPU_LinAlg_INV=-1 # [PARALLEL] CPUs for Linear Algebra (if -1 it is automatically set)
Chimod= "hartree" # [X] IP/Hartree/ALDA/LRC/BSfxc
% BndsRnXs
1 | 200 | # [Xs] Polarization function bands
%
% LongDrXs
1.000000 | 1.000000 | 1.000000 | # [Xs] [cc] Electric Field
%
NGsBlkXs= 8000 mRy # [Xs] Response block size
# BSE
BS_CPU= "4.1.2" # [PARALLEL] CPUs for each role
BS_ROLEs= "k.eh.t" # [PARALLEL] CPUs roles (k,eh,t)
BS_nCPU_diago=4 # [PARALLEL] CPUs for matrix diagonalization
BSEmod= "causal" # [BSE] resonant/causal/coupling
BSKmod= "SEX" # [BSE] IP/Hartree/HF/ALDA/SEX/BSfxc
BSSmod= "d" # [BSS] (h)aydock/(d)iagonalization/(s)lepc/(i)nversion/(t)ddft`
BSENGexx= 40000 mRy # [BSK] Exchange components
ALLGexx # [BSS] Force the use use all RL vectors for the exchange part
BSENGBlk= 8000 mRy # [BSK] Screened interaction block size
Lkind="full" #[BSE,X] bar(default)/full/tilde
% KfnQP_E
1.000000 | 1.000000 | 1.000000 | # [EXTQP BSK BSS] E parameters (c/v) eV|adim|adim
%
% BEnRange
0.00000 | 4.00000 | eV # [BSS] Energy range
%
% BDmRange
0.05000 | 0.05000 | eV # [BSS] Damping range
%
BEnSteps= 2000 # [BSS] Energy steps
% BLongDir
1.000000 | 0.000000 | 0.000000 | # [BSS] [cc] Electric Field
%
% BSEQptR
 1 | 7 | # [BSK] Transferred momenta range
%
% BSEBands
25 | 28 | # [BSK] Bands range
%
WRbsWF # [BSS] Write to disk excitonic the FWs

This file was generated using the command: <code> yambo -X s -o b -k sex -y d -r</code> 

First of all, we compute the excitons for all the momenta in the irreducible Brillouin zone for our discrete grid via the <code>BSEQptR</code> variable. This will be a '''finite-momentum''' BSE calculation, analogous to the phonon one.

Second, we change the variable <code>Lkind</code> from <code>bar</code> to <code>full</code>. In Yambo, <code>Lkind="bar"</code>, which is the default for optical absorption, means that we are computing the excitonic response function without the long-range component of the exchange interaction. This cannot be used when computing the exciton momentum dependence, where the long-range exchange interaction can play a role, therefore we have to include it with <code>Lkind="full"</code>. This allows for the calculation of the excitonic longitudinal-transverse splitting (in 3D systems) as well.

We can now run the code:

nohup mpirun -np 8 yambo -F bse.in -J bse_Lfull -C bse_Lfull &

At the end of the calculation, we have obtained the <code>ndb.BS_diago_Q*</code> databases inside the directory <code>bse_Lfull</code>. They contain information on the exciton energies and wavefunctions at each momentum. Do not forget to check the report and logs of your calculation in the same directory to make sure that the code is doing what you want.

== Step 6: obtain the electron-phonon matrix elements ==

We have finished the heavy simulations. Now it's time for the postprocessing. The first order of business is the reconstruction of the electron-phonon coupling matrix elements from the dvscf results and the electronic wavefunctions.

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

We run in the same directory where the Yambo <code>SAVE</code> 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>n_i</math> to <math>n_f</math>, we should type:

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

Here <math>n_i</math> and <math>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>[n_i,n_f]</math> including the extrema of the interval.

These should coincide with those used for the Bethe-Salpeter kernel, i.e. those specified in the <code>BSEBands</code> variable of the BSE input file (this is not strictly necessary, but certainly efficient since these calculations use a lot of disk space).

For our system, we want to do a parallel calculation with 4 qpools and 2 kpools. In addition, we want to explicitly specify the path of the <code>lelphc</code> executable and avoid automatically deleting the LetzElPhC data. So we type:

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

At the end, check your directory: you should find the <code>lelphc.in</code> 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 <code>convention=yambo</code>: 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>n</math> and momentum <math>k-q</math> to band <math>m</math> and momentum <math>k</math>. In the "forward" momentum transfer convention (the more standard one), the transitions go from <math>nk</math> to <math>mk+q</math>. Therefore, this variable ensures that the electron-phonon coupling matrix elements are computed as <math>\langle mk|dV|nk-q\rangle</math>. This will have consequences also in the formulation of the ''exciton''-phonon coupling matrix element.

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

In addition, if you check the <code>SAVE</code> folder:

ls SAVE/ndb.elph_gkkp*

you will see that yambopy has created the Yambo-compatible electron-phonon databases.

If you want to run LetzElPhC directly, without using yambopy, you can refer to its [[https://gitlab.com/lumen-code/LetzElPhC/-/blob/main/docs/main.pdf?ref_type=heads|user guide]].
Keep in mind that in this case, in order to convert the database to the <code>ndb.elph_gkkp*</code> databases of Yambo, you will then need a couple of lines of python using the Yambopy class <code>ConvertElectronPhononDB</code> in <code>yambopy/letzelph_interface/lelph2y.py</code>.

If you don't need the <code>ndb.elph_gkkp*</code> databases -- e.g., because you are doing the exc-ph postprocessing with yambopy -- you can run <code>yambopy l2y ...</code> with the <code>--no_gkkp</code> option.

If you don't need the <code>ndb.elph</code> databases -- e.g., because you are using <code>yambo_ph</code> for the exc-ph part -- you can run <code>yambopy l2y ...</code> with the <code>--no_lelphc_dbs</code> option.

== Step 7: Obtain the exciton-phonon coupling ==

Now, we can finally access our basic building block for exciton-phonon physics. This could be done entirely in python (using '''Yambopy'''), or by running '''Yambo'''.

* For the '''Yambo postprocessing''' case (running yambo inputs with the <code>yambo_ph</code> executable), '''follow the alternative route to Steps 7-8 [[Exciton-phonon coupling and luminescence - Yambo postprocessing|at this link]]'''.
* For the '''Yambopy postprocessing''' case (using flexible python scripting), '''keep following Steps 7-8 on this page'''.

Our objective is obtaining the following quantity:

<math>\mathcal{G}^\mu_{\alpha\lambda}(0,q)=\sum_{vv^\prime c k} A^{\alpha, *}_{cv^\prime} (k, q) g_{vv^\prime}^\mu (k,q) A^{\lambda}_{cv}(k,0) - \sum_{cc^\prime vk} A^{\alpha, *}_{c^\prime v} (k+q, q) g_{c^\prime c}^\mu (k+q,q) A^{\lambda}_{cv}(k, 0)</math>

Here, <math>A^{\alpha}_{cv}(k,q)</math> are the exciton coefficients extracted from the eigenvector of the two-particles Hamiltonian during the BSE calculation in step 5, while <math>g_{nm}^\mu (k,q)</math> are the electron-phonon coupling matrix elements obtained in step 6. As you can see, the exciton <math>\lambda</math> undergoes phonon-mediated scattering to state <math>\alpha</math> via phonon mode <math>\mu</math>. The scattering can happen for the hole (valence, <math>v</math>) or for the electron (conduction, <math>c</math>).

NB:

(1) This is written in the "backward" momentum transfer convention used by Yambo. The momentum dependence is different in the "forward" transfer convention.

(2) For simplicity, this is written for zero initial exciton momentum. This means that one of the two states involved in the phonon-mediated scattering process will be in the optical limit (and possibly an optically generated exciton), while the other state can have any momentum: this momentum will be the same as the phonon one. This matrix element can be used to describe phonon-assisted absorption and emission spectra.

In order to calculate this quantity using python, we need the <code>ndb.elph</code> databases natively generated by the <code>LetzElPhC</code> code, as well as the BSE databases <code>ndb.BS_diago_Q*</code> containing the information on exciton wavefunctions and energies.

Next, we write a python user script importing the yambopy exciton-phonon tools. You can find a version of this script in <code>yambopy/tutorials/exciton-phonon/calculate_excph.py</code>.

import numpy as np
from yambopy import YamboLatticeDB,YamboWFDB,LetzElphElectronPhononDB #Specific Yambopy dbs loading classes
from yambopy.exciton_phonon.excph_matrix_elements import exciton_phonon_matelem #Specific exc-ph functions

path = '1L_MoS2'
bands_range=[24,28] # 2 valence bands, 2 conduction bands
nexc = 12 # number of excitonic states

bsepath = f'{path}/bse-allq_full' # Path to BSE calculation (Lin=Lout)
savepath = f'{path}/SAVE' # Yambo SAVE
ndb_elph = f'{path}/ndb.elph' # LetzElPhC electron-phonon database (any convention)

# Read lattice
lattice = YamboLatticeDB.from_db_file(filename=f'{savepath}/ns.db1')
# Read electron-phonon
elph = LetzElphElectronPhononDB(ndb_elph,read_all=False)
# Read wave functions
wfcs = YamboWFDB(filename='ns.wf',save=savepath,latdb=lattice,bands_range=bands_range)
# Calculate exciton-phonon matrix elements
exph = exciton_phonon_matelem(lattice,elph,wfcs,BSE_dir=bsepath,nexc_in=nexc,nexc_out=nexc,dmat_mode='save',exph_file='MoS2_Ex-ph.npy')

In this script, we can select the number exciton states <math>\lambda</math> with <code>nexc</code>, the single-particle bands range with <code>bands_range</code>. '''Please note''': in this case, the band index starts from 0 (python indexing) and the the interval of bands read by the code is <math>[n_i,n_f)</math>, therefore the last value (28 in the example) is excluded. That is, in the example we are selecting the 25th, 26th, 27th and 28th bands. Those bands have to be present in both the electron-phonon and BSE calculations.

Here we calculate the couplings of the first twelve states at each finite-<math>q</math> point including <math>q=0</math>. We also include all the nine phonon modes of monolayer MoS2. We also need access to the Yambo <code>SAVE</code> directory in order to read the electronic wavefunctions: they are used to compute the electronic representation matrices (<code>dmat</code> in the code). The argument <code>dmat_mode</code> can be set to <code>'load'</code> for subsequent calculations.

When we are satisfied with the input, we run the code:

python calculate_excph.py

If you check the output, you should find the <code>MoS2_Ex-ph.npy</code> binary file in the directory where you ran.

=== Analysis of the couplings ===

It is a good idea to have a look at what we computed up to now in order to make sure nothing has gone wrong.

It is not easy to know what to expect (apart from symmetry and gauge compliance of the matrix elements), but one can work out the exciton-phonon selection rules in advance, check that the magnitude is reasonable, etc.

It is also not easy to meaningfully plot this quantity. We have to make sure that we are not breaking degenerate states, otherwise the plots will not be invariant.

First of all, we have to know our system: in monolayer MoS2, the first four excitons are all doubly degenerate. The first exciton responsible for a bright peak in the absorption spectrum (the '''A''' peak), is the second state, corresponding to state indices <code>(3,4)</code> in fortran indexing or <code>(2,3)</code> in python indexing.

All these information can be obtained by analyzing the BSE results (this stuff is explained in the BSE tutorials) and by knowledge of the system or class of systems from the literature.

Thus, a good quantity to plot may be the norm of the matrix elements, summed over the degenerate subspace of exciton A, for a certain number of scattered final states mediated by certain phonon modes:

<math>F_A(q)= \sqrt{ \sum_{\alpha \in A,\lambda,\mu} |\mathcal{G}_{\alpha\lambda}^\mu (0,q)|^2 }</math>

In order to do this, we create a python script <code>analyse_excph.py</code> in which we first load the excph dabatases.
You can find a version of this script in the yambopy directory, in <code>tutorials/exciton-phonon</code>.
First, we select the exciton and phonon states to be included in <code>F_A</code>, together with the path of databases and plot details:

# Exciton "in" states
exc_in = [2,3] # First bright peak (A: 2,3 -- B: 6,7)
exc_out = [0,1,2,3] # first 4 states (dispersion of dark triplet state and A)
ph_in = 'all'
# Paths of databases
ns_db1 =f'{path}/SAVE/ns.db1'
ns_ypy = 'MoS2_Ex-ph.npy'

...

Then, we load the data:

# Read lattice and k-space info
ylat = YamboLatticeDB.from_db_file(filename=ns_db1)
print(ylat)

# Load exc-ph database
X_py = np.load(ns_ypy)
G_squared = np.abs(X_py)**2.

The quantity <math>F_A(q)</math> is obtained from a dedicated function as:

if exc_in == 'all': exc_in = range(G_squared.shape[2])
if exc_out == 'all': exc_out = range(G_squared.shape[3])
if ph_in == 'all': ph_in = range(G_squared.shape[1])

G_squared = G_squared[:, ph_in, :, :].sum(axis=(1))
G_squared = G_squared[:, exc_in, :].sum(axis=(1))
G_squared = G_squared[:, exc_out].sum(axis=(1))

F_q = np.sqrt( G_squared )*ha2ev # Switch from Ha to eV

And finally, we have to make a plotting function. For this tutorial we will use a custom scatterplot employing some of the plotting tools provided by yambopy (but you can do whatever you want).

plot_2D_excph(qgrid,G2_to_plot,rlat=ylat.rlat,plt_cbar=True,\
marker='H',s=700,cmap='magma')
...

You can get more experience on using Yambopy for these kinds of visualization by following the [https://wiki.yambo-code.eu/wiki/index.php?title=First_steps_in_Yambopy Yambopy tutorials]. In fact, remember that these scripts and all the other Yambopy tutorial scripts are just suggestions, not source code written in stone: if you know <code>numpy</code> and <code>matplotlib</code> you can do your own analysis and your own plots, you just need to import the required Yambopy modules to load the data.

In our case, the resulting plot is the following.

[[File:1L MoS2 MoS2 Ex-ph.png|500px|center]]

This can be checked against Fig. 2(d) of reference <ref name="chan2023" />, although you have to keep in mind that our results are badly undersampled in terms of the reciprocal-space grid, as can be easily seen, and the quantity plotted is not exactly the same. However, the main features are already there since they are dictated mostly by crystal symmetries.

Now that we have the exciton-phonon matrix elements, we can use them to build several kinds of observables. Below, we give an example related to phonon-assisted luminescence, but we may update this tutorial in the future to include more cases.

== Step 8: Compute phonon-assisted luminescence ==

[[File:Luminescence scheme.png|250px|right]]

We want to compute the experimental optical signature due to the phonon-assisted recombination of an exciton (as sketched in the figure).

The signal from the phonon replicas can be modeled as a second-order scattering process involving one phonon and one photon:

<math>I^{Sat}(\omega)=\frac{1}{ N_q} \frac{1}{3} \sum_{\epsilon s\beta \mu q} \frac{1}{E_{\beta q}-s\Omega_{\mu q}}\left|\sum_\alpha\frac{ D^{\epsilon}_\alpha \mathcal{G}_{\beta \alpha}^{\mu,*}(q)}{E_\alpha -E_{\beta q} +s\Omega_{\mu q}+\mathrm{i}\eta}\right|^2 \frac{N^{exc}_{\beta q}(T_{exc})[\frac{1+s}{2}+n_{\mu q}(T)]}{\omega -[E_{\beta q}-s\Omega_{\mu q}]+\mathrm{i}\eta}</math>

In this equation, the oscillator strength of the peak is given by the exciton-phonon coupling matrix elements <math>\mathcal{G}</math> multiplied by the exciton dipoles <math>D</math> (they are called "residuals" in Yambo). Here <math>E_\lambda</math> and <math>E_{\alpha q}</math> are the energies of the optical and finite-momentum excitons, respectively, while <math>\Omega_{\mu q}</math> are the phonon energies.

Here, <math>n_{\mu q}(T)</math> is the temperature-dependent phonon Bose-Einstein occupation function. As it can be seen, <math>s=1</math> corresponds to processes of phonon ''emission'' (<math>\propto n(T)+1</math>), while <math>s=-1</math> corresponds to processes of phonon ''absorption'' (<math>\propto n(T)</math>). Therefore, <math>I^{Sat}_{PL}(\omega;T)</math> describes ''light'' emission by recombining excitons mediated by either ''phonon'' absorption or emission.

The quantity <math> N_{\alpha q}(T_{exc})</math> is the exciton occupation function. Luminescence is technically an out-of-equilibrium process, but we can assume that for very low density of excitations and in steady-state conditions, the exciton population can be approximately described by an equilibrium distribution evaluated at an effective temperature. Here, we use the Boltzmann distribution. Experimentally, <math>T_{exc}</math> tends to coincide with the lattice temperature <math>T</math> more or less above 100 K, while at very low temperature (< 10 K), <math>T_{exc}</math> may vary between 10-50 K. It goes without saying that this needs to carefully be checked in your realistic calculations.

Finally, the spectrum is averaged over the polarization directions of the emitted photons (<math>\epsilon=x,y,z</math> representing the respective dipole components).

=== Running the jobs ===

In order to study luminescence in a paradigmatic system, we switch to bulk hexagonal boron nitride and we repeat the workflow. As you can easily see, one can think about automatizing the execution of all these calculations via scripting or more advanced tools. However, in the case of very large simulations (memory-limited or disk-space limited) or for systems whose electronic and lattice properties are fragile with respect to tiny calculation details, one must be very careful and run many basic tests.

Fortunately, we are running a fast underconverged example. We use LDA pseudopotentials from the pseudo-dojo library and the following are the calculations steps.

1. Input <code>hbn.scf</code>:

&control
calculation='scf',
prefix='hBN',
restart_mode='from_scratch'
pseudo_dir = '$PSEUDO_DIR',
outdir = './tmp'
verbosity = 'high'
wf_collect=.true.
/
&system
ibrav = 4,
celldm(1) = 4.703675849
celldm(3) = 2.603711434
nat= 4,
ntyp= 2,
force_symmorphic=.true.
ecutwfc = 100,
/
&electrons
diago_david_ndim = 2
diago_full_acc=.true.
diago_thr_init=5.0e-6
mixing_mode = 'plain'
mixing_beta = 0.7
conv_thr = 1.0d-16
/
ATOMIC_SPECIES
B 10.81100 B_LDA_dojo.UPF
N 14.00674 N_LDA_dojo.UPF
ATOMIC_POSITIONS {crystal}
N 0.6666666670 0.3333333330 -0.250000000000
B 0.3333333330 0.6666666670 -0.250000000000
B 0.6666666670 0.3333333330 0.25000000000
N 0.3333333330 0.6666666670 0.25000000000
K_POINTS {automatic}
6 6 2 0 0 0

mpirun -np 4 pw.x -inp hbn.scf > scf.out

2. Input <code>hbn.nscf</code>:

&control
calculation='nscf',
prefix='hBN',
restart_mode='from_scratch'
pseudo_dir = '$PSEUDO_DIR'
outdir = './'
verbosity = 'high'
wf_collect=.true.
/
&system
ibrav = 4,
celldm(1) = 4.703675849
celldm(3) = 2.603711434
nat= 4,
ntyp= 2,
force_symmorphic=.true.
ecutwfc = 100,
nbnd = 120
/
&electrons
diago_david_ndim = 2
diago_full_acc=.true.
diago_thr_init=5.0e-6
mixing_mode = 'plain'
mixing_beta = 0.7
conv_thr = 1.0d-16
/
ATOMIC_SPECIES
B 10.81100 B_LDA_dojo.UPF
N 14.00674 N_LDA_dojo.UPF
ATOMIC_POSITIONS {crystal}
N 0.6666666670 0.3333333330 -0.250000000000
B 0.3333333330 0.6666666670 -0.250000000000
B 0.6666666670 0.3333333330 0.25000000000
N 0.3333333330 0.6666666670 0.25000000000
K_POINTS {automatic}
6 6 2 0 0 0

mpirun -np 4 pw.x -inp hbn.nscf > nscf.out

3. Input <code>hbn.dvscf</code>:

hbn_dvscf
&inputph
tr2_ph=1.0d-12,
verbosity='high'
prefix='hBN',
fildvscf = 'hBN-dvscf',
electron_phonon = 'dvscf',
fildyn='hBN.dyn',
epsil=.false.,
ldisp=.true.,
recover=.true.,
nq1=6,
nq2=6,
nq3=2
/

nohup mpirun -np 8 pw.x -inp hbn.dvscf > dvscf.out &

4. Input <code>bse.in</code> (we include 2 valence and 2 conduction bands):

optics # [R] Linear Response optical properties
bss # [R] BSE solver
bse # [R][BSE] Bethe Salpeter Equation.
dipoles # [R] Oscillator strenghts (or dipoles)
em1s
DIP_CPU= "1 8 1" # [PARALLEL] CPUs for each role
DIP_ROLEs= "k c v" # [PARALLEL] CPUs roles (k,c,v)
DIP_Threads=0 # [OPENMP/X] Number of threads for dipoles
X_and_IO_CPU= "1 1 1 8 1" # [PARALLEL] CPUs for each role
X_and_IO_ROLEs= "q g k c v" # [PARALLEL] CPUs roles (q,g,k,c,v)
X_and_IO_nCPU_LinAlg_INV=-1 # [PARALLEL] CPUs for Linear Algebra (if -1 it is automatically set)
X_Threads=0 # [OPENMP/X] Number of threads for response functions
BS_CPU= "8 1 1" # [PARALLEL] CPUs for each role
BS_ROLEs= "k eh t" # [PARALLEL] CPUs roles (k,eh,t)
BS_nCPU_LinAlg_INV=-1 # [PARALLEL] CPUs for Linear Algebra (if -1 it is automatically set)
BS_nCPU_LinAlg_DIAGO=-1 # [PARALLEL] CPUs for Linear Algebra (if -1 it is automatically set)
X_Threads=0 # [OPENMP/X] Number of threads for response functions
K_Threads=0 # [OPENMP/BSK] Number of threads for response functions
% QpntsRXs
1 | 14 | # [Xs] Transferred momenta
%
% BndsRnXs
1 | 120 | # [Xs] Polarization function bands
%
NGsBlkXs= 10 Ry # [Xs] Response block size
% LongDrXs
1.000000 | 1.000000 | 1.000000 | # [Xs] [cc] Electric Field
%
BSEmod= "resonant" # [BSE] resonant/retarded/coupling
BSKmod= "SEX" # [BSE] IP/Hartree/HF/ALDA/SEX/BSfxc
Lkind= "Lfull" # [BSE] Lbar (default) / full
BSSmod= "d" # [BSS] (h)aydock/(d)iagonalization/(s)lepc/(i)nversion/(t)ddft`
% DipBands
1 | 120 | # [DIP] Bands range for dipoles
%
DipApproach= "G-space v" # [DIP] [G-space v/R-space x/Covariant/Shifted grids]
DipComputed= "R V P" # [DIP] [default R P V; extra P2 Spin Orb]
BSENGexx= 30000 Ry # [BSK] Exchange components
#ALLGexx # [BSS] Force the use use all RL vectors for the exchange part
BSENGBlk= 9000 Ry # [BSK] Screened interaction block size [if -1 uses all the G-vectors of W(q,G,Gp)]
% KfnQP_E
1.25997 | 1.08816 | 1.12683 | # [EXTQP BSK BSS] E parameters (c/v) eV|adim|adim
%
% BSEQptR
 1 | 14 | # [BSK] Transferred momenta range
%
% BSEBands
 7 | 10 | # [BSK] Bands range
%
% BEnRange
0.50000 | 8.00000 | eV # [BSS] Energy range
%
% BDmRange
0.050000 | 0.050000 | eV # [BSS] Damping range
%
BEnSteps= 1000 # [BSS] Energy steps
% BLongDir
1.000000 | 1.000000 | 0.000000 | # [BSS] [cc] Electric Field
%
WRbsWF # [BSS] Write to disk excitonic the WFs

nohup mpirun -np 8 yambo -F bse.in -J bse_Lfull -C bse_Lfull &

Importantly, since we want to describe the phonon-assisted recombination process of an *optical* exciton (i.e., emitting a transverse photon), this time we also run an additional calculation at `Q=0` omitting the nonanalytic long-range Coulomb exchange. Make a second input <code>bse_Lbar.in</code> with the following changes:

Lkind= "Lbar" # [BSE] Lbar (default) / full
% BSEQptR
 1 | 1 | # [BSK] Transferred momenta range
%

4b. So now we make a second BSE run in a different directory specified by <code>-J</code>. Here, we also pass to yambo the directory of the previous run as it includes the important screening databases <code>ndb.em1s*</code> that we do not want to recompute from scratch.

mpirun -np 8 yambo -F bse_Lbar.in -J bse_Lbar,bse_Lfull -C bse_Lbar

5. Now we run <code>lelphc</code> (with or without yambopy: in the latter case remember the option <code>-D</code>) to get the el-ph matrix elements, particularly the <code>ndb.elph</code> databases:

yambopy l2y -ph path/of/dvscf/hbn.dvscf -b 7 10 -par 4 2 -D

=== Luminescence calculation ===

6. And finally we calculate exciton-phonon matrix elements and the luminescence spectrum in one go using a python script importing the Yambopy exciton-phonon tools: in order to do this, we need to take a look at all the necessary input variables for the formula written above.

We can start from the script <code>luminescence.py</code> available in <code>tutorials/exciton-phonon</code>.

import numpy as np
import matplotlib.pyplot as plt
from yambopy.exciton_phonon.excph_luminescence import exc_ph_luminescence
from yambopy.exciton_phonon.excph_input_data import exc_ph_get_inputs

We import the necessary tools...

path = '3D_hBN'
# Path to BSE calculation (Lout--> response is Lfull)
bsepath = f'{path}/bse_Lfull' # ndb.BS_diago_Q* databases are needed
# Path to BSE calculation for optically active exciton (Lin --> response is Lbar)
bseBARpath = f'{path}/bse_Lbar' # ndb.BS_diago_Q1 database is needed
# Path to electron-phonon calculation
elphpath = path # ndb.elph is needed
# Path to unprojected dipoles matrix elements (optional)
dipolespath = bsepath # ndb.dipoles is needed (optional)
# Path to lattice and k-space info
savepath = f'{path}/SAVE' # ns.db1 database is needed

... and we specify the paths to the necessary databases. Note that, if we want to perform polarization averaging, we have to recompute the excitonic dipoles in python as seen here.

What about <code>bseBARpath</code>? This variable points to the directory where the databases for the optical (zero-momentum) excitons <math>\alpha</math> (which may be computed with <code>Lkind='Lbar'</code>) is located, which can be different from the directory with the full indirect exciton dispersion <math>\beta</math> (usually computed with <code>Lkind='Lfull'</code>, however <code>Lkind='Ltilde'</code> can also be used if one is interested in "irreducible" excitons). This makes it possible to compute the coupling between different exciton kinds.

bands_range=[6,10] # 2 valence, 2 conduction bands
phonons_range=[0,12] # All phonons
nexc_out = 12 # 12 excitonic states at each momentum (Lout)
nexc_in = 12 # 12 excitonic states at Q=0 (Lin)
T_ph = 10 # Lattice temperature
T_exc = 10 # Effective excitonic temperature

emin=4.4 # Energy range and plot details (in eV)
emax=4.7
estep=0.0002
broad = 0.005 # Broadening parameter for peak width (in eV)

Next, we specify the parameters for the calculation. We include valence bands from 7 to 10 (6 to 9 in python index) and the contribution of all 12 phonon modes. We consider 12 excitonic states for the coupling matrix elements.

Here <code>T_ph</code> and <code>T_exc</code> are the lattice and excitonic temperatures, respectively.

# We calculate and load all the inputs:
# * Exciton-phonon matrix elements
# * Excitonic dipole matrix elements
# * Exciton energies
# * Phonon energies
# * We specify bse_path2=bseBARpath meaning we use Lbar calculation for Q=0 excitons
input_data = exc_ph_get_inputs(savepath,elphpath,bsepath,\
bse_path2=bseBARpath,dipoles_path=dipolespath,\
nexc_in=12,nexc_out=12,\
bands_range=[6,10],phonons_range=[0,12])

ph_energies, exc_energies, exc_energies_in, G, exc_dipoles = input_data

The function <code>exc_ph_get_inputs</code> gives us all the input data for luminescence in the correct format: phonon energies, exciton energies, optical exciton energies (if needed), exciton-phonon matrix elements (calculated on the fly and printed to file), unprojected exciton dipoles (optional, calculated on the fly and printed to file).
The exc-ph matrix element calculation is just a wrapper of the same tools that we have tested in the above section on MoS2.

Finally, there is the calculation of the luminescence spectrum via the function <code>exc_ph_luminescence</code>:
# We calculate the luminescence spectrum including the input data from before
w,PL = exc_ph_luminescence(T_ph,ph_energies,exc_energies,exc_dipoles,G,\
exc_energies_in=exc_energies_in,exc_temp=T_exc,\
nexc_out=nexc_out,nexc_in=nexc_in,emin=emin,emax=emax,\
estep=estep,broad=broad)

If you want to print the luminescence data for later plotting, you can also add the following line to the script:
# Save to file
data = np.column_stack((w, PL))
np.savetxt("hBN_luminescence_12x12x1.dat", data, fmt="%.8f")

It is now time to run the whole script:

python luminescence.py

NB: By using Yambopy for Step 6, we have limited the use of the Yambo code to just step 4 in the entire workflow. This option is more flexible, as it allows for a greater degree of control by the user. On the other hand the Yambo postprocessing route features a Yambo-style input that doesn't require python knowledge and the calculation is currently faster in fortran. However, the luminescence expression computed in Yambo is a slightly different than this one: it is more approximated in the description of the satellite oscillator strengths, but it explicitly includes the renormalization of the direct exciton peak. You can check the differences [[Exciton-phonon coupling and luminescence - Yambo postprocessing|here]].

=== Results ===
We can plot the results of the step 6 calculation. If we do it in the same script we can add something like this:
fig = plt.figure()
ax = fig.add_subplot(1,1,1)
ax.set_xlim(emin,emax)
ax.set_ylim(0,np.max(PL)*1.1)
ax.get_yaxis().set_visible(False)

ax.plot(w, PL, '-',c='red', label="AA' hBN luminescence")

plt.legend()
plt.savefig('hBN_luminescence.png')
plt.show()

[[File:HBN luminescence satellites.png|500px|center]]

Here, the signal corresponds to a finite-momentum exciton that recombines with the help of several different phonon modes, both optical and acoustic. Each phonon mode whose coupling with the exciton is allowed can generate a peak, and the energy shifts of these peaks with respect to the initial exciton energy correspond to the phonon energies. This result is underconverged, but the main features are all there. In the plot, we show a more converged example using a 12x12x4 grid (all the other parameters being equal). These plots can be compared with Fig. 4(a) of reference <ref name="zanfrognini2023" />.

== References ==

<references>
<ref name="toyozawa2003" >Toyozawa, Yutaka, and Chris Oxlade, ''Optical processes in solids'', [https://m.booksee.org/book/1121964?force_lang=en Cambridge University Press, (2003)]. </ref>
<ref name='lechifflart2023'>P. Lechifflart, F. Paleari, D. Sangalli, C. Attaccalite, ''First-principles study of luminescence in hexagonal boron nitride single layer: Exciton-phonon coupling and the role of substrate'',
[https://doi.org/10.1103/PhysRevMaterials.7.024006 Phys. Rev. M, '''7''' (2), 024006 (2023)]; [https://arxiv.org/abs/2212.10407 arXiv2212.1047]</ref>
<ref name='cannuccia2019'>E. Cannuccia, B. Monserrat and C. Attaccalite, ''Theory of phonon-assisted luminescence in solids: Application to hexagonal boron nitride'', [https://doi.org/10.1103/PhysRevB.99.081109 Phys. Rev. B '''99''', 081109(R) (2019)]; [https://arxiv.org/abs/1807.11797 arXiv1807.11797]</ref>
<ref name='paleari2019'>F. Paleari et al., ''Exciton-Phonon Coupling in the Ultraviolet Absorption and Emission Spectra of Bulk Hexagonal Boron Nitride'', [https://doi.org/10.1103/PhysRevLett.122.187401 Phys. Rev. Lett. '''122''', 187401 (2019)]; [https://arxiv.org/abs/1810.08976 arXiv1810.089776] </ref>
<ref name='chen2020'>''Exciton-Phonon Interaction and Relaxation Times from First Principles'',
Hsiao-Yi Chen, Davide Sangalli, and Marco Bernardi, [https://doi.org/10.1103/PhysRevLett.125.107401 Phys. Rev. Lett. '''125''', 107401 (2020)]; [https://arxiv.org/abs/2002.08913 arXiv 2002.08913 (2020)]</ref>
<ref name="lechifflart2023_PhD">P. Lechifflart, ''Exciton-phonon coupling and phonon-assisted luminescence in hexagonal Boron Nitride nanostructures'', [https://hal.science/tel-04266805v1 PhD Thesis, University of Marseille (2023)]; [https://www.yambo-code.eu/wiki/images/5/54/These_final.pdf From the yambo website]</ref>
<ref name='paleari2019_PhD'>F. Paleari, ''First-principles approaches to the description of indirect absorption and luminescence spectroscopy: exciton-phonon coupling in hexagonal boron nitride'', [https://wwwen.uni.lu/research/fstm/dphyms/people/fulvio_paleari PhD thesis, University of Luxembourg (2019)]</ref>
<ref name='zanfrognini2023'>M. Zanfrognini et al., ''Distinguishing different stackings in layered materials via luminescence spectroscopy'', [https://doi.org/10.1103/PhysRevLett.131.206902 Phys. Rev. Lett. '''131''', 206902 (2023)]; [https://arxiv.org/abs/2305.17554 arXiv 2305.17554] </ref>
<ref name='marini2024'>G. Marini, M. Calandra, P. Cudazzo, ''Optical absorption and photoluminescence of single layer boron nitride from a first principles cumulant approach'', [https://doi.org/10.1021/acs.nanolett.4c00669 Nano Lett., '''24''', 20, 6017 (2024)]; [https://arxiv.org/abs/2402.03826 arXiv 2402.03826 (2024)]</ref>
<ref name='antonius2017'>G. Antonius, S. G. Louie, ''Theory of exciton-phonon coupling'', [https://doi.org/10.1103/PhysRevB.105.085111 Phys. Rev. B, '''105''', 085111 (2022)]; [https://arxiv.org/abs/1705.04245 arXiv1705.04245 (2017)]</ref>
<ref name='paleari2022'> F. Paleari, and A. Marini, ''Exciton-phonon interaction calls for a revision of the “exciton” concept'', [https://doi.org/10.1103/PhysRevB.106.125403 Phys. Rev. B, '''106''', 125403 (2022)]; [https://arxiv.org/abs/2205.02783 arXiv 2205.02783]</ref>
<ref name='cudazzo2020'> P. Cudazzo, ''First-principles description of the exciton-phonon interaction: A cumulant approach'', [https://doi.org/10.1103/PhysRevB.102.045136 Phys. Rev. B, '''102''', 045136 (2020)]; [https://orbilu.uni.lu/bitstream/10993/44769/1/main.pdf Open access pdf from Luxembourg University]</ref>
<ref name='chan2023'>Y-h Chan, J. B. Haber, M. H. Naik, J. B. Neaton, D. Y. Qiu, F. H. da Jornada, S. G. Louie, ''Exciton Lifetime and Optical Line Width Profile via Exciton–Phonon Interactions: Theory and First-Principles Calculations for Monolayer MoS2'', [https://doi.org/10.1021/acs.nanolett.3c00732 Nano Lett., '''23''', 9 (2023)]; [https://arxiv.org/abs/2212.08451 arXiv 2212.08451 (2023)]</ref>
<ref name='murali2025'>M. Nalabothula, S. Reichardt, L. Wirtz, ''Origin of Interlayer Exciton–Phonon Coupling in 2D Heterostructures'', [https://doi.org/10.1021/acs.nanolett.5c00355 Nano Lett., '''25''', 15 (2025)], [https://arxiv.org/abs/2407.16111 arXiv 2407.16111 (2025)]</ref>
</references>

Exciton-phonon coupling and luminescence

2026-03-13T14:40:58Z

FulvioPaleari: /* Requirements */

[[File:Tdgw-phonon-usc-01-1024x829.jpg| 400px | right]]

In this advanced tutorial, we will calculate exciton-phonon interactions from first principles by interfacing DFPT (for phonon calculations) and BSE (for exciton calculations).

The DFTP calculations are run with Quantum ESPRESSO, while the many-body GW-BSE calculations are run with Yambo. Finally, the exciton-phonon interaction will be obtained by combining and postprocessing the databases computed in the two previous runs. The great advantage of this workflow is that the calculations can be run in the irreducible Brillouin zones both for the electronic momenta ('''k''') and the transfer momenta ('''Q''', '''q''') of excitons and phonons, thus speeding up considerably the jobs while reducing the IO and memory load.

We will first compute the exciton-phonon coupling matrix elements: these are the building blocks needed to construct experimental observables such as phonon-assisted optical spectra (such as luminescence), Raman spectra and exciton lifetimes. We will do this in the case of monolayer MoS2, a 2D system with large spin-orbit interaction.

As an example of application, we will consider the case of phonon-assisted luminescence. We will do this in the case of bulk hBN, a layered indirect insulator with strong electron-phonon coupling.

'''Note:''' this tutorial will be updated when new exc-ph tools become available in Yambopy (including full-python postprocessing, Raman spectra, interpolated lifetimes, etc).

== Requirements ==

This is an advanced topic: we assume that you already know something about the theory<ref name="toyozawa2003" /><ref name="antonius2017" /><ref name="cudazzo2020" /><ref name="paleari2019_PhD" /><ref name="paleari2022" /><ref name="lechifflart2023_PhD" /> and applications<ref name="paleari2019" /><ref name="cannuccia2019" /><ref name="chen2020" /><ref name="zanfrognini2023" /><ref name="lechifflart2023" /><ref name="chan2023" /><ref name="marini2024" /><ref name="murali2025" /> of exciton-phonon physics.

Also, we assume that you already know how to run both a basic '''Yambo''' GW-BSE calculation and a DFPT phonon calculation with '''Quantum ESPRESSO'''.

Besides the QE executables <code>pw.x</code> and <code>ph.x</code>, we also use the yambo phonon-specific executable <code>yambo_ph</code> and the python utility '''Yambopy'''. The auxiliary code '''LetzElPhC''' (executable <code>lelphc</code>) will be used to obtain the electron-phonon matrix elements by reading the same electronic wavefunctions used by Yambo (and stored in the <code>SAVE</code> directory), while also making full use of crystal symmetries. [https://github.com/yambo-code/LetzElPhC LetzElPhC] will be run by Yambopy, but it must nonetheless be installed. Finally, the exciton-phonon properties can be computed either using <code>yambo_ph</code> or using Yambopy itself. Both cases will be covered in this tutorial.

[[File:Workflow scheme.png|800px|center]]

== Step 0: Pseudopotentials, equilibrium structure and convergence ==

In a real calculation, it is important to ensure that both the pseudopotential and the lattice parameters that we are using are compatible and perform well for the electronic excited states and for the lattice vibrations simultaneously. Furthermore, you have to make sure that the wave function cutoff <code>ecutwfc</code> is converged with respect to the DFPT step and not just to the DFT one. This is in addition to the other customary convergence tests for DFT, DFPT, GW and BSE calculations.

This is often the most time-demanding step when starting on a new system.

For the sake of this tutorial, we assume that we have already done all these tests and we are starting the final workflow to get the exciton-phonon properties.

== Step 1: scf calculation ==

First of all, we run a standard scf calculation with <code>pw.x</code> for Yambo. We stick with non-symmorphic symmetries. At the end, we will have the QE <code>save</code> directory.

This is the input <code>mos2.scf</code>:

&control
wf_collect = .true.,
calculation = "scf",
verbosity = 'high',
pseudo_dir = '$PSEUDO_DIR',
prefix = "mos2",
outdir = '.',
/&end
&system
ecutwfc = 100.0,
occupations = 'fixed',
ibrav = 4,
celldm(1) = 5.9000811881,
celldm(3) = 6.7795677253,
nat = 3,
ntyp = 2,
lspinorb = .true.
noncolin = .true.
assume_isolated = '2D'
force_symmorphic = .true.
/&end
&electrons
electron_maxstep = 200,
mixing_beta = 0.7,
conv_thr = 1.d-08,
/&end
ATOMIC_SPECIES
Mo 95.940 Mo_ONCV_PBE_FR-1.0.upf
S 32.065 S_ONCV_PBE_FR-1.1.upf
ATOMIC_POSITIONS { crystal }
Mo 0.333333333 0.666666667 0.000000000
S 0.666666667 0.333333333 0.073413577
S 0.666666667 0.333333333 -0.073413577
K_POINTS { automatic }
6 6 1 0 0 0

Here we are using full relativistic pseudopotentials from the SG-15 database.

We can run it on our machine (for example using 4 MPI tasks) as:

mpirun -np 4 pw.x -inp mos2.scf > scf.out

== Step 2: nscf calculation for Yambo ==

Copy the QE <code>save</code> directory from the scf calculation and run the nscf calculation for any number of empty states, with the correct <code>k</code>-grid we want to use in Yambo. Here we are using a badly underconverged grid of 6x6x1.

This reciprocal-space grid will also match the momentum transfer <code>q</code> grid on which excitons and phonons will be defined!

The electronic wavefunctions computed at this step and stored in the new nscf <code>save</code> directory will be used both by Yambo and by the electron-phonon code: this is important because using different sets of wavefunctions would lead to a phase mismatch issue in the exciton-phonon matrix elements.

The nscf input <code>mos2.nscf</code> is
&control
wf_collect = .true.,
calculation = "nscf",
verbosity = 'high',
pseudo_dir = '$PSEUDO_DIR',
prefix = "mos2",
outdir = '.',
/&end
&system
ecutwfc = 100.0,
occupations = 'fixed',
ibrav = 4,
celldm(1) = 5.9000811881,
celldm(3) = 6.7795677253,
nat = 3,
ntyp = 2,
lspinorb = .true.
noncolin = .true.
nbnd = 250
assume_isolated = '2D'
force_symmorphic = .true.
/&end
&electrons
electron_maxstep = 200,
mixing_beta = 0.7,
conv_thr = 1.d-08,
/&end
ATOMIC_SPECIES
Mo 95.940 Mo_ONCV_PBE_FR-1.0.upf
S 32.065 S_ONCV_PBE_FR-1.1.upf
ATOMIC_POSITIONS { crystal }
Mo 0.333333333 0.666666667 0.000000000
S 0.666666667 0.333333333 0.073413577
S 0.666666667 0.333333333 -0.073413577
K_POINTS { automatic }
6 6 1 0 0 0

Again, we run the calculation

mpirun -np 4 pw.x -inp mos2.nscf > nscf.out

== Step 3: dvscf phonon calculation ==

Now we run the phonon calculation.

Copy the <code>save</code> directory from the '''scf''' calculation and run <code>ph.x</code> for a dvscf calculation with a standard <code>q</code>-grid matching the <code>k</code>-grid we wanna use in Yambo.

At the end, we will have the <code>_ph0</code> directory containing the variation of the self-consistent potential, <math>\Delta V_{SCF}(q)</math>, and the <code>*.dyn</code> files with the phonon energies and eigenvectors.

NB: one could further refine the phonon energies by enforcing the acoustic sum rule, including non-analytic long-range contributions, interpolating to finer grids... all of this can be done within Quantum ESPRESSO and will not be covered in this version of the tutorial.

The input is <code>mos2.dvscf</code>:

mos2_dvscf
&inputph
tr2_ph=1.0d-12,
verbosity='high'
prefix='mos2',
fildvscf = 'mos2-dvscf',
electron_phonon = 'dvscf',
fildyn='mos2.dyn',
epsil=.false.,
ldisp=.true.,
recover=.true.,
nq1=6,
nq2=6,
nq3=1
/

And now we run as

nohup mpirun -np 8 ph.x -inp mos2.dvscf > dvscf.out &

This time we use nohup and more processes because this calculation may take some time. It is a good idea to set <code>recover=.true.</code> as in a real calculation you will easily breach walltime, and in this way you can safely restart.

== Step 4: create Yambo <code>SAVE</code> directory ==

This is just the standard Yambo initialization: run

p2y

and then

yambo

in the '''nscf''' <code>save</code> folder and then move the newly generated <code>SAVE</code> directory to a convenient place.

== Step 5: run a BSE calculation ==

Now we switch from QE to Yambo. Here, we forgo the GW step for simplicity (we can use a scissor operator to open the band gap).

This calculation has a couple of differences with respect to a standard BSE calculation for optical absorption. We can look at the input file <code>bse.in</code>:

# Runlevels
optics # [R OPT] Optics
rim_cut # [R RIM CUT] Coulomb potential
bss # [R BSS] Bethe Salpeter Equation solver
em1s # [R Xs] Static Inverse Dielectric Matrix
bse # [R BSE] Bethe Salpeter Equation.
bsk # [R BSK] Bethe Salpeter Equation kernel
# RIM and cutoff settings
RandQpts=1000000 # [RIM] Number of random q-points in the BZ
RandGvec= 100 RL # [RIM] Coulomb interaction RS components
CUTGeo= "slab z" # [CUT] Coulomb Cutoff geometry: box/cylinder/sphere X/Y/Z/XY..
# Static screening
X_and_IO_CPU= "1 1 4 2 1" # [PARALLEL] CPUs for each role
X_and_IO_ROLEs= "q g k c v" # [PARALLEL] CPUs roles (q,g,k,c,v)
X_and_IO_nCPU_LinAlg_INV=-1 # [PARALLEL] CPUs for Linear Algebra (if -1 it is automatically set)
Chimod= "hartree" # [X] IP/Hartree/ALDA/LRC/BSfxc
% BndsRnXs
1 | 200 | # [Xs] Polarization function bands
%
% LongDrXs
1.000000 | 1.000000 | 1.000000 | # [Xs] [cc] Electric Field
%
NGsBlkXs= 8000 mRy # [Xs] Response block size
# BSE
BS_CPU= "4.1.2" # [PARALLEL] CPUs for each role
BS_ROLEs= "k.eh.t" # [PARALLEL] CPUs roles (k,eh,t)
BS_nCPU_diago=4 # [PARALLEL] CPUs for matrix diagonalization
BSEmod= "causal" # [BSE] resonant/causal/coupling
BSKmod= "SEX" # [BSE] IP/Hartree/HF/ALDA/SEX/BSfxc
BSSmod= "d" # [BSS] (h)aydock/(d)iagonalization/(s)lepc/(i)nversion/(t)ddft`
BSENGexx= 40000 mRy # [BSK] Exchange components
ALLGexx # [BSS] Force the use use all RL vectors for the exchange part
BSENGBlk= 8000 mRy # [BSK] Screened interaction block size
Lkind="full" #[BSE,X] bar(default)/full/tilde
% KfnQP_E
1.000000 | 1.000000 | 1.000000 | # [EXTQP BSK BSS] E parameters (c/v) eV|adim|adim
%
% BEnRange
0.00000 | 4.00000 | eV # [BSS] Energy range
%
% BDmRange
0.05000 | 0.05000 | eV # [BSS] Damping range
%
BEnSteps= 2000 # [BSS] Energy steps
% BLongDir
1.000000 | 0.000000 | 0.000000 | # [BSS] [cc] Electric Field
%
% BSEQptR
 1 | 7 | # [BSK] Transferred momenta range
%
% BSEBands
25 | 28 | # [BSK] Bands range
%
WRbsWF # [BSS] Write to disk excitonic the FWs

This file was generated using the command: <code> yambo -X s -o b -k sex -y d -r</code> 

First of all, we compute the excitons for all the momenta in the irreducible Brillouin zone for our discrete grid via the <code>BSEQptR</code> variable. This will be a '''finite-momentum''' BSE calculation, analogous to the phonon one.

Second, we change the variable <code>Lkind</code> from <code>bar</code> to <code>full</code>. In Yambo, <code>Lkind="bar"</code>, which is the default for optical absorption, means that we are computing the excitonic response function without the long-range component of the exchange interaction. This cannot be used when computing the exciton momentum dependence, where the long-range exchange interaction can play a role, therefore we have to include it with <code>Lkind="full"</code>. This allows for the calculation of the excitonic longitudinal-transverse splitting (in 3D systems) as well.

We can now run the code:

nohup mpirun -np 8 yambo -F bse.in -J bse_Lfull -C bse_Lfull &

At the end of the calculation, we have obtained the <code>ndb.BS_diago_Q*</code> databases inside the directory <code>bse_Lfull</code>. They contain information on the exciton energies and wavefunctions at each momentum. Do not forget to check the report and logs of your calculation in the same directory to make sure that the code is doing what you want.

== Step 6: obtain the electron-phonon matrix elements ==

We have finished the heavy simulations. Now it's time for the postprocessing. The first order of business is the reconstruction of the electron-phonon coupling matrix elements from the dvscf results and the electronic wavefunctions.

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

We run in the same directory where the Yambo <code>SAVE</code> 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>n_i</math> to <math>n_f</math>, we should type:

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

Here <math>n_i</math> and <math>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>[n_i,n_f]</math> including the extrema of the interval.

These should coincide with those used for the Bethe-Salpeter kernel, i.e. those specified in the <code>BSEBands</code> variable of the BSE input file (this is not strictly necessary, but certainly efficient since these calculations use a lot of disk space).

For our system, we want to do a parallel calculation with 4 qpools and 2 kpools. In addition, we want to explicitly specify the path of the <code>lelphc</code> executable and avoid automatically deleting the LetzElPhC data. So we type:

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

At the end, check your directory: you should find the <code>lelphc.in</code> 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 <code>convention=yambo</code>: 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>n</math> and momentum <math>k-q</math> to band <math>m</math> and momentum <math>k</math>. In the "forward" momentum transfer convention (the more standard one), the transitions go from <math>nk</math> to <math>mk+q</math>. Therefore, this variable ensures that the electron-phonon coupling matrix elements are computed as <math>\langle mk|dV|nk-q\rangle</math>. This will have consequences also in the formulation of the ''exciton''-phonon coupling matrix element.

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

In addition, if you check the <code>SAVE</code> folder:

ls SAVE/ndb.elph_gkkp*

you will see that yambopy has created the Yambo-compatible electron-phonon databases.

If you want to run LetzElPhC directly, without using yambopy, you can refer to its [[https://gitlab.com/lumen-code/LetzElPhC/-/blob/main/docs/main.pdf?ref_type=heads|user guide]].
Keep in mind that in this case, in order to convert the database to the <code>ndb.elph_gkkp*</code> databases of Yambo, you will then need a couple of lines of python using the Yambopy class <code>ConvertElectronPhononDB</code> in <code>yambopy/letzelph_interface/lelph2y.py</code>.

If you don't need the <code>ndb.elph_gkkp*</code> databases -- e.g., because you are doing the exc-ph postprocessing with yambopy -- you can run <code>yambopy l2y ...</code> with the <code>--no_gkkp</code> option.

If you don't need the <code>ndb.elph</code> databases -- e.g., because you are using <code>yambo_ph</code> for the exc-ph part -- you can run <code>yambopy l2y ...</code> with the <code>--no_lelphc_dbs</code> option.

== Step 7: Obtain the exciton-phonon coupling ==

Now, we can finally access our basic building block for exciton-phonon physics. This could be done entirely in python (using '''Yambopy'''), or by running '''Yambo'''.

* For the '''Yambo postprocessing''' case (running yambo inputs with the <code>yambo_ph</code> executable), '''follow the alternative route to Steps 7-8 [[Exciton-phonon coupling and luminescence - Yambo postprocessing|at this link]]'''.
* For the '''Yambopy postprocessing''' case (using flexible python scripting), '''keep following Steps 7-8 on this page'''.

Our objective is obtaining the following quantity:

<math>\mathcal{G}^\mu_{\alpha\lambda}(0,q)=\sum_{vv^\prime c k} A^{\alpha, *}_{cv^\prime} (k, q) g_{vv^\prime}^\mu (k,q) A^{\lambda}_{cv}(k,0) - \sum_{cc^\prime vk} A^{\alpha, *}_{c^\prime v} (k+q, q) g_{c^\prime c}^\mu (k+q,q) A^{\lambda}_{cv}(k, 0)</math>

Here, <math>A^{\alpha}_{cv}(k,q)</math> are the exciton coefficients extracted from the eigenvector of the two-particles Hamiltonian during the BSE calculation in step 5, while <math>g_{nm}^\mu (k,q)</math> are the electron-phonon coupling matrix elements obtained in step 6. As you can see, the exciton <math>\lambda</math> undergoes phonon-mediated scattering to state <math>\alpha</math> via phonon mode <math>\mu</math>. The scattering can happen for the hole (valence, <math>v</math>) or for the electron (conduction, <math>c</math>).

NB:

(1) This is written in the "backward" momentum transfer convention used by Yambo. The momentum dependence is different in the "forward" transfer convention.

(2) For simplicity, this is written for zero initial exciton momentum. This means that one of the two states involved in the phonon-mediated scattering process will be in the optical limit (and possibly an optically generated exciton), while the other state can have any momentum: this momentum will be the same as the phonon one. This matrix element can be used to describe phonon-assisted absorption and emission spectra.

In order to calculate this quantity using python, we need the <code>ndb.elph</code> databases natively generated by the <code>LetzElPhC</code> code, as well as the BSE databases <code>ndb.BS_diago_Q*</code> containing the information on exciton wavefunctions and energies.

Next, we write a python user script importing the yambopy exciton-phonon tools. You can find a version of this script in <code>yambopy/tutorials/exciton-phonon/calculate_excph.py</code>.

import numpy as np
from yambopy import YamboLatticeDB,YamboWFDB,LetzElphElectronPhononDB #Specific Yambopy dbs loading classes
from yambopy.exciton_phonon.excph_matrix_elements import exciton_phonon_matelem #Specific exc-ph functions

path = '1L_MoS2'
bands_range=[24,28] # 2 valence bands, 2 conduction bands
nexc = 12 # number of excitonic states

bsepath = f'{path}/bse-allq_full' # Path to BSE calculation (Lin=Lout)
savepath = f'{path}/SAVE' # Yambo SAVE
ndb_elph = f'{path}/ndb.elph' # LetzElPhC electron-phonon database (any convention)

# Read lattice
lattice = YamboLatticeDB.from_db_file(filename=f'{savepath}/ns.db1')
# Read electron-phonon
elph = LetzElphElectronPhononDB(ndb_elph,read_all=False)
# Read wave functions
wfcs = YamboWFDB(filename='ns.wf',save=savepath,latdb=lattice,bands_range=bands_range)
# Calculate exciton-phonon matrix elements
exph = exciton_phonon_matelem(lattice,elph,wfcs,BSE_dir=bsepath,nexc_in=nexc,nexc_out=nexc,dmat_mode='save',exph_file='MoS2_Ex-ph.npy')

In this script, we can select the number exciton states <math>\lambda</math> with <code>nexc</code>, the single-particle bands range with <code>bands_range</code>. '''Please note''': in this case, the band index starts from 0 (python indexing) and the the interval of bands read by the code is <math>[n_i,n_f)</math>, therefore the last value (28 in the example) is excluded. That is, in the example we are selecting the 25th, 26th, 27th and 28th bands. Those bands have to be present in both the electron-phonon and BSE calculations.

Here we calculate the couplings of the first twelve states at each finite-<math>q</math> point including <math>q=0</math>. We also include all the nine phonon modes of monolayer MoS2. We also need access to the Yambo <code>SAVE</code> directory in order to read the electronic wavefunctions: they are used to compute the electronic representation matrices (<code>dmat</code> in the code). The argument <code>dmat_mode</code> can be set to <code>'load'</code> for subsequent calculations.

When we are satisfied with the input, we run the code:

python calculate_excph.py

If you check the output, you should find the <code>MoS2_Ex-ph.npy</code> binary file in the directory where you ran.

=== Analysis of the couplings ===

It is a good idea to have a look at what we computed up to now in order to make sure nothing has gone wrong.

It is not easy to know what to expect (apart from symmetry and gauge compliance of the matrix elements), but one can work out the exciton-phonon selection rules in advance, check that the magnitude is reasonable, etc.

It is also not easy to meaningfully plot this quantity. We have to make sure that we are not breaking degenerate states, otherwise the plots will not be invariant.

First of all, we have to know our system: in monolayer MoS2, the first four excitons are all doubly degenerate. The first exciton responsible for a bright peak in the absorption spectrum (the '''A''' peak), is the second state, corresponding to state indices <code>(3,4)</code> in fortran indexing or <code>(2,3)</code> in python indexing.

All these information can be obtained by analyzing the BSE results (this stuff is explained in the BSE tutorials) and by knowledge of the system or class of systems from the literature.

Thus, a good quantity to plot may be the norm of the matrix elements, summed over the degenerate subspace of exciton A, for a certain number of scattered final states mediated by certain phonon modes:

<math>F_A(q)= \sqrt{ \sum_{\alpha \in A,\lambda,\mu} |\mathcal{G}_{\alpha\lambda}^\mu (0,q)|^2 }</math>

In order to do this, we create a python script <code>analyse_excph.py</code> in which we first load the excph dabatases.
You can find a version of this script in the yambopy directory, in <code>tutorials/exciton-phonon</code>.
First, we select the exciton and phonon states to be included in <code>F_A</code>, together with the path of databases and plot details:

# Exciton "in" states
exc_in = [2,3] # First bright peak (A: 2,3 -- B: 6,7)
exc_out = [0,1,2,3] # first 4 states (dispersion of dark triplet state and A)
ph_in = 'all'
# Paths of databases
ns_db1 =f'{path}/SAVE/ns.db1'
ns_ypy = 'MoS2_Ex-ph.npy'

...

Then, we load the data:

# Read lattice and k-space info
ylat = YamboLatticeDB.from_db_file(filename=ns_db1)
print(ylat)

# Load exc-ph database
X_py = np.load(ns_ypy)
G_squared = np.abs(X_py)**2.

The quantity <math>F_A(q)</math> is obtained from a dedicated function as:

if exc_in == 'all': exc_in = range(G_squared.shape[2])
if exc_out == 'all': exc_out = range(G_squared.shape[3])
if ph_in == 'all': ph_in = range(G_squared.shape[1])

G_squared = G_squared[:, ph_in, :, :].sum(axis=(1))
G_squared = G_squared[:, exc_in, :].sum(axis=(1))
G_squared = G_squared[:, exc_out].sum(axis=(1))

F_q = np.sqrt( G_squared )*ha2ev # Switch from Ha to eV

And finally, we have to make a plotting function. For this tutorial we will use a custom scatterplot employing some of the plotting tools provided by yambopy (but you can do whatever you want).

plot_2D_excph(qgrid,G2_to_plot,rlat=ylat.rlat,plt_cbar=True,\
marker='H',s=700,cmap='magma')
...

You can get more experience on using Yambopy for these kinds of visualization by following the [https://wiki.yambo-code.eu/wiki/index.php?title=First_steps_in_Yambopy Yambopy tutorials]. In fact, remember that these scripts and all the other Yambopy tutorial scripts are just suggestions, not source code written in stone: if you know <code>numpy</code> and <code>matplotlib</code> you can do your own analysis and your own plots, you just need to import the required Yambopy modules to load the data.

In our case, the resulting plot is the following.

[[File:1L MoS2 MoS2 Ex-ph.png|500px|center]]

This can be checked against Fig. 2(d) of reference <ref name="chan2023" />, although you have to keep in mind that our results are badly undersampled in terms of the reciprocal-space grid, as can be easily seen, and the quantity plotted is not exactly the same. However, the main features are already there since they are dictated mostly by crystal symmetries.

Now that we have the exciton-phonon matrix elements, we can use them to build several kinds of observables. Below, we give an example related to phonon-assisted luminescence, but we may update this tutorial in the future to include more cases.

== Step 8: Compute phonon-assisted luminescence ==

[[File:Luminescence scheme.png|250px|right]]

We want to compute the experimental optical signature due to the phonon-assisted recombination of an exciton (as sketched in the figure).

The signal from the phonon replicas can be modeled as a second-order scattering process involving one phonon and one photon:

<math>I^{Sat}(\omega)=\frac{1}{ N_q} \frac{1}{3} \sum_{\epsilon s\beta \mu q} \frac{1}{E_{\beta q}-s\Omega_{\mu q}}\left|\sum_\alpha\frac{ D^{\epsilon}_\alpha \mathcal{G}_{\beta \alpha}^{\mu,*}(q)}{E_\alpha -E_{\beta q} +s\Omega_{\mu q}+\mathrm{i}\eta}\right|^2 \frac{N^{exc}_{\beta q}(T_{exc})[\frac{1+s}{2}+n_{\mu q}(T)]}{\omega -[E_{\beta q}-s\Omega_{\mu q}]+\mathrm{i}\eta}</math>

In this equation, the oscillator strength of the peak is given by the exciton-phonon coupling matrix elements <math>\mathcal{G}</math> multiplied by the exciton dipoles <math>D</math> (they are called "residuals" in Yambo). Here <math>E_\lambda</math> and <math>E_{\alpha q}</math> are the energies of the optical and finite-momentum excitons, respectively, while <math>\Omega_{\mu q}</math> are the phonon energies.

Here, <math>n_{\mu q}(T)</math> is the temperature-dependent phonon Bose-Einstein occupation function. As it can be seen, <math>s=1</math> corresponds to processes of phonon ''emission'' (<math>\propto n(T)+1</math>), while <math>s=-1</math> corresponds to processes of phonon ''absorption'' (<math>\propto n(T)</math>). Therefore, <math>I^{Sat}_{PL}(\omega;T)</math> describes ''light'' emission by recombining excitons mediated by either ''phonon'' absorption or emission.

The quantity <math> N_{\alpha q}(T_{exc})</math> is the exciton occupation function. Luminescence is technically an out-of-equilibrium process, but we can assume that for very low density of excitations and in steady-state conditions, the exciton population can be approximately described by an equilibrium distribution evaluated at an effective temperature. Here, we use the Boltzmann distribution. Experimentally, <math>T_{exc}</math> tends to coincide with the lattice temperature <math>T</math> more or less above 100 K, while at very low temperature (< 10 K), <math>T_{exc}</math> may vary between 10-50 K. It goes without saying that this needs to carefully be checked in your realistic calculations.

Finally, the spectrum is averaged over the polarization directions of the emitted photons (<math>\epsilon=x,y,z</math> representing the respective dipole components).

=== Running the jobs ===

In order to study luminescence in a paradigmatic system, we switch to bulk hexagonal boron nitride and we repeat the workflow. As you can easily see, one can think about automatizing the execution of all these calculations via scripting or more advanced tools. However, in the case of very large simulations (memory-limited or disk-space limited) or for systems whose electronic and lattice properties are fragile with respect to tiny calculation details, one must be very careful and run many basic tests.

Fortunately, we are running a fast underconverged example. We use LDA pseudopotentials from the pseudo-dojo library and the following are the calculations steps.

1. Input <code>hbn.scf</code>:

&control
calculation='scf',
prefix='hBN',
restart_mode='from_scratch'
pseudo_dir = '$PSEUDO_DIR',
outdir = './tmp'
verbosity = 'high'
wf_collect=.true.
/
&system
ibrav = 4,
celldm(1) = 4.703675849
celldm(3) = 2.603711434
nat= 4,
ntyp= 2,
force_symmorphic=.true.
ecutwfc = 100,
/
&electrons
diago_david_ndim = 2
diago_full_acc=.true.
diago_thr_init=5.0e-6
mixing_mode = 'plain'
mixing_beta = 0.7
conv_thr = 1.0d-16
/
ATOMIC_SPECIES
B 10.81100 B_LDA_dojo.UPF
N 14.00674 N_LDA_dojo.UPF
ATOMIC_POSITIONS {crystal}
N 0.6666666670 0.3333333330 -0.250000000000
B 0.3333333330 0.6666666670 -0.250000000000
B 0.6666666670 0.3333333330 0.25000000000
N 0.3333333330 0.6666666670 0.25000000000
K_POINTS {automatic}
6 6 2 0 0 0

mpirun -np 4 pw.x -inp hbn.scf > scf.out

2. Input <code>hbn.nscf</code>:

&control
calculation='nscf',
prefix='hBN',
restart_mode='from_scratch'
pseudo_dir = '$PSEUDO_DIR'
outdir = './'
verbosity = 'high'
wf_collect=.true.
/
&system
ibrav = 4,
celldm(1) = 4.703675849
celldm(3) = 2.603711434
nat= 4,
ntyp= 2,
force_symmorphic=.true.
ecutwfc = 100,
nbnd = 120
/
&electrons
diago_david_ndim = 2
diago_full_acc=.true.
diago_thr_init=5.0e-6
mixing_mode = 'plain'
mixing_beta = 0.7
conv_thr = 1.0d-16
/
ATOMIC_SPECIES
B 10.81100 B_LDA_dojo.UPF
N 14.00674 N_LDA_dojo.UPF
ATOMIC_POSITIONS {crystal}
N 0.6666666670 0.3333333330 -0.250000000000
B 0.3333333330 0.6666666670 -0.250000000000
B 0.6666666670 0.3333333330 0.25000000000
N 0.3333333330 0.6666666670 0.25000000000
K_POINTS {automatic}
6 6 2 0 0 0

mpirun -np 4 pw.x -inp hbn.nscf > nscf.out

3. Input <code>hbn.dvscf</code>:

hbn_dvscf
&inputph
tr2_ph=1.0d-12,
verbosity='high'
prefix='hBN',
fildvscf = 'hBN-dvscf',
electron_phonon = 'dvscf',
fildyn='hBN.dyn',
epsil=.false.,
ldisp=.true.,
recover=.true.,
nq1=6,
nq2=6,
nq3=2
/

nohup mpirun -np 8 pw.x -inp hbn.dvscf > dvscf.out &

4. Input <code>bse.in</code> (we include 2 valence and 2 conduction bands):

optics # [R] Linear Response optical properties
bss # [R] BSE solver
bse # [R][BSE] Bethe Salpeter Equation.
dipoles # [R] Oscillator strenghts (or dipoles)
em1s
DIP_CPU= "1 8 1" # [PARALLEL] CPUs for each role
DIP_ROLEs= "k c v" # [PARALLEL] CPUs roles (k,c,v)
DIP_Threads=0 # [OPENMP/X] Number of threads for dipoles
X_and_IO_CPU= "1 1 1 8 1" # [PARALLEL] CPUs for each role
X_and_IO_ROLEs= "q g k c v" # [PARALLEL] CPUs roles (q,g,k,c,v)
X_and_IO_nCPU_LinAlg_INV=-1 # [PARALLEL] CPUs for Linear Algebra (if -1 it is automatically set)
X_Threads=0 # [OPENMP/X] Number of threads for response functions
BS_CPU= "8 1 1" # [PARALLEL] CPUs for each role
BS_ROLEs= "k eh t" # [PARALLEL] CPUs roles (k,eh,t)
BS_nCPU_LinAlg_INV=-1 # [PARALLEL] CPUs for Linear Algebra (if -1 it is automatically set)
BS_nCPU_LinAlg_DIAGO=-1 # [PARALLEL] CPUs for Linear Algebra (if -1 it is automatically set)
X_Threads=0 # [OPENMP/X] Number of threads for response functions
K_Threads=0 # [OPENMP/BSK] Number of threads for response functions
% QpntsRXs
1 | 14 | # [Xs] Transferred momenta
%
% BndsRnXs
1 | 120 | # [Xs] Polarization function bands
%
NGsBlkXs= 10 Ry # [Xs] Response block size
% LongDrXs
1.000000 | 1.000000 | 1.000000 | # [Xs] [cc] Electric Field
%
BSEmod= "resonant" # [BSE] resonant/retarded/coupling
BSKmod= "SEX" # [BSE] IP/Hartree/HF/ALDA/SEX/BSfxc
Lkind= "Lfull" # [BSE] Lbar (default) / full
BSSmod= "d" # [BSS] (h)aydock/(d)iagonalization/(s)lepc/(i)nversion/(t)ddft`
% DipBands
1 | 120 | # [DIP] Bands range for dipoles
%
DipApproach= "G-space v" # [DIP] [G-space v/R-space x/Covariant/Shifted grids]
DipComputed= "R V P" # [DIP] [default R P V; extra P2 Spin Orb]
BSENGexx= 30000 Ry # [BSK] Exchange components
#ALLGexx # [BSS] Force the use use all RL vectors for the exchange part
BSENGBlk= 9000 Ry # [BSK] Screened interaction block size [if -1 uses all the G-vectors of W(q,G,Gp)]
% KfnQP_E
1.25997 | 1.08816 | 1.12683 | # [EXTQP BSK BSS] E parameters (c/v) eV|adim|adim
%
% BSEQptR
 1 | 14 | # [BSK] Transferred momenta range
%
% BSEBands
 7 | 10 | # [BSK] Bands range
%
% BEnRange
0.50000 | 8.00000 | eV # [BSS] Energy range
%
% BDmRange
0.050000 | 0.050000 | eV # [BSS] Damping range
%
BEnSteps= 1000 # [BSS] Energy steps
% BLongDir
1.000000 | 1.000000 | 0.000000 | # [BSS] [cc] Electric Field
%
WRbsWF # [BSS] Write to disk excitonic the WFs

nohup mpirun -np 8 yambo -F bse.in -J bse_Lfull -C bse_Lfull &

Importantly, since we want to describe the phonon-assisted recombination process of an *optical* exciton (i.e., emitting a transverse photon), this time we also run an additional calculation at `Q=0` omitting the nonanalytic long-range Coulomb exchange. Make a second input <code>bse_Lbar.in</code> with the following changes:

Lkind= "Lbar" # [BSE] Lbar (default) / full
% BSEQptR
 1 | 1 | # [BSK] Transferred momenta range
%

4b. So now we make a second BSE run in a different directory specified by <code>-J</code>. Here, we also pass to yambo the directory of the previous run as it includes the important screening databases <code>ndb.em1s*</code> that we do not want to recompute from scratch.

mpirun -np 8 yambo -F bse_Lbar.in -J bse_Lbar,bse_Lfull -C bse_Lbar

5. Now we run <code>lelphc</code> (with or without yambopy: in the latter case remember the option <code>-D</code>) to get the el-ph matrix elements, particularly the <code>ndb.elph</code> databases:

yambopy l2y -ph path/of/dvscf/hbn.dvscf -b 7 10 -par 4 2 -D

=== Luminescence calculation ===

6. And finally we calculate exciton-phonon matrix elements and the luminescence spectrum in one go using a python script importing the Yambopy exciton-phonon tools: in order to do this, we need to take a look at all the necessary input variables for the formula written above.

We can start from the script <code>luminescence.py</code> available in <code>tutorials/exciton-phonon</code>.

import numpy as np
import matplotlib.pyplot as plt
from yambopy.exciton_phonon.excph_luminescence import exc_ph_luminescence
from yambopy.exciton_phonon.excph_input_data import exc_ph_get_inputs

We import the necessary tools...

path = '3D_hBN'
# Path to BSE calculation (Lout--> response is Lfull)
bsepath = f'{path}/bse_Lfull' # ndb.BS_diago_Q* databases are needed
# Path to BSE calculation for optically active exciton (Lin --> response is Lbar)
bseBARpath = f'{path}/bse_Lbar' # ndb.BS_diago_Q1 database is needed
# Path to electron-phonon calculation
elphpath = path # ndb.elph is needed
# Path to unprojected dipoles matrix elements (optional)
dipolespath = bsepath # ndb.dipoles is needed (optional)
# Path to lattice and k-space info
savepath = f'{path}/SAVE' # ns.db1 database is needed

... and we specify the paths to the necessary databases. Note that, if we want to perform polarization averaging, we have to recompute the excitonic dipoles in python as seen here.

What about <code>bseBARpath</code>? This variable points to the directory where the databases for the optical (zero-momentum) excitons <math>\alpha</math> (which may be computed with <code>Lkind='Lbar'</code>) is located, which can be different from the directory with the full indirect exciton dispersion <math>\beta</math> (usually computed with <code>Lkind='Lfull'</code>, however <code>Lkind='Ltilde'</code> can also be used if one is interested in "irreducible" excitons). This makes it possible to compute the coupling between different exciton kinds.

bands_range=[6,10] # 2 valence, 2 conduction bands
phonons_range=[0,12] # All phonons
nexc_out = 12 # 12 excitonic states at each momentum (Lout)
nexc_in = 12 # 12 excitonic states at Q=0 (Lin)
T_ph = 10 # Lattice temperature
T_exc = 10 # Effective excitonic temperature

emin=4.4 # Energy range and plot details (in eV)
emax=4.7
estep=0.0002
broad = 0.005 # Broadening parameter for peak width (in eV)

Next, we specify the parameters for the calculation. We include valence bands from 7 to 10 (6 to 9 in python index) and the contribution of all 12 phonon modes. We consider 12 excitonic states for the coupling matrix elements.

Here <code>T_ph</code> and <code>T_exc</code> are the lattice and excitonic temperatures, respectively.

# We calculate and load all the inputs:
# * Exciton-phonon matrix elements
# * Excitonic dipole matrix elements
# * Exciton energies
# * Phonon energies
# * We specify bse_path2=bseBARpath meaning we use Lbar calculation for Q=0 excitons
input_data = exc_ph_get_inputs(savepath,elphpath,bsepath,\
bse_path2=bseBARpath,dipoles_path=dipolespath,\
nexc_in=12,nexc_out=12,\
bands_range=[6,10],phonons_range=[0,12])

ph_energies, exc_energies, exc_energies_in, G, exc_dipoles = input_data

The function <code>exc_ph_get_inputs</code> gives us all the input data for luminescence in the correct format: phonon energies, exciton energies, optical exciton energies (if needed), exciton-phonon matrix elements (calculated on the fly and printed to file), unprojected exciton dipoles (optional, calculated on the fly and printed to file).
The exc-ph matrix element calculation is just a wrapper of the same tools that we have tested in the above section on MoS2.

Finally, there is the calculation of the luminescence spectrum via the function <code>exc_ph_luminescence</code>:
# We calculate the luminescence spectrum including the input data from before
w,PL = exc_ph_luminescence(T_ph,ph_energies,exc_energies,exc_dipoles,G,\
exc_energies_in=exc_energies_in,exc_temp=T_exc,\
nexc_out=nexc_out,nexc_in=nexc_in,emin=emin,emax=emax,\
estep=estep,broad=broad)

If you want to print the luminescence data for later plotting, you can also add the following line to the script:
# Save to file
data = np.column_stack((w, PL))
np.savetxt("hBN_luminescence_12x12x1.dat", data, fmt="%.8f")

It is now time to run the whole script:

python luminescence.py

NB: By using Yambopy for Step 6, we have limited the use of the Yambo code to just step 4 in the entire workflow. This option is more flexible, as it allows for a greater degree of control by the user. On the other hand the Yambo postprocessing route features a Yambo-style input that doesn't require python knowledge and the calculation is currently faster in fortran. However, the luminescence expression computed in Yambo is a slightly different than this one: it is more approximated in the description of the satellite oscillator strengths, but it explicitly includes the renormalization of the direct exciton peak. You can check the differences [[Exciton-phonon coupling and luminescence - Yambo postprocessing|here]].

=== Results ===
We can plot the results of the step 6 calculation. If we do it in the same script we can add something like this:
fig = plt.figure()
ax = fig.add_subplot(1,1,1)
ax.set_xlim(emin,emax)
ax.set_ylim(0,np.max(PL)*1.1)
ax.get_yaxis().set_visible(False)

ax.plot(w, PL, '-',c='red', label="AA' hBN luminescence")

plt.legend()
plt.savefig('hBN_luminescence.png')
plt.show()

[[File:HBN luminescence satellites.png|500px|center]]

Here, the signal corresponds to a finite-momentum exciton that recombines with the help of several different phonon modes, both optical and acoustic. Each phonon mode whose coupling with the exciton is allowed can generate a peak, and the energy shifts of these peaks with respect to the initial exciton energy correspond to the phonon energies. This result is underconverged, but the main features are all there. In the plot, we show a more converged example using a 12x12x4 grid (all the other parameters being equal). These plots can be compared with Fig. 4(a) of reference <ref name="zanfrognini2023" />.

== References ==

<references>
<ref name="toyozawa2003" >Toyozawa, Yutaka, and Chris Oxlade, ''Optical processes in solids'', [https://m.booksee.org/book/1121964?force_lang=en Cambridge University Press, (2003)]. </ref>
<ref name='lechifflart2023'>P. Lechifflart, F. Paleari, D. Sangalli, C. Attaccalite, ''First-principles study of luminescence in hexagonal boron nitride single layer: Exciton-phonon coupling and the role of substrate'',
[https://doi.org/10.1103/PhysRevMaterials.7.024006 Phys. Rev. M, '''7''' (2), 024006 (2023)]; [https://arxiv.org/abs/2212.10407 arXiv2212.1047]</ref>
<ref name='cannuccia2019'>E. Cannuccia, B. Monserrat and C. Attaccalite, ''Theory of phonon-assisted luminescence in solids: Application to hexagonal boron nitride'', [https://doi.org/10.1103/PhysRevB.99.081109 Phys. Rev. B '''99''', 081109(R) (2019)]; [https://arxiv.org/abs/1807.11797 arXiv1807.11797]</ref>
<ref name='paleari2019'>F. Paleari et al., ''Exciton-Phonon Coupling in the Ultraviolet Absorption and Emission Spectra of Bulk Hexagonal Boron Nitride'', [https://doi.org/10.1103/PhysRevLett.122.187401 Phys. Rev. Lett. '''122''', 187401 (2019)]; [https://arxiv.org/abs/1810.08976 arXiv1810.089776] </ref>
<ref name='chen2020'>''Exciton-Phonon Interaction and Relaxation Times from First Principles'',
Hsiao-Yi Chen, Davide Sangalli, and Marco Bernardi, [https://doi.org/10.1103/PhysRevLett.125.107401 Phys. Rev. Lett. '''125''', 107401 (2020)]; [https://arxiv.org/abs/2002.08913 arXiv 2002.08913 (2020)]</ref>
<ref name="lechifflart2023_PhD">P. Lechifflart, ''Exciton-phonon coupling and phonon-assisted luminescence in hexagonal Boron Nitride nanostructures'', [https://hal.science/tel-04266805v1 PhD Thesis, University of Marseille (2023)]; [https://www.yambo-code.eu/wiki/images/5/54/These_final.pdf From the yambo website]</ref>
<ref name='paleari2019_PhD'>F. Paleari, ''First-principles approaches to the description of indirect absorption and luminescence spectroscopy: exciton-phonon coupling in hexagonal boron nitride'', [https://wwwen.uni.lu/research/fstm/dphyms/people/fulvio_paleari PhD thesis, University of Luxembourg (2019)]</ref>
<ref name='zanfrognini2023'>M. Zanfrognini et al., ''Distinguishing different stackings in layered materials via luminescence spectroscopy'', [https://doi.org/10.1103/PhysRevLett.131.206902 Phys. Rev. Lett. '''131''', 206902 (2023)]; [https://arxiv.org/abs/2305.17554 arXiv 2305.17554] </ref>
<ref name='marini2024'>G. Marini, M. Calandra, P. Cudazzo, ''Optical absorption and photoluminescence of single layer boron nitride from a first principles cumulant approach'', [https://doi.org/10.1021/acs.nanolett.4c00669 Nano Lett., '''24''', 20, 6017 (2024)]; [https://arxiv.org/abs/2402.03826 arXiv 2402.03826 (2024)]</ref>
<ref name='antonius2017'>G. Antonius, S. G. Louie, ''Theory of exciton-phonon coupling'', [https://doi.org/10.1103/PhysRevB.105.085111 Phys. Rev. B, '''105''', 085111 (2022)]; [https://arxiv.org/abs/1705.04245 arXiv1705.04245 (2017)]</ref>
<ref name='paleari2022'> F. Paleari, and A. Marini, ''Exciton-phonon interaction calls for a revision of the “exciton” concept'', [https://doi.org/10.1103/PhysRevB.106.125403 Phys. Rev. B, '''106''', 125403 (2022)]; [https://arxiv.org/abs/2205.02783 arXiv 2205.02783]</ref>
<ref name='cudazzo2020'> P. Cudazzo, ''First-principles description of the exciton-phonon interaction: A cumulant approach'', [https://doi.org/10.1103/PhysRevB.102.045136 Phys. Rev. B, '''102''', 045136 (2020)]; [https://orbilu.uni.lu/bitstream/10993/44769/1/main.pdf Open access pdf from Luxembourg University]</ref>
<ref name='chan2023'>Y-h Chan, J. B. Haber, M. H. Naik, J. B. Neaton, D. Y. Qiu, F. H. da Jornada, S. G. Louie, ''Exciton Lifetime and Optical Line Width Profile via Exciton–Phonon Interactions: Theory and First-Principles Calculations for Monolayer MoS2'', [https://doi.org/10.1021/acs.nanolett.3c00732 Nano Lett., '''23''', 9 (2023)]; [https://arxiv.org/abs/2212.08451 arXiv 2212.08451 (2023)]</ref>
<ref name='murali2025'>M. Nalabothula, S. Reichardt, L. Wirtz, ''Origin of Interlayer Exciton–Phonon Coupling in 2D Heterostructures'', [https://doi.org/10.1021/acs.nanolett.5c00355 Nano Lett., '''25''', 15 (2025)], [https://arxiv.org/abs/2407.16111 arXiv 2407.16111 (2025)]</ref>
</references>

Yambopy tutorial: electron-phonon coupling

2026-03-11T13:33:50Z

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

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

# Quantum Espresso calculation of phonon energies, eigenmodes and variations of the self-consistent potential via <code>ph.x</code>.
# Electron-phonon matrix element calculation, symmetry expansion and conversion by the <code>LetzElPhC</code>.

For more information on the <code>LetzElPhC</code> code and how you should run step 1., please see the related documentation [https://github.com/yambo-code/LetzElPhC here].

We can use Yambopy to:
* Run <code>LetzElPhC</code> (both preprocessing and main run) without explicitly writing an input file.
* Convert the resulting databases into <code>Yambo</code> format.
* Analyse the electron-phonon coupling both in <code>LetzElPhC</code> or <code>Yambo</code> format.

In particular we will take a look at:
* Lattice geometry data (Yambo database: <code>ns.db1</code>, Yambopy class: <code>YamboLatticeDB</code>).
* Electron-phonon matrix elements (Yambo databases: <code>ndb.elph_gkkp*</code>, Yambopy class: <code>YamboElectronPhononDB</code>; LetzElPhC databases: <code>ndb.elph</code>, Yambopy class: <code>LetzElphElectronPhononDB</code>).

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/yambopy_electron_phonon.tar.gz
tar -xvzf yambopy_electron_phonon.tar.gz
cd electron_phonon

We will work with monolayer molybdenum disulphide electron-phonon data obtained on a <code>6x6x1</code> 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''' and '''Quantum ESPRESSO''' 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

Here you will find:
* A scf input file for MoS2, <code>scf/mos2.scf</code>
* A dvscf input file for MoS2, <code>dvscf/mos2.dvscf</code>
* A Yambo <code>SAVE</code> directory corresponding to a nscf calculation (this has been run already).
* The pseudopotential files to be used for the calculation.

As a first step, you need to run the Quantum ESPRESSO calculations (it is assumed that you are familiar with this). First run the scf calculation inside <code>scf</code>, then copy the <code>mos2.save</code> directory into the <code>dvscf</code> folder and run the dvscf calculation there. When everything is completed correctly, you will have achieved step 1. above.

Now, you will find the phonon results in the <code>dvscf</code> directory. We also have done a non-self-consistent calculation to be used in Yambo, and created the relative <code>SAVE</code> directory. If you check this directory, you will find the <code>ns.wf</code> databases containing the electronic wavefunctions.

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

In order to do this, we will run the <code>lelphc</code> executable of the '''LetzElPhC''' code (this will be step 2. from above). We will run via command line using yambopy, although it will be instructive to have look at the <code>lelphc</code> input files later.

We run in the same directory where the Yambo <code>SAVE</code> 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>n_i</math> to <math>n_f</math>, we should type:

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

Here <math>n_i</math> and <math>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>[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 <code>lelphc</code> 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 <code>ndb.elph_gkkp*</code> databases you can run <code>yambopy l2y ...</code> with the <code>--no_gkkp</code> option.
* If you don't need the default <code>ndb.elph</code> databases you can run <code>yambopy l2y ...</code> with the <code>--no_lelphc_dbs</code> 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 <code>lelphc</code> executable is in the <code>PATH</code>, you do not need to specify the last flag.

At the end, check your directory: you should find the <code>lelphc.in</code> 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 <code>convention=yambo</code>: 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>n</math> and momentum <math>k-q</math> to band <math>m</math> and momentum <math>k</math>. In the "forward" momentum transfer convention (the more standard one), the transitions go from <math>nk</math> to <math>mk+q</math>. Therefore, this variable ensures that the electron-phonon coupling matrix elements are computed as <math>\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 <code>ndb.elph</code> database that contains the computed electron-phonon matrix elements, in the output format of <code>LetzElPhC</code>.

In addition, if you check the <code>SAVE</code> folder:

ls SAVE/ndb.elph_gkkp*

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

If you want to run LetzElPhC directly, without using yambopy, you can refer to its [[https://gitlab.com/lumen-code/LetzElPhC/-/blob/main/docs/main.pdf?ref_type=heads|user guide]].
Keep in mind that in this case, in order to convert the database to the <code>ndb.elph_gkkp*</code> databases of Yambo, you will then need a couple of lines of python using the Yambopy class <code>ConvertElectronPhononDB</code> in <code>yambopy/letzelph_interface/lelph2y.py</code>.

At the end of this section, you should have produced the same databases that you find in the main <code>electron_phonon</code> 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 precomputed ones.

=== Electron-phonon intro: plots of el-ph matrix elements on k-BZ and q-BZ ===
In this section we will use the script <code>elph_plot.py</code> and read the electron-phonon databases that you generated in the previous section.

In order to read the <code>ndb.elph_gkkp_expanded*</code> databases in python we use the Yambopy class <code>YamboElectronPhononDB</code>, which can be instanced like this:
elph = YamboElectronPhononDB(ylat,folder_gkkp='path/to/elph/folder',save='path/to/SAVE')
(notice that it requires a previous instance of <code>YamboLatticeDB</code>).

Instead, in order to read the <code>ndb.elph</code> databases from LetzElPhC, we use a different class:
elph = LetzElphElectronPhononDB('path/to/ndb.elph')

Now, the <code>elph</code> objects contain phonon frequencies, phonon eigenvectors, q-point information and, of course, the electron-phonon matrix elements <math>g_{nm\nu}(k,q)</math> where <math>n</math>, <math>m</math> are electron band states, <math>\nu</math> is a phonon branch, and <math>k</math> and <math>q</math> are the electronic and transfer momenta.

We can print the docstring of the <code>YamboElectronPhononDB</code> class with
print(yelph.__doc__)
and of the <code>LetzElphElectronPhononDB</code> class with
print(lelph.__doc__)
to get an idea of the information stored and of their capabilities.

Now check the <code>elph_plot.py</code> script. Besides choosing which database to load, it also performs two plots:

* Plot of |g(k)| in the k-BZ for selected bands n,m, phonon mode \nu and q [<code>kspace_Plot=True</code>].
* Plot of |g(q)| in the q-BZ for selected bands n,m, phonon mode \nu and k [<code>qspace_Plot=True</code>].

You will see that after loading the database, it first postprocesses the electron-phonon data to obtain a plottable quantity. Indeed, it is not necessarily easy to understand what to plot and what to keep fixed, since the matrix element depends on two momenta and three state indices. In addition, bands or phonon states may be degenerate at certain momenta.

In practice, we set a phonon mode (the eighth mode, this is the branch with symmetry <math>A_1^\prime</math> at zone center) and either a <math>k</math> or <math>q</math> point to keep fixed (in each case, we select the high-symmetry <math>K</math> point). As for the bands, we consider the top two valence bands. These are mostly degenerate, except around the points <math>K</math> and <math>K^\prime</math> where they are split by spin-orbit interaction. We then average over these states before plotting, obtaining the quantity (in k-space below):

<math> I^{\mu}_{<v>q}(\mathbf{k}) = \sqrt{\sum_{v,v^\prime=24,25}|g^{\mu}_{vv^\prime q}(\mathbf{k})|^2}</math>

You are invited to play with the electronic, phononic and momentum indices to see what happens! (beware of degenerate states: if not properly accounted for by the sum of the norms, the plots will be phase-dependent and unphysical)

[[File:MoS2 6x6x1 g vv' in kspace.png|yambopy el-ph plot for tutorial|500px]] [[File:MoS2 6x6x1 g vv' in qspace.png|yambopy el-ph plot for tutorial|500px]]

Yambopy tutorial: electron-phonon coupling

2026-03-11T13:33:36Z

FulvioPaleari:

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

# Quantum Espresso calculation of phonon energies, eigenmodes and variations of the self-consistent potential via <code>ph.x</code>.
# Electron-phonon matrix element calculation, symmetry expansion and conversion by the <code>LetzElPhC</code>.

For more information on the <code>LetzElPhC</code> code and how you should run step 1., please see the related documentation [https://github.com/yambo-code/LetzElPhC here].

We can use Yambopy to:
* Run <code>LetzElPhC</code> (both preprocessing and main run) without explicitly writing an input file.
* Convert the resulting databases into <code>Yambo</code> format.
* Analyse the electron-phonon coupling both in <code>LetzElPhC</code> or <code>Yambo</code> format.

In particular we will take a look at:
* Lattice geometry data (Yambo database: <code>ns.db1</code>, Yambopy class: <code>YamboLatticeDB</code>).
* Electron-phonon matrix elements (Yambo databases: <code>ndb.elph_gkkp*</code>, Yambopy class: <code>YamboElectronPhononDB</code>; LetzElPhC databases: <code>ndb.elph</code>, Yambopy class: <code>LetzElphElectronPhononDB</code>).

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/yambopy_electron_phonon.tar.gz
tar -xvzf yambopy_electron_phonon.tar.gz
cd electron_phonon

We will work with monolayer molybdenum disulphide electron-phonon data obtained on a <code>6x6x1</code> 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''' and '''Quantum ESPRESSO''' 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

Here you will find:
* A scf input file for MoS2, <code>scf/mos2.scf</code>
* A dvscf input file for MoS2, <code>dvscf/mos2.dvscf</code>
* A Yambo <code>SAVE</code> directory corresponding to a nscf calculation (this has been run already).
* The pseudopotential files to be used for the calculation.

As a first step, you need to run the Quantum ESPRESSO calculations (it is assumed that you are familiar with this). First run the scf calculation inside <code>scf</code>, then copy the <code>mos2.save</code> directory into the <code>dvscf</code> folder and run the dvscf calculation there. When everything is completed correctly, you will have achieved step 1. above.

Now, you will find the phonon results in the <code>dvscf</code> directory. We also have done a non-self-consistent calculation to be used in Yambo, and created the relative <code>SAVE</code> directory. If you check this directory, you will find the <code>ns.wf</code> databases containing the electronic wavefunctions.

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

In order to do this, we will run the <code>lelphc</code> executable of the '''LetzElPhC''' code (this will be step 2. from above). We will run via command line using yambopy, although it will be instructive to have look at the <code>lelphc</code> input files later.

We run in the same directory where the Yambo <code>SAVE</code> 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>n_i</math> to <math>n_f</math>, we should type:

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

Here <math>n_i</math> and <math>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>[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 <code>lelphc</code> 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 <code>ndb.elph_gkkp*</code> databases you can run <code>yambopy l2y ...</code> with the <code>--no_gkkp</code> option.
* If you don't need the default <code>ndb.elph</code> databases you can run <code>yambopy l2y ...</code> with the <code>--no_lelphc_dbs</code> 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 <code>lelphc</code> executable is in the <code>PATH</code>, you do not need to specify the last flag.

At the end, check your directory: you should find the <code>lelphc.in</code> 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 <code>convention=yambo</code>: 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>n</math> and momentum <math>k-q</math> to band <math>m</math> and momentum <math>k</math>. In the "forward" momentum transfer convention (the more standard one), the transitions go from <math>nk</math> to <math>mk+q</math>. Therefore, this variable ensures that the electron-phonon coupling matrix elements are computed as <math>\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 <code>ndb.elph</code> database that contains the computed electron-phonon matrix elements, in the output format of <code>LetzElPhC</code>.

In addition, if you check the <code>SAVE</code> folder:

ls SAVE/ndb.elph_gkkp*

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

If you want to run LetzElPhC directly, without using yambopy, you can refer to its [[https://gitlab.com/lumen-code/LetzElPhC/-/blob/main/docs/main.pdf?ref_type=heads|user guide]].
Keep in mind that in this case, in order to convert the database to the <code>ndb.elph_gkkp*</code> databases of Yambo, you will then need a couple of lines of python using the Yambopy class <code>ConvertElectronPhononDB</code> in <code>yambopy/letzelph_interface/lelph2y.py</code>.

At the end of this section, you should have produced the same databases that you find in the main <code>electron_phonon</code> 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 precomputed ones.

=== Electron-phonon intro: plots of el-ph matrix elements on k-BZ and q-BZ ===
In this section we will use the script <code>elph_plot.py</code> and read the electron-phonon databases that you generated in the previous section.

In order to read the <code>ndb.elph_gkkp_expanded*</code> databases in python we use the Yambopy class <code>YamboElectronPhononDB</code>, which can be instanced like this:
elph = YamboElectronPhononDB(ylat,folder_gkkp='path/to/elph/folder',save='path/to/SAVE')
(notice that it requires a previous instance of <code>YamboLatticeDB</code>).

Instead, in order to read the <code>ndb.elph</code> databases from LetzElPhC, we use a different class:
elph = LetzElphElectronPhononDB('path/to/ndb.elph')

Now, the <code>elph</code> objects contain phonon frequencies, phonon eigenvectors, q-point information and, of course, the electron-phonon matrix elements <math>g_{nm\nu}(k,q)</math> where <math>n</math>, <math>m</math> are electron band states, <math>\nu</math> is a phonon branch, and <math>k</math> and <math>q</math> are the electronic and transfer momenta.

We can print the docstring of the <code>YamboElectronPhononDB</code> class with
print(yelph.__doc__)
and of the <code>LetzElphElectronPhononDB</code> class with
print(lelph.__doc__)
to get an idea of the information stored and of their capabilities.

Now check the <code>elph_plot.py</code> script. Besides choosing which database to load, it also performs two plots:

* Plot of |g(k)| in the k-BZ for selected bands n,m, phonon mode \nu and q [<code>kspace_Plot=True</code>].
* Plot of |g(q)| in the q-BZ for selected bands n,m, phonon mode \nu and k [<code>qspace_Plot=True</code>].

You will see that after loading the database, it first postprocesses the electron-phonon data to obtain a plottable quantity. Indeed, it is not necessarily easy to understand what to plot and what to keep fixed, since the matrix element depends on two momenta and three state indices. In addition, bands or phonon states may be degenerate at certain momenta.

In practice, we set a phonon mode (the eighth mode, this is the branch with symmetry <math>A_1^\prime</math> at zone center) and either a <math>k</math> or <math>q</math> point to keep fixed (in each case, we select the high-symmetry <math>K</math> point). As for the bands, we consider the top two valence bands. These are mostly degenerate, except around the points <math>K</math> and <math>K^\prime</math> where they are split by spin-orbit interaction. We then average over these states before plotting, obtaining the quantity (in k-space below):

<math> I^{\mu}_{<v>q}(\mathbf{k}) = \sqrt{\sum_{v,v^\prime=24,25}|g^{\mu}_{vv^\prime q}(\mathbf{k})|^2}</math>

You are invited to play with the electronic, phononic and momentum indices to see what happens! (beware of degenerate states: if not properly accounted for by the sum of the norms, the plots will be phase-dependent and unphysical)

[[File:MoS2 6x6x1 g vv' in kspace.png|yambopy el-ph plot for tutorial|500px]] [[File:MoS2 6x6x1 g vv' in qspace.png|yambopy el-ph plot for tutorial|500px]]

First steps in Yambopy

2026-03-11T13:32:46Z

FulvioPaleari: /* Tutorials */

Yambopy tutorial: band structures

2026-03-11T12:14:18Z

FulvioPaleari: /* Tutorial 2. Iron. Ferromagnetic metallic material */

This tutorial will show you how to visualise wave-function and band-structure related information, such as atomic, orbital and spin projections, following a DFT Quantum Espresso calculation using the "qepy" module of Yambopy. It also contains a section about Yambo and GW band structures.

The full tutorial, including the Quantum espresso 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/databases_qepy.tar.gz
tar -xvzf databases_qepy.tar.gz
cd databases_qepy

==Tutorial 1. BN (semiconductor). Band structure==

First enter in the folder
cd databases_qepy/bn-semiconductor
and have a look to the
vim plot-qe-bands.py
The qepy classes are useful both to execute Quantum Espresso and to analyze the results. Enter in the python environment, by typing <code>python</code>, then the full qepy library is imported by simply doing:

from qepy import *

However, for this plot we just need two classes, namely:

from qepy import Path,PwXML

===Plot Band structure===

The qepy class '''PwXML''' reads the data file generated by Quantum Espresso and post-processes the data. The class is instanced by doing:

xml = PwXML(prefix='bn', path='bands')

The variable prefix corresponds to the same variable of the QE input. The folder location is indicated by variable path. In order to plot the bands, we also define the k-points path (in crystal coordinates) using the function Path:

npoints = 50
path_kpoints = Path([ [[0.0, 0.0, 0.0],'$\Gamma$'],
[[0.5, 0.0, 0.0],'M'],
[[1./3,1./3,0.0],'K'],
[[0.0, 0.0, 0.0],'$\Gamma$']], [int(npoints*2),int(npoints),int(sqrt(5)*npoints)])

It is worth to note that the path should coincide with the selected path for the QE band calculations.

In order to show the plot we call the '''plot_eigen''' method of the '''PwXML''' class:

xml.plot_eigen(path_kpoints)

This function will automatically plot the bands as shown below running the script:

python plot-qe-bands.py

[[File:Bands BN 1.png| 400 px | center |Band structure of BN calculated at the level of DFT-LDA]]

Alternatively, we can use the function '''plot_eigen_ax'''. This functions requires as input a matplotlib '''figure''' object with given axes, as you will see in the next example.

===Plot atomic orbital projected Band structure===

In addition to the band structure, useful information regarding the atomic orbital nature of the electronic wave functions can be displayed using the class '''ProjwfcXML'''.
In order to make quantum espresso calculate the relevant data, we need to use the QE executable '''projwfc.x''', which will create the file '''atomic_proj.xml'''. This executable projects the Kohn-Sham wavefunctions onto orthogonalized atomic orbitals, among others functionalities. The orbital indexing and ordering are explained in the input documentation of the projwfc.x function which you are invited to check (https://www.quantum-espresso.org/Doc/INPUT_PROJWFC.html#idm94). We can run '''projwf.x''' directly from the python script using the qepy class '''ProjwfcIn''':

proj = ProjwfcIn(prefix='bn')
proj.run(folder='bands')

Be aware that this can take a while in a large system with many k-points. As in the class '''PwXML''', we then define the path_kpoints and also the selected atomic orbitals to project our bands. We have chosen to represent the projection weight onto the nitrogen (1) and boron (2) orbitals, which can be obtained with

# Automatic selection of the states
atom_1 = band.get_states_helper(atom_query=['N'])
atom_2 = band.get_states_helper(atom_query=['B'])

The full list of orbitals is written in the file '''bands/prowfc.log'''. By inspecting it, you may also construct custom lists of states.

We have also defined the figure box

import matplotlib.pyplot as plt
fig = plt.figure(figsize=(5,7))
ax = fig.add_axes( [ 0.12, 0.10, 0.70, 0.80 ])

The class '''ProjwfcXML''' then runs as in this example:

band = ProjwfcXML(prefix='bn',path='bands',qe_version='7.0')
band.plot_eigen(ax,path_kpoints=path_kpoints,cmap='viridis',selected_orbitals=atom_1,selected_orbitals_2=atom_2)

We can run now the file:

python plot-qe-orbitals.py

[[File:Bands AOP BN 1.png| 400 px | center | Atomic orbital projected band structure of monolayer BN]]

We have chosen the colormap 'viridis' (variable cmap). You see that the colormap goes from maximum '''selected_orbitals''' content (in this case nitrogen) to the maximum '''selected_orbitals_2''' content (in this case boron).
The colormap can be represented in many ways and qepy does not include a particular function for this. An example is:

import matplotlib as mpl
cmap=plt.get_cmap('viridis')
bx = fig.add_axes( [ 0.88, 0.10, 0.05, 0.80 ])
norm = mpl.colors.Normalize(vmin=0.,vmax=1.)
cb1 = mpl.colorbar.ColorbarBase(bx, cmap=cmap, norm=norm,orientation='vertical',ticks=[0,1])
cb1.set_ticklabels(['B', 'N'])

Suppose now that we have run the G0W0 calculation from the last tutorial, and we want to represent the atomic weights on top of the quasiparticle band structure instead of the Kohn-Sham one. However, we do not have the same kpoint grid between the G0W0 calculation and the quantum espresso "band" calculation along a path. We can then extract the parameters for a scissor operator (this is done below) and feed them to the '''ProjwfcXML''' class together with the number of valence bands. Try uncommenting the following lines in the tutorial script:

# Add scissor operator to the bands from a G0W0 calculation
scissor= [1.8985195950522469, 1.0265240811345133, 1.051588659878575]
n_val = 4
band.add_scissor(n_val,scissor)

Finally, we can also plot the band orbital character with size variation instead of a color scale. In this case we have to pass only the variable selected_orbitals (see the next tutorial).

==Tutorial 2. Iron. Ferromagnetic metallic material==

In the case of spin-polarized calculations we can plot the spin up and down band structures.

After running a band structure calculation for iron (the results are in the <code>bands</code> folder), we can load the data from the QE xml output files and make the band plot by running the script:

python plot-qe-bands.py

The class <code>PwXML</code> automatically detects the spin polarized case (nspin=2 in the QE input file). The spin up channel is displayed with red and the spin down channel with blue. In the case of iron we have selected this k-point path:

npoints = 50
path_kpoints = Path([ [[0.0, 0.0, 0.0 ],'G'],
[[0.0, 0.0, 1.0 ],'H'],
[[1./2,0.0,1./2.],'N'],
[[0.0, 0.0, 0.0 ],'G'],
[[1./2, 1./2, 1./2 ],'P'],
[[1./2,0.0,1./2. ],'N']], [npoints,npoints,npoints,npoints,npoints])

xml = PwXML(prefix='pw',path='bands/t0')
xml.plot_eigen(path_kpoints)

[[File:Figure 3-iron-bands.png| 600 px | center |Spin polarized band structure of iron calculated by DFT]]

The analysis of the projected atomic orbitals is also implemented. In this case the results are more cumbersome because the projection is separated in spin up and down channels. 
Let us look first at the file '''plot-qe-orbitals-size'''. 

'''NB: If you generated your own qe band structure instead of relying on the precomputed databases, you can run the quantum espresso executable projwfc.x to compute the orbital projections using yambopy. In this case, please uncomment the following lines in the script''' (plot-qe-orbitals-size.py) :
#proj = ProjwfcIn(prefix='pw')
#proj.run(folder='bands')

Now, we can use the dot size as a function of the weight of the orbitals
# Automatic selection of the states
s = band.get_states_helper(orbital_query=['s'])
p = band.get_states_helper(orbital_query=['p'])
d = band.get_states_helper(orbital_query=['d'])

and the plots are done with
band = ProjwfcXML(prefix='pw',path='bands',qe_version='7.0')
band.plot_eigen(ax,path_kpoints=path_kpoints,selected_orbitals=s,color='pink',color_2='black')
band.plot_eigen(ax,path_kpoints=path_kpoints,selected_orbitals=p,color='green',color_2='orange')
band.plot_eigen(ax,path_kpoints=path_kpoints,selected_orbitals=d,color='red',color_2='blue')

As an example, we can select just the ''d'' orbitals by commenting the first two plots and then running the file:

plot-qe-orbitals-size.py

[[File:Figure 4-iron-bands-size-d-orbitals.png|400px|center|Iron band structure. Size is proportional to the weights of the projection on atomic d-orbitals. Red (blue) is up (down) spin polarization.]]

From the plot is clear that ''d'' orbitals are mainly localized around the Fermi energy. The plot above is in red and blue, while the default choice in your script should be pink and black. You can experiment with the colors and other ''matplotlib'' plot options and also plot the other orbital types.

Another option is to plot the orbital composition as a colormap running the file:

plot-qe-orbitals-colormap.py

[[File:Figure 5-iron-bands-colormap.png|400px|center]]

Here we have added the p and d orbitals in the analysis:

p = band.get_states_helper(orbital_query=['p'])
d = band.get_states_helper(orbital_query=['d'])
band = ProjwfcXML(prefix='pw',path='bands',qe_version='7.0')
band.plot_eigen(ax,path_kpoints=path_kpoints,cmap='viridis',cmap2='rainbow',selected_orbitals=p,selected_orbitals_2=d)

The colormap bar is added in the same way as in Tutorial 1 (see script), but this time we have a different colormap for each spin polarisation.

==Tutorial 3: GW bands==

Yambopy can be used either to run Yambo and QE calculations, or to analyse the results of QE and Yambo by dealing with their generated databases. This is done with a variety of classes included in the qepy (for QE) or yambopy (for Yambo) modules.
In the case of Yambo GW quasi-particle calculations, we can use the yambopy class '''YamboQPDB''' to read the database produced by the simulation.
Enter in the folder
cd ../gw-bands
We can use this to find the scissor operator, plot the GW bands and to interpolate the GW bands on a smoother k-path. The example runs by typing:

python plot-qp.py

See below for an explanation of the tutorial. As usual, we can import the qepy and yambopy libraries (in addition to the standard modules we will need):

from yambopy import YamboLatticeDB,YamboQPDB # Load yambo netcdf databases
from qepy import Path # Define path in k-space
import numpy as np
import matplotlib.pyplot as plt
from math import sqrt

We define the k-points path.
npoints = 10
path = Path([ [[ 0.0, 0.0, 0.0],'$\Gamma$'],
[[ 0.5, 0.0, 0.0],'M'],
[[1./3.,1./3., 0.0],'K'],
[[ 0.0, 0.0, 0.0],'$\Gamma$']], [int(npoints*2),int(npoints),int(sqrt(5)*npoints)] )

Importantly, the number of points is a free choice. We can increase the variable npoints as we wish, it just means that the interpolation step will take more time. In order to analyse GW results we need to have the file related to the basic data of our Yambo calculation ('''SAVE/ns.db1''') and the netcdf file with the quasi-particle results ('''ndb.QP'''). We load the data calling the respective classes:

# Read Lattice information from SAVE
## Note: we do not expand the kpts because QP database is in the IBZ
lat = YamboLatticeDB.from_db_file(filename='SAVE/ns.db1',Expand=False)
# Read QP database
ydb = YamboQPDB.from_db(filename='ndb.QP',folder='qp-gw')

The first option is to plot the energies and calculate the ideal Kohn-Sham to GW scissor operator. We need to select the index of the top valence band:

n_top_vb = 4
ydb.plot_scissor_ax(ax,n_top_vb)

Yambopy displays the fitting and also the data of the slope of each fitting. Notice that this is also a test if the GW calculations are running well. '''If the dependence is not linear you should double-check your results!'''

[[File:Figure 6-slope-scissor.png|400px|center]]

In this case the slope is:

valence bands:
slope: 1.0515886598785766
conduction bands:
slope: 1.026524081134514
scissor list (shift,c,v) [eV,adim,adim]: [1.8985204833551723, 1.026524081134514, 1.0515886598785766]

In addition to the scissor operator, we can plot the GW (and DFT) band structure along the path. The first choice would be to plot the actual GW calculations, without interpolation, to check that the results are meaningful (or not). This plot is independent of the number of k-points ('''npoints''') that we want to put in the interpolation. The class YamboQPDB finds the calculated points that belong to the path and plots them. Be aware that if we use coarse grids the class would not find any point and the function will not work.

ks_bs_0, qp_bs_0 = ydb.get_bs_path(lat,path)
ks_bs_0.plot_ax(ax,legend=True,c_bands='r',label='KS')
qp_bs_0.plot_ax(ax,legend=True,c_bands='b',label='QP-GW')

[[File:Figure 7-GW-band-structure-non-interpolated.png|400px|center]]

The interpolation of the DFT and GW band structures looks similar:

ks_bs, qp_bs = ydb.interpolate(lat,path,what='QP+KS',lpratio=20)
ks_bs.plot_ax(ax,legend=True,c_bands='r',label='KS')
qp_bs.plot_ax(ax,legend=True,c_bands='b',label='QP-GW')

The '''lpratio''' can be increased if the interpolation does not work as well as intended. The SKW interpolation scheme is the same on implemented in Abipy.

[[File:Figure 8-GW-band-structure-interpolated.png|400px|center]]

Finally, we can compare the calculated GW eigenvalues with the interpolation.

[[File:Figure 8-GW-band-structure-comparison.png|400px|center]]

As always, remember that you can do your own script, the one provided is just an example.

'''What to do if the interpolation does not seem to work well'''

* First of all, you can try to modify the '''lpratio''' parameter and see if it improves.

* If it does not, often you can obtain better results by just interpolating the '''differences''' between QP and DFT energies. This can be done by first subtracting the DFT value from the QP energies, then interpolate, and finally re-add the DFT interpolated values. You can also run a separate band structure calculation in DFT on a dense grid (so that you don't need to interpolate the DFT energies) and read it into your script either with <code>qepy</code> or <code>YamboElectronsDB</code> after creating a SAVE directory. If you have (i) a QP calculation and SAVE on the original grid and (ii) a DFT SAVE on a denser grid, you could do this directly via the <code>interpolate_QP_corrections</code> method in <code>YamboQPDB</code>.

* If this also does not improve anything, consider that the quality of the interpolation improves the denser your actual calculated kmesh is. Thus, as a last resort, you can try to run an '''additional''' GW calculation on a '''shifted k-point grid'''. For example, you shift it by (0.5,0.5,0.5) in fractional coordinates. Yambo is able to calculate the self-energy corrections on this grid without recalculating the screening. Now, you have effectively doubled the k-density of your QP corrections. In this case, you have to do a bit of yambopy scripting yourself to merge the two databases and obtain the band plot: this is an advanced application but you can do everything with the tools yambopy makes available.

==Links==
* Back to [[Rome 2023#Tutorials]]
* Back to [[ICTP 2022#Tutorials]]

Yambopy tutorial: electron-phonon coupling

2026-03-11T10:37:29Z

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

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

# Quantum Espresso calculation of phonon energies, eigenmodes and variations of the self-consistent potential via <code>ph.x</code>.
# Electron-phonon matrix element calculation, symmetry expansion and conversion by the <code>LetzElPhC</code>.

For more information on the <code>LetzElPhC</code> code and how you should run step 1., please see the related documentation [https://github.com/yambo-code/LetzElPhC here].

We can use Yambopy to:
* Run <code>LetzElPhC</code> (both preprocessing and main run) without explicitly writing an input file.
* Convert the resulting databases into <code>Yambo</code> format.
* Analyse the electron-phonon coupling both in <code>LetzElPhC</code> or <code>Yambo</code> format.

In particular we will take a look at:
* Lattice geometry data (Yambo database: <code>ns.db1</code>, Yambopy class: <code>YamboLatticeDB</code>).
* Electron-phonon matrix elements (Yambo databases: <code>ndb.elph_gkkp*</code>, Yambopy class: <code>YamboElectronPhononDB</code>; LetzElPhC databases: <code>ndb.elph</code>, Yambopy class: <code>LetzElphElectronPhononDB</code>).

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 <code>6x6x1</code> 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''' and '''Quantum ESPRESSO''' 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

Here you will find:
* A scf input file for MoS2, <code>scf/mos2.scf</code>
* A dvscf input file for MoS2, <code>dvscf/mos2.dvscf</code>
* A Yambo <code>SAVE</code> directory corresponding to a nscf calculation (this has been run already).
* The pseudopotential files to be used for the calculation.

As a first step, you need to run the Quantum ESPRESSO calculations (it is assumed that you are familiar with this). First run the scf calculation inside <code>scf</code>, then copy the <code>mos2.save</code> directory into the <code>dvscf</code> folder and run the dvscf calculation there. When everything is completed correctly, you will have achieved step 1. above.

Now, you will find the phonon results in the <code>dvscf</code> directory. We also have done a non-self-consistent calculation to be used in Yambo, and created the relative <code>SAVE</code> directory. If you check this directory, you will find the <code>ns.wf</code> databases containing the electronic wavefunctions.

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

In order to do this, we will run the <code>lelphc</code> executable of the '''LetzElPhC''' code (this will be step 2. from above). We will run via command line using yambopy, although it will be instructive to have look at the <code>lelphc</code> input files later.

We run in the same directory where the Yambo <code>SAVE</code> 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>n_i</math> to <math>n_f</math>, we should type:

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

Here <math>n_i</math> and <math>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>[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 <code>lelphc</code> 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 <code>ndb.elph_gkkp*</code> databases you can run <code>yambopy l2y ...</code> with the <code>--no_gkkp</code> option.
* If you don't need the default <code>ndb.elph</code> databases you can run <code>yambopy l2y ...</code> with the <code>--no_lelphc_dbs</code> 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 <code>lelphc</code> executable is in the <code>PATH</code>, you do not need to specify the last flag.

At the end, check your directory: you should find the <code>lelphc.in</code> 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 <code>convention=yambo</code>: 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>n</math> and momentum <math>k-q</math> to band <math>m</math> and momentum <math>k</math>. In the "forward" momentum transfer convention (the more standard one), the transitions go from <math>nk</math> to <math>mk+q</math>. Therefore, this variable ensures that the electron-phonon coupling matrix elements are computed as <math>\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 <code>ndb.elph</code> database that contains the computed electron-phonon matrix elements, in the output format of <code>LetzElPhC</code>.

In addition, if you check the <code>SAVE</code> folder:

ls SAVE/ndb.elph_gkkp*

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

If you want to run LetzElPhC directly, without using yambopy, you can refer to its [[https://gitlab.com/lumen-code/LetzElPhC/-/blob/main/docs/main.pdf?ref_type=heads|user guide]].
Keep in mind that in this case, in order to convert the database to the <code>ndb.elph_gkkp*</code> databases of Yambo, you will then need a couple of lines of python using the Yambopy class <code>ConvertElectronPhononDB</code> in <code>yambopy/letzelph_interface/lelph2y.py</code>.

At the end of this section, you should have produced the same databases that you find in the main <code>electron_phonon</code> 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 precomputed ones.

=== Electron-phonon intro: plots of el-ph matrix elements on k-BZ and q-BZ ===
In this section we will use the script <code>elph_plot.py</code> and read the electron-phonon databases that you generated in the previous section.

In order to read the <code>ndb.elph_gkkp_expanded*</code> databases in python we use the Yambopy class <code>YamboElectronPhononDB</code>, which can be instanced like this:
elph = YamboElectronPhononDB(ylat,folder_gkkp='path/to/elph/folder',save='path/to/SAVE')
(notice that it requires a previous instance of <code>YamboLatticeDB</code>).

Instead, in order to read the <code>ndb.elph</code> databases from LetzElPhC, we use a different class:
elph = LetzElphElectronPhononDB('path/to/ndb.elph')

Now, the <code>elph</code> objects contain phonon frequencies, phonon eigenvectors, q-point information and, of course, the electron-phonon matrix elements <math>g_{nm\nu}(k,q)</math> where <math>n</math>, <math>m</math> are electron band states, <math>\nu</math> is a phonon branch, and <math>k</math> and <math>q</math> are the electronic and transfer momenta.

We can print the docstring of the <code>YamboElectronPhononDB</code> class with
print(yelph.__doc__)
and of the <code>LetzElphElectronPhononDB</code> class with
print(lelph.__doc__)
to get an idea of the information stored and of their capabilities.

Now check the <code>elph_plot.py</code> script. Besides choosing which database to load, it also performs two plots:

* Plot of |g(k)| in the k-BZ for selected bands n,m, phonon mode \nu and q [<code>kspace_Plot=True</code>].
* Plot of |g(q)| in the q-BZ for selected bands n,m, phonon mode \nu and k [<code>qspace_Plot=True</code>].

You will see that after loading the database, it first postprocesses the electron-phonon data to obtain a plottable quantity. Indeed, it is not necessarily easy to understand what to plot and what to keep fixed, since the matrix element depends on two momenta and three state indices. In addition, bands or phonon states may be degenerate at certain momenta.

In practice, we set a phonon mode (the eighth mode, this is the branch with symmetry <math>A_1^\prime</math> at zone center) and either a <math>k</math> or <math>q</math> point to keep fixed (in each case, we select the high-symmetry <math>K</math> point). As for the bands, we consider the top two valence bands. These are mostly degenerate, except around the points <math>K</math> and <math>K^\prime</math> where they are split by spin-orbit interaction. We then average over these states before plotting, obtaining the quantity (in k-space below):

<math> I^{\mu}_{<v>q}(\mathbf{k}) = \sqrt{\sum_{v,v^\prime=24,25}|g^{\mu}_{vv^\prime q}(\mathbf{k})|^2}</math>

You are invited to play with the electronic, phononic and momentum indices to see what happens! (beware of degenerate states: if not properly accounted for by the sum of the norms, the plots will be phase-dependent and unphysical)

[[File:MoS2 6x6x1 g vv' in kspace.png|yambopy el-ph plot for tutorial|500px]] [[File:MoS2 6x6x1 g vv' in qspace.png|yambopy el-ph plot for tutorial|500px]]

Yambopy tutorial: electron-phonon coupling

2026-03-11T10:36:55Z

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

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

# Quantum Espresso calculation of phonon energies, eigenmodes and variations of the self-consistent potential via <code>ph.x</code>.
# Electron-phonon matrix element calculation, symmetry expansion and conversion by the <code>LetzElPhC</code>.

For more information on the <code>LetzElPhC</code> code and how you should run step 1., please see the related documentation [https://github.com/yambo-code/LetzElPhC here].

We can use Yambopy to:
* Run <code>LetzElPhC</code> (both preprocessing and main run) without explicitly writing an input file.
* Convert the resulting databases into <code>Yambo</code> format.
* Analyse the electron-phonon coupling both in <code>LetzElPhC</code> or <code>Yambo</code> format.

In particular we will take a look at:
* Lattice geometry data (Yambo database: <code>ns.db1</code>, Yambopy class: <code>YamboLatticeDB</code>).
* Electron-phonon matrix elements (Yambo databases: <code>ndb.elph_gkkp*</code>, Yambopy class: <code>YamboElectronPhononDB</code>; LetzElPhC databases: <code>ndb.elph</code>, Yambopy class: <code>LetzElphElectronPhononDB</code>).

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 <code>6x6x1</code> 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''' and '''Quantum ESPRESSO''' 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

Here you will find:
* A scf input file for MoS2, <code>scf/mos2.scf</code>
* A dvscf input file for MoS2, <code>dvscf/mos2.dvscf</code>
* A Yambo <code>SAVE</code> directory corresponding to a nscf calculation (this has been run already).
* The pseudopotential files to be used for the calculation.

As a first step, you need to run the Quantum ESPRESSO calculations (it is assumed that you are familiar with this). First run the scf calculation inside <code>scf</code>, then copy the <code>mos2.save</code> directory into the <code>dvscf</code> folder and run the dvscf calculation there. When everything is completed correctly, you will have achieved step 1. above.

Now, you will find the phonon results in the <code>dvscf</code> directory. We also have done a non-self-consistent calculation to be used in Yambo, and created the relative <code>SAVE</code> directory. If you check this directory, you will find the <code>ns.wf</code> databases containing the electronic wavefunctions.

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

In order to do this, we will run the <code>lelphc</code> executable of the '''LetzElPhC''' code (this will be step 2. from above). We will run via command line using yambopy, although it will be instructive to have look at the <code>lelphc</code> input files later.

We run in the same directory where the Yambo <code>SAVE</code> 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>n_i</math> to <math>n_f</math>, we should type:

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

Here <math>n_i</math> and <math>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>[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 <code>lelphc</code> 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 <code>ndb.elph_gkkp*</code> databases you can run <code>yambopy l2y ...</code> with the <code>--no_gkkp</code> option.
* If you don't need the default <code>ndb.elph</code> databases you can run <code>yambopy l2y ...</code> with the <code>--no_lelphc_dbs</code> 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 <code>lelphc</code> executable is in the <code>PATH</code>, you do not need to specify the last flag.

At the end, check your directory: you should find the <code>lelphc.in</code> 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 <code>convention=yambo</code>: 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>n</math> and momentum <math>k-q</math> to band <math>m</math> and momentum <math>k</math>. In the "forward" momentum transfer convention (the more standard one), the transitions go from <math>nk</math> to <math>mk+q</math>. Therefore, this variable ensures that the electron-phonon coupling matrix elements are computed as <math>\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 <code>ndb.elph</code> database that contains the computed electron-phonon matrix elements, in the output format of <code>LetzElPhC</code>.

In addition, if you check the <code>SAVE</code> folder:

ls SAVE/ndb.elph_gkkp*

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

If you want to run LetzElPhC directly, without using yambopy, you can refer to its [[https://gitlab.com/lumen-code/LetzElPhC/-/blob/main/docs/main.pdf?ref_type=heads|user guide]].
Keep in mind that in this case, in order to convert the database to the <code>ndb.elph_gkkp*</code> databases of Yambo, you will then need a couple of lines of python using the Yambopy class <code>ConvertElectronPhononDB</code> in <code>yambopy/letzelph_interface/lelph2y.py</code>.

At the end of this section, you should have produced the same databases that you find in the main <code>electron_phonon</code> 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 precomputed ones.

=== Electron-phonon intro: plots of el-ph matrix elements on k-BZ and q-BZ ===
In this section we will use the script <code>elph_plot.py</code> and read the electron-phonon databases that you generated in the previous section.

In order to read the <code>ndb.elph_gkkp_expanded*</code> databases in python we use the Yambopy class <code>YamboElectronPhononDB</code>, which can be instanced like this:
elph = YamboElectronPhononDB(ylat,folder_gkkp='path/to/elph/folder',save='path/to/SAVE')
(notice that it requires a previous instance of <code>YamboLatticeDB</code>).

Instead, in order to read the <code>ndb.elph</code> databases from LetzElPhC, we use a different class:
elph = LetzElphElectronPhononDB('path/to/ndb.elph')

Now, the <code>elph</code> objects contain phonon frequencies, phonon eigenvectors, q-point information and, of course, the electron-phonon matrix elements <math>g_{nm\nu}(k,q)</math> where <math>n</math>, <math>m</math> are electron band states, <math>\nu</math> is a phonon branch, and <math>k</math> and <math>q</math> are the electronic and transfer momenta.

We can print the docstring of the <code>YamboElectronPhononDB</code> class with
print(yelph.__doc__)
and of the <code>LetzElphElectronPhononDB</code> class with
print(lelph.__doc__)
to get an idea of the information stored and of their capabilities.

Now check the <code>elph_plot.py</code> script. Besides choosing which database to load, it also performs two plots:

* Plot of |g(k)| in the k-BZ for selected bands n,m, phonon mode \nu and q [<code>kspace_Plot=True</code>].
* Plot of |g(q)| in the q-BZ for selected bands n,m, phonon mode \nu and k [<code>qspace_Plot=True</code>].

You will see that after loading the database, it first postprocesses the electron-phonon data to obtain a plottable quantity. Indeed, it is not necessarily easy to understand what to plot and what to keep fixed, since the matrix element depends on two momenta and three state indices. In addition, bands or phonon states may be degenerate at certain momenta.

In practice, we set a phonon mode (the eighth mode, this is the branch with symmetry <math>A_1^\prime</math> at zone center) and either a <math>k</math> or <math>q</math> point to keep fixed (in each case, we select the high-symmetry <math>K</math> point). As for the bands, we consider the top two valence bands. These are mostly degenerate, except around the points <math>K</math> and <math>K^\prime</math> where they are split by spin-orbit interaction. We then average over these states before plotting, obtaining the quantity (in k-space below):

<math> I^{\mu}_{<v>q}(\mathbf{k}) = \sqrt{\sum_{v,v^\prime=24,25}|g^{\mu}_{vv^\prime q}(\mathbf{k})|^2}</math>

You are invited to play with the electronic, phononic and momentum indices to see what happens! (beware of degenerate states: if not properly accounted for by the sum of the norms, the plots will be phase-dependent and unphysical)

[[File:MoS2 6x6x1 g vv' in kspace.png|yambopy el-ph plot for tutorial|400px]] [[File:MoS2 6x6x1 g vv' in qspace.png|yambopy el-ph plot for tutorial|400px]]

File:MoS2 6x6x1 g vv' in qspace.png

2026-03-11T10:35:14Z

FulvioPaleari: Uploaded own work with UploadWizard

=={{int:filedesc}}==
{{Information
|description={{en|1=Yambo tutorial image}}
|date=2026-03-10
|source={{own}}
|author=[[User:FulvioPaleari|FulvioPaleari]]
|permission=
|other versions=
}}

=={{int:license-header}}==
{{self|cc-by-sa-4.0}}

This file was uploaded with the UploadWizard extension.

[[Category:Uploaded with UploadWizard]]

File:MoS2 6x6x1 g vv' in kspace.png

2026-03-11T10:35:14Z

FulvioPaleari: Uploaded own work with UploadWizard

Yambopy tutorial: electron-phonon coupling

2026-03-10T14:37:47Z

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

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

# Quantum Espresso calculation of phonon energies, eigenmodes and variations of the self-consistent potential via <code>ph.x</code>.
# Electron-phonon matrix element calculation, symmetry expansion and conversion by the <code>LetzElPhC</code>.

For more information on the <code>LetzElPhC</code> code and how you should run step 1., please see the related documentation [https://github.com/yambo-code/LetzElPhC here].

We can use Yambopy to:
* Run <code>LetzElPhC</code> (both preprocessing and main run) without explicitly writing an input file.
* Convert the resulting databases into <code>Yambo</code> format.
* Analyse the electron-phonon coupling both in <code>LetzElPhC</code> or <code>Yambo</code> format.

In particular we will take a look at:
* Lattice geometry data (Yambo database: <code>ns.db1</code>, Yambopy class: <code>YamboLatticeDB</code>).
* Electron-phonon matrix elements (Yambo databases: <code>ndb.elph_gkkp*</code>, Yambopy class: <code>YamboElectronPhononDB</code>; LetzElPhC databases: <code>ndb.elph</code>, Yambopy class: <code>LetzElphElectronPhononDB</code>).

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 <code>6x6x1</code> 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''' and '''Quantum ESPRESSO''' 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

Here you will find:
* A scf input file for MoS2, <code>scf/mos2.scf</code>
* A dvscf input file for MoS2, <code>dvscf/mos2.dvscf</code>
* A Yambo <code>SAVE</code> directory corresponding to a nscf calculation (this has been run already).
* The pseudopotential files to be used for the calculation.

As a first step, you need to run the Quantum ESPRESSO calculations (it is assumed that you are familiar with this). First run the scf calculation inside <code>scf</code>, then copy the <code>mos2.save</code> directory into the <code>dvscf</code> folder and run the dvscf calculation there. When everything is completed correctly, you will have achieved step 1. above.

Now, you will find the phonon results in the <code>dvscf</code> directory. We also have done a non-self-consistent calculation to be used in Yambo, and created the relative <code>SAVE</code> directory. If you check this directory, you will find the <code>ns.wf</code> databases containing the electronic wavefunctions.

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

In order to do this, we will run the <code>lelphc</code> executable of the '''LetzElPhC''' code (this will be step 2. from above). We will run via command line using yambopy, although it will be instructive to have look at the <code>lelphc</code> input files later.

We run in the same directory where the Yambo <code>SAVE</code> 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>n_i</math> to <math>n_f</math>, we should type:

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

Here <math>n_i</math> and <math>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>[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 <code>lelphc</code> 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 <code>ndb.elph_gkkp*</code> databases you can run <code>yambopy l2y ...</code> with the <code>--no_gkkp</code> option.
* If you don't need the default <code>ndb.elph</code> databases you can run <code>yambopy l2y ...</code> with the <code>--no_lelphc_dbs</code> 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 <code>lelphc</code> executable is in the <code>PATH</code>, you do not need to specify the last flag.

At the end, check your directory: you should find the <code>lelphc.in</code> 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 <code>convention=yambo</code>: 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>n</math> and momentum <math>k-q</math> to band <math>m</math> and momentum <math>k</math>. In the "forward" momentum transfer convention (the more standard one), the transitions go from <math>nk</math> to <math>mk+q</math>. Therefore, this variable ensures that the electron-phonon coupling matrix elements are computed as <math>\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 <code>ndb.elph</code> database that contains the computed electron-phonon matrix elements, in the output format of <code>LetzElPhC</code>.

In addition, if you check the <code>SAVE</code> folder:

ls SAVE/ndb.elph_gkkp*

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

If you want to run LetzElPhC directly, without using yambopy, you can refer to its [[https://gitlab.com/lumen-code/LetzElPhC/-/blob/main/docs/main.pdf?ref_type=heads|user guide]].
Keep in mind that in this case, in order to convert the database to the <code>ndb.elph_gkkp*</code> databases of Yambo, you will then need a couple of lines of python using the Yambopy class <code>ConvertElectronPhononDB</code> in <code>yambopy/letzelph_interface/lelph2y.py</code>.

At the end of this section, you should have produced the same databases that you find in the main <code>electron_phonon</code> 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 precomputed ones.

=== Electron-phonon intro: plots of el-ph matrix elements on k-BZ and q-BZ ===
In this section we will use the script <code>elph_plot.py</code> and read the electron-phonon databases that you generated in the previous section.

In order to read the <code>ndb.elph_gkkp_expanded*</code> databases in python we use the Yambopy class <code>YamboElectronPhononDB</code>, which can be instanced like this:
elph = YamboElectronPhononDB(ylat,folder_gkkp='path/to/elph/folder',save='path/to/SAVE')
(notice that it requires a previous instance of <code>YamboLatticeDB</code>).

Instead, in order to read the <code>ndb.elph</code> databases from LetzElPhC, we use a different class:
elph = LetzElphElectronPhononDB('path/to/ndb.elph')

Now, the <code>elph</code> objects contain phonon frequencies, phonon eigenvectors, q-point information and, of course, the electron-phonon matrix elements <math>g_{nm\nu}(k,q)</math> where <math>n</math>, <math>m</math> are electron band states, <math>\nu</math> is a phonon branch, and <math>k</math> and <math>q</math> are the electronic and transfer momenta.

We can print the docstring of the <code>YamboElectronPhononDB</code> class with
print(yelph.__doc__)
and of the <code>LetzElphElectronPhononDB</code> class with
print(lelph.__doc__)
to get an idea of the information stored and of their capabilities.

Now check the <code>elph_plot.py</code> script. Besides choosing which database to load, it also performs two plots:

* Plot of |g(k)| in the k-BZ for selected bands n,m, phonon mode \nu and q [<code>kspace_Plot=True</code>].
* Plot of |g(q)| in the q-BZ for selected bands n,m, phonon mode \nu and k [<code>qspace_Plot=True</code>].

You will see that after loading the database, it first postprocesses the electron-phonon data to obtain a plottable quantity. Indeed, it is not necessarily easy to understand what to plot and what to keep fixed, since the matrix element depends on two momenta and three state indices. In addition, bands or phonon states may be degenerate at certain momenta.

In practice, we set a phonon mode (the eighth mode, this is the branch with symmetry <math>A_1^\prime</math> at zone center) and either a <math>k</math> or <math>q</math> point to keep fixed (in each case, we select the high-symmetry <math>K</math> point). As for the bands, we consider the top two valence bands. These are mostly degenerate, except around the points <math>K</math> and <math>K^\prime</math> where they are split by spin-orbit interaction. We then average over these states before plotting, obtaining the quantity (in k-space below):

<math> I^{\mu}_{<v>q}(\mathbf{k}) = \sqrt{\sum_{v,v^\prime=24,25}|g^{\mu}_{vv^\prime q}(\mathbf{k})|^2}</math>

You are invited to play with the electronic, phononic and momentum indices to see what happens! (beware of degenerate states: if not properly accounted for by the sum of the norms, the plots will be phase-dependent and unphysical)

[[File:Elph hbn.jpg|YamboElectronPhononDB plot from yambopy tutorial|500px]]

Yambopy tutorial: electron-phonon coupling

2026-03-10T14:32:45Z

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

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

# Quantum Espresso calculation of phonon energies, eigenmodes and variations of the self-consistent potential via <code>ph.x</code>.
# Electron-phonon matrix element calculation, symmetry expansion and conversion by the <code>LetzElPhC</code>.

For more information on the <code>LetzElPhC</code> code and how you should run step 1., please see the related documentation [https://github.com/yambo-code/LetzElPhC here].

We can use Yambopy to:
* Run <code>LetzElPhC</code> (both preprocessing and main run) without explicitly writing an input file.
* Convert the resulting databases into <code>Yambo</code> format.
* Analyse the electron-phonon coupling both in <code>LetzElPhC</code> or <code>Yambo</code> format.

In particular we will take a look at:
* Lattice geometry data (Yambo database: <code>ns.db1</code>, Yambopy class: <code>YamboLatticeDB</code>).
* Electron-phonon matrix elements (Yambo databases: <code>ndb.elph_gkkp*</code>, Yambopy class: <code>YamboElectronPhononDB</code>; LetzElPhC databases: <code>ndb.elph</code>, Yambopy class: <code>LetzElphElectronPhononDB</code>).

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 <code>6x6x1</code> 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''' and '''Quantum ESPRESSO''' 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

Here you will find:
* A scf input file for MoS2, <code>scf/mos2.scf</code>
* A dvscf input file for MoS2, <code>dvscf/mos2.dvscf</code>
* A Yambo <code>SAVE</code> directory corresponding to a nscf calculation (this has been run already).
* The pseudopotential files to be used for the calculation.

As a first step, you need to run the Quantum ESPRESSO calculations (it is assumed that you are familiar with this). First run the scf calculation inside <code>scf</code>, then copy the <code>mos2.save</code> directory into the <code>dvscf</code> folder and run the dvscf calculation there. When everything is completed correctly, you will have achieved step 1. above.

Now, you will find the phonon results in the <code>dvscf</code> directory. We also have done a non-self-consistent calculation to be used in Yambo, and created the relative <code>SAVE</code> directory. If you check this directory, you will find the <code>ns.wf</code> databases containing the electronic wavefunctions.

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

In order to do this, we will run the <code>lelphc</code> executable of the '''LetzElPhC''' code (this will be step 2. from above). We will run via command line using yambopy, although it will be instructive to have look at the <code>lelphc</code> input files later.

We run in the same directory where the Yambo <code>SAVE</code> 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>n_i</math> to <math>n_f</math>, we should type:

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

Here <math>n_i</math> and <math>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>[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 <code>lelphc</code> 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 <code>ndb.elph_gkkp*</code> databases you can run <code>yambopy l2y ...</code> with the <code>--no_gkkp</code> option.
* If you don't need the default <code>ndb.elph</code> databases you can run <code>yambopy l2y ...</code> with the <code>--no_lelphc_dbs</code> 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 <code>lelphc</code> executable is in the <code>PATH</code>, you do not need to specify the last flag.

At the end, check your directory: you should find the <code>lelphc.in</code> 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 <code>convention=yambo</code>: 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>n</math> and momentum <math>k-q</math> to band <math>m</math> and momentum <math>k</math>. In the "forward" momentum transfer convention (the more standard one), the transitions go from <math>nk</math> to <math>mk+q</math>. Therefore, this variable ensures that the electron-phonon coupling matrix elements are computed as <math>\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 <code>ndb.elph</code> database that contains the computed electron-phonon matrix elements, in the output format of <code>LetzElPhC</code>.

In addition, if you check the <code>SAVE</code> folder:

ls SAVE/ndb.elph_gkkp*

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

If you want to run LetzElPhC directly, without using yambopy, you can refer to its [[https://gitlab.com/lumen-code/LetzElPhC/-/blob/main/docs/main.pdf?ref_type=heads|user guide]].
Keep in mind that in this case, in order to convert the database to the <code>ndb.elph_gkkp*</code> databases of Yambo, you will then need a couple of lines of python using the Yambopy class <code>ConvertElectronPhononDB</code> in <code>yambopy/letzelph_interface/lelph2y.py</code>.

At the end of this section, you should have produced the same databases that you find in the main <code>electron_phonon</code> 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 precomputed ones.

=== Electron-phonon intro: plots of el-ph matrix elements on k-BZ and q-BZ ===
In this section we will use the script <code>elph_plot.py</code> and read the electron-phonon databases that you generated in the previous section.

In order to read the <code>ndb.elph_gkkp_expanded*</code> databases in python we use the Yambopy class <code>YamboElectronPhononDB</code>, which can be instanced like this:
elph = YamboElectronPhononDB(ylat,folder_gkkp='path/to/elph/folder',save='path/to/SAVE')
(notice that it requires a previous instance of <code>YamboLatticeDB</code>).

Instead, in order to read the <code>ndb.elph</code> databases from LetzElPhC, we use a different class:
elph = LetzElphElectronPhononDB('path/to/ndb.elph')

Now, the <code>elph</code> objects contain phonon frequencies, phonon eigenvectors, q-point information and, of course, the electron-phonon matrix elements <math>g_{nm\nu}(k,q)</math> where <math>n</math>, <math>m</math> are electron band states, <math>\nu</math> is a phonon branch, and <math>k</math> and <math>q</math> are the electronic and transfer momenta.

We can print the docstring of the <code>YamboElectronPhononDB</code> class with
print(yelph.__doc__)
and of the <code>LetzElphElectronPhononDB</code> class with
print(lelph.__doc__)
to get an idea of the information stored and of their capabilities.

Now check the <code>elph_plot.py</code> script. You will see that after loading the database, it first postprocesses the electron-phonon data to obtain a plottable quantity.
In practice, we set a phonon mode (the eighth mode, this is the branch with symmetry <math>A_1^\prime</math> at zone center) and either a <math>k</math> or <math>q</math> point to keep fixed (in each case, we select the high-symmetry <math>K</math> point). As for the bands, we consider the top two valence bands. These are mostly degenerate, except around the points <math>K</math> and <math>K^\prime</math> where they are split by spin-orbit interaction. We then average over these states before plotting, obtaining the quantity:

<math> I^{\mu}_{<v>q}(\mathbf{k}) = \sqrt{\sum_{v,v^\prime=24,25}|g^{\mu}_{vv^\prime q}(\mathbf{k})|^2}</math>

performs two plots:
* Plot of |g(k)| in the k-BZ for selected n,m,\nu and q [<code>Kspace_Plot=True</code>].
* Plot of |g(q)| in the q-BZ for selected n,m,\nu and k [<code>Qspace_Plot=True</code>].

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

[[File:Elph hbn.jpg|YamboElectronPhononDB plot from yambopy tutorial|500px]]

Yambopy tutorial: electron-phonon coupling

2026-03-10T13:30:59Z

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

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

# Quantum Espresso calculation of phonon energies, eigenmodes and variations of the self-consistent potential via <code>ph.x</code>.
# Electron-phonon matrix element calculation, symmetry expansion and conversion by the <code>LetzElPhC</code>.

For more information on the <code>LetzElPhC</code> code and how you should run step 1., please see the related documentation [https://github.com/yambo-code/LetzElPhC here].

We can use Yambopy to:
* Run <code>LetzElPhC</code> (both preprocessing and main run) without explicitly writing an input file.
* Convert the resulting databases into <code>Yambo</code> format.
* Analyse the electron-phonon coupling both in <code>LetzElPhC</code> or <code>Yambo</code> format.

In particular we will take a look at:
* Lattice geometry data (Yambo database: <code>ns.db1</code>, Yambopy class: <code>YamboLatticeDB</code>).
* Electron-phonon matrix elements (Yambo databases: <code>ndb.elph_gkkp*</code>, Yambopy class: <code>YamboElectronPhononDB</code>; LetzElPhC databases: <code>ndb.elph</code>, Yambopy class: <code>LetzElphElectronPhononDB</code>).

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 <code>6x6x1</code> 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''' and '''Quantum ESPRESSO''' 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

Here you will find:
* A scf input file for MoS2, <code>scf/mos2.scf</code>
* A dvscf input file for MoS2, <code>dvscf/mos2.dvscf</code>
* A Yambo <code>SAVE</code> directory corresponding to a nscf calculation (this has been run already).
* The pseudopotential files to be used for the calculation.

As a first step, you need to run the Quantum ESPRESSO calculations (it is assumed that you are familiar with this). First run the scf calculation inside <code>scf</code>, then copy the <code>mos2.save</code> directory into the <code>dvscf</code> folder and run the dvscf calculation there. When everything is completed correctly, you will have achieved step 1. above.

Now, you will find the phonon results in the <code>dvscf</code> directory. We also have done a non-self-consistent calculation to be used in Yambo, and created the relative <code>SAVE</code> directory. If you check this directory, you will find the <code>ns.wf</code> databases containing the electronic wavefunctions.

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

In order to do this, we will run the <code>lelphc</code> executable of the '''LetzElPhC''' code (this will be step 2. from above). We will run via command line using yambopy, although it will be instructive to have look at the <code>lelphc</code> input files later.

We run in the same directory where the Yambo <code>SAVE</code> 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>n_i</math> to <math>n_f</math>, we should type:

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

Here <math>n_i</math> and <math>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>[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 <code>lelphc</code> 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 <code>ndb.elph_gkkp*</code> databases you can run <code>yambopy l2y ...</code> with the <code>--no_gkkp</code> option.
* If you don't need the default <code>ndb.elph</code> databases you can run <code>yambopy l2y ...</code> with the <code>--no_lelphc_dbs</code> 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 <code>lelphc</code> executable is in the <code>PATH</code>, you do not need to specify the last flag.

At the end, check your directory: you should find the <code>lelphc.in</code> 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 <code>convention=yambo</code>: 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>n</math> and momentum <math>k-q</math> to band <math>m</math> and momentum <math>k</math>. In the "forward" momentum transfer convention (the more standard one), the transitions go from <math>nk</math> to <math>mk+q</math>. Therefore, this variable ensures that the electron-phonon coupling matrix elements are computed as <math>\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 <code>ndb.elph</code> database that contains the computed electron-phonon matrix elements, in the output format of <code>LetzElPhC</code>.

In addition, if you check the <code>SAVE</code> folder:

ls SAVE/ndb.elph_gkkp*

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

If you want to run LetzElPhC directly, without using yambopy, you can refer to its [[https://gitlab.com/lumen-code/LetzElPhC/-/blob/main/docs/main.pdf?ref_type=heads|user guide]].
Keep in mind that in this case, in order to convert the database to the <code>ndb.elph_gkkp*</code> databases of Yambo, you will then need a couple of lines of python using the Yambopy class <code>ConvertElectronPhononDB</code> in <code>yambopy/letzelph_interface/lelph2y.py</code>.

At the end of this section, you should have produced the same databases that you find in the main <code>electron_phonon</code> 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 precomputed ones.

=== Electron-phonon intro: plots of el-ph matrix elements on k-BZ and q-BZ ===
In this section we will use the script <code>elph_plot.py</code> and read the electron-phonon databases that you generated in the previous section.

In order to read the <code>ndb.elph_gkkp_expanded*</code> databases in python we use the Yambopy class <code>YamboElectronPhononDB</code>, which can be instanced like this:
elph = YamboElectronPhononDB(ylat,folder_gkkp='path/to/elph/folder',save='path/to/SAVE')
(notice that it requires a previous instance of <code>YamboLatticeDB</code>).

Instead, in order to read the <code>ndb.elph</code> databases from LetzElPhC, we use a different class:
elph = LetzElphElectronPhononDB('path/to/ndb.elph')

Now, the <code>elph</code> objects contain phonon frequencies, phonon eigenvectors, q-point information and, of course, the electron-phonon matrix elements <math>g_{nm\nu}(k,q)</math> where <math>n</math>, <math>m</math> are electron band states, <math>\nu</math> is a phonon branch, and <math>k</math> and <math>q</math> are the electronic and transfer momenta.

We can print the docstring of the <code>YamboElectronPhononDB</code> class with
print(yelph.__doc__)
and of the <code>LetzElphElectronPhononDB</code> class with
print(lelph.__doc__)
to get an idea of the information stored and of their capabilities.

Now check the <code>elph_plot.py</code> script. You will see that it performs two plots:
* Plot of |g(k)| in the k-BZ for selected n,m,\nu and q [<code>Kspace_Plot=True</code>].
* Plot of |g(q)| in the q-BZ for selected n,m,\nu and k [<code>Qspace_Plot=True</code>].

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

[[File:Elph hbn.jpg|YamboElectronPhononDB plot from yambopy tutorial|500px]]

Yambopy tutorial: electron-phonon coupling

2026-03-10T13:15:33Z

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

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

# Quantum Espresso calculation of phonon energies, eigenmodes and variations of the self-consistent potential via <code>ph.x</code>.
# Electron-phonon matrix element calculation, symmetry expansion and conversion by the <code>LetzElPhC</code>.

For more information on the <code>LetzElPhC</code> code and how you should run step 1., please see the related documentation [https://github.com/yambo-code/LetzElPhC here].

We can use Yambopy to:
* Run <code>LetzElPhC</code> (both preprocessing and main run) without explicitly writing an input file.
* Convert the resulting databases into <code>Yambo</code> format.
* Analyse the electron-phonon coupling both in <code>LetzElPhC</code> or <code>Yambo</code> format.

In particular we will take a look at:
* Lattice geometry data (Yambo database: <code>ns.db1</code>, Yambopy class: <code>YamboLatticeDB</code>).
* Electron-phonon matrix elements (Yambo databases: <code>ndb.elph_gkkp*</code>, Yambopy class: <code>YamboElectronPhononDB</code>; LetzElPhC databases: <code>ndb.elph</code>, Yambopy class: <code>LetzElphElectronPhononDB</code>).

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 <code>6x6x1</code> 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''' and '''Quantum ESPRESSO''' 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

Here you will find:
* A scf input file for MoS2, <code>scf/mos2.scf</code>
* A dvscf input file for MoS2, <code>dvscf/mos2.dvscf</code>
* A Yambo <code>SAVE</code> directory corresponding to a nscf calculation (this has been run already).
* The pseudopotential files to be used for the calculation.

As a first step, you need to run the Quantum ESPRESSO calculations (it is assumed that you are familiar with this). First run the scf calculation inside <code>scf</code>, then copy the <code>mos2.save</code> directory into the <code>dvscf</code> folder and run the dvscf calculation there. When everything is completed correctly, you will have achieved step 1. above.

Now, you will find the phonon results in the <code>dvscf</code> directory. We also have done a non-self-consistent calculation to be used in Yambo, and created the relative <code>SAVE</code> directory. If you check this directory, you will find the <code>ns.wf</code> databases containing the electronic wavefunctions.

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

In order to do this, we will run the <code>lelphc</code> executable of the '''LetzElPhC''' code (this will be step 2. from above). We will run via command line using yambopy, although it will be instructive to have look at the <code>lelphc</code> input files later.

We run in the same directory where the Yambo <code>SAVE</code> 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>n_i</math> to <math>n_f</math>, we should type:

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

Here <math>n_i</math> and <math>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>[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 <code>lelphc</code> 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 <code>ndb.elph_gkkp*</code> databases you can run <code>yambopy l2y ...</code> with the <code>--no_gkkp</code> option.
* If you don't need the default <code>ndb.elph</code> databases you can run <code>yambopy l2y ...</code> with the <code>--no_lelphc_dbs</code> 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 <code>lelphc</code> executable is in the <code>PATH</code>, you do not need to specify the last flag.

At the end, check your directory: you should find the <code>lelphc.in</code> 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 <code>convention=yambo</code>: 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>n</math> and momentum <math>k-q</math> to band <math>m</math> and momentum <math>k</math>. In the "forward" momentum transfer convention (the more standard one), the transitions go from <math>nk</math> to <math>mk+q</math>. Therefore, this variable ensures that the electron-phonon coupling matrix elements are computed as <math>\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 <code>ndb.elph</code> database that contains the computed electron-phonon matrix elements, in the output format of <code>LetzElPhC</code>.

In addition, if you check the <code>SAVE</code> folder:

ls SAVE/ndb.elph_gkkp*

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

If you want to run LetzElPhC directly, without using yambopy, you can refer to its [[https://gitlab.com/lumen-code/LetzElPhC/-/blob/main/docs/main.pdf?ref_type=heads|user guide]].
Keep in mind that in this case, in order to convert the database to the <code>ndb.elph_gkkp*</code> databases of Yambo, you will then need a couple of lines of python using the Yambopy class <code>ConvertElectronPhononDB</code> in <code>yambopy/letzelph_interface/lelph2y.py</code>.

At the end of this section, you should have produced the same databases that you find in the main <code>electron_phonon</code> 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 precomputed ones.

=== Electron-phonon intro: plots of el-ph matrix elements on k-BZ and q-BZ ===
In this section we will use the script <code>elph_plot.py</code> and read the electron-phonon databases that you generated in the previous section.

In order to read the <code>ndb.elph_gkkp_expanded*</code> databases in python we use the Yambopy class <code>YamboElectronPhononDB</code>, 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 <code>YamboLatticeDB</code>).

Instead, in order to read the <code>ndb.elph</code> databases from LetzElPhC, we use a different class:
lelph = LetzElphElectronPhononDB('path/to/ndb.elph')

Now, the <code>*elph</code> objects contain phonon frequencies, phonon eigenvectors, q-point information and, of course, the electron-phonon matrix elements <math>g_{nm\nu}(k,q)</math> where <math>n</math>, <math>m</math> are electron band states, <math>\nu</math> is a phonon branch, and <math>k</math> and <math>q</math> are the electronic and transfer momenta.

We can print the docstring of the <code>YamboElectronPhononDB</code> class with
print(yelph.__doc__)
and of the <code>LetzElphElectronPhononDB</code> class with
print(lelph.__doc__)
to get an idea of the information stored and of their capabilities.

Now check the <code>elph_plot.py</code> script. You will see that it performs two plots:
* Plot of |g(k)| in the k-BZ for selected n,m,\nu and q [<code>Kspace_Plot=True</code>].
* Plot of |g(q)| in the q-BZ for selected n,m,\nu and k [<code>Qspace_Plot=True</code>].

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

[[File:Elph hbn.jpg|YamboElectronPhononDB plot from yambopy tutorial|500px]]

Yambopy tutorial: electron-phonon coupling

2026-03-10T13:14:05Z

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

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

# Quantum Espresso calculation of phonon energies, eigenmodes and variations of the self-consistent potential via <code>ph.x</code>.
# Electron-phonon matrix element calculation, symmetry expansion and conversion by the <code>LetzElPhC</code>.

For more information on the <code>LetzElPhC</code> code and how you should run step 1., please see the related documentation [https://github.com/yambo-code/LetzElPhC here].

We can use Yambopy to:
* Run <code>LetzElPhC</code> (both preprocessing and main run) without explicitly writing an input file.
* Convert the resulting databases into <code>Yambo</code> format.
* Analyse the electron-phonon coupling both in <code>LetzElPhC</code> or <code>Yambo</code> format.

In particular we will take a look at:
* Lattice geometry data (Yambo database: <code>ns.db1</code>, Yambopy class: <code>YamboLatticeDB</code>).
* Electron-phonon matrix elements (Yambo databases: <code>ndb.elph_gkkp*</code>, Yambopy class: <code>YamboElectronPhononDB</code>; LetzElPhC databases: <code>ndb.elph</code>, Yambopy class: <code>LetzElphElectronPhononDB</code>).

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 <code>6x6x1</code> 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''' and '''Quantum ESPRESSO''' 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

Here you will find:
* A scf input file for MoS2, <code>scf/mos2.scf</code>
* A dvscf input file for MoS2, <code>dvscf/mos2.dvscf</code>
* A Yambo <code>SAVE</code> directory corresponding to a nscf calculation (this has been run already).
* The pseudopotential files to be used for the calculation.

As a first step, you need to run the Quantum ESPRESSO calculations (it is assumed that you are familiar with this). First run the scf calculation inside <code>scf</code>, then copy the <code>mos2.save</code> directory into the <code>dvscf</code> folder and run the dvscf calculation there. When everything is completed correctly, you will have achieved step 1. above.

Now, you will find the phonon results in the <code>dvscf</code> directory. We also have done a non-self-consistent calculation to be used in Yambo, and created the relative <code>SAVE</code> directory. If you check this directory, you will find the <code>ns.wf</code> databases containing the electronic wavefunctions.

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

In order to do this, we will run the <code>lelphc</code> executable of the '''LetzElPhC''' code (this will be step 2. from above). We will run via command line using yambopy, although it will be instructive to have look at the <code>lelphc</code> input files later.

We run in the same directory where the Yambo <code>SAVE</code> 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>n_i</math> to <math>n_f</math>, we should type:

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

Here <math>n_i</math> and <math>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>[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 <code>lelphc</code> 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 <code>ndb.elph_gkkp*</code> databases you can run <code>yambopy l2y ...</code> with the <code>--no_gkkp</code> option.
* If you don't need the default <code>ndb.elph</code> databases you can run <code>yambopy l2y ...</code> with the <code>--no_lelphc_dbs</code> 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 <code>lelphc</code> executable is in the <code>PATH</code>, you do not need to specify the last flag.

At the end, check your directory: you should find the <code>lelphc.in</code> 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 <code>convention=yambo</code>: 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>n</math> and momentum <math>k-q</math> to band <math>m</math> and momentum <math>k</math>. In the "forward" momentum transfer convention (the more standard one), the transitions go from <math>nk</math> to <math>mk+q</math>. Therefore, this variable ensures that the electron-phonon coupling matrix elements are computed as <math>\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 <code>ndb.elph</code> database that contains the computed electron-phonon matrix elements, in the output format of <code>LetzElPhC</code>.

In addition, if you check the <code>SAVE</code> folder:

ls SAVE/ndb.elph_gkkp*

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

If you want to run LetzElPhC directly, without using yambopy, you can refer to its [[https://gitlab.com/lumen-code/LetzElPhC/-/blob/main/docs/main.pdf?ref_type=heads|user guide]].
Keep in mind that in this case, in order to convert the database to the <code>ndb.elph_gkkp*</code> databases of Yambo, you will then need a couple of lines of python using the Yambopy class <code>ConvertElectronPhononDB</code> in <code>yambopy/letzelph_interface/lelph2y.py</code>.

At the end of this section, you should have produced the same databases that you find in the main <code>electron_phonon</code> 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.

=== Electron-phonon intro: plots of el-ph matrix elements on k-BZ and q-BZ ===
In this section we will use the script <code>elph_plot.py</code> and read the electron-phonon databases that you generated in the previous section.

In order to read the <code>ndb.elph_gkkp_expanded*</code> databases in python we use the Yambopy class <code>YamboElectronPhononDB</code>, 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 <code>YamboLatticeDB</code>).

Instead, in order to read the <code>ndb.elph</code> databases from LetzElPhC, we use a different class:
lelph = LetzElphElectronPhononDB('path/to/ndb.elph')

Now, the <code>*elph</code> objects contain phonon frequencies, phonon eigenvectors, q-point information and, of course, the electron-phonon matrix elements <math>g_{nm\nu}(k,q)</math> where <math>n</math>, <math>m</math> are electron band states, <math>\nu</math> is a phonon branch, and <math>k</math> and <math>q</math> are the electronic and transfer momenta.

We can print the docstring of the <code>YamboElectronPhononDB</code> class with
print(yelph.__doc__)
and of the <code>LetzElphElectronPhononDB</code> class with
print(lelph.__doc__)
to get an idea of the information stored and of their capabilities.

Now check the <code>elph_plot.py</code> script. You will see that it performs two plots:
* Plot of |g(k)| in the k-BZ for selected n,m,\nu and q [<code>Kspace_Plot=True</code>].
* Plot of |g(q)| in the q-BZ for selected n,m,\nu and k [<code>Qspace_Plot=True</code>].

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

[[File:Elph hbn.jpg|YamboElectronPhononDB plot from yambopy tutorial|500px]]

Yambopy tutorial: electron-phonon coupling

2026-03-10T13:13:23Z

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

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

# Quantum Espresso calculation of phonon energies, eigenmodes and variations of the self-consistent potential via <code>ph.x</code>.
# Electron-phonon matrix element calculation, symmetry expansion and conversion by the <code>LetzElPhC</code>.

For more information on the <code>LetzElPhC</code> code and how you should run step 1., please see the related documentation [https://github.com/yambo-code/LetzElPhC here].

We can use Yambopy to:
* Run <code>LetzElPhC</code> (both preprocessing and main run) without explicitly writing an input file.
* Convert the resulting databases into <code>Yambo</code> format.
* Analyse the electron-phonon coupling both in <code>LetzElPhC</code> or <code>Yambo</code> format.

In particular we will take a look at:
* Lattice geometry data (Yambo database: <code>ns.db1</code>, Yambopy class: <code>YamboLatticeDB</code>).
* Electron-phonon matrix elements (Yambo databases: <code>ndb.elph_gkkp*</code>, Yambopy class: <code>YamboElectronPhononDB</code>; LetzElPhC databases: <code>ndb.elph</code>, Yambopy class: <code>LetzElphElectronPhononDB</code>).

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 <code>6x6x1</code> 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''' and '''Quantum ESPRESSO''' 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

Here you will find:
* A scf input file for MoS2, <code>scf/mos2.scf</code>
* A dvscf input file for MoS2, <code>dvscf/mos2.dvscf</code>
* A Yambo <code>SAVE</code> directory corresponding to a nscf calculation (this has been run already).
* The pseudopotential files to be used for the calculation.

As a first step, you need to run the Quantum ESPRESSO calculations (it is assumed that you are familiar with this). First run the scf calculation inside <code>scf</code>, then copy the <code>mos2.save</code> directory into the <code>dvscf</code> folder and run the dvscf calculation there. When everything is completed correctly, you will have achieved step 1. above.

Now, you will find the phonon results in the <code>dvscf</code> directory. We also have done a non-self-consistent calculation to be used in Yambo, and created the relative <code>SAVE</code> directory. If you check this directory, you will find the <code>ns.wf</code> containing the electronic wavefunctions.

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

In order to do this, we will run the <code>lelphc</code> executable of the '''LetzElPhC''' code (this will be step 2. from above). We will run via command line using yambopy, although it will be instructive to have look at the <code>lelphc</code> input files later.

We run in the same directory where the Yambo <code>SAVE</code> 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>n_i</math> to <math>n_f</math>, we should type:

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

Here <math>n_i</math> and <math>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>[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 <code>lelphc</code> 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 <code>ndb.elph_gkkp*</code> databases you can run <code>yambopy l2y ...</code> with the <code>--no_gkkp</code> option.
* If you don't need the default <code>ndb.elph</code> databases you can run <code>yambopy l2y ...</code> with the <code>--no_lelphc_dbs</code> 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 <code>lelphc</code> executable is in the <code>PATH</code>, you do not need to specify the last flag.

At the end, check your directory: you should find the <code>lelphc.in</code> 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 <code>convention=yambo</code>: 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>n</math> and momentum <math>k-q</math> to band <math>m</math> and momentum <math>k</math>. In the "forward" momentum transfer convention (the more standard one), the transitions go from <math>nk</math> to <math>mk+q</math>. Therefore, this variable ensures that the electron-phonon coupling matrix elements are computed as <math>\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 <code>ndb.elph</code> database that contains the computed electron-phonon matrix elements, in the output format of <code>LetzElPhC</code>.

In addition, if you check the <code>SAVE</code> folder:

ls SAVE/ndb.elph_gkkp*

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

If you want to run LetzElPhC directly, without using yambopy, you can refer to its [[https://gitlab.com/lumen-code/LetzElPhC/-/blob/main/docs/main.pdf?ref_type=heads|user guide]].
Keep in mind that in this case, in order to convert the database to the <code>ndb.elph_gkkp*</code> databases of Yambo, you will then need a couple of lines of python using the Yambopy class <code>ConvertElectronPhononDB</code> in <code>yambopy/letzelph_interface/lelph2y.py</code>.

At the end of this section, you should have produced the same databases that you find in the main <code>electron_phonon</code> 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.

=== Electron-phonon intro: plots of el-ph matrix elements on k-BZ and q-BZ ===
In this section we will use the script <code>elph_plot.py</code> and read the electron-phonon databases that you generated in the previous section.

In order to read the <code>ndb.elph_gkkp_expanded*</code> databases in python we use the Yambopy class <code>YamboElectronPhononDB</code>, 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 <code>YamboLatticeDB</code>).

Instead, in order to read the <code>ndb.elph</code> databases from LetzElPhC, we use a different class:
lelph = LetzElphElectronPhononDB('path/to/ndb.elph')

Now, the <code>*elph</code> objects contain phonon frequencies, phonon eigenvectors, q-point information and, of course, the electron-phonon matrix elements <math>g_{nm\nu}(k,q)</math> where <math>n</math>, <math>m</math> are electron band states, <math>\nu</math> is a phonon branch, and <math>k</math> and <math>q</math> are the electronic and transfer momenta.

We can print the docstring of the <code>YamboElectronPhononDB</code> class with
print(yelph.__doc__)
and of the <code>LetzElphElectronPhononDB</code> class with
print(lelph.__doc__)
to get an idea of the information stored and of their capabilities.

Now check the <code>elph_plot.py</code> script. You will see that it performs two plots:
* Plot of |g(k)| in the k-BZ for selected n,m,\nu and q [<code>Kspace_Plot=True</code>].
* Plot of |g(q)| in the q-BZ for selected n,m,\nu and k [<code>Qspace_Plot=True</code>].

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

[[File:Elph hbn.jpg|YamboElectronPhononDB plot from yambopy tutorial|500px]]

Yambopy tutorial: electron-phonon coupling

2026-03-10T11:27:43Z

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

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

# Quantum Espresso calculation of phonon energies, eigenmodes and variations of the self-consistent potential via <code>ph.x</code>.
# Electron-phonon matrix element calculation, symmetry expansion and conversion by the <code>LetzElPhC</code>.

For more information on the <code>LetzElPhC</code> code and how you should run step 1., please see the related documentation [https://github.com/yambo-code/LetzElPhC here].

We can use Yambopy to:
* Run <code>LetzElPhC</code> (both preprocessing and main run) without explicitly writing an input file.
* Convert the resulting databases into <code>Yambo</code> format.
* Analyse the electron-phonon coupling both in <code>LetzElPhC</code> or <code>Yambo</code> format.

In particular we will take a look at:
* Lattice geometry data (Yambo database: <code>ns.db1</code>, Yambopy class: <code>YamboLatticeDB</code>).
* Electron-phonon matrix elements (Yambo databases: <code>ndb.elph_gkkp*</code>, Yambopy class: <code>YamboElectronPhononDB</code>; LetzElPhC databases: <code>ndb.elph</code>, Yambopy class: <code>LetzElphElectronPhononDB</code>).

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 <code>6x6x1</code> 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 <code>dvscf</code> directory. We also have done a non-self-consistent calculation to be used in Yambo, and created the relative <code>SAVE</code> directory.

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

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

We run in the same directory where the Yambo <code>SAVE</code> 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>n_i</math> to <math>n_f</math>, we should type:

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

Here <math>n_i</math> and <math>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>[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 <code>lelphc</code> 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 <code>ndb.elph_gkkp*</code> databases you can run <code>yambopy l2y ...</code> with the <code>--no_gkkp</code> option.
* If you don't need the default <code>ndb.elph</code> databases you can run <code>yambopy l2y ...</code> with the <code>--no_lelphc_dbs</code> 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 <code>lelphc</code> executable is in the <code>PATH</code>, you do not need to specify the last flag.

At the end, check your directory: you should find the <code>lelphc.in</code> 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 <code>convention=yambo</code>: 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>n</math> and momentum <math>k-q</math> to band <math>m</math> and momentum <math>k</math>. In the "forward" momentum transfer convention (the more standard one), the transitions go from <math>nk</math> to <math>mk+q</math>. Therefore, this variable ensures that the electron-phonon coupling matrix elements are computed as <math>\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 <code>ndb.elph</code> database that contains the computed electron-phonon matrix elements, in the output format of <code>LetzElPhC</code>.

In addition, if you check the <code>SAVE</code> folder:

ls SAVE/ndb.elph_gkkp*

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

If you want to run LetzElPhC directly, without using yambopy, you can refer to its [[https://gitlab.com/lumen-code/LetzElPhC/-/blob/main/docs/main.pdf?ref_type=heads|user guide]].
Keep in mind that in this case, in order to convert the database to the <code>ndb.elph_gkkp*</code> databases of Yambo, you will then need a couple of lines of python using the Yambopy class <code>ConvertElectronPhononDB</code> in <code>yambopy/letzelph_interface/lelph2y.py</code>.

At the end of this section, you should have produced the same databases that you find in the main <code>electron_phonon</code> 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.

=== Electron-phonon intro: plots of el-ph matrix elements on k-BZ and q-BZ ===
In this section we will use the script <code>elph_plot.py</code> and read the electron-phonon databases that you generated in the previous section.

In order to read the <code>ndb.elph_gkkp_expanded*</code> databases in python we use the Yambopy class <code>YamboElectronPhononDB</code>, 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 <code>YamboLatticeDB</code>).

Instead, in order to read the <code>ndb.elph</code> databases from LetzElPhC, we use a different class:
lelph = LetzElphElectronPhononDB('path/to/ndb.elph')

Now, the <code>*elph</code> objects contain phonon frequencies, phonon eigenvectors, q-point information and, of course, the electron-phonon matrix elements <math>g_{nm\nu}(k,q)</math> where <math>n</math>, <math>m</math> are electron band states, <math>\nu</math> is a phonon branch, and <math>k</math> and <math>q</math> are the electronic and transfer momenta.

We can print the docstring of the <code>YamboElectronPhononDB</code> class with
print(yelph.__doc__)
and of the <code>LetzElphElectronPhononDB</code> class with
print(lelph.__doc__)
to get an idea of the information stored and of their capabilities.

Now check the <code>elph_plot.py</code> script. You will see that it performs two plots:
* Plot of |g(k)| in the k-BZ for selected n,m,\nu and q [<code>Kspace_Plot=True</code>].
* Plot of |g(q)| in the q-BZ for selected n,m,\nu and k [<code>Qspace_Plot=True</code>].

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

[[File:Elph hbn.jpg|YamboElectronPhononDB plot from yambopy tutorial|500px]]

Yambopy tutorial: electron-phonon coupling

2026-03-10T11:04:58Z

FulvioPaleari:

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

# Quantum Espresso calculation of phonon energies, eigenmodes and variations of the self-consistent potential via <code>ph.x</code>.
# Electron-phonon matrix element calculation, symmetry expansion and conversion by the <code>LetzElPhC</code>.

For more information on the <code>LetzElPhC</code> code and how you should run step 1., please see the related documentation [https://github.com/yambo-code/LetzElPhC here].

We can use Yambopy to:
* Run <code>LetzElPhC</code> (both preprocessing and main run) without explicitly writing an input file.
* Convert the resulting databases into <code>Yambo</code> format.
* Analyse the electron-phonon coupling both in <code>LetzElPhC</code> or <code>Yambo</code> format.

In particular we will take a look at:
* Lattice geometry data (Yambo database: <code>ns.db1</code>, Yambopy class: <code>YamboLatticeDB</code>).
* Electron-phonon matrix elements (Yambo databases: <code>ndb.elph_gkkp*</code>, Yambopy class: <code>YamboElectronPhononDB</code>; LetzElPhC databases: <code>ndb.elph</code>, Yambopy class: <code>LetzElphElectronPhononDB</code>).

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 <code>6x6x1</code> 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 <code>dvscf</code> directory. We also have done a non-self-consistent calculation to be used in Yambo, and created the relative <code>SAVE</code> directory.

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

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

We run in the same directory where the Yambo <code>SAVE</code> 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>n_i</math> to <math>n_f</math>, we should type:

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

Here <math>n_i</math> and <math>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>[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 <code>lelphc</code> 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 <code>ndb.elph_gkkp*</code> databases you can run <code>yambopy l2y ...</code> with the <code>--no_gkkp</code> option.
* If you don't need the default <code>ndb.elph</code> databases you can run <code>yambopy l2y ...</code> with the <code>--no_lelphc_dbs</code> 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 <code>lelphc</code> executable is in the <code>PATH</code>, you do not need to specify the last flag.

At the end, check your directory: you should find the <code>lelphc.in</code> 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 <code>convention=yambo</code>: 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>n</math> and momentum <math>k-q</math> to band <math>m</math> and momentum <math>k</math>. In the "forward" momentum transfer convention (the more standard one), the transitions go from <math>nk</math> to <math>mk+q</math>. Therefore, this variable ensures that the electron-phonon coupling matrix elements are computed as <math>\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 <code>ndb.elph</code> database that contains the computed electron-phonon matrix elements, in the output format of <code>LetzElPhC</code>.

In addition, if you check the <code>SAVE</code> folder:

ls SAVE/ndb.elph_gkkp*

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

If you want to run LetzElPhC directly, without using yambopy, you can refer to its [[https://gitlab.com/lumen-code/LetzElPhC/-/blob/main/docs/main.pdf?ref_type=heads|user guide]].
Keep in mind that in this case, in order to convert the database to the <code>ndb.elph_gkkp*</code> databases of Yambo, you will then need a couple of lines of python using the Yambopy class <code>ConvertElectronPhononDB</code> in <code>yambopy/letzelph_interface/lelph2y.py</code>.

At the end of this section, you should have produced the same databases that you find in the main <code>electron_phonon</code> 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.

=== Electron-phonon intro: plots of el-ph matrix elements on k-BZ and q-BZ ===
In this section we will use the script <code>elph_plot.py</code> and read the electron-phonon databases that you generated in the previous section.

In order to read the <code>ndb.elph_gkkp_expanded*</code> databases in python we use the Yambopy class <code>YamboElectronPhononDB</code>, 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 <code>YamboLatticeDB</code>).

Now, the <code>yelph</code> 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 <code>YamboElectronPhononDB</code> class with
print(yelph.__doc__)
to get an idea of the information stored and of its capabilities.

Now check the <code>elph_plot.py</code> script. You will see that it performs two plots:
* Plot of |g(k)| in the k-BZ for selected n,m,\nu and q [<code>Kspace_Plot=True</code>].
* Plot of |g(q)| in the q-BZ for selected n,m,\nu and k [<code>Qspace_Plot=True</code>].

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

[[File:Elph hbn.jpg|YamboElectronPhononDB plot from yambopy tutorial|500px]]

Yambopy tutorial: electron-phonon coupling

2026-03-10T10:49:26Z

FulvioPaleari: /* Command line: electron-phonon calculation and databases */

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

# Quantum Espresso calculation of phonon energies, eigenmodes and variations of the self-consistent potential via <code>ph.x</code>.
# Electron-phonon matrix element calculation, symmetry expansion and conversion by the <code>LetzElPhC</code>.

For more information on the <code>LetzElPhC</code> code and how you should run step 1., please see the related documentation [https://github.com/yambo-code/LetzElPhC here].

We can use Yambopy to:
* Run <code>LetzElPhC</code> (both preprocessing and main run) without explicitly writing an input file.
* Convert the resulting databases into <code>Yambo</code> format.
* Analyse the electron-phonon coupling both in <code>LetzElPhC</code> or <code>Yambo</code> 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 <code>6x6x1</code> 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 <code>dvscf</code> directory. We also have done a non-self-consistent calculation to be used in Yambo, and created the relative <code>SAVE</code> directory.

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

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

We run in the same directory where the Yambo <code>SAVE</code> 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>n_i</math> to <math>n_f</math>, we should type:

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

Here <math>n_i</math> and <math>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>[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 <code>lelphc</code> 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 <code>ndb.elph_gkkp*</code> databases you can run <code>yambopy l2y ...</code> with the <code>--no_gkkp</code> option.
* If you don't need the default <code>ndb.elph</code> databases you can run <code>yambopy l2y ...</code> with the <code>--no_lelphc_dbs</code> 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 <code>lelphc</code> executable is in the <code>PATH</code>, you do not need to specify the last flag.

At the end, check your directory: you should find the <code>lelphc.in</code> 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 <code>convention=yambo</code>: 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>n</math> and momentum <math>k-q</math> to band <math>m</math> and momentum <math>k</math>. In the "forward" momentum transfer convention (the more standard one), the transitions go from <math>nk</math> to <math>mk+q</math>. Therefore, this variable ensures that the electron-phonon coupling matrix elements are computed as <math>\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 <code>ndb.elph</code> database that contains the computed electron-phonon matrix elements, in the output format of <code>LetzElPhC</code>.

In addition, if you check the <code>SAVE</code> folder:

ls SAVE/ndb.elph_gkkp*

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

If you want to run LetzElPhC directly, without using yambopy, you can refer to its [[https://gitlab.com/lumen-code/LetzElPhC/-/blob/main/docs/main.pdf?ref_type=heads|user guide]].
Keep in mind that in this case, in order to convert the database to the <code>ndb.elph_gkkp*</code> databases of Yambo, you will then need a couple of lines of python using the Yambopy class <code>ConvertElectronPhononDB</code> in <code>yambopy/letzelph_interface/lelph2y.py</code>.

At the end of this section, you should have produced the same databases that you find in the main <code>electron_phonon</code> 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.

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

=== 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 Coupling|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 <code>ELPH_SAVES/QE_SAVES/hBN.save</code> (nscf calculation) and <code>ELPH_SAVES/QE_SAVES/elph_dir</code> (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 <code>ndb.elph_gkkp_expanded*</code> 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 <code>elph_plot.py</code> and read the electron-phonon databases that you generated in the previous section.

In order to read the <code>ndb.elph_gkkp_expanded*</code> databases in python we use the Yambopy class <code>YamboElectronPhononDB</code>, 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 <code>YamboLatticeDB</code>).

Now, the <code>yelph</code> 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 <code>YamboElectronPhononDB</code> class with
print(yelph.__doc__)
to get an idea of the information stored and of its capabilities.

Now check the <code>elph_plot.py</code> script. You will see that it performs two plots:
* Plot of |g(k)| in the k-BZ for selected n,m,\nu and q [<code>Kspace_Plot=True</code>].
* Plot of |g(q)| in the q-BZ for selected n,m,\nu and k [<code>Qspace_Plot=True</code>].

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

[[File:Elph hbn.jpg|YamboElectronPhononDB plot from yambopy tutorial|500px]]

Yambopy tutorial: electron-phonon coupling

2026-03-10T10:48:58Z

FulvioPaleari: /* Command line: electron-phonon calculation and databases */

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

# Quantum Espresso calculation of phonon energies, eigenmodes and variations of the self-consistent potential via <code>ph.x</code>.
# Electron-phonon matrix element calculation, symmetry expansion and conversion by the <code>LetzElPhC</code>.

For more information on the <code>LetzElPhC</code> code and how you should run step 1., please see the related documentation [https://github.com/yambo-code/LetzElPhC here].

We can use Yambopy to:
* Run <code>LetzElPhC</code> (both preprocessing and main run) without explicitly writing an input file.
* Convert the resulting databases into <code>Yambo</code> format.
* Analyse the electron-phonon coupling both in <code>LetzElPhC</code> or <code>Yambo</code> 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 <code>6x6x1</code> 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 ===
'''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 <code>dvscf</code> directory. We also have done a non-self-consistent calculation to be used in Yambo, and created the relative <code>SAVE</code> directory.

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

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

We run in the same directory where the Yambo <code>SAVE</code> 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>n_i</math> to <math>n_f</math>, we should type:

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

Here <math>n_i</math> and <math>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>[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 <code>lelphc</code> 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 <code>ndb.elph_gkkp*</code> databases you can run <code>yambopy l2y ...</code> with the <code>--no_gkkp</code> option.
* If you don't need the default <code>ndb.elph</code> databases you can run <code>yambopy l2y ...</code> with the <code>--no_lelphc_dbs</code> 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 <code>lelphc</code> executable is in the <code>PATH</code>, you do not need to specify the last flag.

At the end, check your directory: you should find the <code>lelphc.in</code> 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 <code>convention=yambo</code>: 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>n</math> and momentum <math>k-q</math> to band <math>m</math> and momentum <math>k</math>. In the "forward" momentum transfer convention (the more standard one), the transitions go from <math>nk</math> to <math>mk+q</math>. Therefore, this variable ensures that the electron-phonon coupling matrix elements are computed as <math>\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 <code>ndb.elph</code> database that contains the computed electron-phonon matrix elements, in the output format of <code>LetzElPhC</code>.

In addition, if you check the <code>SAVE</code> folder:

ls SAVE/ndb.elph_gkkp*

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

If you want to run LetzElPhC directly, without using yambopy, you can refer to its [[https://gitlab.com/lumen-code/LetzElPhC/-/blob/main/docs/main.pdf?ref_type=heads|user guide]].
Keep in mind that in this case, in order to convert the database to the <code>ndb.elph_gkkp*</code> databases of Yambo, you will then need a couple of lines of python using the Yambopy class <code>ConvertElectronPhononDB</code> in <code>yambopy/letzelph_interface/lelph2y.py</code>.

At the end of this section, you should have produced the same databases that you find in the main <code>electron_phonon</code> 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.

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

=== 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 Coupling|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 <code>ELPH_SAVES/QE_SAVES/hBN.save</code> (nscf calculation) and <code>ELPH_SAVES/QE_SAVES/elph_dir</code> (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 <code>ndb.elph_gkkp_expanded*</code> 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 <code>elph_plot.py</code> and read the electron-phonon databases that you generated in the previous section.

In order to read the <code>ndb.elph_gkkp_expanded*</code> databases in python we use the Yambopy class <code>YamboElectronPhononDB</code>, 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 <code>YamboLatticeDB</code>).

Now, the <code>yelph</code> 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 <code>YamboElectronPhononDB</code> class with
print(yelph.__doc__)
to get an idea of the information stored and of its capabilities.

Now check the <code>elph_plot.py</code> script. You will see that it performs two plots:
* Plot of |g(k)| in the k-BZ for selected n,m,\nu and q [<code>Kspace_Plot=True</code>].
* Plot of |g(q)| in the q-BZ for selected n,m,\nu and k [<code>Qspace_Plot=True</code>].

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

[[File:Elph hbn.jpg|YamboElectronPhononDB plot from yambopy tutorial|500px]]

Yambopy tutorial: electron-phonon coupling

2026-03-10T10:43:16Z

FulvioPaleari: /* Command line: electron-phonon calculation and databases */

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

# Quantum Espresso calculation of phonon energies, eigenmodes and variations of the self-consistent potential via <code>ph.x</code>.
# Electron-phonon matrix element calculation, symmetry expansion and conversion by the <code>LetzElPhC</code>.

For more information on the <code>LetzElPhC</code> code and how you should run step 1., please see the related documentation [https://github.com/yambo-code/LetzElPhC here].

We can use Yambopy to:
* Run <code>LetzElPhC</code> (both preprocessing and main run) without explicitly writing an input file.
* Convert the resulting databases into <code>Yambo</code> format.
* Analyse the electron-phonon coupling both in <code>LetzElPhC</code> or <code>Yambo</code> 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 <code>6x6x1</code> 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 ===
'''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.

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

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

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

We run in the same directory where the Yambo <code>SAVE</code> 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>n_i</math> to <math>n_f</math>, we should type:

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

Here <math>n_i</math> and <math>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>[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 <code>lelphc</code> 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 <code>ndb.elph_gkkp*</code> databases you can run <code>yambopy l2y ...</code> with the <code>--no_gkkp</code> option.
* If you don't need the default <code>ndb.elph</code> databases you can run <code>yambopy l2y ...</code> with the <code>--no_lelphc_dbs</code> 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 <code>lelphc</code> executable is in the <code>PATH</code>, you do not need to specify the last flag.

At the end, check your directory: you should find the <code>lelphc.in</code> 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 <code>convention=yambo</code>: 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>n</math> and momentum <math>k-q</math> to band <math>m</math> and momentum <math>k</math>. In the "forward" momentum transfer convention (the more standard one), the transitions go from <math>nk</math> to <math>mk+q</math>. Therefore, this variable ensures that the electron-phonon coupling matrix elements are computed as <math>\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 <code>ndb.elph</code> database that contains the computed electron-phonon matrix elements, in the output format of <code>LetzElPhC</code>.

In addition, if you check the <code>SAVE</code> folder:

ls SAVE/ndb.elph_gkkp*

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

If you want to run LetzElPhC directly, without using yambopy, you can refer to its [[https://gitlab.com/lumen-code/LetzElPhC/-/blob/main/docs/main.pdf?ref_type=heads|user guide]].
Keep in mind that in this case, in order to convert the database to the <code>ndb.elph_gkkp*</code> databases of Yambo, you will then need a couple of lines of python using the Yambopy class <code>ConvertElectronPhononDB</code> in <code>yambopy/letzelph_interface/lelph2y.py</code>.

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

=== 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 Coupling|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 <code>ELPH_SAVES/QE_SAVES/hBN.save</code> (nscf calculation) and <code>ELPH_SAVES/QE_SAVES/elph_dir</code> (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 <code>ndb.elph_gkkp_expanded*</code> 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 <code>elph_plot.py</code> and read the electron-phonon databases that you generated in the previous section.

In order to read the <code>ndb.elph_gkkp_expanded*</code> databases in python we use the Yambopy class <code>YamboElectronPhononDB</code>, 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 <code>YamboLatticeDB</code>).

Now, the <code>yelph</code> 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 <code>YamboElectronPhononDB</code> class with
print(yelph.__doc__)
to get an idea of the information stored and of its capabilities.

Now check the <code>elph_plot.py</code> script. You will see that it performs two plots:
* Plot of |g(k)| in the k-BZ for selected n,m,\nu and q [<code>Kspace_Plot=True</code>].
* Plot of |g(q)| in the q-BZ for selected n,m,\nu and k [<code>Qspace_Plot=True</code>].

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

[[File:Elph hbn.jpg|YamboElectronPhononDB plot from yambopy tutorial|500px]]

Yambopy tutorial: electron-phonon coupling

2026-03-10T10:42:50Z

FulvioPaleari: /* Command line: electron-phonon calculation and databases */

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

# Quantum Espresso calculation of phonon energies, eigenmodes and variations of the self-consistent potential via <code>ph.x</code>.
# Electron-phonon matrix element calculation, symmetry expansion and conversion by the <code>LetzElPhC</code>.

For more information on the <code>LetzElPhC</code> code and how you should run step 1., please see the related documentation [https://github.com/yambo-code/LetzElPhC here].

We can use Yambopy to:
* Run <code>LetzElPhC</code> (both preprocessing and main run) without explicitly writing an input file.
* Convert the resulting databases into <code>Yambo</code> format.
* Analyse the electron-phonon coupling both in <code>LetzElPhC</code> or <code>Yambo</code> 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 <code>6x6x1</code> 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 ===
'''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.

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

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

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

We run in the same directory where the Yambo <code>SAVE</code> 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>n_i</math> to <math>n_f</math>, we should type:

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

Here <math>n_i</math> and <math>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>[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 <code>lelphc</code> 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 <code>ndb.elph_gkkp*</code> databases you can run <code>yambopy l2y ...</code> with the <code>--no_gkkp</code> option.
* If you don't need the default <code>ndb.elph</code> databases you can run <code>yambopy l2y ...</code> with the <code>--no_lelphc_dbs</code> 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 <code>lelphc</code> executable is in the <code>PATH</code>, you do not need to specify the last flag.

At the end, check your directory: you should find the <code>lelphc.in</code> 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 <code>convention=yambo</code>: 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>n</math> and momentum <math>k-q</math> to band <math>m</math> and momentum <math>k</math>. In the "forward" momentum transfer convention (the more standard one), the transitions go from <math>nk</math> to <math>mk+q</math>. Therefore, this variable ensures that the electron-phonon coupling matrix elements are computed as <math>\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 <code>ndb.elph</code> database that contains the computed electron-phonon matrix elements, in the output format of <code>LetzElPhC</code>.

In addition, if you check the <code>SAVE</code> folder:

ls SAVE/ndb.elph_gkkp*

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

If you want to run LetzElPhC directly, without using yambopy, you can refer to its [[https://gitlab.com/lumen-code/LetzElPhC/-/blob/main/docs/main.pdf?ref_type=heads|user guide]].
Keep in mind that in this case, in order to convert the database to the <code>ndb.elph_gkkp*</code> databases of Yambo, you will then need a couple of lines of python using the Yambopy class <code>ConvertElectronPhononDB</code> in <code>yambopy/letzelph_interface/lelph2y.py</code>.

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

=== 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 Coupling|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 <code>ELPH_SAVES/QE_SAVES/hBN.save</code> (nscf calculation) and <code>ELPH_SAVES/QE_SAVES/elph_dir</code> (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 <code>ndb.elph_gkkp_expanded*</code> 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 <code>elph_plot.py</code> and read the electron-phonon databases that you generated in the previous section.

In order to read the <code>ndb.elph_gkkp_expanded*</code> databases in python we use the Yambopy class <code>YamboElectronPhononDB</code>, 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 <code>YamboLatticeDB</code>).

Now, the <code>yelph</code> 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 <code>YamboElectronPhononDB</code> class with
print(yelph.__doc__)
to get an idea of the information stored and of its capabilities.

Now check the <code>elph_plot.py</code> script. You will see that it performs two plots:
* Plot of |g(k)| in the k-BZ for selected n,m,\nu and q [<code>Kspace_Plot=True</code>].
* Plot of |g(q)| in the q-BZ for selected n,m,\nu and k [<code>Qspace_Plot=True</code>].

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

[[File:Elph hbn.jpg|YamboElectronPhononDB plot from yambopy tutorial|500px]]

Yambopy tutorial: electron-phonon coupling

2026-03-10T10:42:28Z

FulvioPaleari: /* Command line: electron-phonon calculation and databases */

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

# Quantum Espresso calculation of phonon energies, eigenmodes and variations of the self-consistent potential via <code>ph.x</code>.
# Electron-phonon matrix element calculation, symmetry expansion and conversion by the <code>LetzElPhC</code>.

For more information on the <code>LetzElPhC</code> code and how you should run step 1., please see the related documentation [https://github.com/yambo-code/LetzElPhC here].

We can use Yambopy to:
* Run <code>LetzElPhC</code> (both preprocessing and main run) without explicitly writing an input file.
* Convert the resulting databases into <code>Yambo</code> format.
* Analyse the electron-phonon coupling both in <code>LetzElPhC</code> or <code>Yambo</code> 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 <code>6x6x1</code> 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 ===
'''Note''': you can run this step only if you have compiled <code>LetzElPhC</code> 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.

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

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

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

We run in the same directory where the Yambo <code>SAVE</code> 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>n_i</math> to <math>n_f</math>, we should type:

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

Here <math>n_i</math> and <math>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>[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 <code>lelphc</code> 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 <code>ndb.elph_gkkp*</code> databases you can run <code>yambopy l2y ...</code> with the <code>--no_gkkp</code> option.
* If you don't need the default <code>ndb.elph</code> databases you can run <code>yambopy l2y ...</code> with the <code>--no_lelphc_dbs</code> 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 <code>lelphc</code> executable is in the <code>PATH</code>, you do not need to specify the last flag.

At the end, check your directory: you should find the <code>lelphc.in</code> 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 <code>convention=yambo</code>: 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>n</math> and momentum <math>k-q</math> to band <math>m</math> and momentum <math>k</math>. In the "forward" momentum transfer convention (the more standard one), the transitions go from <math>nk</math> to <math>mk+q</math>. Therefore, this variable ensures that the electron-phonon coupling matrix elements are computed as <math>\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 <code>ndb.elph</code> database that contains the computed electron-phonon matrix elements, in the output format of <code>LetzElPhC</code>.

In addition, if you check the <code>SAVE</code> folder:

ls SAVE/ndb.elph_gkkp*

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

If you want to run LetzElPhC directly, without using yambopy, you can refer to its [[https://gitlab.com/lumen-code/LetzElPhC/-/blob/main/docs/main.pdf?ref_type=heads|user guide]].
Keep in mind that in this case, in order to convert the database to the <code>ndb.elph_gkkp*</code> databases of Yambo, you will then need a couple of lines of python using the Yambopy class <code>ConvertElectronPhononDB</code> in <code>yambopy/letzelph_interface/lelph2y.py</code>.

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

=== 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 Coupling|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 <code>ELPH_SAVES/QE_SAVES/hBN.save</code> (nscf calculation) and <code>ELPH_SAVES/QE_SAVES/elph_dir</code> (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 <code>ndb.elph_gkkp_expanded*</code> 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 <code>elph_plot.py</code> and read the electron-phonon databases that you generated in the previous section.

In order to read the <code>ndb.elph_gkkp_expanded*</code> databases in python we use the Yambopy class <code>YamboElectronPhononDB</code>, 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 <code>YamboLatticeDB</code>).

Now, the <code>yelph</code> 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 <code>YamboElectronPhononDB</code> class with
print(yelph.__doc__)
to get an idea of the information stored and of its capabilities.

Now check the <code>elph_plot.py</code> script. You will see that it performs two plots:
* Plot of |g(k)| in the k-BZ for selected n,m,\nu and q [<code>Kspace_Plot=True</code>].
* Plot of |g(q)| in the q-BZ for selected n,m,\nu and k [<code>Qspace_Plot=True</code>].

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

[[File:Elph hbn.jpg|YamboElectronPhononDB plot from yambopy tutorial|500px]]

Yambopy tutorial: electron-phonon coupling

2026-03-10T10:41:41Z

FulvioPaleari:

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

# Quantum Espresso calculation of phonon energies, eigenmodes and variations of the self-consistent potential via <code>ph.x</code>.
# Electron-phonon matrix element calculation, symmetry expansion and conversion by the <code>LetzElPhC</code>.

For more information on the <code>LetzElPhC</code> code and how you should run step 1., please see the related documentation [https://github.com/yambo-code/LetzElPhC here].

We can use Yambopy to:
* Run <code>LetzElPhC</code> (both preprocessing and main run) without explicitly writing an input file.
* Convert the resulting databases into <code>Yambo</code> format.
* Analyse the electron-phonon coupling both in <code>LetzElPhC</code> or <code>Yambo</code> 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 <code>6x6x1</code> 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 ===
'''Note''': you can run this step only if you have compiled <code>LetzElPhC</code> 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.

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

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

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

We run in the same directory where the Yambo <code>SAVE</code> 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>n_i</math> to <math>n_f</math>, we should type:

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

Here <math>n_i</math> and <math>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>[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 <code>lelphc</code> 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 <code>ndb.elph_gkkp*</code> databases you can run <code>yambopy l2y ...</code> with the <code>--no_gkkp</code> option.
* If you don't need the default <code>ndb.elph</code> databases you can run <code>yambopy l2y ...</code> with the <code>--no_lelphc_dbs</code> 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 <code>lelphc</code> executable is in the <code>PATH</code>, you do not need to specify the last flag.

At the end, check your directory: you should find the <code>lelphc.in</code> 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 <code>convention=yambo</code>: 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>n</math> and momentum <math>k-q</math> to band <math>m</math> and momentum <math>k</math>. In the "forward" momentum transfer convention (the more standard one), the transitions go from <math>nk</math> to <math>mk+q</math>. Therefore, this variable ensures that the electron-phonon coupling matrix elements are computed as <math>\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 <code>ndb.elph</code> database that contains the computed electron-phonon matrix elements, in the output format of <code>LetzElPhC</code>.

In addition, if you check the <code>SAVE</code> folder:

ls SAVE/ndb.elph_gkkp*

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

If you want to run LetzElPhC directly, without using yambopy, you can refer to its [[https://gitlab.com/lumen-code/LetzElPhC/-/blob/main/docs/main.pdf?ref_type=heads|user guide]].
Keep in mind that in this case, in order to convert the database to the <code>ndb.elph_gkkp*</code> databases of Yambo, you will then need a couple of lines of python using the Yambopy class <code>ConvertElectronPhononDB</code> in <code>yambopy/letzelph_interface/lelph2y.py</code>.

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

=== 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 Coupling|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 <code>ELPH_SAVES/QE_SAVES/hBN.save</code> (nscf calculation) and <code>ELPH_SAVES/QE_SAVES/elph_dir</code> (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 <code>ndb.elph_gkkp_expanded*</code> 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 <code>elph_plot.py</code> and read the electron-phonon databases that you generated in the previous section.

In order to read the <code>ndb.elph_gkkp_expanded*</code> databases in python we use the Yambopy class <code>YamboElectronPhononDB</code>, 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 <code>YamboLatticeDB</code>).

Now, the <code>yelph</code> 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 <code>YamboElectronPhononDB</code> class with
print(yelph.__doc__)
to get an idea of the information stored and of its capabilities.

Now check the <code>elph_plot.py</code> script. You will see that it performs two plots:
* Plot of |g(k)| in the k-BZ for selected n,m,\nu and q [<code>Kspace_Plot=True</code>].
* Plot of |g(q)| in the q-BZ for selected n,m,\nu and k [<code>Qspace_Plot=True</code>].

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

[[File:Elph hbn.jpg|YamboElectronPhononDB plot from yambopy tutorial|500px]]

Yambopy tutorial: electron-phonon coupling

2026-03-10T10:40:34Z

FulvioPaleari: /* Command line: electron-phonon calculation and databases */

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

# Quantum Espresso calculation of phonon energies, eigenmodes and variations of the self-consistent potential via <code>ph.x</code>.
# Electron-phonon matrix element calculation, symmetry expansion and conversion by the <code>LetzElPhC</code>.

For more information on the <code>LetzElPhC</code> code and how you should run step 1., please see the related documentation [https://github.com/yambo-code/LetzElPhC here].

We can use Yambopy to:
* Run <code>LetzElPhC</code> (both preprocessing and main run) without explicitly writing an input file.
* Convert the resulting databases into <code>Yambo</code> format.
* Analyse the electron-phonon coupling both in <code>LetzElPhC</code> or <code>Yambo</code> 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 disulfide electron-phonon data obtained on a <code>6x6x1</code> kpoint grid. Beware that these are most certainly not converged.

=== Command line: electron-phonon calculation and databases ===
'''Note''': you can run this step only if you have compiled <code>LetzElPhC</code> 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.

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

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

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

We run in the same directory where the Yambo <code>SAVE</code> 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>n_i</math> to <math>n_f</math>, we should type:

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

Here <math>n_i</math> and <math>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>[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 <code>lelphc</code> 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 <code>ndb.elph_gkkp*</code> databases you can run <code>yambopy l2y ...</code> with the <code>--no_gkkp</code> option.
* If you don't need the default <code>ndb.elph</code> databases you can run <code>yambopy l2y ...</code> with the <code>--no_lelphc_dbs</code> 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 <code>lelphc</code> executable is in the <code>PATH</code>, you do not need to specify the last flag.

At the end, check your directory: you should find the <code>lelphc.in</code> 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 <code>convention=yambo</code>: 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>n</math> and momentum <math>k-q</math> to band <math>m</math> and momentum <math>k</math>. In the "forward" momentum transfer convention (the more standard one), the transitions go from <math>nk</math> to <math>mk+q</math>. Therefore, this variable ensures that the electron-phonon coupling matrix elements are computed as <math>\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 <code>ndb.elph</code> database that contains the computed electron-phonon matrix elements, in the output format of <code>LetzElPhC</code>.

In addition, if you check the <code>SAVE</code> folder:

ls SAVE/ndb.elph_gkkp*

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

If you want to run LetzElPhC directly, without using yambopy, you can refer to its [[https://gitlab.com/lumen-code/LetzElPhC/-/blob/main/docs/main.pdf?ref_type=heads|user guide]].
Keep in mind that in this case, in order to convert the database to the <code>ndb.elph_gkkp*</code> databases of Yambo, you will then need a couple of lines of python using the Yambopy class <code>ConvertElectronPhononDB</code> in <code>yambopy/letzelph_interface/lelph2y.py</code>.

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

=== 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 Coupling|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 <code>ELPH_SAVES/QE_SAVES/hBN.save</code> (nscf calculation) and <code>ELPH_SAVES/QE_SAVES/elph_dir</code> (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 <code>ndb.elph_gkkp_expanded*</code> 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 <code>elph_plot.py</code> and read the electron-phonon databases that you generated in the previous section.

In order to read the <code>ndb.elph_gkkp_expanded*</code> databases in python we use the Yambopy class <code>YamboElectronPhononDB</code>, 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 <code>YamboLatticeDB</code>).

Now, the <code>yelph</code> 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 <code>YamboElectronPhononDB</code> class with
print(yelph.__doc__)
to get an idea of the information stored and of its capabilities.

Now check the <code>elph_plot.py</code> script. You will see that it performs two plots:
* Plot of |g(k)| in the k-BZ for selected n,m,\nu and q [<code>Kspace_Plot=True</code>].
* Plot of |g(q)| in the q-BZ for selected n,m,\nu and k [<code>Qspace_Plot=True</code>].

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

[[File:Elph hbn.jpg|YamboElectronPhononDB plot from yambopy tutorial|500px]]

Yambopy tutorial: electron-phonon coupling

2026-03-10T09:56:10Z

FulvioPaleari:

Yambopy tutorial: electron-phonon coupling

2026-03-10T09:55:20Z

FulvioPaleari:

Yambopy tutorial: electron-phonon coupling

2026-03-10T09:53:27Z

FulvioPaleari:

Yambopy tutorial: electron-phonon coupling

2026-03-10T09:41:36Z

FulvioPaleari:

Yambopy tutorial: electron-phonon coupling

2026-03-10T09:41:01Z

FulvioPaleari:

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 <code>ph.x</code>.
2. Electron-phonon matrix element calculation, symmetry expansion and conversion by the <code>LetzElPhC</code>.

For more information on the <code>LetzElPhC</code> and how you should run step 1., please see the related documentation [https://github.com/yambo-code/LetzElPhC here].

* Electron-phonon matrix elements (Yambo databases: <code>ndb.elph_gkkp*</code>, Yambopy class: <code>YamboElectronPhononDB</code>).

=== Command line: importing electron-phonon matrix elements ===
You may have seen how to calculate and import electron-phonon matrix elements in yambo in the [[Electron Phonon Coupling|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 <code>ELPH_SAVES/QE_SAVES/hBN.save</code> (nscf calculation) and <code>ELPH_SAVES/QE_SAVES/elph_dir</code> (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 <code>ndb.elph_gkkp_expanded*</code> databases.

=== Electron-phonon intro: plots of el-ph matrix elements on k-BZ and q-BZ ===
In this section we will use the script <code>elph_plot.py</code> and read the electron-phonon databases that you generated in the previous section.

In order to read the <code>ndb.elph_gkkp_expanded*</code> databases in python we use the Yambopy class <code>YamboElectronPhononDB</code>, 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 <code>YamboLatticeDB</code>).

Now, the <code>yelph</code> 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 <code>YamboElectronPhononDB</code> class with
print(yelph.__doc__)
to get an idea of the information stored and of its capabilities.

Now check the <code>elph_plot.py</code> script. You will see that it performs two plots:
* Plot of |g(k)| in the k-BZ for selected n,m,\nu and q [<code>Kspace_Plot=True</code>].
* Plot of |g(q)| in the q-BZ for selected n,m,\nu and k [<code>Qspace_Plot=True</code>].

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

[[File:Elph hbn.jpg|YamboElectronPhononDB plot from yambopy tutorial|500px]]

Yambopy tutorial: electron-phonon coupling

2026-03-10T09:40:46Z

FulvioPaleari:

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 <code>ph.x</code>.
2. Electron-phonon matrix element calculation, symmetry expansion and conversion by the <code>LetzElPhC</code>.

For more information on the <code>LetzElPhC</code> and how you should run step 1., please see the related documentation [https://github.com/yambo-code/LetzElPhC | here].

* Electron-phonon matrix elements (Yambo databases: <code>ndb.elph_gkkp*</code>, Yambopy class: <code>YamboElectronPhononDB</code>).

=== Command line: importing electron-phonon matrix elements ===
You may have seen how to calculate and import electron-phonon matrix elements in yambo in the [[Electron Phonon Coupling|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 <code>ELPH_SAVES/QE_SAVES/hBN.save</code> (nscf calculation) and <code>ELPH_SAVES/QE_SAVES/elph_dir</code> (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 <code>ndb.elph_gkkp_expanded*</code> databases.

=== Electron-phonon intro: plots of el-ph matrix elements on k-BZ and q-BZ ===
In this section we will use the script <code>elph_plot.py</code> and read the electron-phonon databases that you generated in the previous section.

In order to read the <code>ndb.elph_gkkp_expanded*</code> databases in python we use the Yambopy class <code>YamboElectronPhononDB</code>, 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 <code>YamboLatticeDB</code>).

Now, the <code>yelph</code> 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 <code>YamboElectronPhononDB</code> class with
print(yelph.__doc__)
to get an idea of the information stored and of its capabilities.

Now check the <code>elph_plot.py</code> script. You will see that it performs two plots:
* Plot of |g(k)| in the k-BZ for selected n,m,\nu and q [<code>Kspace_Plot=True</code>].
* Plot of |g(q)| in the q-BZ for selected n,m,\nu and k [<code>Qspace_Plot=True</code>].

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

[[File:Elph hbn.jpg|YamboElectronPhononDB plot from yambopy tutorial|500px]]

Yambopy tutorial: electron-phonon coupling

2026-03-10T09:40:16Z

FulvioPaleari:

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 <code>ph.x</code>.
2. Electron-phonon matrix element calculation, symmetry expansion and conversion by the <code>LetzElPhC</code>.

For more information on the <code>LetzElPhC</code> and how you should run step 1., please see the related documentation [[https://github.com/yambo-code/LetzElPhC | here]].

* Electron-phonon matrix elements (Yambo databases: <code>ndb.elph_gkkp*</code>, Yambopy class: <code>YamboElectronPhononDB</code>).

=== Command line: importing electron-phonon matrix elements ===
You may have seen how to calculate and import electron-phonon matrix elements in yambo in the [[Electron Phonon Coupling|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 <code>ELPH_SAVES/QE_SAVES/hBN.save</code> (nscf calculation) and <code>ELPH_SAVES/QE_SAVES/elph_dir</code> (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 <code>ndb.elph_gkkp_expanded*</code> databases.

=== Electron-phonon intro: plots of el-ph matrix elements on k-BZ and q-BZ ===
In this section we will use the script <code>elph_plot.py</code> and read the electron-phonon databases that you generated in the previous section.

In order to read the <code>ndb.elph_gkkp_expanded*</code> databases in python we use the Yambopy class <code>YamboElectronPhononDB</code>, 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 <code>YamboLatticeDB</code>).

Now, the <code>yelph</code> 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 <code>YamboElectronPhononDB</code> class with
print(yelph.__doc__)
to get an idea of the information stored and of its capabilities.

Now check the <code>elph_plot.py</code> script. You will see that it performs two plots:
* Plot of |g(k)| in the k-BZ for selected n,m,\nu and q [<code>Kspace_Plot=True</code>].
* Plot of |g(q)| in the q-BZ for selected n,m,\nu and k [<code>Qspace_Plot=True</code>].

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

[[File:Elph hbn.jpg|YamboElectronPhononDB plot from yambopy tutorial|500px]]

Yambopy tutorial: electron-phonon coupling

2026-03-10T09:34:25Z

FulvioPaleari:

In this tutorial we will see some examples on how to read and analyse the data contained in the Yambo netCDF databases, which are not readily available as human readable outputs.

* Electron-phonon matrix elements (Yambo databases: <code>ndb.elph_gkkp*</code>, Yambopy class: <code>YamboElectronPhononDB</code>).

=== Command line: importing electron-phonon matrix elements ===
You may have seen how to calculate and import electron-phonon matrix elements in yambo in the [[Electron Phonon Coupling|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 <code>ELPH_SAVES/QE_SAVES/hBN.save</code> (nscf calculation) and <code>ELPH_SAVES/QE_SAVES/elph_dir</code> (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 <code>ndb.elph_gkkp_expanded*</code> databases.

=== Electron-phonon intro: plots of el-ph matrix elements on k-BZ and q-BZ ===
In this section we will use the script <code>elph_plot.py</code> and read the electron-phonon databases that you generated in the previous section.

In order to read the <code>ndb.elph_gkkp_expanded*</code> databases in python we use the Yambopy class <code>YamboElectronPhononDB</code>, 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 <code>YamboLatticeDB</code>).

Now, the <code>yelph</code> 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 <code>YamboElectronPhononDB</code> class with
print(yelph.__doc__)
to get an idea of the information stored and of its capabilities.

Now check the <code>elph_plot.py</code> script. You will see that it performs two plots:
* Plot of |g(k)| in the k-BZ for selected n,m,\nu and q [<code>Kspace_Plot=True</code>].
* Plot of |g(q)| in the q-BZ for selected n,m,\nu and k [<code>Qspace_Plot=True</code>].

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

[[File:Elph hbn.jpg|YamboElectronPhononDB plot from yambopy tutorial|500px]]

Yambopy tutorial: Yambo databases

2026-03-10T09:34:12Z

FulvioPaleari:

In this tutorial we will see some examples on how to read and analyse the data contained in the Yambo netCDF databases, which are not readily available as human readable outputs.

In particular we will take a look at:
* Lattice geometry data (Yambo database: <code>ns.db1</code>, Yambopy class: <code>YamboLatticeDB</code>).
* Dipole matrix elements (Yambo databases: <code>ndb.dipoles</code>, Yambopy class: <code>YamboDipolesDB</code>).
* Exciton energies, symmetries, wavefunctions and spectra (Yambo databases: <code>ndb.BS_diago_Q*</code>, Yambopy class: <code>YamboExcitonDB</code>).

We will also check the command line instructions to quickly generate yambo SAVE folders.

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

The full tutorial, including the Quantum espresso 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/databases_yambopy.tar.gz
$tar -xvzf databases_yambopy.tar.gz
$cd databases_yambopy

We will work with monolayer hexagonal boron nitride electron-phonon and exciton data obtained on a <code>12x12x1</code> kpoint grid. Beware that these are certainly not converged.

=== Command line: generating the Yambo SAVE ===
Yambopy offers a set of command line options. In order to review them, you can type
$yambopy
which will print the output
yambopy v0.7
Available commands are:

plotem1s -> Plot em1s calculation.
analysebse -> Study the convergence of BSE calculations.
analysegw -> Study the convergence of GW calculations by looking at the change in band-gap value.
plotexcitons -> Plot excitons calculation.
addqp -> Add corrections from QP databases.
mergeqp -> Merge QP databases.
save -> Produce a SAVE folder.
gkkp -> Produce a SAVE folder including elph_gkkp databases.
bands -> Script to produce band structure data and visualization from QE.
serial -> Script to update serial numbers of yambo ndb.* databases in order to import them to new calculations.
gwsubspace -> Script to calculate off-diago corrections of yambo ndb.QP databases in order to plot band structure.
phinp -> Script to update the explicit list of q-points in a ph input file (ldisp=.false., qplot=.true.).
convert -> Script to convert RL number in Ry energy units using ndb.gops.
bsesize -> Script to calculate the expected BSE kernel size, in GB, to be loaded by each MPI task.
l2y -> Calculate gauge-invariant electron-phonon matrix elements with LetzElPhC and convert them into Yambo format.
exc-irrep -> Script to get the irreducible representation labels for excitonic states. [-h for help]
exc-wf -> Real space exciton wf for either fixed hole/electron. [-h for help]
exc-sort -> Script to sort excitonic states according to energies and intensities. [-h for help]

For this tutorial, we will need the <code>save</code> and <code>gkkp</code> options.
By typing in one of these, additional information about how to run the commands will be printed, e.g.:
$yambopy save

Produce a SAVE folder

Arguments are:
-nscf, --nscf_dir -> Path to nscf save folder
-y, --yambo_dir -> <Optional> Path to yambo executables

The quantum espresso save for hBN is provided in the directory <code>BSE_saves/QE_saves/hBN.save</code> (you can check the contents of the various folders).
Then, following the instructions printed on screen, we can generate a yambo SAVE from the hBN.save by typing

$yambopy save -nscf BSE_saves/QE_saves/hBN.save

This should produce a SAVE folder in the current directory.

=== Lattice intro: plot k-point coordinates in IBZ/BZ ===
For this section we will use the script <code>bz_plot.py</code>.

By inspecting the SAVE folder we have just generated, we will find the <code>ns.db1</code> database which contains all the geometry and lattice information.
We are now going to read it in python by using the Yambopy class <code>YamboLatticeDB</code>, which can be instanced like this:

from yambopy import YamboLatticeDB
ylat = YamboLatticeDB.from_db_file(filename="PATH/TO/SAVE/ns.db1")
(remember to edit the variable <code>save_path</code> in order to point at your yambo SAVE).

The <code>ylat</code> object now contains many useful information as attributes, such as the k-points in Cartesian or crystal coordinates, the system symmetries, lattice constants and basis vectors in real and reciprocal space, etc.
The k-points are also automatically expanded in the full Brillouin zone from the irreducible one (you can turn this off with the option <code>Expand=False</code>).

Directly printing the object with
print(ylat)
will also give us some general parameters related to the database.

Now check the <code>bz_plot.py</code> script. You will see that it performs three plots:
* Scatterplot of the k-points in Cartesian coordinates with both expanded and unexpanded grids, with annotated indices [<code>Cartesian_Plot=True</code>].
* Scatterplot of the k-points in crystal coordinates [<code>Crystal_Plot=True</code>].
* Manual transformation of a chosen k-point from irreducible to full Brillouin zone (you can change the index <code>i_k</code> in the script to check different cases) [<code>Symmetry_Plot=True</code>].

Below, the result of the first plot.

[[File:Car kpoints hbn.jpg|YamboLatticeDB plot from yambopy tutorial| 500px]]

'''What about the units?'''

Below we report the relation between units used in Yambo, Quantum Espresso, and Yambopy.

* bohr^-1 (atomic units): <code>YamboLatticeDB.car_kpoints*2.*pi</code>. Divide by the bohr-to-angstrom conversion factor to obtain angs^-1
* Yambo cartesian units (<code>[cc]</code> in Yambo outputs): <code>YamboLatticeDB.car_kpoints*2.*pi</code> (same as above).
* QE cartesian units (<code>[cart. coord. in units 2pi/alat]</code> in QE outputs): <code>YamboLatticeDB.car_kpoints*YamboLatticeDB.alat[0]</code>.
* Internal yambo units (<code>[iku]</code> in yambo outputs): <code>YamboLatticeDB.iku_kpoints</code>
* Fractional coordinates (<code>[rlu]</code> in yambo, <code>cryst. coord.</code> in QE): <code>YamboLatticeDB.red_kpoints</code>.

=== Dipoles intro: plots of dipoles on BZ, plot of IP absorption ===
In this section we will use the script <code>dipoles_plot.py</code> and read the dipole databases generated in an optical absorption calculation by yambo. Keep in mind that from now on we will use the "BSE" yambo SAVE generated in the [[#Command line: generating the Yambo SAVE|first section]].

The databases written after a calculation of optical properties with yambo (dipoles, static screening, excitons) are in the directory <code>BSE_saves/BSE_databases</code>. Here we will also find <code>ndb.dipoles</code> which is needed now, since it contains the matrix elements d_{vck}(\alpha) where vk and ck are the valence and electron states involved in the transition and \alpha the polarisation direction of the external electric field.

In order to read it in python we use the Yambopy class <code>YamboDipolesDB</code>, which can be instanced like this:
ydip = YamboDipolesDB(ylat,save='path/to/BSE/databases',filename='ndb.dipoles')
(notice that it requires a previous instance of <code>YamboLatticeDB</code>).

In addition, in order to read the Kohn-Sham energies, we can also instance the <code>YamboElectronsDB</code> as
yel = YamboElectronsDB.from_db_file(folder='path/to/SAVE')

The object <code>ydip</code> now has a method that permits to retrieve the independent-particle absorption spectrum with customly chosen energy range, steps, and broadening:
w, eps2 = ydip.ip_eps2(yel)

In order to see all this in action, take a look at the <code>dipoles_plot.py</code> script. You will see that it performs two plots:
* Plot of |d(k)| in the BZ for selected v,c and \alpha (we choose the layer plane 'xy') [<code>Kspace_Plot=True</code>]. From this plot you can appreciate which sections of the BZ contribute the most to the absorption rate.
* Plot of the independent-particles absorption spectrum [<code>Absorption_Plot=True</code>].

You can play with the indices and the plot parameters to check what happens.

[[File:Dipoles hbn2.png|YamboDipolesDB plot from yambopy tutorial|500px]]

=== Exciton intro 1: read and sort data ===
In this section we will use both the script <code>exc_read.py</code> and the command line in order to read the exciton data resulting from a BSE calculation to familiarise with their structure. This time we are going to read the <code>ndb.BS_diago_Q*</code> databases which correspond to BSE calculations at various momenta Q (Q=1 being the zero-momentum optical absorption limit - notice that python indexing starts from 0, while the databases are counted starting from 1).

In order to read them in python we use the Yambopy class <code>YamboExcitonDB</code>, which can be instanced like this:
yexc = YamboExcitonDB.from_db_file(ylat,filename=f'path/to/BSE/databases/ndb.BS_diago_Q{i}')
(where i is the number of BS_diago_Qi file. Notice that it requires a previous instance of <code>YamboLatticeDB</code>).

Now the <code>yexc</code> object contains information about the exciton energies (<code>yexc.eigenvalues</code>), wave functions (<code>yexc.eigenvectors</code>) and intensities (<code>yexc.l_residuals</code>, <code>yexc.r_residuals</code>) for Qpoint i_Q. You can start by keeping <code>Q1</code> which is the optical limit and then check other momenta.

The exciton wave function components A_{vck}^{\lambda Q} (\lambda being the exciton index) are stored as A_{t}^{\lambda} in each Q-dependent database, with t being the transition index grouping the single-particle indices vck. Therefore, <code>yexc.eigenvectors</code> is an array with (N_excitons,N_transitions) dimension. In order to make the connection t->kcv, the table <code>yexc.table</code> provides k,v,c and spin indices corresponding to each transition.

In order to get a clearer picture, take a look at the script <code>exc_read.py</code>. Run it and try to understand the outputs.
$ python exc_read.py

Actually, we can produce output files with the sorted exciton energies in a much more convenient way by using the command line instruction <code>exc-sort</code>. Check its syntax via:
$ yambopy exc-sort -h

Then, we run it for our specific calculation with:
$ yambopy exc-sort --save BSE_saves/YAMBO_saves/SAVE -J BSE_saves/BSE_databases --iqpt 1

This should produce the <code>o-BSE_databases.exc_qpt1_sorted_E.dat</code> and <code>o-BSE_databases.exc_qpt1_sorted_I.dat</code> output files for you to inspect. These are very useful as they allow for identification of degenerate states and degree of optical activity. You will see that in our system most states are doubly degenerate, a byproduct of crystal symmetry. This is an updated version of the ypp exciton analysis that you can find [[How to analyse excitons#Sort the excitonic eigenvalues|here]].

=== Exciton intro 2: symmetry analysis and wavefunction plot in real space ===

==== Symmetries of excitons====
We can analyse the symmetries of the excitonic wavefunctions in terms of irreducible representation of the point group of the system (if at Q=0) or the Q little group. For more information, the methodology is explained in Ref. <ref>Symmetries of excitons, M. Nalabothula et al., [https://arxiv.org/abs/2511.21540 preprint arXiv]</ref>.

We use the <code>exc-irrep</code> command line option, check the arguments with:
$ yambopy exc-irrep -h

We know from the previous section (by inspecting the sorted energies) that the first four BSE eigenvalues correspond to two doubly-degenerate bright states. Let us analyse their symmetry by running
$ yambopy exc-irrep --path BSE_saves/YAMBO_saves -J BSE_saves/BSE_databases --iqpt 1 --nstates 4

This command first loads the electronic wave functions and calculated the electronic representation matrices (called <code>Dmats</code> in the code). As a second step, they are used to compute the '''excitonic''' representation matrices.

We obtain the following output:

========================================
Group theory analysis for Q point : (0.000000, 0.000000, 0.000000)
****************************************
Little group : D3h
Little group symmetries : [ 1 2 3 4 5 6 7 8 9 10 11 12]
Classes (symmetry indices in each class):
E : [1]
2S_3 : [2 6]
2C_3 : [3 5]
sigma_h : [4]
3C_2 : [ 7 9 11]
3sigma_v : [ 8 10 12]

====== Exciton representations ======
Energy (eV), degeneracy : representation
----------------------------------------
1.9139 2 : E'
2.5988 2 : E'
****************************************

This is similar to the group theory analysis done by Quantum Espresso on the electronic states, and is actually analogous to the one performed for the phonon modes of crystals. We see that the first two states transform as the E' representation of the D3h point group of the crystal. By optical selection rules, only states with this symmetry can form absorption peaks in monolayer BN when light is polarized along the layer plane.

We could go further and calculate the total crystal angular momentum of these states, while also rotate the degenerate exciton states so that they are both eigenvectors of the BSE Hamiltonian and the total crystal angular momentum operator. This is very useful for analyses involving selection rules, exciton-boson couplings, chirality, etc. This is an advanced topic and will not be covered, nonetheless an example script is provided in the tutorial folder called <code>total_crystal_angular_momentum_exciton.py</code>.

''' What to do when symmetry analysis does not seem to work well '''

* Check for warnings during execution. If the BSE calculation was done with a response function that breaks the symmetries (such as the longitudinal response in place of the transverse one at q=0), that may explain the issues.

* If the exciton density of states is very high (such as for a bulk 3D system or for a 2D system at higher energies in the optical spectrum), the analyser may fail to resolve degenerate states, and incorporate a bunch of states together. The symmetry analysis will still be performed but the representation labels will appear as summed. In severe cases, the code may crash. You can try to get a better result by carefully selecting the degeneracy tolerance with <code>degen_tol</code> and restricting the number of states with <code>nstates</code> in the command line options.

====Exciton wave functions in real space====
We can also plot the wave functions of the exciton states on the crystal lattice. In practice, what we do is set the position of the hole at a "physical" point, and then visualize the resulting electronic distribution:

<math>I^{e}_{\lambda \mathbf{Q}}(\mathbf{r}_e)= |\Psi_{\alpha \mathbf{Q}}(\mathbf{r}_e,\mathbf{r}_h=\mathbf{r}_0)|^2</math>

Let us focus on the lowest exciton state, which gives rise to the largest peak in absorption (see the last part of the tutorial). We will set the hole position on top of a nitrogen atom, since that's where the <math>p_z</math> orbitals where the hole comes from are mostly localized.

If we don't know the correct coordinates, we can modify the <code>bz_plot.py</code> script by adding (after instancing the lattice object):
for iat in range(len(ylat.atomic_numbers)): print(ylat.atomic_numbers[iat],ylat.red_atomic_positions[iat])
which will print
5 [0.6666667 0.3333333 0. ]
7 [-0.6666667 -0.3333333 0. ]

In order to make the plot, we have to give yambopy the same inputs that are used in the equivalent [[How to analyse excitons#Plot the exciton spatial distribution| ypp calculation]]. First, let's check all the options via
$ yambopy exc-wf -h

Then, we can run our calculation (by selecting a 9x9x1 supercell and a 30 Ry cutoff) as
$ yambopy exc-wf --path BSE_saves/YAMBO_saves -J BSE_saves/BSE_databases --iqpt 1 --iexe 1 --supercell 9 9 1 --wfc_cutoff 30 --hole 0.33333333 0.66666667 0.03

Yambopy will produce a *.cube file that can be visualized with VESTA, xcrysden or the like, producing a figure similar to the one below.

The example script <code>exc_real_wf.py</code>, which runs the same calculation by explicitly calling the necessary functions, will give you more info about what is happening behind the scenes.

[[File:Exc BN yambopy.png|YamboExcitonDB exciton wave function|400px]]

We see that electron is localised in <math>p_z</math>-like distributions on top of boron atoms around the nitrogen where the hole is set.

=== Exciton intro 3: plot exciton weights on k-BZ and (interpolated) band structure ===
In this section we will use the script <code>exc_kspace_plot.py</code> and work with the quantities defined in the previous section.

For now, only the i_Q=0 case is implemented in this section.
We want to check the relative importance of the various (vk->ck) electronic transitions in forming a certain excitonic state.

Since many excitonic states are degenerate, we first need to tell Yambopy which states we want to check. For example, in monolayer hexagonal boron nitride, the lowest-bound exciton - forming the main peak in the BSE absorption spectrum - is doubly degenerate. In order to analyse it, in the <code>exc_kspace_plot.py</code> script we set
states = [1,2]
(we can also set [3,4] to check the second excitonic state, and then [5] for the non-degenerate third state, and so on; we can check degeneracies by printing the energies using the script <code>exc_read.py</code>).

In order to make a band structure plot, it is necessary to read the band energies, for example with the <code>YamboSaveDB</code> class
yel = YamboSaveDB.from_db_file(folder='path/to/SAVE')
and specify the path in the BZ using crystal coordinates via the <code>Path</code> function:
npoints = 20
path = Path([ [[ 0.0, 0.0, 0.0],'$\Gamma$'],
[[ 0.5, 0.0, 0.0],'M'],
[[1./3.,1./3., 0.0],'K'],
[[ 0.0, 0.0, 0.0],'$\Gamma$']],
[int(npoints*2),int(npoints),int(sqrt(5)*npoints)] )

Now let's take a closer look at the <code>exc_kspace_plot.py</code> script. You will see that it performs three plots:
* Plot of |A(k)| in the k-BZ for the selected exciton state. You can see how most contributions come from the area around K and the MK direction [<code>Kspace_Plot=True</code>].
* Plot of |A(v,c,k)| on the electronic band structure for the selected exciton state. Here you can better see how the top valence and bottom conduction around MK are mostly involved [<code>Bands_Plot=True</code>].
* Plot of interpolated |A(v,c,k)| on the interpolated electronic band structure for the selected exciton state [<code>Bands_Plot_Interpolated=True</code>].

As always, try to play with the parameters, for example by changing the excitonic states to analyse.

[[File:Exc bands1 hbn.jpg|YamboExcitonDB plot from yambopy tutorial|300px| Uninterpolated exciton weights on top of band structure]][[File:Exc bands2 hbn.jpg|YamboExcitonDB plot from yambopy tutorial|300px]]

=== Exciton intro 4: plot BSE optical absorption with custom options ===
In this section we will use the script <code>exc_abs_plot.py</code> and work with the quantities defined in the previous sections.

The class <code>YamboExcitonDB</code> also enables us, of course, to read the dielectric function eps(w) and print absorption and related spectra in python.

The advantages over using the standard human-readable yambo outputs are mainly two:
# We can freely select energy ranges, energy steps, peak broadenings and number of excitonic states included without having to rerun the <code>yambo</code> executable every time. This reduces the chance of mistakenly editing the yambo input and allows for greater freedom since these plots can now be done in your local machine without having to transfer the output data from a remote cluster.
# The dielectric function constructed from netCDF database variables has a much higher precision (number of significant digits) than the human readable output, which may be important if you want to perform additional operations in python (e.g., computing refractive index, reflectivity and other optical spectra from it, performing finite-difference derivatives, etc).

We can read eps(w) as a <code>numpy</code> array with the specified options as (energy values are in eV):
w, eps = yexc.get_chi(nexcitons='all',emin=0,emax=7,estep=0.005,broad=0.04)
Or, you can directly prepare a plot of its imaginary part with
w, chi = yexc.plot_chi_ax(ax,nexcitons='all',emin=0,emax=7,estep=0.005,broad=0.04)
where <code>ax</code> is a previously defined <code>Axes</code> object from <code>matplotlib</code>.

In order to see how this works, let's take a look at the <code>exc_abs_plot.py</code> script.
You will see that it performs the two operations described above:
* Plotting the BSE absorption spectrum [<code>Absorption_Plot=True</code>].
* Reading the complex dielectric function.

Try to customise the plots by changing the <code>nexcitons</code>, <code>emin</code>, <code>emax</code>, <code>estep</code>, <code>broad</code> parameters.

[[File:Absalpha.png|Yambo alpha_2D tutorial plot|700px]]

==Links==
* Back to [[Rome 2023#Tutorials]]
* Back to [[ICTP 2022#Tutorials]]

==References==

Yambopy tutorial: electron-phonon coupling

2026-03-10T09:33:32Z

FulvioPaleari:

First steps in Yambopy

2026-03-10T09:32:49Z

FulvioPaleari: /* Tutorials */

The yambopy project aims to develop python tools to:

* Read and edit yambo and quantum espresso input files
* Easily perform pre- and post-processing of the simulation data for these two codes - including hard-to-get, database-encoded data beyond standard outputs
* Provide easy visualization and plotting options
* Set up simple automatization workflows (e.g., convergence tests)

=== Setup ===
First of all, make sure that you have a suitable python environment (crated for example with [https://docs.anaconda.com/miniconda/install/ conda] or [https://docs.python.org/3/library/venv.html venv]) with '''python >=3.8'''.

If you are not used with python environments, here two simple commands that you can use
python -m venv MYPATH/yamboenv/
(you can replace `MYPATH` with any path you prefer, e.g. `~/`)
source MYPATH/yamboenv/bin/activate
(for bash users, you can add to your .bashrt the line `. MYPATH/yamboenv/bin/activate`)

Then, you may install yambopy in one of the following ways.

==== Quick installation from PyPI repository ====

* In order to quickly install the officially released version type:

pip install yambopy

==== Installation from tarball ====

* In case you don't want to download from the pip repository and prefer to install a version of yambopy locally, you may download the appropriate tarball from the [https://github.com/yambo-code/yambopy/releases| yambopy github page]. Extract the tarball, enter the yambopy folder and type <code>pip install .</code>

==== Installation of latest patch ====

* In case you want the latest version of the code including new updates and patches that might not be present in the official version, then you can clone the yambopy git repository (a basic knowledge of git may be helpful):

git clone https://github.com/yambo-code/yambopy.git
cd yambopy
pip install .

==== Installation for developers ====
* If you want to install YamboPy in developing mode (to modify or add new functions) you have to download the code from github repository then go in the YamboPy folder and install with the command:

pip install -e .

'''Important:''' if you want your changes to be included into a new patch/version of Yambopy, you need to first create your own personal fork of the git repository, make the changes there, and then create a pull request for the original repository.

==== Dependencies ====

* In principle, <code>pip</code> should take care of the required python dependencies. They are <code>numpy</code>, <code>scipy</code>, <code>matplotlib</code>, <code>netCDF4</code>, <code>h5py</code>, <code>lxml</code>, <code>PyYAML</code>, <code>monty</code>, <code>scikit-learn</code>, <code>tqdm</code>, <code>spglib</code>, <code>spgrep</code>, <code>pykdtree</code>, and <code>numba</code>. In case some dependency-related problem arises, you can install each of them separately beforehand with:

pip install <code>dependency-name</code>

* If you experience errors related to <code>NetCDF4</code> or <code>hdf5</code>, these are usually due to incompatibilities between the python modules the library in your environment. In this case, you can force the python installation to match the system library. For example, if you have an <code>hdf5</code> problem and you are using conda, you could try:

conda install --force-reinstall h5py hdf5

=== Tutorials ===
Now yambopy is ready to use! Just go to the tutorials folder and follow the docs!

cd tutorial/

On this wiki, we provide steps for the following tutorials:

1. Data postprocessing:
* [[Yambopy tutorial: band structures | Database and plotting tutorial for quantum espresso (qepy) and GW '''band structures''']] (Get the databases: [https://media.yambo-code.eu/educational/tutorials/files/databases_qepy.tar.gz databases_qepy], 46.5MB)
* [[Yambopy tutorial: Yambo databases | Database and plotting tutorial for yambo (yambopy) and '''exciton''' analysis ]] (Get the databases: [https://media.yambo-code.eu/educational/tutorials/files/databases_yambopy.tar.gz databases_yambopy], 129MB)
2. Manage QE and Yambo runs: [WARNING: these tutorials are currently under maintenance due to updates to the scheduler class]
* [[GW tutorial. Convergence and approximations (BN)]]
* [[Bethe-Salpeter equation tutorial. Optical absorption (BN)]]
3. Advanced topics:
* [[Yambopy tutorial: electron-phonon coupling|Databases and plotting tutorial for electron-phonon coupling with yambopy]] (Get the databases: )
* [[Exciton-phonon coupling and luminescence]]
* [[Phonon-assisted luminescence by finite atomic displacements]]

=== How to cite ===
If yambopy helped you with your data analysis, workflow management of figure preparation, you can consider citing us.

The way to do so in BibTeX format is the following:
@misc{yambopy,
author = {Paleari, Fulvio and Molina-Sánchez, Alejandro and Nalabothula, Muralidhar and Reho, Riccardo and Bonacci, Miki and Castelo, José M. and Cervantes-Villanueva, Jorge and Pionteck, Mike and Silvetti, Martino and Attaccalite, Claudio and Pereira Coutada Miranda, Henrique},
title = {Yambopy},
month = mar,
year = 2025,
publisher = {Zenodo},
version = {0.4.0},
doi = {10.5281/zenodo.15012962},
url = {[[https://doi.org/10.5281/zenodo.15012962 https://doi.org/10.5281/zenodo.15012962]]}, }

Yambopy tutorial: Yambo databases

2026-03-09T19:12:58Z

FulvioPaleari: /* Command line: generating the Yambo SAVE */

In this tutorial we will see some examples on how to read and analyse the data contained in the Yambo netCDF databases, which are not readily available as human readable outputs.

In particular we will take a look at:
* Lattice geometry data (Yambo database: <code>ns.db1</code>, Yambopy class: <code>YamboLatticeDB</code>).
* Dipole matrix elements (Yambo databases: <code>ndb.dipoles</code>, Yambopy class: <code>YamboDipolesDB</code>).
* Exciton energies, symmetries, wavefunctions and spectra (Yambo databases: <code>ndb.BS_diago_Q*</code>, Yambopy class: <code>YamboExcitonDB</code>).

We will also check the command line instructions to quickly generate yambo SAVE folders.

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

The full tutorial, including the Quantum espresso 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/databases_yambopy.tar.gz
$tar -xvzf databases_yambopy.tar.gz
$cd databases_yambopy

We will work with monolayer hexagonal boron nitride electron-phonon and exciton data obtained on a <code>12x12x1</code> kpoint grid. Beware that these are certainly not converged.

=== Command line: generating the Yambo SAVE ===
Yambopy offers a set of command line options. In order to review them, you can type
$yambopy
which will print the output
yambopy v0.7
Available commands are:

plotem1s -> Plot em1s calculation.
analysebse -> Study the convergence of BSE calculations.
analysegw -> Study the convergence of GW calculations by looking at the change in band-gap value.
plotexcitons -> Plot excitons calculation.
addqp -> Add corrections from QP databases.
mergeqp -> Merge QP databases.
save -> Produce a SAVE folder.
gkkp -> Produce a SAVE folder including elph_gkkp databases.
bands -> Script to produce band structure data and visualization from QE.
serial -> Script to update serial numbers of yambo ndb.* databases in order to import them to new calculations.
gwsubspace -> Script to calculate off-diago corrections of yambo ndb.QP databases in order to plot band structure.
phinp -> Script to update the explicit list of q-points in a ph input file (ldisp=.false., qplot=.true.).
convert -> Script to convert RL number in Ry energy units using ndb.gops.
bsesize -> Script to calculate the expected BSE kernel size, in GB, to be loaded by each MPI task.
l2y -> Calculate gauge-invariant electron-phonon matrix elements with LetzElPhC and convert them into Yambo format.
exc-irrep -> Script to get the irreducible representation labels for excitonic states. [-h for help]
exc-wf -> Real space exciton wf for either fixed hole/electron. [-h for help]
exc-sort -> Script to sort excitonic states according to energies and intensities. [-h for help]

For this tutorial, we will need the <code>save</code> and <code>gkkp</code> options.
By typing in one of these, additional information about how to run the commands will be printed, e.g.:
$yambopy save

Produce a SAVE folder

Arguments are:
-nscf, --nscf_dir -> Path to nscf save folder
-y, --yambo_dir -> <Optional> Path to yambo executables

The quantum espresso save for hBN is provided in the directory <code>BSE_saves/QE_saves/hBN.save</code> (you can check the contents of the various folders).
Then, following the instructions printed on screen, we can generate a yambo SAVE from the hBN.save by typing

$yambopy save -nscf BSE_saves/QE_saves/hBN.save

This should produce a SAVE folder in the current directory.

=== Lattice intro: plot k-point coordinates in IBZ/BZ ===
For this section we will use the script <code>bz_plot.py</code>.

By inspecting the SAVE folder we have just generated, we will find the <code>ns.db1</code> database which contains all the geometry and lattice information.
We are now going to read it in python by using the Yambopy class <code>YamboLatticeDB</code>, which can be instanced like this:

from yambopy import YamboLatticeDB
ylat = YamboLatticeDB.from_db_file(filename="PATH/TO/SAVE/ns.db1")
(remember to edit the variable <code>save_path</code> in order to point at your yambo SAVE).

The <code>ylat</code> object now contains many useful information as attributes, such as the k-points in Cartesian or crystal coordinates, the system symmetries, lattice constants and basis vectors in real and reciprocal space, etc.
The k-points are also automatically expanded in the full Brillouin zone from the irreducible one (you can turn this off with the option <code>Expand=False</code>).

Directly printing the object with
print(ylat)
will also give us some general parameters related to the database.

Now check the <code>bz_plot.py</code> script. You will see that it performs three plots:
* Scatterplot of the k-points in Cartesian coordinates with both expanded and unexpanded grids, with annotated indices [<code>Cartesian_Plot=True</code>].
* Scatterplot of the k-points in crystal coordinates [<code>Crystal_Plot=True</code>].
* Manual transformation of a chosen k-point from irreducible to full Brillouin zone (you can change the index <code>i_k</code> in the script to check different cases) [<code>Symmetry_Plot=True</code>].

Below, the result of the first plot.

[[File:Car kpoints hbn.jpg|YamboLatticeDB plot from yambopy tutorial| 500px]]

'''What about the units?'''

Below we report the relation between units used in Yambo, Quantum Espresso, and Yambopy.

* bohr^-1 (atomic units): <code>YamboLatticeDB.car_kpoints*2.*pi</code>. Divide by the bohr-to-angstrom conversion factor to obtain angs^-1
* Yambo cartesian units (<code>[cc]</code> in Yambo outputs): <code>YamboLatticeDB.car_kpoints*2.*pi</code> (same as above).
* QE cartesian units (<code>[cart. coord. in units 2pi/alat]</code> in QE outputs): <code>YamboLatticeDB.car_kpoints*YamboLatticeDB.alat[0]</code>.
* Internal yambo units (<code>[iku]</code> in yambo outputs): <code>YamboLatticeDB.iku_kpoints</code>
* Fractional coordinates (<code>[rlu]</code> in yambo, <code>cryst. coord.</code> in QE): <code>YamboLatticeDB.red_kpoints</code>.

=== Dipoles intro: plots of dipoles on BZ, plot of IP absorption ===
In this section we will use the script <code>dipoles_plot.py</code> and read the dipole databases generated in an optical absorption calculation by yambo. Keep in mind that from now on we will use the "BSE" yambo SAVE generated in the [[#Command line: generating the Yambo SAVE|first section]].

The databases written after a calculation of optical properties with yambo (dipoles, static screening, excitons) are in the directory <code>BSE_saves/BSE_databases</code>. Here we will also find <code>ndb.dipoles</code> which is needed now, since it contains the matrix elements d_{vck}(\alpha) where vk and ck are the valence and electron states involved in the transition and \alpha the polarisation direction of the external electric field.

In order to read it in python we use the Yambopy class <code>YamboDipolesDB</code>, which can be instanced like this:
ydip = YamboDipolesDB(ylat,save='path/to/BSE/databases',filename='ndb.dipoles')
(notice that it requires a previous instance of <code>YamboLatticeDB</code>).

In addition, in order to read the Kohn-Sham energies, we can also instance the <code>YamboElectronsDB</code> as
yel = YamboElectronsDB.from_db_file(folder='path/to/SAVE')

The object <code>ydip</code> now has a method that permits to retrieve the independent-particle absorption spectrum with customly chosen energy range, steps, and broadening:
w, eps2 = ydip.ip_eps2(yel)

In order to see all this in action, take a look at the <code>dipoles_plot.py</code> script. You will see that it performs two plots:
* Plot of |d(k)| in the BZ for selected v,c and \alpha (we choose the layer plane 'xy') [<code>Kspace_Plot=True</code>]. From this plot you can appreciate which sections of the BZ contribute the most to the absorption rate.
* Plot of the independent-particles absorption spectrum [<code>Absorption_Plot=True</code>].

You can play with the indices and the plot parameters to check what happens.

[[File:Dipoles hbn2.png|YamboDipolesDB plot from yambopy tutorial|500px]]

=== Exciton intro 1: read and sort data ===
In this section we will use both the script <code>exc_read.py</code> and the command line in order to read the exciton data resulting from a BSE calculation to familiarise with their structure. This time we are going to read the <code>ndb.BS_diago_Q*</code> databases which correspond to BSE calculations at various momenta Q (Q=1 being the zero-momentum optical absorption limit - notice that python indexing starts from 0, while the databases are counted starting from 1).

In order to read them in python we use the Yambopy class <code>YamboExcitonDB</code>, which can be instanced like this:
yexc = YamboExcitonDB.from_db_file(ylat,filename=f'path/to/BSE/databases/ndb.BS_diago_Q{i}')
(where i is the number of BS_diago_Qi file. Notice that it requires a previous instance of <code>YamboLatticeDB</code>).

Now the <code>yexc</code> object contains information about the exciton energies (<code>yexc.eigenvalues</code>), wave functions (<code>yexc.eigenvectors</code>) and intensities (<code>yexc.l_residuals</code>, <code>yexc.r_residuals</code>) for Qpoint i_Q. You can start by keeping <code>Q1</code> which is the optical limit and then check other momenta.

The exciton wave function components A_{vck}^{\lambda Q} (\lambda being the exciton index) are stored as A_{t}^{\lambda} in each Q-dependent database, with t being the transition index grouping the single-particle indices vck. Therefore, <code>yexc.eigenvectors</code> is an array with (N_excitons,N_transitions) dimension. In order to make the connection t->kcv, the table <code>yexc.table</code> provides k,v,c and spin indices corresponding to each transition.

In order to get a clearer picture, take a look at the script <code>exc_read.py</code>. Run it and try to understand the outputs.
$ python exc_read.py

Actually, we can produce output files with the sorted exciton energies in a much more convenient way by using the command line instruction <code>exc-sort</code>. Check its syntax via:
$ yambopy exc-sort -h

Then, we run it for our specific calculation with:
$ yambopy exc-sort --save BSE_saves/YAMBO_saves/SAVE -J BSE_saves/BSE_databases --iqpt 1

This should produce the <code>o-BSE_databases.exc_qpt1_sorted_E.dat</code> and <code>o-BSE_databases.exc_qpt1_sorted_I.dat</code> output files for you to inspect. These are very useful as they allow for identification of degenerate states and degree of optical activity. You will see that in our system most states are doubly degenerate, a byproduct of crystal symmetry. This is an updated version of the ypp exciton analysis that you can find [[How to analyse excitons#Sort the excitonic eigenvalues|here]].

=== Exciton intro 2: symmetry analysis and wavefunction plot in real space ===

==== Symmetries of excitons====
We can analyse the symmetries of the excitonic wavefunctions in terms of irreducible representation of the point group of the system (if at Q=0) or the Q little group. For more information, the methodology is explained in Ref. <ref>Symmetries of excitons, M. Nalabothula et al., [https://arxiv.org/abs/2511.21540 preprint arXiv]</ref>.

We use the <code>exc-irrep</code> command line option, check the arguments with:
$ yambopy exc-irrep -h

We know from the previous section (by inspecting the sorted energies) that the first four BSE eigenvalues correspond to two doubly-degenerate bright states. Let us analyse their symmetry by running
$ yambopy exc-irrep --path BSE_saves/YAMBO_saves -J BSE_saves/BSE_databases --iqpt 1 --nstates 4

This command first loads the electronic wave functions and calculated the electronic representation matrices (called <code>Dmats</code> in the code). As a second step, they are used to compute the '''excitonic''' representation matrices.

We obtain the following output:

========================================
Group theory analysis for Q point : (0.000000, 0.000000, 0.000000)
****************************************
Little group : D3h
Little group symmetries : [ 1 2 3 4 5 6 7 8 9 10 11 12]
Classes (symmetry indices in each class):
E : [1]
2S_3 : [2 6]
2C_3 : [3 5]
sigma_h : [4]
3C_2 : [ 7 9 11]
3sigma_v : [ 8 10 12]

====== Exciton representations ======
Energy (eV), degeneracy : representation
----------------------------------------
1.9139 2 : E'
2.5988 2 : E'
****************************************

This is similar to the group theory analysis done by Quantum Espresso on the electronic states, and is actually analogous to the one performed for the phonon modes of crystals. We see that the first two states transform as the E' representation of the D3h point group of the crystal. By optical selection rules, only states with this symmetry can form absorption peaks in monolayer BN when light is polarized along the layer plane.

We could go further and calculate the total crystal angular momentum of these states, while also rotate the degenerate exciton states so that they are both eigenvectors of the BSE Hamiltonian and the total crystal angular momentum operator. This is very useful for analyses involving selection rules, exciton-boson couplings, chirality, etc. This is an advanced topic and will not be covered, nonetheless an example script is provided in the tutorial folder called <code>total_crystal_angular_momentum_exciton.py</code>.

''' What to do when symmetry analysis does not seem to work well '''

* Check for warnings during execution. If the BSE calculation was done with a response function that breaks the symmetries (such as the longitudinal response in place of the transverse one at q=0), that may explain the issues.

* If the exciton density of states is very high (such as for a bulk 3D system or for a 2D system at higher energies in the optical spectrum), the analyser may fail to resolve degenerate states, and incorporate a bunch of states together. The symmetry analysis will still be performed but the representation labels will appear as summed. In severe cases, the code may crash. You can try to get a better result by carefully selecting the degeneracy tolerance with <code>degen_tol</code> and restricting the number of states with <code>nstates</code> in the command line options.

====Exciton wave functions in real space====
We can also plot the wave functions of the exciton states on the crystal lattice. In practice, what we do is set the position of the hole at a "physical" point, and then visualize the resulting electronic distribution:

<math>I^{e}_{\lambda \mathbf{Q}}(\mathbf{r}_e)= |\Psi_{\alpha \mathbf{Q}}(\mathbf{r}_e,\mathbf{r}_h=\mathbf{r}_0)|^2</math>

Let us focus on the lowest exciton state, which gives rise to the largest peak in absorption (see the last part of the tutorial). We will set the hole position on top of a nitrogen atom, since that's where the <math>p_z</math> orbitals where the hole comes from are mostly localized.

If we don't know the correct coordinates, we can modify the <code>bz_plot.py</code> script by adding (after instancing the lattice object):
for iat in range(len(ylat.atomic_numbers)): print(ylat.atomic_numbers[iat],ylat.red_atomic_positions[iat])
which will print
5 [0.6666667 0.3333333 0. ]
7 [-0.6666667 -0.3333333 0. ]

In order to make the plot, we have to give yambopy the same inputs that are used in the equivalent [[How to analyse excitons#Plot the exciton spatial distribution| ypp calculation]]. First, let's check all the options via
$ yambopy exc-wf -h

Then, we can run our calculation (by selecting a 9x9x1 supercell and a 30 Ry cutoff) as
$ yambopy exc-wf --path BSE_saves/YAMBO_saves -J BSE_saves/BSE_databases --iqpt 1 --iexe 1 --supercell 9 9 1 --wfc_cutoff 30 --hole 0.33333333 0.66666667 0.03

Yambopy will produce a *.cube file that can be visualized with VESTA, xcrysden or the like, producing a figure similar to the one below.

The example script <code>exc_real_wf.py</code>, which runs the same calculation by explicitly calling the necessary functions, will give you more info about what is happening behind the scenes.

[[File:Exc BN yambopy.png|YamboExcitonDB exciton wave function|400px]]

We see that electron is localised in <math>p_z</math>-like distributions on top of boron atoms around the nitrogen where the hole is set.

=== Exciton intro 3: plot exciton weights on k-BZ and (interpolated) band structure ===
In this section we will use the script <code>exc_kspace_plot.py</code> and work with the quantities defined in the previous section.

For now, only the i_Q=0 case is implemented in this section.
We want to check the relative importance of the various (vk->ck) electronic transitions in forming a certain excitonic state.

Since many excitonic states are degenerate, we first need to tell Yambopy which states we want to check. For example, in monolayer hexagonal boron nitride, the lowest-bound exciton - forming the main peak in the BSE absorption spectrum - is doubly degenerate. In order to analyse it, in the <code>exc_kspace_plot.py</code> script we set
states = [1,2]
(we can also set [3,4] to check the second excitonic state, and then [5] for the non-degenerate third state, and so on; we can check degeneracies by printing the energies using the script <code>exc_read.py</code>).

In order to make a band structure plot, it is necessary to read the band energies, for example with the <code>YamboSaveDB</code> class
yel = YamboSaveDB.from_db_file(folder='path/to/SAVE')
and specify the path in the BZ using crystal coordinates via the <code>Path</code> function:
npoints = 20
path = Path([ [[ 0.0, 0.0, 0.0],'$\Gamma$'],
[[ 0.5, 0.0, 0.0],'M'],
[[1./3.,1./3., 0.0],'K'],
[[ 0.0, 0.0, 0.0],'$\Gamma$']],
[int(npoints*2),int(npoints),int(sqrt(5)*npoints)] )

Now let's take a closer look at the <code>exc_kspace_plot.py</code> script. You will see that it performs three plots:
* Plot of |A(k)| in the k-BZ for the selected exciton state. You can see how most contributions come from the area around K and the MK direction [<code>Kspace_Plot=True</code>].
* Plot of |A(v,c,k)| on the electronic band structure for the selected exciton state. Here you can better see how the top valence and bottom conduction around MK are mostly involved [<code>Bands_Plot=True</code>].
* Plot of interpolated |A(v,c,k)| on the interpolated electronic band structure for the selected exciton state [<code>Bands_Plot_Interpolated=True</code>].

As always, try to play with the parameters, for example by changing the excitonic states to analyse.

[[File:Exc bands1 hbn.jpg|YamboExcitonDB plot from yambopy tutorial|300px| Uninterpolated exciton weights on top of band structure]][[File:Exc bands2 hbn.jpg|YamboExcitonDB plot from yambopy tutorial|300px]]

=== Exciton intro 4: plot BSE optical absorption with custom options ===
In this section we will use the script <code>exc_abs_plot.py</code> and work with the quantities defined in the previous sections.

The class <code>YamboExcitonDB</code> also enables us, of course, to read the dielectric function eps(w) and print absorption and related spectra in python.

The advantages over using the standard human-readable yambo outputs are mainly two:
# We can freely select energy ranges, energy steps, peak broadenings and number of excitonic states included without having to rerun the <code>yambo</code> executable every time. This reduces the chance of mistakenly editing the yambo input and allows for greater freedom since these plots can now be done in your local machine without having to transfer the output data from a remote cluster.
# The dielectric function constructed from netCDF database variables has a much higher precision (number of significant digits) than the human readable output, which may be important if you want to perform additional operations in python (e.g., computing refractive index, reflectivity and other optical spectra from it, performing finite-difference derivatives, etc).

We can read eps(w) as a <code>numpy</code> array with the specified options as (energy values are in eV):
w, eps = yexc.get_chi(nexcitons='all',emin=0,emax=7,estep=0.005,broad=0.04)
Or, you can directly prepare a plot of its imaginary part with
w, chi = yexc.plot_chi_ax(ax,nexcitons='all',emin=0,emax=7,estep=0.005,broad=0.04)
where <code>ax</code> is a previously defined <code>Axes</code> object from <code>matplotlib</code>.

In order to see how this works, let's take a look at the <code>exc_abs_plot.py</code> script.
You will see that it performs the two operations described above:
* Plotting the BSE absorption spectrum [<code>Absorption_Plot=True</code>].
* Reading the complex dielectric function.

Try to customise the plots by changing the <code>nexcitons</code>, <code>emin</code>, <code>emax</code>, <code>estep</code>, <code>broad</code> parameters.

[[File:Absalpha.png|Yambo alpha_2D tutorial plot|700px]]

=== Command line: importing electron-phonon matrix elements ===
You may have seen how to calculate and import electron-phonon matrix elements in yambo in the [[Electron Phonon Coupling|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 <code>ELPH_SAVES/QE_SAVES/hBN.save</code> (nscf calculation) and <code>ELPH_SAVES/QE_SAVES/elph_dir</code> (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 <code>ndb.elph_gkkp_expanded*</code> databases.

=== Electron-phonon intro: plots of el-ph matrix elements on k-BZ and q-BZ ===
In this section we will use the script <code>elph_plot.py</code> and read the electron-phonon databases that you generated in the previous section.

In order to read the <code>ndb.elph_gkkp_expanded*</code> databases in python we use the Yambopy class <code>YamboElectronPhononDB</code>, 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 <code>YamboLatticeDB</code>).

Now, the <code>yelph</code> 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 <code>YamboElectronPhononDB</code> class with
print(yelph.__doc__)
to get an idea of the information stored and of its capabilities.

Now check the <code>elph_plot.py</code> script. You will see that it performs two plots:
* Plot of |g(k)| in the k-BZ for selected n,m,\nu and q [<code>Kspace_Plot=True</code>].
* Plot of |g(q)| in the q-BZ for selected n,m,\nu and k [<code>Qspace_Plot=True</code>].

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

[[File:Elph hbn.jpg|YamboElectronPhononDB plot from yambopy tutorial|500px]]

==Links==
* Back to [[Rome 2023#Tutorials]]
* Back to [[ICTP 2022#Tutorials]]

==References==

Yambopy tutorial: Yambo databases

2026-03-09T19:09:35Z

FulvioPaleari: /* Lattice intro: plot k-point coordinates in IBZ/BZ */

In this tutorial we will see some examples on how to read and analyse the data contained in the Yambo netCDF databases, which are not readily available as human readable outputs.

In particular we will take a look at:
* Lattice geometry data (Yambo database: <code>ns.db1</code>, Yambopy class: <code>YamboLatticeDB</code>).
* Dipole matrix elements (Yambo databases: <code>ndb.dipoles</code>, Yambopy class: <code>YamboDipolesDB</code>).
* Exciton energies, symmetries, wavefunctions and spectra (Yambo databases: <code>ndb.BS_diago_Q*</code>, Yambopy class: <code>YamboExcitonDB</code>).

We will also check the command line instructions to quickly generate yambo SAVE folders.

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

The full tutorial, including the Quantum espresso 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/databases_yambopy.tar.gz
$tar -xvzf databases_yambopy.tar.gz
$cd databases_yambopy

We will work with monolayer hexagonal boron nitride electron-phonon and exciton data obtained on a <code>12x12x1</code> kpoint grid. Beware that these are certainly not converged.

=== Command line: generating the Yambo SAVE ===
Yambopy offers a set of command line options. In order to review them, you can type
$yambopy
which will print the output
yambopy v0.7
Available commands are:

plotem1s -> Plot em1s calculation.
analysebse -> Study the convergence of BSE calculations.
analysegw -> Study the convergence of GW calculations by looking at the change in band-gap value.
plotexcitons -> Plot excitons calculation
addqp -> Add corrections from QP databases.
mergeqp -> Merge QP databases
save -> Produce a SAVE folder
gkkp -> Produce a SAVE folder including elph_gkkp databases
bands -> Script to produce band structure data and visualization from QE.
serial -> Script to update serial numbers of yambo ndb.* databases in order to import them to new calculations.
gwsubspace -> Script to calculate off-diago corrections of yambo ndb.QP databases in order to plot band structure.
phinp -> Script to update the explicit list of q-points in a ph input file (ldisp=.false., qplot=.true.).
convert -> Script to convert RL number in Ry energy units using ndb.gops.
bsesize -> Script to calculate the expected BSE kernel size, in GB, to be loaded by each MPI task.
l2y -> Calculate gauge-invariant electron-phonon matrix elements with LetzElPhC and convert them into Yambo format.
exc-irrep -> Script to get the irreducible representation labels for excitonic states. [-h for help]
exc-wf -> Real space exciton wf for either fixed hole/electron. [-h for help]
exc-sort -> Script to sort excitonic states according to energies and intensities. [-h for help]

For this tutorial, we will need the <code>save</code> and <code>gkkp</code> options.
By typing in one of these, additional information about how to run the commands will be printed, e.g.:
$yambopy save

Produce a SAVE folder

Arguments are:
-nscf, --nscf_dir -> Path to nscf save folder
-y, --yambo_dir -> <Optional> Path to yambo executables

The quantum espresso save for hBN is provided in the directory <code>BSE_saves/QE_saves/hBN.save</code> (you can check the contents of the various folders).
Then, following the instructions printed on screen, we can generate a yambo SAVE from the hBN.save by typing

$yambopy save -nscf BSE_saves/QE_saves/hBN.save

This should produce a SAVE folder in the current directory.

=== Lattice intro: plot k-point coordinates in IBZ/BZ ===
For this section we will use the script <code>bz_plot.py</code>.

By inspecting the SAVE folder we have just generated, we will find the <code>ns.db1</code> database which contains all the geometry and lattice information.
We are now going to read it in python by using the Yambopy class <code>YamboLatticeDB</code>, which can be instanced like this:

from yambopy import YamboLatticeDB
ylat = YamboLatticeDB.from_db_file(filename="PATH/TO/SAVE/ns.db1")
(remember to edit the variable <code>save_path</code> in order to point at your yambo SAVE).

The <code>ylat</code> object now contains many useful information as attributes, such as the k-points in Cartesian or crystal coordinates, the system symmetries, lattice constants and basis vectors in real and reciprocal space, etc.
The k-points are also automatically expanded in the full Brillouin zone from the irreducible one (you can turn this off with the option <code>Expand=False</code>).

Directly printing the object with
print(ylat)
will also give us some general parameters related to the database.

Now check the <code>bz_plot.py</code> script. You will see that it performs three plots:
* Scatterplot of the k-points in Cartesian coordinates with both expanded and unexpanded grids, with annotated indices [<code>Cartesian_Plot=True</code>].
* Scatterplot of the k-points in crystal coordinates [<code>Crystal_Plot=True</code>].
* Manual transformation of a chosen k-point from irreducible to full Brillouin zone (you can change the index <code>i_k</code> in the script to check different cases) [<code>Symmetry_Plot=True</code>].

Below, the result of the first plot.

[[File:Car kpoints hbn.jpg|YamboLatticeDB plot from yambopy tutorial| 500px]]

'''What about the units?'''

Below we report the relation between units used in Yambo, Quantum Espresso, and Yambopy.

* bohr^-1 (atomic units): <code>YamboLatticeDB.car_kpoints*2.*pi</code>. Divide by the bohr-to-angstrom conversion factor to obtain angs^-1
* Yambo cartesian units (<code>[cc]</code> in Yambo outputs): <code>YamboLatticeDB.car_kpoints*2.*pi</code> (same as above).
* QE cartesian units (<code>[cart. coord. in units 2pi/alat]</code> in QE outputs): <code>YamboLatticeDB.car_kpoints*YamboLatticeDB.alat[0]</code>.
* Internal yambo units (<code>[iku]</code> in yambo outputs): <code>YamboLatticeDB.iku_kpoints</code>
* Fractional coordinates (<code>[rlu]</code> in yambo, <code>cryst. coord.</code> in QE): <code>YamboLatticeDB.red_kpoints</code>.

=== Dipoles intro: plots of dipoles on BZ, plot of IP absorption ===
In this section we will use the script <code>dipoles_plot.py</code> and read the dipole databases generated in an optical absorption calculation by yambo. Keep in mind that from now on we will use the "BSE" yambo SAVE generated in the [[#Command line: generating the Yambo SAVE|first section]].

The databases written after a calculation of optical properties with yambo (dipoles, static screening, excitons) are in the directory <code>BSE_saves/BSE_databases</code>. Here we will also find <code>ndb.dipoles</code> which is needed now, since it contains the matrix elements d_{vck}(\alpha) where vk and ck are the valence and electron states involved in the transition and \alpha the polarisation direction of the external electric field.

In order to read it in python we use the Yambopy class <code>YamboDipolesDB</code>, which can be instanced like this:
ydip = YamboDipolesDB(ylat,save='path/to/BSE/databases',filename='ndb.dipoles')
(notice that it requires a previous instance of <code>YamboLatticeDB</code>).

In addition, in order to read the Kohn-Sham energies, we can also instance the <code>YamboElectronsDB</code> as
yel = YamboElectronsDB.from_db_file(folder='path/to/SAVE')

The object <code>ydip</code> now has a method that permits to retrieve the independent-particle absorption spectrum with customly chosen energy range, steps, and broadening:
w, eps2 = ydip.ip_eps2(yel)

In order to see all this in action, take a look at the <code>dipoles_plot.py</code> script. You will see that it performs two plots:
* Plot of |d(k)| in the BZ for selected v,c and \alpha (we choose the layer plane 'xy') [<code>Kspace_Plot=True</code>]. From this plot you can appreciate which sections of the BZ contribute the most to the absorption rate.
* Plot of the independent-particles absorption spectrum [<code>Absorption_Plot=True</code>].

You can play with the indices and the plot parameters to check what happens.

[[File:Dipoles hbn2.png|YamboDipolesDB plot from yambopy tutorial|500px]]

=== Exciton intro 1: read and sort data ===
In this section we will use both the script <code>exc_read.py</code> and the command line in order to read the exciton data resulting from a BSE calculation to familiarise with their structure. This time we are going to read the <code>ndb.BS_diago_Q*</code> databases which correspond to BSE calculations at various momenta Q (Q=1 being the zero-momentum optical absorption limit - notice that python indexing starts from 0, while the databases are counted starting from 1).

In order to read them in python we use the Yambopy class <code>YamboExcitonDB</code>, which can be instanced like this:
yexc = YamboExcitonDB.from_db_file(ylat,filename=f'path/to/BSE/databases/ndb.BS_diago_Q{i}')
(where i is the number of BS_diago_Qi file. Notice that it requires a previous instance of <code>YamboLatticeDB</code>).

Now the <code>yexc</code> object contains information about the exciton energies (<code>yexc.eigenvalues</code>), wave functions (<code>yexc.eigenvectors</code>) and intensities (<code>yexc.l_residuals</code>, <code>yexc.r_residuals</code>) for Qpoint i_Q. You can start by keeping <code>Q1</code> which is the optical limit and then check other momenta.

The exciton wave function components A_{vck}^{\lambda Q} (\lambda being the exciton index) are stored as A_{t}^{\lambda} in each Q-dependent database, with t being the transition index grouping the single-particle indices vck. Therefore, <code>yexc.eigenvectors</code> is an array with (N_excitons,N_transitions) dimension. In order to make the connection t->kcv, the table <code>yexc.table</code> provides k,v,c and spin indices corresponding to each transition.

In order to get a clearer picture, take a look at the script <code>exc_read.py</code>. Run it and try to understand the outputs.
$ python exc_read.py

Actually, we can produce output files with the sorted exciton energies in a much more convenient way by using the command line instruction <code>exc-sort</code>. Check its syntax via:
$ yambopy exc-sort -h

Then, we run it for our specific calculation with:
$ yambopy exc-sort --save BSE_saves/YAMBO_saves/SAVE -J BSE_saves/BSE_databases --iqpt 1

This should produce the <code>o-BSE_databases.exc_qpt1_sorted_E.dat</code> and <code>o-BSE_databases.exc_qpt1_sorted_I.dat</code> output files for you to inspect. These are very useful as they allow for identification of degenerate states and degree of optical activity. You will see that in our system most states are doubly degenerate, a byproduct of crystal symmetry. This is an updated version of the ypp exciton analysis that you can find [[How to analyse excitons#Sort the excitonic eigenvalues|here]].

=== Exciton intro 2: symmetry analysis and wavefunction plot in real space ===

==== Symmetries of excitons====
We can analyse the symmetries of the excitonic wavefunctions in terms of irreducible representation of the point group of the system (if at Q=0) or the Q little group. For more information, the methodology is explained in Ref. <ref>Symmetries of excitons, M. Nalabothula et al., [https://arxiv.org/abs/2511.21540 preprint arXiv]</ref>.

We use the <code>exc-irrep</code> command line option, check the arguments with:
$ yambopy exc-irrep -h

We know from the previous section (by inspecting the sorted energies) that the first four BSE eigenvalues correspond to two doubly-degenerate bright states. Let us analyse their symmetry by running
$ yambopy exc-irrep --path BSE_saves/YAMBO_saves -J BSE_saves/BSE_databases --iqpt 1 --nstates 4

This command first loads the electronic wave functions and calculated the electronic representation matrices (called <code>Dmats</code> in the code). As a second step, they are used to compute the '''excitonic''' representation matrices.

We obtain the following output:

========================================
Group theory analysis for Q point : (0.000000, 0.000000, 0.000000)
****************************************
Little group : D3h
Little group symmetries : [ 1 2 3 4 5 6 7 8 9 10 11 12]
Classes (symmetry indices in each class):
E : [1]
2S_3 : [2 6]
2C_3 : [3 5]
sigma_h : [4]
3C_2 : [ 7 9 11]
3sigma_v : [ 8 10 12]

====== Exciton representations ======
Energy (eV), degeneracy : representation
----------------------------------------
1.9139 2 : E'
2.5988 2 : E'
****************************************

This is similar to the group theory analysis done by Quantum Espresso on the electronic states, and is actually analogous to the one performed for the phonon modes of crystals. We see that the first two states transform as the E' representation of the D3h point group of the crystal. By optical selection rules, only states with this symmetry can form absorption peaks in monolayer BN when light is polarized along the layer plane.

We could go further and calculate the total crystal angular momentum of these states, while also rotate the degenerate exciton states so that they are both eigenvectors of the BSE Hamiltonian and the total crystal angular momentum operator. This is very useful for analyses involving selection rules, exciton-boson couplings, chirality, etc. This is an advanced topic and will not be covered, nonetheless an example script is provided in the tutorial folder called <code>total_crystal_angular_momentum_exciton.py</code>.

''' What to do when symmetry analysis does not seem to work well '''

* Check for warnings during execution. If the BSE calculation was done with a response function that breaks the symmetries (such as the longitudinal response in place of the transverse one at q=0), that may explain the issues.

* If the exciton density of states is very high (such as for a bulk 3D system or for a 2D system at higher energies in the optical spectrum), the analyser may fail to resolve degenerate states, and incorporate a bunch of states together. The symmetry analysis will still be performed but the representation labels will appear as summed. In severe cases, the code may crash. You can try to get a better result by carefully selecting the degeneracy tolerance with <code>degen_tol</code> and restricting the number of states with <code>nstates</code> in the command line options.

====Exciton wave functions in real space====
We can also plot the wave functions of the exciton states on the crystal lattice. In practice, what we do is set the position of the hole at a "physical" point, and then visualize the resulting electronic distribution:

<math>I^{e}_{\lambda \mathbf{Q}}(\mathbf{r}_e)= |\Psi_{\alpha \mathbf{Q}}(\mathbf{r}_e,\mathbf{r}_h=\mathbf{r}_0)|^2</math>

Let us focus on the lowest exciton state, which gives rise to the largest peak in absorption (see the last part of the tutorial). We will set the hole position on top of a nitrogen atom, since that's where the <math>p_z</math> orbitals where the hole comes from are mostly localized.

If we don't know the correct coordinates, we can modify the <code>bz_plot.py</code> script by adding (after instancing the lattice object):
for iat in range(len(ylat.atomic_numbers)): print(ylat.atomic_numbers[iat],ylat.red_atomic_positions[iat])
which will print
5 [0.6666667 0.3333333 0. ]
7 [-0.6666667 -0.3333333 0. ]

In order to make the plot, we have to give yambopy the same inputs that are used in the equivalent [[How to analyse excitons#Plot the exciton spatial distribution| ypp calculation]]. First, let's check all the options via
$ yambopy exc-wf -h

Then, we can run our calculation (by selecting a 9x9x1 supercell and a 30 Ry cutoff) as
$ yambopy exc-wf --path BSE_saves/YAMBO_saves -J BSE_saves/BSE_databases --iqpt 1 --iexe 1 --supercell 9 9 1 --wfc_cutoff 30 --hole 0.33333333 0.66666667 0.03

Yambopy will produce a *.cube file that can be visualized with VESTA, xcrysden or the like, producing a figure similar to the one below.

The example script <code>exc_real_wf.py</code>, which runs the same calculation by explicitly calling the necessary functions, will give you more info about what is happening behind the scenes.

[[File:Exc BN yambopy.png|YamboExcitonDB exciton wave function|400px]]

We see that electron is localised in <math>p_z</math>-like distributions on top of boron atoms around the nitrogen where the hole is set.

=== Exciton intro 3: plot exciton weights on k-BZ and (interpolated) band structure ===
In this section we will use the script <code>exc_kspace_plot.py</code> and work with the quantities defined in the previous section.

For now, only the i_Q=0 case is implemented in this section.
We want to check the relative importance of the various (vk->ck) electronic transitions in forming a certain excitonic state.

Since many excitonic states are degenerate, we first need to tell Yambopy which states we want to check. For example, in monolayer hexagonal boron nitride, the lowest-bound exciton - forming the main peak in the BSE absorption spectrum - is doubly degenerate. In order to analyse it, in the <code>exc_kspace_plot.py</code> script we set
states = [1,2]
(we can also set [3,4] to check the second excitonic state, and then [5] for the non-degenerate third state, and so on; we can check degeneracies by printing the energies using the script <code>exc_read.py</code>).

In order to make a band structure plot, it is necessary to read the band energies, for example with the <code>YamboSaveDB</code> class
yel = YamboSaveDB.from_db_file(folder='path/to/SAVE')
and specify the path in the BZ using crystal coordinates via the <code>Path</code> function:
npoints = 20
path = Path([ [[ 0.0, 0.0, 0.0],'$\Gamma$'],
[[ 0.5, 0.0, 0.0],'M'],
[[1./3.,1./3., 0.0],'K'],
[[ 0.0, 0.0, 0.0],'$\Gamma$']],
[int(npoints*2),int(npoints),int(sqrt(5)*npoints)] )

Now let's take a closer look at the <code>exc_kspace_plot.py</code> script. You will see that it performs three plots:
* Plot of |A(k)| in the k-BZ for the selected exciton state. You can see how most contributions come from the area around K and the MK direction [<code>Kspace_Plot=True</code>].
* Plot of |A(v,c,k)| on the electronic band structure for the selected exciton state. Here you can better see how the top valence and bottom conduction around MK are mostly involved [<code>Bands_Plot=True</code>].
* Plot of interpolated |A(v,c,k)| on the interpolated electronic band structure for the selected exciton state [<code>Bands_Plot_Interpolated=True</code>].

As always, try to play with the parameters, for example by changing the excitonic states to analyse.

[[File:Exc bands1 hbn.jpg|YamboExcitonDB plot from yambopy tutorial|300px| Uninterpolated exciton weights on top of band structure]][[File:Exc bands2 hbn.jpg|YamboExcitonDB plot from yambopy tutorial|300px]]

=== Exciton intro 4: plot BSE optical absorption with custom options ===
In this section we will use the script <code>exc_abs_plot.py</code> and work with the quantities defined in the previous sections.

The class <code>YamboExcitonDB</code> also enables us, of course, to read the dielectric function eps(w) and print absorption and related spectra in python.

The advantages over using the standard human-readable yambo outputs are mainly two:
# We can freely select energy ranges, energy steps, peak broadenings and number of excitonic states included without having to rerun the <code>yambo</code> executable every time. This reduces the chance of mistakenly editing the yambo input and allows for greater freedom since these plots can now be done in your local machine without having to transfer the output data from a remote cluster.
# The dielectric function constructed from netCDF database variables has a much higher precision (number of significant digits) than the human readable output, which may be important if you want to perform additional operations in python (e.g., computing refractive index, reflectivity and other optical spectra from it, performing finite-difference derivatives, etc).

We can read eps(w) as a <code>numpy</code> array with the specified options as (energy values are in eV):
w, eps = yexc.get_chi(nexcitons='all',emin=0,emax=7,estep=0.005,broad=0.04)
Or, you can directly prepare a plot of its imaginary part with
w, chi = yexc.plot_chi_ax(ax,nexcitons='all',emin=0,emax=7,estep=0.005,broad=0.04)
where <code>ax</code> is a previously defined <code>Axes</code> object from <code>matplotlib</code>.

In order to see how this works, let's take a look at the <code>exc_abs_plot.py</code> script.
You will see that it performs the two operations described above:
* Plotting the BSE absorption spectrum [<code>Absorption_Plot=True</code>].
* Reading the complex dielectric function.

Try to customise the plots by changing the <code>nexcitons</code>, <code>emin</code>, <code>emax</code>, <code>estep</code>, <code>broad</code> parameters.

[[File:Absalpha.png|Yambo alpha_2D tutorial plot|700px]]

=== Command line: importing electron-phonon matrix elements ===
You may have seen how to calculate and import electron-phonon matrix elements in yambo in the [[Electron Phonon Coupling|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 <code>ELPH_SAVES/QE_SAVES/hBN.save</code> (nscf calculation) and <code>ELPH_SAVES/QE_SAVES/elph_dir</code> (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 <code>ndb.elph_gkkp_expanded*</code> databases.

=== Electron-phonon intro: plots of el-ph matrix elements on k-BZ and q-BZ ===
In this section we will use the script <code>elph_plot.py</code> and read the electron-phonon databases that you generated in the previous section.

In order to read the <code>ndb.elph_gkkp_expanded*</code> databases in python we use the Yambopy class <code>YamboElectronPhononDB</code>, 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 <code>YamboLatticeDB</code>).

Now, the <code>yelph</code> 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 <code>YamboElectronPhononDB</code> class with
print(yelph.__doc__)
to get an idea of the information stored and of its capabilities.

Now check the <code>elph_plot.py</code> script. You will see that it performs two plots:
* Plot of |g(k)| in the k-BZ for selected n,m,\nu and q [<code>Kspace_Plot=True</code>].
* Plot of |g(q)| in the q-BZ for selected n,m,\nu and k [<code>Qspace_Plot=True</code>].

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

[[File:Elph hbn.jpg|YamboElectronPhononDB plot from yambopy tutorial|500px]]

==Links==
* Back to [[Rome 2023#Tutorials]]
* Back to [[ICTP 2022#Tutorials]]

==References==

Yambopy tutorial: Yambo databases

2026-03-09T19:09:00Z

FulvioPaleari: /* Command line: generating the Yambo SAVE */

In this tutorial we will see some examples on how to read and analyse the data contained in the Yambo netCDF databases, which are not readily available as human readable outputs.

In particular we will take a look at:
* Lattice geometry data (Yambo database: <code>ns.db1</code>, Yambopy class: <code>YamboLatticeDB</code>).
* Dipole matrix elements (Yambo databases: <code>ndb.dipoles</code>, Yambopy class: <code>YamboDipolesDB</code>).
* Exciton energies, symmetries, wavefunctions and spectra (Yambo databases: <code>ndb.BS_diago_Q*</code>, Yambopy class: <code>YamboExcitonDB</code>).

We will also check the command line instructions to quickly generate yambo SAVE folders.

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

The full tutorial, including the Quantum espresso 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/databases_yambopy.tar.gz
$tar -xvzf databases_yambopy.tar.gz
$cd databases_yambopy

We will work with monolayer hexagonal boron nitride electron-phonon and exciton data obtained on a <code>12x12x1</code> kpoint grid. Beware that these are certainly not converged.

=== Command line: generating the Yambo SAVE ===
Yambopy offers a set of command line options. In order to review them, you can type
$yambopy
which will print the output
yambopy v0.7
Available commands are:

plotem1s -> Plot em1s calculation.
analysebse -> Study the convergence of BSE calculations.
analysegw -> Study the convergence of GW calculations by looking at the change in band-gap value.
plotexcitons -> Plot excitons calculation
addqp -> Add corrections from QP databases.
mergeqp -> Merge QP databases
save -> Produce a SAVE folder
gkkp -> Produce a SAVE folder including elph_gkkp databases
bands -> Script to produce band structure data and visualization from QE.
serial -> Script to update serial numbers of yambo ndb.* databases in order to import them to new calculations.
gwsubspace -> Script to calculate off-diago corrections of yambo ndb.QP databases in order to plot band structure.
phinp -> Script to update the explicit list of q-points in a ph input file (ldisp=.false., qplot=.true.).
convert -> Script to convert RL number in Ry energy units using ndb.gops.
bsesize -> Script to calculate the expected BSE kernel size, in GB, to be loaded by each MPI task.
l2y -> Calculate gauge-invariant electron-phonon matrix elements with LetzElPhC and convert them into Yambo format.
exc-irrep -> Script to get the irreducible representation labels for excitonic states. [-h for help]
exc-wf -> Real space exciton wf for either fixed hole/electron. [-h for help]
exc-sort -> Script to sort excitonic states according to energies and intensities. [-h for help]

For this tutorial, we will need the <code>save</code> and <code>gkkp</code> options.
By typing in one of these, additional information about how to run the commands will be printed, e.g.:
$yambopy save

Produce a SAVE folder

Arguments are:
-nscf, --nscf_dir -> Path to nscf save folder
-y, --yambo_dir -> <Optional> Path to yambo executables

The quantum espresso save for hBN is provided in the directory <code>BSE_saves/QE_saves/hBN.save</code> (you can check the contents of the various folders).
Then, following the instructions printed on screen, we can generate a yambo SAVE from the hBN.save by typing

$yambopy save -nscf BSE_saves/QE_saves/hBN.save

This should produce a SAVE folder in the current directory.

=== Lattice intro: plot k-point coordinates in IBZ/BZ ===
For this section we will use the script <code>bz_plot.py</code>.

By inspecting the SAVE folder we have just generated, we will find the <code>ns.db1</code> database which contains all the geometry and lattice information.
We are now going to read it in python by using the Yambopy class <code>YamboLatticeDB</code>, which can be instanced like this:

from yambopy import *
ylat = YamboLatticeDB.from_db_file(filename="PATH/TO/SAVE/ns.db1")
(remember to edit the variable <code>save_path</code> in order to point at your yambo SAVE).

The <code>ylat</code> object now contains many useful information as attributes, such as the k-points in Cartesian or crystal coordinates, the system symmetries, lattice constants and basis vectors in real and reciprocal space, etc.
The k-points are also automatically expanded in the full Brillouin zone from the irreducible one (you can turn this off with the option <code>Expand=False</code>).

Directly printing the object with
print(ylat)
will also give us some general parameters related to the database.

Now check the <code>bz_plot.py</code> script. You will see that it performs three plots:
* Scatterplot of the k-points in Cartesian coordinates with both expanded and unexpanded grids, with annotated indices [<code>Cartesian_Plot=True</code>].
* Scatterplot of the k-points in crystal coordinates [<code>Crystal_Plot=True</code>].
* Manual transformation of a chosen k-point from irreducible to full Brillouin zone (you can change the index <code>i_k</code> in the script to check different cases) [<code>Symmetry_Plot=True</code>].

Below, the result of the first plot.

[[File:Car kpoints hbn.jpg|YamboLatticeDB plot from yambopy tutorial| 500px]]

'''What about the units?'''

Below we report the relation between units used in Yambo, Quantum Espresso, and Yambopy.

* bohr^-1 (atomic units): <code>YamboLatticeDB.car_kpoints*2.*pi</code>. Divide by the bohr-to-angstrom conversion factor to obtain angs^-1
* Yambo cartesian units (<code>[cc]</code> in Yambo outputs): <code>YamboLatticeDB.car_kpoints*2.*pi</code> (same as above).
* QE cartesian units (<code>[cart. coord. in units 2pi/alat]</code> in QE outputs): <code>YamboLatticeDB.car_kpoints*YamboLatticeDB.alat[0]</code>.
* Internal yambo units (<code>[iku]</code> in yambo outputs): <code>YamboLatticeDB.iku_kpoints</code>
* Fractional coordinates (<code>[rlu]</code> in yambo, <code>cryst. coord.</code> in QE): <code>YamboLatticeDB.red_kpoints</code>.

=== Dipoles intro: plots of dipoles on BZ, plot of IP absorption ===
In this section we will use the script <code>dipoles_plot.py</code> and read the dipole databases generated in an optical absorption calculation by yambo. Keep in mind that from now on we will use the "BSE" yambo SAVE generated in the [[#Command line: generating the Yambo SAVE|first section]].

The databases written after a calculation of optical properties with yambo (dipoles, static screening, excitons) are in the directory <code>BSE_saves/BSE_databases</code>. Here we will also find <code>ndb.dipoles</code> which is needed now, since it contains the matrix elements d_{vck}(\alpha) where vk and ck are the valence and electron states involved in the transition and \alpha the polarisation direction of the external electric field.

In order to read it in python we use the Yambopy class <code>YamboDipolesDB</code>, which can be instanced like this:
ydip = YamboDipolesDB(ylat,save='path/to/BSE/databases',filename='ndb.dipoles')
(notice that it requires a previous instance of <code>YamboLatticeDB</code>).

In addition, in order to read the Kohn-Sham energies, we can also instance the <code>YamboElectronsDB</code> as
yel = YamboElectronsDB.from_db_file(folder='path/to/SAVE')

The object <code>ydip</code> now has a method that permits to retrieve the independent-particle absorption spectrum with customly chosen energy range, steps, and broadening:
w, eps2 = ydip.ip_eps2(yel)

In order to see all this in action, take a look at the <code>dipoles_plot.py</code> script. You will see that it performs two plots:
* Plot of |d(k)| in the BZ for selected v,c and \alpha (we choose the layer plane 'xy') [<code>Kspace_Plot=True</code>]. From this plot you can appreciate which sections of the BZ contribute the most to the absorption rate.
* Plot of the independent-particles absorption spectrum [<code>Absorption_Plot=True</code>].

You can play with the indices and the plot parameters to check what happens.

[[File:Dipoles hbn2.png|YamboDipolesDB plot from yambopy tutorial|500px]]

=== Exciton intro 1: read and sort data ===
In this section we will use both the script <code>exc_read.py</code> and the command line in order to read the exciton data resulting from a BSE calculation to familiarise with their structure. This time we are going to read the <code>ndb.BS_diago_Q*</code> databases which correspond to BSE calculations at various momenta Q (Q=1 being the zero-momentum optical absorption limit - notice that python indexing starts from 0, while the databases are counted starting from 1).

In order to read them in python we use the Yambopy class <code>YamboExcitonDB</code>, which can be instanced like this:
yexc = YamboExcitonDB.from_db_file(ylat,filename=f'path/to/BSE/databases/ndb.BS_diago_Q{i}')
(where i is the number of BS_diago_Qi file. Notice that it requires a previous instance of <code>YamboLatticeDB</code>).

Now the <code>yexc</code> object contains information about the exciton energies (<code>yexc.eigenvalues</code>), wave functions (<code>yexc.eigenvectors</code>) and intensities (<code>yexc.l_residuals</code>, <code>yexc.r_residuals</code>) for Qpoint i_Q. You can start by keeping <code>Q1</code> which is the optical limit and then check other momenta.

The exciton wave function components A_{vck}^{\lambda Q} (\lambda being the exciton index) are stored as A_{t}^{\lambda} in each Q-dependent database, with t being the transition index grouping the single-particle indices vck. Therefore, <code>yexc.eigenvectors</code> is an array with (N_excitons,N_transitions) dimension. In order to make the connection t->kcv, the table <code>yexc.table</code> provides k,v,c and spin indices corresponding to each transition.

In order to get a clearer picture, take a look at the script <code>exc_read.py</code>. Run it and try to understand the outputs.
$ python exc_read.py

Actually, we can produce output files with the sorted exciton energies in a much more convenient way by using the command line instruction <code>exc-sort</code>. Check its syntax via:
$ yambopy exc-sort -h

Then, we run it for our specific calculation with:
$ yambopy exc-sort --save BSE_saves/YAMBO_saves/SAVE -J BSE_saves/BSE_databases --iqpt 1

This should produce the <code>o-BSE_databases.exc_qpt1_sorted_E.dat</code> and <code>o-BSE_databases.exc_qpt1_sorted_I.dat</code> output files for you to inspect. These are very useful as they allow for identification of degenerate states and degree of optical activity. You will see that in our system most states are doubly degenerate, a byproduct of crystal symmetry. This is an updated version of the ypp exciton analysis that you can find [[How to analyse excitons#Sort the excitonic eigenvalues|here]].

=== Exciton intro 2: symmetry analysis and wavefunction plot in real space ===

==== Symmetries of excitons====
We can analyse the symmetries of the excitonic wavefunctions in terms of irreducible representation of the point group of the system (if at Q=0) or the Q little group. For more information, the methodology is explained in Ref. <ref>Symmetries of excitons, M. Nalabothula et al., [https://arxiv.org/abs/2511.21540 preprint arXiv]</ref>.

We use the <code>exc-irrep</code> command line option, check the arguments with:
$ yambopy exc-irrep -h

We know from the previous section (by inspecting the sorted energies) that the first four BSE eigenvalues correspond to two doubly-degenerate bright states. Let us analyse their symmetry by running
$ yambopy exc-irrep --path BSE_saves/YAMBO_saves -J BSE_saves/BSE_databases --iqpt 1 --nstates 4

This command first loads the electronic wave functions and calculated the electronic representation matrices (called <code>Dmats</code> in the code). As a second step, they are used to compute the '''excitonic''' representation matrices.

We obtain the following output:

========================================
Group theory analysis for Q point : (0.000000, 0.000000, 0.000000)
****************************************
Little group : D3h
Little group symmetries : [ 1 2 3 4 5 6 7 8 9 10 11 12]
Classes (symmetry indices in each class):
E : [1]
2S_3 : [2 6]
2C_3 : [3 5]
sigma_h : [4]
3C_2 : [ 7 9 11]
3sigma_v : [ 8 10 12]

====== Exciton representations ======
Energy (eV), degeneracy : representation
----------------------------------------
1.9139 2 : E'
2.5988 2 : E'
****************************************

This is similar to the group theory analysis done by Quantum Espresso on the electronic states, and is actually analogous to the one performed for the phonon modes of crystals. We see that the first two states transform as the E' representation of the D3h point group of the crystal. By optical selection rules, only states with this symmetry can form absorption peaks in monolayer BN when light is polarized along the layer plane.

We could go further and calculate the total crystal angular momentum of these states, while also rotate the degenerate exciton states so that they are both eigenvectors of the BSE Hamiltonian and the total crystal angular momentum operator. This is very useful for analyses involving selection rules, exciton-boson couplings, chirality, etc. This is an advanced topic and will not be covered, nonetheless an example script is provided in the tutorial folder called <code>total_crystal_angular_momentum_exciton.py</code>.

''' What to do when symmetry analysis does not seem to work well '''

* Check for warnings during execution. If the BSE calculation was done with a response function that breaks the symmetries (such as the longitudinal response in place of the transverse one at q=0), that may explain the issues.

* If the exciton density of states is very high (such as for a bulk 3D system or for a 2D system at higher energies in the optical spectrum), the analyser may fail to resolve degenerate states, and incorporate a bunch of states together. The symmetry analysis will still be performed but the representation labels will appear as summed. In severe cases, the code may crash. You can try to get a better result by carefully selecting the degeneracy tolerance with <code>degen_tol</code> and restricting the number of states with <code>nstates</code> in the command line options.

====Exciton wave functions in real space====
We can also plot the wave functions of the exciton states on the crystal lattice. In practice, what we do is set the position of the hole at a "physical" point, and then visualize the resulting electronic distribution:

<math>I^{e}_{\lambda \mathbf{Q}}(\mathbf{r}_e)= |\Psi_{\alpha \mathbf{Q}}(\mathbf{r}_e,\mathbf{r}_h=\mathbf{r}_0)|^2</math>

Let us focus on the lowest exciton state, which gives rise to the largest peak in absorption (see the last part of the tutorial). We will set the hole position on top of a nitrogen atom, since that's where the <math>p_z</math> orbitals where the hole comes from are mostly localized.

If we don't know the correct coordinates, we can modify the <code>bz_plot.py</code> script by adding (after instancing the lattice object):
for iat in range(len(ylat.atomic_numbers)): print(ylat.atomic_numbers[iat],ylat.red_atomic_positions[iat])
which will print
5 [0.6666667 0.3333333 0. ]
7 [-0.6666667 -0.3333333 0. ]

In order to make the plot, we have to give yambopy the same inputs that are used in the equivalent [[How to analyse excitons#Plot the exciton spatial distribution| ypp calculation]]. First, let's check all the options via
$ yambopy exc-wf -h

Then, we can run our calculation (by selecting a 9x9x1 supercell and a 30 Ry cutoff) as
$ yambopy exc-wf --path BSE_saves/YAMBO_saves -J BSE_saves/BSE_databases --iqpt 1 --iexe 1 --supercell 9 9 1 --wfc_cutoff 30 --hole 0.33333333 0.66666667 0.03

Yambopy will produce a *.cube file that can be visualized with VESTA, xcrysden or the like, producing a figure similar to the one below.

The example script <code>exc_real_wf.py</code>, which runs the same calculation by explicitly calling the necessary functions, will give you more info about what is happening behind the scenes.

[[File:Exc BN yambopy.png|YamboExcitonDB exciton wave function|400px]]

We see that electron is localised in <math>p_z</math>-like distributions on top of boron atoms around the nitrogen where the hole is set.

=== Exciton intro 3: plot exciton weights on k-BZ and (interpolated) band structure ===
In this section we will use the script <code>exc_kspace_plot.py</code> and work with the quantities defined in the previous section.

For now, only the i_Q=0 case is implemented in this section.
We want to check the relative importance of the various (vk->ck) electronic transitions in forming a certain excitonic state.

Since many excitonic states are degenerate, we first need to tell Yambopy which states we want to check. For example, in monolayer hexagonal boron nitride, the lowest-bound exciton - forming the main peak in the BSE absorption spectrum - is doubly degenerate. In order to analyse it, in the <code>exc_kspace_plot.py</code> script we set
states = [1,2]
(we can also set [3,4] to check the second excitonic state, and then [5] for the non-degenerate third state, and so on; we can check degeneracies by printing the energies using the script <code>exc_read.py</code>).

In order to make a band structure plot, it is necessary to read the band energies, for example with the <code>YamboSaveDB</code> class
yel = YamboSaveDB.from_db_file(folder='path/to/SAVE')
and specify the path in the BZ using crystal coordinates via the <code>Path</code> function:
npoints = 20
path = Path([ [[ 0.0, 0.0, 0.0],'$\Gamma$'],
[[ 0.5, 0.0, 0.0],'M'],
[[1./3.,1./3., 0.0],'K'],
[[ 0.0, 0.0, 0.0],'$\Gamma$']],
[int(npoints*2),int(npoints),int(sqrt(5)*npoints)] )

Now let's take a closer look at the <code>exc_kspace_plot.py</code> script. You will see that it performs three plots:
* Plot of |A(k)| in the k-BZ for the selected exciton state. You can see how most contributions come from the area around K and the MK direction [<code>Kspace_Plot=True</code>].
* Plot of |A(v,c,k)| on the electronic band structure for the selected exciton state. Here you can better see how the top valence and bottom conduction around MK are mostly involved [<code>Bands_Plot=True</code>].
* Plot of interpolated |A(v,c,k)| on the interpolated electronic band structure for the selected exciton state [<code>Bands_Plot_Interpolated=True</code>].

As always, try to play with the parameters, for example by changing the excitonic states to analyse.

[[File:Exc bands1 hbn.jpg|YamboExcitonDB plot from yambopy tutorial|300px| Uninterpolated exciton weights on top of band structure]][[File:Exc bands2 hbn.jpg|YamboExcitonDB plot from yambopy tutorial|300px]]

=== Exciton intro 4: plot BSE optical absorption with custom options ===
In this section we will use the script <code>exc_abs_plot.py</code> and work with the quantities defined in the previous sections.

The class <code>YamboExcitonDB</code> also enables us, of course, to read the dielectric function eps(w) and print absorption and related spectra in python.

The advantages over using the standard human-readable yambo outputs are mainly two:
# We can freely select energy ranges, energy steps, peak broadenings and number of excitonic states included without having to rerun the <code>yambo</code> executable every time. This reduces the chance of mistakenly editing the yambo input and allows for greater freedom since these plots can now be done in your local machine without having to transfer the output data from a remote cluster.
# The dielectric function constructed from netCDF database variables has a much higher precision (number of significant digits) than the human readable output, which may be important if you want to perform additional operations in python (e.g., computing refractive index, reflectivity and other optical spectra from it, performing finite-difference derivatives, etc).

We can read eps(w) as a <code>numpy</code> array with the specified options as (energy values are in eV):
w, eps = yexc.get_chi(nexcitons='all',emin=0,emax=7,estep=0.005,broad=0.04)
Or, you can directly prepare a plot of its imaginary part with
w, chi = yexc.plot_chi_ax(ax,nexcitons='all',emin=0,emax=7,estep=0.005,broad=0.04)
where <code>ax</code> is a previously defined <code>Axes</code> object from <code>matplotlib</code>.

In order to see how this works, let's take a look at the <code>exc_abs_plot.py</code> script.
You will see that it performs the two operations described above:
* Plotting the BSE absorption spectrum [<code>Absorption_Plot=True</code>].
* Reading the complex dielectric function.

Try to customise the plots by changing the <code>nexcitons</code>, <code>emin</code>, <code>emax</code>, <code>estep</code>, <code>broad</code> parameters.

[[File:Absalpha.png|Yambo alpha_2D tutorial plot|700px]]

=== Command line: importing electron-phonon matrix elements ===
You may have seen how to calculate and import electron-phonon matrix elements in yambo in the [[Electron Phonon Coupling|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 <code>ELPH_SAVES/QE_SAVES/hBN.save</code> (nscf calculation) and <code>ELPH_SAVES/QE_SAVES/elph_dir</code> (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 <code>ndb.elph_gkkp_expanded*</code> databases.

=== Electron-phonon intro: plots of el-ph matrix elements on k-BZ and q-BZ ===
In this section we will use the script <code>elph_plot.py</code> and read the electron-phonon databases that you generated in the previous section.

In order to read the <code>ndb.elph_gkkp_expanded*</code> databases in python we use the Yambopy class <code>YamboElectronPhononDB</code>, 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 <code>YamboLatticeDB</code>).

Now, the <code>yelph</code> 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 <code>YamboElectronPhononDB</code> class with
print(yelph.__doc__)
to get an idea of the information stored and of its capabilities.

Now check the <code>elph_plot.py</code> script. You will see that it performs two plots:
* Plot of |g(k)| in the k-BZ for selected n,m,\nu and q [<code>Kspace_Plot=True</code>].
* Plot of |g(q)| in the q-BZ for selected n,m,\nu and k [<code>Qspace_Plot=True</code>].

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

[[File:Elph hbn.jpg|YamboElectronPhononDB plot from yambopy tutorial|500px]]

==Links==
* Back to [[Rome 2023#Tutorials]]
* Back to [[ICTP 2022#Tutorials]]

==References==

Yambopy tutorial: Yambo databases

2026-03-09T19:08:25Z

FulvioPaleari:

In this tutorial we will see some examples on how to read and analyse the data contained in the Yambo netCDF databases, which are not readily available as human readable outputs.

In particular we will take a look at:
* Lattice geometry data (Yambo database: <code>ns.db1</code>, Yambopy class: <code>YamboLatticeDB</code>).
* Dipole matrix elements (Yambo databases: <code>ndb.dipoles</code>, Yambopy class: <code>YamboDipolesDB</code>).
* Exciton energies, symmetries, wavefunctions and spectra (Yambo databases: <code>ndb.BS_diago_Q*</code>, Yambopy class: <code>YamboExcitonDB</code>).

We will also check the command line instructions to quickly generate yambo SAVE folders.

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

The full tutorial, including the Quantum espresso 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/databases_yambopy.tar.gz
$tar -xvzf databases_yambopy.tar.gz
$cd databases_yambopy

We will work with monolayer hexagonal boron nitride electron-phonon and exciton data obtained on a <code>12x12x1</code> kpoint grid. Beware that these are certainly not converged.

=== Command line: generating the Yambo SAVE ===
Yambopy offers a set of command line options. In order to review them, you can type
$yambopy
which will print the output
yambopy v0.7
Available commands are:

plotem1s -> Plot em1s calculation.
analysebse -> Study the convergence of BSE calculations.
analysegw -> Study the convergence of GW calculations by looking at the change in band-gap value.
plotexcitons -> Plot excitons calculation
addqp -> Add corrections from QP databases.
mergeqp -> Merge QP databases
save -> Produce a SAVE folder
gkkp -> Produce a SAVE folder including elph_gkkp databases
bands -> Script to produce band structure data and visualization from QE.
serial -> Script to update serial numbers of yambo ndb.* databases in order to import them to new calculations.
gwsubspace -> Script to calculate off-diago corrections of yambo ndb.QP databases in order to plot band structure.
phinp -> Script to update the explicit list of q-points in a ph input file (ldisp=.false., qplot=.true.).
convert -> Script to convert RL number in Ry energy units using ndb.gops.
bsesize -> Script to calculate the expected BSE kernel size, in GB, to be loaded by each MPI task.
l2y -> Calculate gauge-invariant electron-phonon matrix elements with LetzElPhC and convert them into Yambo format.
exc-irrep -> Script to get the irreducible representation labels for excitonic states. [-h for help]
exc-wf -> Real space exciton wf for either fixed hole/electron. [-h for help]
exc-sort -> Script to sort excitonic states according to energies and intensities. [-h for help]

For this tutorial, we will need the <code>save</code> and <code>gkkp</code> options.
By typing in one of these, additional information about how to run the commands will be printed, e.g.:
$yambopy save

Produce a SAVE folder

Arguments are:
-nscf, --nscf_dir -> Path to nscf save folder
-y, --yambo_dir -> <Optional> Path to yambo executables

The quantum espresso save for hBN is provided in the directory <code>BSE_saves/QE_saves/hBN.save</code> (you can check the contents of the various folders).
Then, following the instructions printed on screen, we can generate a yambo SAVE from the hBN.save by typing

$yambopy save -nscf BSE_saves/QE_saves/hBN.save

This should produce a SAVE folder in the current directory.

=== Lattice intro: plot k-point coordinates in IBZ/BZ ===
For this section we will use the script <code>bz_plot.py</code>.

By inspecting the SAVE folder we have just generated, we will find the <code>ns.db1</code> database which contains all the geometry and lattice information.
We are now going to read it in python by using the Yambopy class <code>YamboLatticeDB</code>, which can be instanced like this:

from yambopy import *
ylat = YamboLatticeDB.from_db_file(filename="PATH/TO/SAVE/ns.db1")
(remember to edit the variable <code>save_path</code> in order to point at your yambo SAVE).

The <code>ylat</code> object now contains many useful information as attributes, such as the k-points in Cartesian or crystal coordinates, the system symmetries, lattice constants and basis vectors in real and reciprocal space, etc.
The k-points are also automatically expanded in the full Brillouin zone from the irreducible one (you can turn this off with the option <code>Expand=False</code>).

Directly printing the object with
print(ylat)
will also give us some general parameters related to the database.

Now check the <code>bz_plot.py</code> script. You will see that it performs three plots:
* Scatterplot of the k-points in Cartesian coordinates with both expanded and unexpanded grids, with annotated indices [<code>Cartesian_Plot=True</code>].
* Scatterplot of the k-points in crystal coordinates [<code>Crystal_Plot=True</code>].
* Manual transformation of a chosen k-point from irreducible to full Brillouin zone (you can change the index <code>i_k</code> in the script to check different cases) [<code>Symmetry_Plot=True</code>].

Below, the result of the first plot.

[[File:Car kpoints hbn.jpg|YamboLatticeDB plot from yambopy tutorial| 500px]]

'''What about the units?'''

Below we report the relation between units used in Yambo, Quantum Espresso, and Yambopy.

* bohr^-1 (atomic units): <code>YamboLatticeDB.car_kpoints*2.*pi</code>. Divide by the bohr-to-angstrom conversion factor to obtain angs^-1
* Yambo cartesian units (<code>[cc]</code> in Yambo outputs): <code>YamboLatticeDB.car_kpoints*2.*pi</code> (same as above).
* QE cartesian units (<code>[cart. coord. in units 2pi/alat]</code> in QE outputs): <code>YamboLatticeDB.car_kpoints*YamboLatticeDB.alat[0]</code>.
* Internal yambo units (<code>[iku]</code> in yambo outputs): <code>YamboLatticeDB.iku_kpoints</code>
* Fractional coordinates (<code>[rlu]</code> in yambo, <code>cryst. coord.</code> in QE): <code>YamboLatticeDB.red_kpoints</code>.

=== Dipoles intro: plots of dipoles on BZ, plot of IP absorption ===
In this section we will use the script <code>dipoles_plot.py</code> and read the dipole databases generated in an optical absorption calculation by yambo. Keep in mind that from now on we will use the "BSE" yambo SAVE generated in the [[#Command line: generating the Yambo SAVE|first section]].

The databases written after a calculation of optical properties with yambo (dipoles, static screening, excitons) are in the directory <code>BSE_saves/BSE_databases</code>. Here we will also find <code>ndb.dipoles</code> which is needed now, since it contains the matrix elements d_{vck}(\alpha) where vk and ck are the valence and electron states involved in the transition and \alpha the polarisation direction of the external electric field.

In order to read it in python we use the Yambopy class <code>YamboDipolesDB</code>, which can be instanced like this:
ydip = YamboDipolesDB(ylat,save='path/to/BSE/databases',filename='ndb.dipoles')
(notice that it requires a previous instance of <code>YamboLatticeDB</code>).

In addition, in order to read the Kohn-Sham energies, we can also instance the <code>YamboElectronsDB</code> as
yel = YamboElectronsDB.from_db_file(folder='path/to/SAVE')

The object <code>ydip</code> now has a method that permits to retrieve the independent-particle absorption spectrum with customly chosen energy range, steps, and broadening:
w, eps2 = ydip.ip_eps2(yel)

In order to see all this in action, take a look at the <code>dipoles_plot.py</code> script. You will see that it performs two plots:
* Plot of |d(k)| in the BZ for selected v,c and \alpha (we choose the layer plane 'xy') [<code>Kspace_Plot=True</code>]. From this plot you can appreciate which sections of the BZ contribute the most to the absorption rate.
* Plot of the independent-particles absorption spectrum [<code>Absorption_Plot=True</code>].

You can play with the indices and the plot parameters to check what happens.

[[File:Dipoles hbn2.png|YamboDipolesDB plot from yambopy tutorial|500px]]

=== Exciton intro 1: read and sort data ===
In this section we will use both the script <code>exc_read.py</code> and the command line in order to read the exciton data resulting from a BSE calculation to familiarise with their structure. This time we are going to read the <code>ndb.BS_diago_Q*</code> databases which correspond to BSE calculations at various momenta Q (Q=1 being the zero-momentum optical absorption limit - notice that python indexing starts from 0, while the databases are counted starting from 1).

In order to read them in python we use the Yambopy class <code>YamboExcitonDB</code>, which can be instanced like this:
yexc = YamboExcitonDB.from_db_file(ylat,filename=f'path/to/BSE/databases/ndb.BS_diago_Q{i}')
(where i is the number of BS_diago_Qi file. Notice that it requires a previous instance of <code>YamboLatticeDB</code>).

Now the <code>yexc</code> object contains information about the exciton energies (<code>yexc.eigenvalues</code>), wave functions (<code>yexc.eigenvectors</code>) and intensities (<code>yexc.l_residuals</code>, <code>yexc.r_residuals</code>) for Qpoint i_Q. You can start by keeping <code>Q1</code> which is the optical limit and then check other momenta.

The exciton wave function components A_{vck}^{\lambda Q} (\lambda being the exciton index) are stored as A_{t}^{\lambda} in each Q-dependent database, with t being the transition index grouping the single-particle indices vck. Therefore, <code>yexc.eigenvectors</code> is an array with (N_excitons,N_transitions) dimension. In order to make the connection t->kcv, the table <code>yexc.table</code> provides k,v,c and spin indices corresponding to each transition.

In order to get a clearer picture, take a look at the script <code>exc_read.py</code>. Run it and try to understand the outputs.
$ python exc_read.py

Actually, we can produce output files with the sorted exciton energies in a much more convenient way by using the command line instruction <code>exc-sort</code>. Check its syntax via:
$ yambopy exc-sort -h

Then, we run it for our specific calculation with:
$ yambopy exc-sort --save BSE_saves/YAMBO_saves/SAVE -J BSE_saves/BSE_databases --iqpt 1

This should produce the <code>o-BSE_databases.exc_qpt1_sorted_E.dat</code> and <code>o-BSE_databases.exc_qpt1_sorted_I.dat</code> output files for you to inspect. These are very useful as they allow for identification of degenerate states and degree of optical activity. You will see that in our system most states are doubly degenerate, a byproduct of crystal symmetry. This is an updated version of the ypp exciton analysis that you can find [[How to analyse excitons#Sort the excitonic eigenvalues|here]].

=== Exciton intro 2: symmetry analysis and wavefunction plot in real space ===

==== Symmetries of excitons====
We can analyse the symmetries of the excitonic wavefunctions in terms of irreducible representation of the point group of the system (if at Q=0) or the Q little group. For more information, the methodology is explained in Ref. <ref>Symmetries of excitons, M. Nalabothula et al., [https://arxiv.org/abs/2511.21540 preprint arXiv]</ref>.

We use the <code>exc-irrep</code> command line option, check the arguments with:
$ yambopy exc-irrep -h

We know from the previous section (by inspecting the sorted energies) that the first four BSE eigenvalues correspond to two doubly-degenerate bright states. Let us analyse their symmetry by running
$ yambopy exc-irrep --path BSE_saves/YAMBO_saves -J BSE_saves/BSE_databases --iqpt 1 --nstates 4

This command first loads the electronic wave functions and calculated the electronic representation matrices (called <code>Dmats</code> in the code). As a second step, they are used to compute the '''excitonic''' representation matrices.

We obtain the following output:

========================================
Group theory analysis for Q point : (0.000000, 0.000000, 0.000000)
****************************************
Little group : D3h
Little group symmetries : [ 1 2 3 4 5 6 7 8 9 10 11 12]
Classes (symmetry indices in each class):
E : [1]
2S_3 : [2 6]
2C_3 : [3 5]
sigma_h : [4]
3C_2 : [ 7 9 11]
3sigma_v : [ 8 10 12]

====== Exciton representations ======
Energy (eV), degeneracy : representation
----------------------------------------
1.9139 2 : E'
2.5988 2 : E'
****************************************

This is similar to the group theory analysis done by Quantum Espresso on the electronic states, and is actually analogous to the one performed for the phonon modes of crystals. We see that the first two states transform as the E' representation of the D3h point group of the crystal. By optical selection rules, only states with this symmetry can form absorption peaks in monolayer BN when light is polarized along the layer plane.

We could go further and calculate the total crystal angular momentum of these states, while also rotate the degenerate exciton states so that they are both eigenvectors of the BSE Hamiltonian and the total crystal angular momentum operator. This is very useful for analyses involving selection rules, exciton-boson couplings, chirality, etc. This is an advanced topic and will not be covered, nonetheless an example script is provided in the tutorial folder called <code>total_crystal_angular_momentum_exciton.py</code>.

''' What to do when symmetry analysis does not seem to work well '''

* Check for warnings during execution. If the BSE calculation was done with a response function that breaks the symmetries (such as the longitudinal response in place of the transverse one at q=0), that may explain the issues.

* If the exciton density of states is very high (such as for a bulk 3D system or for a 2D system at higher energies in the optical spectrum), the analyser may fail to resolve degenerate states, and incorporate a bunch of states together. The symmetry analysis will still be performed but the representation labels will appear as summed. In severe cases, the code may crash. You can try to get a better result by carefully selecting the degeneracy tolerance with <code>degen_tol</code> and restricting the number of states with <code>nstates</code> in the command line options.

====Exciton wave functions in real space====
We can also plot the wave functions of the exciton states on the crystal lattice. In practice, what we do is set the position of the hole at a "physical" point, and then visualize the resulting electronic distribution:

<math>I^{e}_{\lambda \mathbf{Q}}(\mathbf{r}_e)= |\Psi_{\alpha \mathbf{Q}}(\mathbf{r}_e,\mathbf{r}_h=\mathbf{r}_0)|^2</math>

Let us focus on the lowest exciton state, which gives rise to the largest peak in absorption (see the last part of the tutorial). We will set the hole position on top of a nitrogen atom, since that's where the <math>p_z</math> orbitals where the hole comes from are mostly localized.

If we don't know the correct coordinates, we can modify the <code>bz_plot.py</code> script by adding (after instancing the lattice object):
for iat in range(len(ylat.atomic_numbers)): print(ylat.atomic_numbers[iat],ylat.red_atomic_positions[iat])
which will print
5 [0.6666667 0.3333333 0. ]
7 [-0.6666667 -0.3333333 0. ]

In order to make the plot, we have to give yambopy the same inputs that are used in the equivalent [[How to analyse excitons#Plot the exciton spatial distribution| ypp calculation]]. First, let's check all the options via
$ yambopy exc-wf -h

Then, we can run our calculation (by selecting a 9x9x1 supercell and a 30 Ry cutoff) as
$ yambopy exc-wf --path BSE_saves/YAMBO_saves -J BSE_saves/BSE_databases --iqpt 1 --iexe 1 --supercell 9 9 1 --wfc_cutoff 30 --hole 0.33333333 0.66666667 0.03

Yambopy will produce a *.cube file that can be visualized with VESTA, xcrysden or the like, producing a figure similar to the one below.

The example script <code>exc_real_wf.py</code>, which runs the same calculation by explicitly calling the necessary functions, will give you more info about what is happening behind the scenes.

[[File:Exc BN yambopy.png|YamboExcitonDB exciton wave function|400px]]

We see that electron is localised in <math>p_z</math>-like distributions on top of boron atoms around the nitrogen where the hole is set.

=== Exciton intro 3: plot exciton weights on k-BZ and (interpolated) band structure ===
In this section we will use the script <code>exc_kspace_plot.py</code> and work with the quantities defined in the previous section.

For now, only the i_Q=0 case is implemented in this section.
We want to check the relative importance of the various (vk->ck) electronic transitions in forming a certain excitonic state.

Since many excitonic states are degenerate, we first need to tell Yambopy which states we want to check. For example, in monolayer hexagonal boron nitride, the lowest-bound exciton - forming the main peak in the BSE absorption spectrum - is doubly degenerate. In order to analyse it, in the <code>exc_kspace_plot.py</code> script we set
states = [1,2]
(we can also set [3,4] to check the second excitonic state, and then [5] for the non-degenerate third state, and so on; we can check degeneracies by printing the energies using the script <code>exc_read.py</code>).

In order to make a band structure plot, it is necessary to read the band energies, for example with the <code>YamboSaveDB</code> class
yel = YamboSaveDB.from_db_file(folder='path/to/SAVE')
and specify the path in the BZ using crystal coordinates via the <code>Path</code> function:
npoints = 20
path = Path([ [[ 0.0, 0.0, 0.0],'$\Gamma$'],
[[ 0.5, 0.0, 0.0],'M'],
[[1./3.,1./3., 0.0],'K'],
[[ 0.0, 0.0, 0.0],'$\Gamma$']],
[int(npoints*2),int(npoints),int(sqrt(5)*npoints)] )

Now let's take a closer look at the <code>exc_kspace_plot.py</code> script. You will see that it performs three plots:
* Plot of |A(k)| in the k-BZ for the selected exciton state. You can see how most contributions come from the area around K and the MK direction [<code>Kspace_Plot=True</code>].
* Plot of |A(v,c,k)| on the electronic band structure for the selected exciton state. Here you can better see how the top valence and bottom conduction around MK are mostly involved [<code>Bands_Plot=True</code>].
* Plot of interpolated |A(v,c,k)| on the interpolated electronic band structure for the selected exciton state [<code>Bands_Plot_Interpolated=True</code>].

As always, try to play with the parameters, for example by changing the excitonic states to analyse.

[[File:Exc bands1 hbn.jpg|YamboExcitonDB plot from yambopy tutorial|300px| Uninterpolated exciton weights on top of band structure]][[File:Exc bands2 hbn.jpg|YamboExcitonDB plot from yambopy tutorial|300px]]

=== Exciton intro 4: plot BSE optical absorption with custom options ===
In this section we will use the script <code>exc_abs_plot.py</code> and work with the quantities defined in the previous sections.

The class <code>YamboExcitonDB</code> also enables us, of course, to read the dielectric function eps(w) and print absorption and related spectra in python.

The advantages over using the standard human-readable yambo outputs are mainly two:
# We can freely select energy ranges, energy steps, peak broadenings and number of excitonic states included without having to rerun the <code>yambo</code> executable every time. This reduces the chance of mistakenly editing the yambo input and allows for greater freedom since these plots can now be done in your local machine without having to transfer the output data from a remote cluster.
# The dielectric function constructed from netCDF database variables has a much higher precision (number of significant digits) than the human readable output, which may be important if you want to perform additional operations in python (e.g., computing refractive index, reflectivity and other optical spectra from it, performing finite-difference derivatives, etc).

We can read eps(w) as a <code>numpy</code> array with the specified options as (energy values are in eV):
w, eps = yexc.get_chi(nexcitons='all',emin=0,emax=7,estep=0.005,broad=0.04)
Or, you can directly prepare a plot of its imaginary part with
w, chi = yexc.plot_chi_ax(ax,nexcitons='all',emin=0,emax=7,estep=0.005,broad=0.04)
where <code>ax</code> is a previously defined <code>Axes</code> object from <code>matplotlib</code>.

In order to see how this works, let's take a look at the <code>exc_abs_plot.py</code> script.
You will see that it performs the two operations described above:
* Plotting the BSE absorption spectrum [<code>Absorption_Plot=True</code>].
* Reading the complex dielectric function.

Try to customise the plots by changing the <code>nexcitons</code>, <code>emin</code>, <code>emax</code>, <code>estep</code>, <code>broad</code> parameters.

[[File:Absalpha.png|Yambo alpha_2D tutorial plot|700px]]

=== Command line: importing electron-phonon matrix elements ===
You may have seen how to calculate and import electron-phonon matrix elements in yambo in the [[Electron Phonon Coupling|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 <code>ELPH_SAVES/QE_SAVES/hBN.save</code> (nscf calculation) and <code>ELPH_SAVES/QE_SAVES/elph_dir</code> (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 <code>ndb.elph_gkkp_expanded*</code> databases.

=== Electron-phonon intro: plots of el-ph matrix elements on k-BZ and q-BZ ===
In this section we will use the script <code>elph_plot.py</code> and read the electron-phonon databases that you generated in the previous section.

In order to read the <code>ndb.elph_gkkp_expanded*</code> databases in python we use the Yambopy class <code>YamboElectronPhononDB</code>, 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 <code>YamboLatticeDB</code>).

Now, the <code>yelph</code> 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 <code>YamboElectronPhononDB</code> class with
print(yelph.__doc__)
to get an idea of the information stored and of its capabilities.

Now check the <code>elph_plot.py</code> script. You will see that it performs two plots:
* Plot of |g(k)| in the k-BZ for selected n,m,\nu and q [<code>Kspace_Plot=True</code>].
* Plot of |g(q)| in the q-BZ for selected n,m,\nu and k [<code>Qspace_Plot=True</code>].

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

[[File:Elph hbn.jpg|YamboElectronPhononDB plot from yambopy tutorial|500px]]

==Links==
* Back to [[Rome 2023#Tutorials]]
* Back to [[ICTP 2022#Tutorials]]

==References==

First steps in Yambopy

2026-03-09T19:05:32Z

FulvioPaleari: /* Tutorials */

The yambopy project aims to develop python tools to:

* Read and edit yambo and quantum espresso input files
* Easily perform pre- and post-processing of the simulation data for these two codes - including hard-to-get, database-encoded data beyond standard outputs
* Provide easy visualization and plotting options
* Set up simple automatization workflows (e.g., convergence tests)

=== Setup ===
First of all, make sure that you have a suitable python environment (crated for example with [https://docs.anaconda.com/miniconda/install/ conda] or [https://docs.python.org/3/library/venv.html venv]) with '''python >=3.8'''.

If you are not used with python environments, here two simple commands that you can use
python -m venv MYPATH/yamboenv/
(you can replace `MYPATH` with any path you prefer, e.g. `~/`)
source MYPATH/yamboenv/bin/activate
(for bash users, you can add to your .bashrt the line `. MYPATH/yamboenv/bin/activate`)

Then, you may install yambopy in one of the following ways.

==== Quick installation from PyPI repository ====

* In order to quickly install the officially released version type:

pip install yambopy

==== Installation from tarball ====

* In case you don't want to download from the pip repository and prefer to install a version of yambopy locally, you may download the appropriate tarball from the [https://github.com/yambo-code/yambopy/releases| yambopy github page]. Extract the tarball, enter the yambopy folder and type <code>pip install .</code>

==== Installation of latest patch ====

* In case you want the latest version of the code including new updates and patches that might not be present in the official version, then you can clone the yambopy git repository (a basic knowledge of git may be helpful):

git clone https://github.com/yambo-code/yambopy.git
cd yambopy
pip install .

==== Installation for developers ====
* If you want to install YamboPy in developing mode (to modify or add new functions) you have to download the code from github repository then go in the YamboPy folder and install with the command:

pip install -e .

'''Important:''' if you want your changes to be included into a new patch/version of Yambopy, you need to first create your own personal fork of the git repository, make the changes there, and then create a pull request for the original repository.

==== Dependencies ====

* In principle, <code>pip</code> should take care of the required python dependencies. They are <code>numpy</code>, <code>scipy</code>, <code>matplotlib</code>, <code>netCDF4</code>, <code>h5py</code>, <code>lxml</code>, <code>PyYAML</code>, <code>monty</code>, <code>scikit-learn</code>, <code>tqdm</code>, <code>spglib</code>, <code>spgrep</code>, <code>pykdtree</code>, and <code>numba</code>. In case some dependency-related problem arises, you can install each of them separately beforehand with:

pip install <code>dependency-name</code>

* If you experience errors related to <code>NetCDF4</code> or <code>hdf5</code>, these are usually due to incompatibilities between the python modules the library in your environment. In this case, you can force the python installation to match the system library. For example, if you have an <code>hdf5</code> problem and you are using conda, you could try:

conda install --force-reinstall h5py hdf5

=== Tutorials ===
Now yambopy is ready to use! Just go to the tutorials folder and follow the docs!

cd tutorial/

On this wiki, we provide steps for the following tutorials:

1. Data postprocessing:
* [[Yambopy tutorial: band structures | Database and plotting tutorial for quantum espresso (qepy) and GW band structures]] (Get the databases: [https://media.yambo-code.eu/educational/tutorials/files/databases_qepy.tar.gz databases_qepy], 46.5MB)
* [[Yambopy tutorial: Yambo databases | Database and plotting tutorial for yambo (yambopy) and exciton analysis ]] (Get the databases: [https://media.yambo-code.eu/educational/tutorials/files/databases_yambopy.tar.gz databases_yambopy], 129MB)
2. Manage QE and Yambo runs: [WARNING: these tutorials are currently under maintenance due to updates to the scheduler class]
* [[GW tutorial. Convergence and approximations (BN)]]
* [[Bethe-Salpeter equation tutorial. Optical absorption (BN)]]
3. Advanced topics:
* [[Yambopy tutorial: electron-phonon coupling|Databases and plotting tutorial for electron-phonon coupling with yambopy]] (Get the databases: )
* [[Exciton-phonon coupling and luminescence]]
* [[Phonon-assisted luminescence by finite atomic displacements]]

=== How to cite ===
If yambopy helped you with your data analysis, workflow management of figure preparation, you can consider citing us.

The way to do so in BibTeX format is the following:
@misc{yambopy,
author = {Paleari, Fulvio and Molina-Sánchez, Alejandro and Nalabothula, Muralidhar and Reho, Riccardo and Bonacci, Miki and Castelo, José M. and Cervantes-Villanueva, Jorge and Pionteck, Mike and Silvetti, Martino and Attaccalite, Claudio and Pereira Coutada Miranda, Henrique},
title = {Yambopy},
month = mar,
year = 2025,
publisher = {Zenodo},
version = {0.4.0},
doi = {10.5281/zenodo.15012962},
url = {[[https://doi.org/10.5281/zenodo.15012962 https://doi.org/10.5281/zenodo.15012962]]}, }