The Yambo Project - User contributions [en]

Phonon-assisted luminescence by finite atomic displacements

2022-09-15T12:39:54Z

ElenaCannuccia:

[[File:Representative-instantaneous-atomic-configurations-of-H2O-top-and-H3O-bottom-Also.gif|thumb| 200px|Finite atomic displacements]]

In recent years, several articles have been published with Yambo, who calculated the phonon-assisted luminescence by means of finite atomic displacements<ref name='cann'>[https://arxiv.org/abs/1807.11797 Theory of phonon-assisted luminescence in solids: Application to hexagonal boron nitride], E. Cannuccia, B. Monserrat and C. Attaccalite, Phys. Rev. B '''99''', 081109(R) (2019)</ref><ref name='fprl'>[https://arxiv.org/abs/1810.08976 Exciton-Phonon Coupling in the Ultraviolet Absorption and Emission Spectra of Bulk Hexagonal Boron Nitride], F. Paleari et al. PRL '''122''', 187401(2019) </ref><ref name=strain>[https://scipost.org/SciPostPhys.12.5.145 Excitons under strain: light absorption and emission in strained hexagonal boron nitride], P. Lechifflart, F. Paleari and C. Attaccalite, SciPost Phys. '''12''', 145(2022). </ref><ref name='mprl'>[https://arxiv.org/abs/2111.03518 Phonon-Assisted Luminescence in Defect Centers from Many-Body Perturbation Theory], F. Libbi, P. M. M. C. de Melo, Z. Zanolli, M. J. Verstraete, and N. Marzari, Phys. Rev. Lett. '''128''', 167401 (2022) </ref>.
In this tutorial, we will show how to use [https://github.com/yambo-code/yambopy YamboPy] in combination with Yambo to perform this kind of calculation. For a general review of finite displacement calculations of vibrational properties we recommend this article<ref>Electron-phonon coupling from finite differences, Bartomeu Monserrat, J. Phys.: Condens. Matter '''30''' 083001(2018)</ref>. 
Notice that the calculation of phonon-assisted luminescence by finite atomic displacements are quite involved and expensive from a computational point of view, for this reason, they are limited to relatively simple systems. 
In this tutorial, we will follow the approach of Ref.<ref name=fprl></ref>, and calculate luminescence using the Roosbroeck–Shockley (RS) relation applied to the excitonic case. 
If you use this approach to calculate luminescence or phonon-assisted absorption please cite references <ref name=cann></ref> and <ref name=fprl></ref>. 
'''Important:''' This tutorial requires that you are familiar with Bethe-Salpeter calculations with Yambo, and phonons with Quantum-Espresso, and YamboPy. If it is not the case please study the corresponding tutorial before continuing.

== Locate the lowest indirect exciton (or indirect band gap) ==

In this tutorial as example, we will consider the hexagonal-BN, which is an indirect insulator. The first step to calculate the phonon-assisted luminescence is to locate the lowest indirect exciton. The cleanest strategy to identify the lowest excitation would be to calculate the excitons along the whole Irreducible Brillouin zone(IBZ), then interpolate them as explained in [https://www.yambo-code.org/wiki/index.php?title=How_to_analyse_excitons#Interpolate_exciton_dispersion_(only_in_Yambo_5.x) Interpolate exciton dispersion] and find the '''q''' point that corresponds to the minimum. 
A simpler approach is to use the GW (or Kohn-Sham) band structure to find the momentum responsible for the indirect band gap, in the major part of cases this corresponds to the lowest exciton. 
In the h-BN case we have:
[[File:Bn band structure.png|1000px|center| Yambo tutorial image]]

The indirect gap is between a point close to '''K''' and the '''M''' point, see panel (a) of the figure above. We will approximate the momentum responsible for the indirect emission with '''q=K-M'''. Notice that then we should build supercells that contain this moment, so it is good to approximate it with fractions of integers that are not too large so as not to have giant supercells. In this case we get '''q=(1/3,-1/6, 0)'''. 
Notice that if you have a direct band gap material, the momentum '''q''' corresponding to the lowest transition is '''q=0''' and you do not need to construct special supercells to sample the corresponding vibration, it will be sufficient to displace atoms in the primitive cell.

== Calculate phonons at momentum '''q''' of the indirect transition ==

Now we need to calculate all atomic vibrations compatible with the momentum of the lowest indirect transition. In order to do so, we first calculate the phonons with QE, here the inputs [https://www.yambo-code.org/educational/tutorials/files/hBN_phonons.tgz hBN_phonons.tgz], then we calculate the force constants with q2r.x and now we can interpolate phonons along all the BZ as shown in panel (b) of Figure 1. Then we use matdyn.x to calculate phonons at momentum '''q=K-M = (1/3, -1/6, 0)''':

&input
asr='crystal',
flfrc='bn.fc',
flfrq='bn.freq',
deltaE=1.d0,
q_in_cryst_coord=.true.
fleig='bn.eig'
/
2
0 0 0
0.3333333333333333 -0.16666666666666666666 0.0

The obtained phonon modes correspond to phonons at the vertical red line in panel(b) of Fig. 1. They are written in the ''matdyn.modes'' file with the corresponding eigenvectors and will be later used to displace atoms along the phonon modes.
If you open the 'matdyn.modes' file you will find phonon modes for the '''q=0''' and '''q=(1/3, -1/6, 0)''' that in cartesian coordinates is (1/3,0,0). We copy the modes corresponding to the second '''q=(1/3, -1/6, 0)''' in a separate file, called ''Q2.modes'' that will look like:

diagonalizing the dynamical matrix ...

q = 0.3333 0.0000 0.0000
**************************************************************************
freq ( 1) = 5.194139 [THz] = 173.257815 [cm-1]
( 0.000000 -0.000000 -0.000000 -0.000000 -0.274372 -0.475224 )
( -0.000000 0.000000 -0.000000 -0.000000 -0.445962 0.000001 )
( -0.000000 -0.000000 -0.000000 -0.000000 -0.222981 -0.386214 )
( 0.000000 0.000000 -0.000000 0.000000 -0.548742 0.000000 )
...........................

== Generate the supercell==

Now we use YamboPy to generate the supercell corresponding to the momentum '''q=(1/3, -1/6, 0)'''. A tutorial is already present in the file ''tutorial/supercell/generate_supercells.py''.
You can edit the file to specify the momentum '''q''', the name of the SCF initial file (uc_filnm), and the name of the phonon mode file (mode_file).

.....
uc_filnm = 'hBN.scf.in' #pw input
Q = [[1,-1,0],[3,6,0]] #qpoint to fold in nondiagonal supercell: Q=(1/3,-1/6,0)
kpoints = [12,12,4] #NB: these fractional crystal coordinates must exactly divide the kpoint mesh!
modes_file = 'Q2.modes' #file with phonon eigenmodes
.....

run the script to generate the supercell without displacing atoms ''python generate_supercells.py -N''. The script will generate a non-diagonal supercell<ref>[https://arxiv.org/abs/1510.04418 Lattice dynamics and electron-phonon coupling calculations using nondiagonal supercells], J. H. Lloyd-Williams and B. Monserrat, Phys. Rev. B '''92''', 184301(2015) </ref> in the file "sc_nondiagonal.bn.scf' that is shown below:

[[File:Supercell.png|500px|center| Supercell for the momentum q=(1/3, -1/6, 0) and the corresponding reciprocal space]]

The YamboPy script automatically reduces the number of k-point in such a way to have the same sampling of the corresponding primitive cell, however we advise you to check if the new k-point grid is what you expect, and modify it in case of the incorrect grid. 
In the same way, you can generate the input file for non-self-consistent calculation in the supercell.

==Calculate the optical spectra in the supercell==

Now you have to calculate the optical spectra and exciton in the new supercell. Do not forget to increase the number of conduction bands in both the screening and the Bethe-Salpeter equation. For example in the supercell shown above, there are 24 atoms, 6 times more than in the original cell, so you will have to multiply the number of bands by 6, if in the base cell you have used 40 bands here you will have to put 240 to have the same convergence parameters. Then print exciton according to their energy with the command ypp -e s. 

'''N. B. ''': in order to not recalculate W for each atomic displacement you can perform calculations without symmetries in the pristine supercell and then copy the corresponding dielectric constant in the calculations with displaced atoms, this is usually a safe approximation described in Ref.<ref name="cann"></ref>. 

After solving the BSE in the supercell you will find the excitons that were already present in the primary cell (within the numerical noise) and new lower energy excitons, with zero dipole matrix elements, that correspond to the indirect excitons that have now been mapped at '''q=0''', something like:

# Maximum Residual Value = 0.38659E+01
#
# E [ev] Strength Index
#
5.7165937 0.47290171E-11 1.0000000 <-- Indirect exciton mapped at q=0
5.7166047 0.58239158E-09 2.0000000 <-- Indirect exciton mapped at q=0
5.7367945 0.31830746E-09 3.0000000 <-- Indirect exciton mapped at q=0
5.7368207 0.33674005E-10 4.0000000 <-- Indirect exciton mapped at q=0
5.80542803 0.100763231E-6 5.00000000 <-- Direct exciton
5.80598068 0.384604526E-8 6.00000000 <-- Direct exciton
5.88944197 1.00000000 7.00000000 <-- Direct exciton
5.88967037 0.102969212E-1 8.00000000 <-- Direct exciton
................

This result shows that indirect exciton without the coupling with phonon does not contribute to the optical response. 

==Displace atoms and calculate dipoles derivatives==
Now you can generate the displaced supercell for all the phonon modes compatible with the indirect band gap '''q''' point by doing: ''python generate_supercells.py -S''. The script will produce a set of input files for each of the 12 phonon modes at '''q=(1/3,-1/6,0)'''. You have to perform BSE calculation for each one of these modes and get exciton dipoles. 
For each phonon mode the atoms are displaced along the corresponding eigenvector read from the "Q2.modes" file multiplied for 0.1 Bohr (the variable Temp=0.1), see the following line in "generate_supercell.py":

...
sc.displace(eivs,nd_atom_positions,Temp=0.1) # Generate list of displaced supercells as PwIn objects called 'modes_qe'
...

this is usually a good value to get correct derivatives. In principle, it is possible to test different displacement lengths to get good second derivatives. The general rule is that the displacement should not be too small to avoid numerical noise and not too large to avoid contribution from third or forth order derivatives. 
Once you get dipoles for a given phonon mode you can calculate the second order dipole derivatives using a finite difference formula and the fact the first order derivatives are zero by construction as:
<center>
<math display="inline"> \frac{\partial^2 | T^S |^2}{\partial R_{\lambda,q}^2 } = 2 \frac{| T^S (R=\Delta R) |^2 - | T (R=0) |^2}{\Delta R^2} = 2 \frac{| T^S (R=\Delta R) |^2}{\Delta R^2}</math>
</center>
In the Ref.<ref name=fprl></ref><ref name=strain></ref> we found that a single point formula above is enough to get good second derivatives, taking into account that the first derivative is zero, however you can test higher-order formulas to be sure that the result is correct, see for example [https://en.wikipedia.org/wiki/Finite_difference#Higher-order_differences higher-order differences] 

'''Important''': in the file produced by ''ypp'' the oscillator strengths are normalized to have the maximum equal to one, before calculating the derivatives remember to remove this normalization by multiplying all Oscillator Strengths for the maximum residual value, in the previous example:

# Maximum Residual Value = 0.38659E+01

==Luminescence==

Now you have all the information necessary to construct the emission spectra. Using the formula, derived in Ref.<ref name=fprl></ref> you obtain the phonon-assisted luminescence as:
[[File:Light emission.png|center|Light emission formula]]

in this formula:
* nr(ω) is the refractive index, that usually can be approximated with a constant in the luminescence energy range.
* ES'''q''' are the excitonic energies in the undistorted supercell, including indirect excitons
* B(ES,Texc) is the Bose occupation of excitons, that can be approximated with a Boltzman function, see Ref.<ref name=fprl></ref><ref name=strain></ref>
* Texc is the excitonic temperature that should be obtained from experimental measurements or used as a parameters, for a discussion see Ref.<ref name=fprl></ref>
* d2|TS|2/dR2λ'''q''' are the derivatives of the exciton dipole matrix elements for a given phonon mode
* Ωλ,'''q''' are the phonon frequencies and the sum on '''q''' is on the different supercells obtained from phonon modes responsible for the luminescence, in this tutorial there is just a single '''q''' point.
* η is the exciton line-width that is given as input parameter to define the broadening of the spectra

In the h-BN example shown here, the Texc was obtained from experimental measurements, only the lowest two excitons were included in the sum and the Bose function was replaced by a Boltzmann distribution with the energy zero fixed at the lowest excitonic energy. An appropriate scissor operator independent of the atomic displacements was added in the calculation. The final result is shown in the figure above and compared with the experimental measurement at 10 Kelvin
[[File:Lum spectra.png|center|800px|Luminescence spectra]]

'''Some additional considerations on luminescence calculations'''

* In general due to the '''Bose''' (or '''Boltzmann''') factor only the lower excitons (often only the lowest one) contribute to the luminescence signal
* The lowest excitons are '''degenerate''' all of them have to be included in the sum, as in the h-BN example
* In the present formulation of luminescence spectra excitons are treated as Bosons (or Boltzman particles), in principle it is possible to define a '''excitonic occupation''' starting from a quasi-equilibrium distribution of excited electron-hole, but this requires a rotation of the electron-hole occupations in the excitonic base for a discussion see Ref.<ref name='cann'></ref><ref name='mprl'></ref>
* In order to '''speed up calculations''' you can perform all calculations without symmetries and copy the dielectric constant (''ndb.em1s*'' or ''ndb.pp*'' files) from the undistorted supercell to the displaced ones. In this case, if you do not need to calculate GW correction, for example using a scissor, you can also reduce the number of bands in the non-self-consistent calculation to the one required by the BSE, for a discussion see Ref<ref name=strain></ref>
* Notice that the '''dipole matrix elements''' that will enter in optical absorption and luminescence depend form the direction of the electric field. In this example shown before the luminescence has been averaged in ''x'' and ''y'' directions because we were interested in the in-place luminescence. In general is it possible to select specific directions to reproduce particular experimental setups<ref name=cann></ref><ref name=fprl></ref>. 

==Some example input files for h-BN==

In this section, I will provide some input files to repeat calculations in h-BN. Luminescence spectra were calculated using a 12x12x4 k-point grid and 200 bands for the dielectric constant in the primitive cell and 3000 mHa block size. In the supercell used to generate the luminescence spectra, there are 24 atoms, this means that the total number of bands has to be increased to 1200 and the corresponding k-point sampling reduced approximately to 12x2x4, this is automatically done by the Yambopy.
Here are the input files:
* Primitive cell SCF and NSCF files and inputs for phonon calculations: [https://www.yambo-code.org/educational/tutorials/files/Luminescence/hBN_scf_nscf_phonons.tgz hBN_scf_nscf_phonons.tgz]
* The Q=(1/3,1/6,0) phonon mode generated by matdyn.x: [https://www.yambo-code.org/educational/tutorials/files/Luminescence/Q_mode.tgz Q_mode.tgz]
* The non-diagonal supercells for SCF and NSCF calculations (without symmetries) and the Yambo file for the BSE [https://www.yambo-code.org/educational/tutorials/files/Luminescence/BSE_supercell.tgz BSE_supercell.tgz]
* The displaced supercells for exciton-phonon calculations [https://www.yambo-code.org/educational/tutorials/files/Luminescence/Displaced_Cells.tgz Displaced_Cells.tgz]

You can the same BSE input file in all the displaced supercells. 
If you did not use symmetries you can avoid recalculating the dielectric constant by copying the SAVE/ndb.em1s* files from the undistributed supercell to the displaced ones.

== References ==

Phonon-assisted luminescence by finite atomic displacements

2022-09-15T12:36:37Z

ElenaCannuccia: /* Calculate phonons at momentum q of the indirect transition */

[[File:Representative-instantaneous-atomic-configurations-of-H2O-top-and-H3O-bottom-Also.gif|thumb| 200px|Finite atomic displacements]]

In recent years, several articles have been published with Yambo, who calculated the phonon-assisted luminescence by means of finite atomic displacements<ref name='cann'>[https://arxiv.org/abs/1807.11797 Theory of phonon-assisted luminescence in solids: Application to hexagonal boron nitride], E. Cannuccia, B. Monserrat and C. Attaccalite, Phys. Rev. B '''99''', 081109(R) (2019)</ref><ref name='fprl'>[https://arxiv.org/abs/1810.08976 Exciton-Phonon Coupling in the Ultraviolet Absorption and Emission Spectra of Bulk Hexagonal Boron Nitride], F. Paleari et al. PRL '''122''', 187401(2019) </ref><ref name=strain>[https://scipost.org/SciPostPhys.12.5.145 Excitons under strain: light absorption and emission in strained hexagonal boron nitride], P. Lechifflart, F. Paleari and C. Attaccalite, SciPost Phys. '''12''', 145(2022). </ref><ref name='mprl'>[https://arxiv.org/abs/2111.03518 Phonon-Assisted Luminescence in Defect Centers from Many-Body Perturbation Theory], F. Libbi, P. M. M. C. de Melo, Z. Zanolli, M. J. Verstraete, and N. Marzari, Phys. Rev. Lett. '''128''', 167401 (2022) </ref>.
In this tutorial we will show how to use [https://github.com/yambo-code/yambopy YamboPy] in combination with Yambo to perform these kind of calculations. For a general review of finite displacements calculations of vibrational properties we recommend this article<ref>Electron-phonon coupling from finite differences, Bartomeu Monserrat, J. Phys.: Condens. Matter '''30''' 083001(2018)</ref>. 
Notice that calculation of phonon-assisted luminescence by finite atomic displacements are quite involved and expensive from a computational point of view, for this reason they are limited to relatively simple systems. 
In this tutorial we will follow the approach of Ref.<ref name=fprl></ref>, and calculate luminescence using the Roosbroeck–Shockley (RS) relation applied to the excitonic case. 
If you use this approach to calculate luminescence or phonon-assisted absorption please cite references <ref name=cann></ref> and <ref name=fprl></ref>. 
'''Important:''' This tutorial requires that you are familiar with Bethe-Salpeter calculations with Yambo, and phonons with Quantum-Espresso, and YamboPy. If it is not the case please study the corresponding tutorial before continuing.

== Locate the lowest indirect exciton (or indirect band gap) ==

In this tutorial as example we will consider the hexagonal-BN, that is an indirect insulator. The first step to calculate the phonon-assisted luminescence is to locate the lowest indirect exciton. The cleanest strategy to identify the lowest excitation would be to calculate the excitons along the whole Irreducible Brillouin zone(IBZ), then interpolate them as explained in [https://www.yambo-code.org/wiki/index.php?title=How_to_analyse_excitons#Interpolate_exciton_dispersion_(only_in_Yambo_5.x) Interpolate exciton dispersion] and find the '''q''' point that correspond to the minimum. 
A simpler approach is to use the GW (or Kohn-Sham) band structure to find the momentum responsible for the indirect band gap, in the major part of cases this corresponds to the lowest exciton. 
In the h-BN case we have:
[[File:Bn band structure.png|1000px|center| Yambo tutorial image]]

The indirect gap is between a point close to '''K''' and the '''M''' point, see panel (a) of the figure above. We will approximate the momentum responsible for the indirect emission with '''q=K-M'''. Notice that then we should build supercells that contain this moment, so it is good to approximate it with fractions of integers that are not too large so as not to have giant supercells. In this case we get '''q=(1/3,-1/6, 0)'''. 
Notice that if you have a direct band gap material, the momentum '''q''' corresponding to the lowest transition is '''q=0''' and you do not need to construct special supercells to sample the corresponding vibration, it will be sufficient to displace atoms in the primitive cell.

== Calculate phonons at momentum '''q''' of the indirect transition ==

Now we need to calculate all atomic vibrations compatible with the momentum of the lowest indirect transition. In order to do so, we first calculate the phonons with QE, here the inputs [https://www.yambo-code.org/educational/tutorials/files/hBN_phonons.tgz hBN_phonons.tgz], then we calculate the force constants with q2r.x and now we can interpolate phonons along all the BZ as shown in panel (b) of Figure 1. Then we use matdyn.x to calculate phonons at momentum '''q=K-M = (1/3, -1/6, 0)''':

&input
asr='crystal',
flfrc='bn.fc',
flfrq='bn.freq',
deltaE=1.d0,
q_in_cryst_coord=.true.
fleig='bn.eig'
/
2
0 0 0
0.3333333333333333 -0.16666666666666666666 0.0

The obtained phonon modes correspond to phonons at the vertical red line in panel(b) of Fig. 1. They are written in the ''matdyn.modes'' file with the corresponding eigenvectors and will be later used to displace atoms along the phonon modes.
If you open the 'matdyn.modes' file you will find phonon modes for the '''q=0''' and '''q=(1/3, -1/6, 0)''' that in cartesian coordinates is (1/3,0,0). We copy the modes corresponding to the second '''q=(1/3, -1/6, 0)''' in a separate file, called ''Q2.modes'' that will look like:

diagonalizing the dynamical matrix ...

q = 0.3333 0.0000 0.0000
**************************************************************************
freq ( 1) = 5.194139 [THz] = 173.257815 [cm-1]
( 0.000000 -0.000000 -0.000000 -0.000000 -0.274372 -0.475224 )
( -0.000000 0.000000 -0.000000 -0.000000 -0.445962 0.000001 )
( -0.000000 -0.000000 -0.000000 -0.000000 -0.222981 -0.386214 )
( 0.000000 0.000000 -0.000000 0.000000 -0.548742 0.000000 )
...........................

== Generate the supercell==

Now we use YamboPy to generate the supercell corresponding to the momentum '''q=(1/3, -1/6, 0)'''. A tutorial is already present in the file ''tutorial/supercell/generate_supercells.py''.
You can edit the file to specify the momentum '''q''', the name of the SCF initial file (uc_filnm) and the name of the phonon mode file (mode_file).

.....
uc_filnm = 'hBN.scf.in' #pw input
Q = [[1,-1,0],[3,6,0]] #qpoint to fold in nondiagonal supercell: Q=(1/3,-1/6,0)
kpoints = [12,12,4] #NB: these fractional crystal coordinates must exactly divide the kpoint mesh!
modes_file = 'Q2.modes' #file with phonon eigenmodes
.....

run the script to generate the supercell without displace atoms ''python generate_supercells.py -N''. The script will generate a non-diagonal supercell<ref>[https://arxiv.org/abs/1510.04418 Lattice dynamics and electron-phonon coupling calculations using nondiagonal supercells], J. H. Lloyd-Williams and B. Monserrat, Phys. Rev. B '''92''', 184301(2015) </ref> in the file "sc_nondiagonal.bn.scf' that is shown below:

[[File:Supercell.png|500px|center| Supercell for the momentum q=(1/3, -1/6, 0) and the corresponding reciprocal space]]

The YamboPy script automatically reduce the number of k-point in such a way to have the same sampling of the corresponding primitive cell, however we advice you to check if the new k-point grid is what you expect, and modify it in case of incorrect grid. 
In the same way you can generate the input file for non-self-consistent calculation in the supercell.

==Calculate the optical spectra in the supercell==

Now you have to calculate the optical spectra and exciton in the new supercell. Do not forget to increase the number of conduction bands in both the screening the Bethe-Salpeter equation. For example in the supercell shown above there are 24 atoms, 6 times more than in the original cell, so you will have to multiply the number of bands by 6, if in the base cell you have used 40 bands here you will have to put 240 to have the same convergence parameters. Then print exciton according to their energy with the command ypp -e s. 

'''N. B. ''': in order to not recalculate W for each atomic displacement you can perform calculations without symmetries in the pristine supercell and then copy the corresponding dielectric constant in the calculations with displaced atoms, this is usually a safe approximation described in Ref.<ref name="cann"></ref>. 

After solving the BSE in the supecell you will find the excitons that were already present in the primary cell (within the numerical noise) and new lower energy excitons, with zero dipole matrix elements, that correspond to the indirect excitons that have now been mapped at '''q=0''', something like:

# Maximum Residual Value = 0.38659E+01
#
# E [ev] Strength Index
#
5.7165937 0.47290171E-11 1.0000000 <-- Indirect exciton mapped at q=0
5.7166047 0.58239158E-09 2.0000000 <-- Indirect exciton mapped at q=0
5.7367945 0.31830746E-09 3.0000000 <-- Indirect exciton mapped at q=0
5.7368207 0.33674005E-10 4.0000000 <-- Indirect exciton mapped at q=0
5.80542803 0.100763231E-6 5.00000000 <-- Direct exciton
5.80598068 0.384604526E-8 6.00000000 <-- Direct exciton
5.88944197 1.00000000 7.00000000 <-- Direct exciton
5.88967037 0.102969212E-1 8.00000000 <-- Direct exciton
................

This result shows that indirect exciton without the coupling with phonon do not contribute to the optical response. 

==Displace atoms and calculate dipoles derivatives==
Now you can generate the displaced supercell for all the phonon modes compatible with the indirect band gap '''q''' point by doing: ''python generate_supercells.py -S''. The script will produce a set of input files for each of the 12 phonon modes at '''q=(1/3,-1/6,0)'''. You have to perform BSE calculation for each one of these modes and get exciton dipoles. 
For each phonon mode the atoms are displaced along the corresponding eigenvector read from the "Q2.modes" file multiplied for 0.1 Bohr (the variable Temp=0.1), see the following line in "generate_supercell.py":

...
sc.displace(eivs,nd_atom_positions,Temp=0.1) # Generate list of displaced supercells as PwIn objects called 'modes_qe'
...

this is usually a good value to get correct derivatives. In principle, it is possible to test different displacement lengths to get good second derivatives. The general rule is that the displacement should not be too small to avoid numerical noise and not too large to avoid contribution from third or forth order derivatives. 
Once you get dipoles for a given phonon mode you can calculate the second order dipole derivatives using a finite difference formula and the fact the first order derivatives are zero by construction as:
<center>
<math display="inline"> \frac{\partial^2 | T^S |^2}{\partial R_{\lambda,q}^2 } = 2 \frac{| T^S (R=\Delta R) |^2 - | T (R=0) |^2}{\Delta R^2} = 2 \frac{| T^S (R=\Delta R) |^2}{\Delta R^2}</math>
</center>
In the Ref.<ref name=fprl></ref><ref name=strain></ref> we found that a single point formula above is enough to get good second derivatives, taking into account that the first derivative is zero, however you can test higher-order formulas to be sure that the result is correct, see for example [https://en.wikipedia.org/wiki/Finite_difference#Higher-order_differences higher-order differences] 

'''Important''': in the file produced by ''ypp'' the oscillator strengths are normalized to have the maximum equal to one, before calculating the derivatives remember to remove this normalization by multiplying all Oscillator Strengths for the maximum residual value, in the previous example:

# Maximum Residual Value = 0.38659E+01

==Luminescence==

Now you have all the information necessary to construct the emission spectra. Using the formula, derived in Ref.<ref name=fprl></ref> you obtain the phonon-assisted luminescence as:
[[File:Light emission.png|center|Light emission formula]]

in this formula:
* nr(ω) is the refractive index, that usually can be approximated with a constant in the luminescence energy range.
* ES'''q''' are the excitonic energies in the undistorted supercell, including indirect excitons
* B(ES,Texc) is the Bose occupation of excitons, that can be approximated with a Boltzman function, see Ref.<ref name=fprl></ref><ref name=strain></ref>
* Texc is the excitonic temperature that should be obtained from experimental measurements or used as a parameters, for a discussion see Ref.<ref name=fprl></ref>
* d2|TS|2/dR2λ'''q''' are the derivatives of the exciton dipole matrix elements for a given phonon mode
* Ωλ,'''q''' are the phonon frequencies and the sum on '''q''' is on the different supercells obtained from phonon modes responsible for the luminescence, in this tutorial there is just a single '''q''' point.
* η is the exciton line-width that is given as input parameter to define the broadening of the spectra

In the h-BN example shown here, the Texc was obtained from experimental measurements, only the lowest two excitons were included in the sum and the Bose function was replaced by a Botlzman distribution with the energy zero was fixed at the lowest excitonic energy. An appropriate scissor operator independent of the atomic displacements was added in the calculation. The final result is shown in the figure above and compared with experimental measurement at 10 Kelvin
[[File:Lum spectra.png|center|800px|Luminescence spectra]]

'''Some additional considerations on luminescence calculations'''

* In general due to the '''Bose''' (or '''Boltzmann''') factor only the lower excitons (often only the lowest one) contribute to the luminescence signal
* The lowest excitons are '''degenerate''' all of them have to be included in the sum, as in the h-BN example
* In the present formulation of luminescence spectra excitons are treated as Bosons (or Boltzman particles), in principle it is possible to define a '''excitonic occupation''' starting from a quasi-equilibrium distribution of excited electron-hole, but this requires a rotation of the electron-hole occupations in the excitonic base for a discussion see Ref.<ref name='cann'></ref><ref name='mprl'></ref>
* In order to '''speed up calculations''' you can perform all calculation without symmetries and copy the dielectric constant (''ndb.em1s*'' or ''ndb.pp*'' files) from the undistorted supercell to the displaced ones. In this case if you do not need to calculate GW correction, for example using a scissor, you can also reduce the number of bands in the the non-self-consistent calculation to the one required by the BSE, for a discussion see Ref<ref name=strain></ref>
* Notice that the '''dipole matrix elements''' that will enter in optical absorption and luminescence depend form the direction of the electric field. In this example show before the luminescence has been averaged on ''x'' and ''y'' directions because we were interested in the in-place luminescence. In general is it possible to select specific directions to reproduce particular experimental setups<ref name=cann></ref><ref name=fprl></ref>. 

==Some example input files for h-BN==

In this section I will provide some input files to repeat calculations in h-BN. Luminescence spectra was calculated using a 12x12x4 k-point grid and 200 bands for the dielectric constant in the primitive cell and 3000 mHa block size. In the supercell used to generate the luminescence spectra there are 24 atoms, this means that the to total number of bands has to bee increased to 1200 and the corresponding k-point sampling reduced approximately to 12x2x4, this is automatically done by the Yambopy.
Here the input files:
* Primitive cell SCF and NSCF files and inputs for phonon calculations: [https://www.yambo-code.org/educational/tutorials/files/Luminescence/hBN_scf_nscf_phonons.tgz hBN_scf_nscf_phonons.tgz]
* The Q=(1/3,1/6,0) phonon mode generated by matdyn.x: [https://www.yambo-code.org/educational/tutorials/files/Luminescence/Q_mode.tgz Q_mode.tgz]
* The non-diagonal supercells for SCF and NSCF calculations (without symmetries) and the Yambo file for the BSE [https://www.yambo-code.org/educational/tutorials/files/Luminescence/BSE_supercell.tgz BSE_supercell.tgz]
* The displaced supercells for exciton-phonon calculations [https://www.yambo-code.org/educational/tutorials/files/Luminescence/Displaced_Cells.tgz Displaced_Cells.tgz]

You can the same BSE input file in all the displaced supercells. 
If you did not use symmetries you can avoid to recalculate the dielectric constant by copying the SAVE/ndb.em1s* files from the undistributed supercell to the displaced ones.

== References ==

Phonon-assisted luminescence by finite atomic displacements

2022-09-15T12:35:44Z

ElenaCannuccia: /* Displace atoms and calculate dipoles derivatives */

[[File:Representative-instantaneous-atomic-configurations-of-H2O-top-and-H3O-bottom-Also.gif|thumb| 200px|Finite atomic displacements]]

In recent years, several articles have been published with Yambo, who calculated the phonon-assisted luminescence by means of finite atomic displacements<ref name='cann'>[https://arxiv.org/abs/1807.11797 Theory of phonon-assisted luminescence in solids: Application to hexagonal boron nitride], E. Cannuccia, B. Monserrat and C. Attaccalite, Phys. Rev. B '''99''', 081109(R) (2019)</ref><ref name='fprl'>[https://arxiv.org/abs/1810.08976 Exciton-Phonon Coupling in the Ultraviolet Absorption and Emission Spectra of Bulk Hexagonal Boron Nitride], F. Paleari et al. PRL '''122''', 187401(2019) </ref><ref name=strain>[https://scipost.org/SciPostPhys.12.5.145 Excitons under strain: light absorption and emission in strained hexagonal boron nitride], P. Lechifflart, F. Paleari and C. Attaccalite, SciPost Phys. '''12''', 145(2022). </ref><ref name='mprl'>[https://arxiv.org/abs/2111.03518 Phonon-Assisted Luminescence in Defect Centers from Many-Body Perturbation Theory], F. Libbi, P. M. M. C. de Melo, Z. Zanolli, M. J. Verstraete, and N. Marzari, Phys. Rev. Lett. '''128''', 167401 (2022) </ref>.
In this tutorial we will show how to use [https://github.com/yambo-code/yambopy YamboPy] in combination with Yambo to perform these kind of calculations. For a general review of finite displacements calculations of vibrational properties we recommend this article<ref>Electron-phonon coupling from finite differences, Bartomeu Monserrat, J. Phys.: Condens. Matter '''30''' 083001(2018)</ref>. 
Notice that calculation of phonon-assisted luminescence by finite atomic displacements are quite involved and expensive from a computational point of view, for this reason they are limited to relatively simple systems. 
In this tutorial we will follow the approach of Ref.<ref name=fprl></ref>, and calculate luminescence using the Roosbroeck–Shockley (RS) relation applied to the excitonic case. 
If you use this approach to calculate luminescence or phonon-assisted absorption please cite references <ref name=cann></ref> and <ref name=fprl></ref>. 
'''Important:''' This tutorial requires that you are familiar with Bethe-Salpeter calculations with Yambo, and phonons with Quantum-Espresso, and YamboPy. If it is not the case please study the corresponding tutorial before continuing.

== Locate the lowest indirect exciton (or indirect band gap) ==

In this tutorial as example we will consider the hexagonal-BN, that is an indirect insulator. The first step to calculate the phonon-assisted luminescence is to locate the lowest indirect exciton. The cleanest strategy to identify the lowest excitation would be to calculate the excitons along the whole Irreducible Brillouin zone(IBZ), then interpolate them as explained in [https://www.yambo-code.org/wiki/index.php?title=How_to_analyse_excitons#Interpolate_exciton_dispersion_(only_in_Yambo_5.x) Interpolate exciton dispersion] and find the '''q''' point that correspond to the minimum. 
A simpler approach is to use the GW (or Kohn-Sham) band structure to find the momentum responsible for the indirect band gap, in the major part of cases this corresponds to the lowest exciton. 
In the h-BN case we have:
[[File:Bn band structure.png|1000px|center| Yambo tutorial image]]

The indirect gap is between a point close to '''K''' and the '''M''' point, see panel (a) of the figure above. We will approximate the momentum responsible for the indirect emission with '''q=K-M'''. Notice that then we should build supercells that contain this moment, so it is good to approximate it with fractions of integers that are not too large so as not to have giant supercells. In this case we get '''q=(1/3,-1/6, 0)'''. 
Notice that if you have a direct band gap material, the momentum '''q''' corresponding to the lowest transition is '''q=0''' and you do not need to construct special supercells to sample the corresponding vibration, it will be sufficient to displace atoms in the primitive cell.

== Calculate phonons at momentum '''q''' of the indirect transition ==

Now we need to calculate all atomic vibrations compatible with the momentum of the lowest indirect transition. In order to do so we first calculate the phonons with QE, here the inputs [https://www.yambo-code.org/educational/tutorials/files/hBN_phonons.tgz hBN_phonons.tgz], then we calculate the force constants with q2r.x and now we can interpolate phonons along all the BZ as shown in panel (b) of Figure 1. Then we use matdyn.x to calculate phonons at momentum '''q=K-M = (1/3, -1/6, 0)''':

&input
asr='crystal',
flfrc='bn.fc',
flfrq='bn.freq',
deltaE=1.d0,
q_in_cryst_coord=.true.
fleig='bn.eig'
/
2
0 0 0
0.3333333333333333 -0.16666666666666666666 0.0

The obtained phonon modes correspond phonons at the vertical red line in panel(b) of Fig. 1. They are written in the ''matdyn.modes'' file with the corresponding eigenvectors and will be later used to displace atoms along the phonon modes.
If you open the 'matdyn.modes' file you will find phonon modes for the '''q=0''' and '''q=(1/3, -1/6, 0)''' that in cartesian coordinates is (1/3,0,0). We copy the modes corresponding to the second '''q=(1/3, -1/6, 0)''' in a separate file, called ''Q2.modes'' that will look like:

diagonalizing the dynamical matrix ...

q = 0.3333 0.0000 0.0000
**************************************************************************
freq ( 1) = 5.194139 [THz] = 173.257815 [cm-1]
( 0.000000 -0.000000 -0.000000 -0.000000 -0.274372 -0.475224 )
( -0.000000 0.000000 -0.000000 -0.000000 -0.445962 0.000001 )
( -0.000000 -0.000000 -0.000000 -0.000000 -0.222981 -0.386214 )
( 0.000000 0.000000 -0.000000 0.000000 -0.548742 0.000000 )
...........................

== Generate the supercell==

Now we use YamboPy to generate the supercell corresponding to the momentum '''q=(1/3, -1/6, 0)'''. A tutorial is already present in the file ''tutorial/supercell/generate_supercells.py''.
You can edit the file to specify the momentum '''q''', the name of the SCF initial file (uc_filnm) and the name of the phonon mode file (mode_file).

.....
uc_filnm = 'hBN.scf.in' #pw input
Q = [[1,-1,0],[3,6,0]] #qpoint to fold in nondiagonal supercell: Q=(1/3,-1/6,0)
kpoints = [12,12,4] #NB: these fractional crystal coordinates must exactly divide the kpoint mesh!
modes_file = 'Q2.modes' #file with phonon eigenmodes
.....

run the script to generate the supercell without displace atoms ''python generate_supercells.py -N''. The script will generate a non-diagonal supercell<ref>[https://arxiv.org/abs/1510.04418 Lattice dynamics and electron-phonon coupling calculations using nondiagonal supercells], J. H. Lloyd-Williams and B. Monserrat, Phys. Rev. B '''92''', 184301(2015) </ref> in the file "sc_nondiagonal.bn.scf' that is shown below:

[[File:Supercell.png|500px|center| Supercell for the momentum q=(1/3, -1/6, 0) and the corresponding reciprocal space]]

The YamboPy script automatically reduce the number of k-point in such a way to have the same sampling of the corresponding primitive cell, however we advice you to check if the new k-point grid is what you expect, and modify it in case of incorrect grid. 
In the same way you can generate the input file for non-self-consistent calculation in the supercell.

==Calculate the optical spectra in the supercell==

Now you have to calculate the optical spectra and exciton in the new supercell. Do not forget to increase the number of conduction bands in both the screening the Bethe-Salpeter equation. For example in the supercell shown above there are 24 atoms, 6 times more than in the original cell, so you will have to multiply the number of bands by 6, if in the base cell you have used 40 bands here you will have to put 240 to have the same convergence parameters. Then print exciton according to their energy with the command ypp -e s. 

'''N. B. ''': in order to not recalculate W for each atomic displacement you can perform calculations without symmetries in the pristine supercell and then copy the corresponding dielectric constant in the calculations with displaced atoms, this is usually a safe approximation described in Ref.<ref name="cann"></ref>. 

After solving the BSE in the supecell you will find the excitons that were already present in the primary cell (within the numerical noise) and new lower energy excitons, with zero dipole matrix elements, that correspond to the indirect excitons that have now been mapped at '''q=0''', something like:

# Maximum Residual Value = 0.38659E+01
#
# E [ev] Strength Index
#
5.7165937 0.47290171E-11 1.0000000 <-- Indirect exciton mapped at q=0
5.7166047 0.58239158E-09 2.0000000 <-- Indirect exciton mapped at q=0
5.7367945 0.31830746E-09 3.0000000 <-- Indirect exciton mapped at q=0
5.7368207 0.33674005E-10 4.0000000 <-- Indirect exciton mapped at q=0
5.80542803 0.100763231E-6 5.00000000 <-- Direct exciton
5.80598068 0.384604526E-8 6.00000000 <-- Direct exciton
5.88944197 1.00000000 7.00000000 <-- Direct exciton
5.88967037 0.102969212E-1 8.00000000 <-- Direct exciton
................

This result shows that indirect exciton without the coupling with phonon do not contribute to the optical response. 

==Displace atoms and calculate dipoles derivatives==
Now you can generate the displaced supercell for all the phonon modes compatible with the indirect band gap '''q''' point by doing: ''python generate_supercells.py -S''. The script will produce a set of input files for each of the 12 phonon modes at '''q=(1/3,-1/6,0)'''. You have to perform BSE calculation for each one of these modes and get exciton dipoles. 
For each phonon mode the atoms are displaced along the corresponding eigenvector read from the "Q2.modes" file multiplied for 0.1 Bohr (the variable Temp=0.1), see the following line in "generate_supercell.py":

...
sc.displace(eivs,nd_atom_positions,Temp=0.1) # Generate list of displaced supercells as PwIn objects called 'modes_qe'
...

this is usually a good value to get correct derivatives. In principle, it is possible to test different displacement lengths to get good second derivatives. The general rule is that the displacement should not be too small to avoid numerical noise and not too large to avoid contribution from third or forth order derivatives. 
Once you get dipoles for a given phonon mode you can calculate the second order dipole derivatives using a finite difference formula and the fact the first order derivatives are zero by construction as:
<center>
<math display="inline"> \frac{\partial^2 | T^S |^2}{\partial R_{\lambda,q}^2 } = 2 \frac{| T^S (R=\Delta R) |^2 - | T (R=0) |^2}{\Delta R^2} = 2 \frac{| T^S (R=\Delta R) |^2}{\Delta R^2}</math>
</center>
In the Ref.<ref name=fprl></ref><ref name=strain></ref> we found that a single point formula above is enough to get good second derivatives, taking into account that the first derivative is zero, however you can test higher-order formulas to be sure that the result is correct, see for example [https://en.wikipedia.org/wiki/Finite_difference#Higher-order_differences higher-order differences] 

'''Important''': in the file produced by ''ypp'' the oscillator strengths are normalized to have the maximum equal to one, before calculating the derivatives remember to remove this normalization by multiplying all Oscillator Strengths for the maximum residual value, in the previous example:

# Maximum Residual Value = 0.38659E+01

==Luminescence==

Now you have all the information necessary to construct the emission spectra. Using the formula, derived in Ref.<ref name=fprl></ref> you obtain the phonon-assisted luminescence as:
[[File:Light emission.png|center|Light emission formula]]

in this formula:
* nr(ω) is the refractive index, that usually can be approximated with a constant in the luminescence energy range.
* ES'''q''' are the excitonic energies in the undistorted supercell, including indirect excitons
* B(ES,Texc) is the Bose occupation of excitons, that can be approximated with a Boltzman function, see Ref.<ref name=fprl></ref><ref name=strain></ref>
* Texc is the excitonic temperature that should be obtained from experimental measurements or used as a parameters, for a discussion see Ref.<ref name=fprl></ref>
* d2|TS|2/dR2λ'''q''' are the derivatives of the exciton dipole matrix elements for a given phonon mode
* Ωλ,'''q''' are the phonon frequencies and the sum on '''q''' is on the different supercells obtained from phonon modes responsible for the luminescence, in this tutorial there is just a single '''q''' point.
* η is the exciton line-width that is given as input parameter to define the broadening of the spectra

In the h-BN example shown here, the Texc was obtained from experimental measurements, only the lowest two excitons were included in the sum and the Bose function was replaced by a Botlzman distribution with the energy zero was fixed at the lowest excitonic energy. An appropriate scissor operator independent of the atomic displacements was added in the calculation. The final result is shown in the figure above and compared with experimental measurement at 10 Kelvin
[[File:Lum spectra.png|center|800px|Luminescence spectra]]

'''Some additional considerations on luminescence calculations'''

* In general due to the '''Bose''' (or '''Boltzmann''') factor only the lower excitons (often only the lowest one) contribute to the luminescence signal
* The lowest excitons are '''degenerate''' all of them have to be included in the sum, as in the h-BN example
* In the present formulation of luminescence spectra excitons are treated as Bosons (or Boltzman particles), in principle it is possible to define a '''excitonic occupation''' starting from a quasi-equilibrium distribution of excited electron-hole, but this requires a rotation of the electron-hole occupations in the excitonic base for a discussion see Ref.<ref name='cann'></ref><ref name='mprl'></ref>
* In order to '''speed up calculations''' you can perform all calculation without symmetries and copy the dielectric constant (''ndb.em1s*'' or ''ndb.pp*'' files) from the undistorted supercell to the displaced ones. In this case if you do not need to calculate GW correction, for example using a scissor, you can also reduce the number of bands in the the non-self-consistent calculation to the one required by the BSE, for a discussion see Ref<ref name=strain></ref>
* Notice that the '''dipole matrix elements''' that will enter in optical absorption and luminescence depend form the direction of the electric field. In this example show before the luminescence has been averaged on ''x'' and ''y'' directions because we were interested in the in-place luminescence. In general is it possible to select specific directions to reproduce particular experimental setups<ref name=cann></ref><ref name=fprl></ref>. 

==Some example input files for h-BN==

In this section I will provide some input files to repeat calculations in h-BN. Luminescence spectra was calculated using a 12x12x4 k-point grid and 200 bands for the dielectric constant in the primitive cell and 3000 mHa block size. In the supercell used to generate the luminescence spectra there are 24 atoms, this means that the to total number of bands has to bee increased to 1200 and the corresponding k-point sampling reduced approximately to 12x2x4, this is automatically done by the Yambopy.
Here the input files:
* Primitive cell SCF and NSCF files and inputs for phonon calculations: [https://www.yambo-code.org/educational/tutorials/files/Luminescence/hBN_scf_nscf_phonons.tgz hBN_scf_nscf_phonons.tgz]
* The Q=(1/3,1/6,0) phonon mode generated by matdyn.x: [https://www.yambo-code.org/educational/tutorials/files/Luminescence/Q_mode.tgz Q_mode.tgz]
* The non-diagonal supercells for SCF and NSCF calculations (without symmetries) and the Yambo file for the BSE [https://www.yambo-code.org/educational/tutorials/files/Luminescence/BSE_supercell.tgz BSE_supercell.tgz]
* The displaced supercells for exciton-phonon calculations [https://www.yambo-code.org/educational/tutorials/files/Luminescence/Displaced_Cells.tgz Displaced_Cells.tgz]

You can the same BSE input file in all the displaced supercells. 
If you did not use symmetries you can avoid to recalculate the dielectric constant by copying the SAVE/ndb.em1s* files from the undistributed supercell to the displaced ones.

== References ==

Electron Phonon Coupling

2022-02-26T07:59:06Z

ElenaCannuccia:

[[File:Electron phonon.png|thumb|200px| Electron-phonon coupling]]
Here we show step-by-step how to use [https://www.quantum-espresso.org/ Quantum Espresso] to calculate phonons and electron-phonon matrix-elements on a regular q-grid.
The final aim is to allow Yambo to read them and calculate the temperature-dependent correction to the electronic states.
This tutorial<ref> This tutorial is based on [http://www.attaccalite.com/elena/news/ Elena Cannuccia blog]</ref> is quite articulated, take your time to do it patiently.

== Electron-phonon matrix elements ==

In this first section we will explain how to generate electron-phonon matrix elements in Quantum-Espresso, and how to import them in Yambo.
Calculations will be divided in different folders:

* '''pseudo''' the pseudo potential folder
* '''scf''' for the self-consistent calculation
* '''nscf''' for the non-self-consistent calculation with a larger number of bands
* '''phonon''' for the phonon calculations
* '''dvscf''' for the calculation of the electron-phonon matrix elements

In this tutorial we will show how to calculate electron-phonon induced corrections to the bands and optical properties for bulk silicon.
All input file are availabe in the following tgz file: [http://www.yambo-code.org/educational/tutorials/files/si.epc.tgz si.epc.tgz]

1. In '''scf''' we run a standard scf calculation choosing a large k-grid in such a way to converge density. Do not forget to set ''force_symmorphic=.true.'', because not symmorphic symmetries are not supported yet in Yambo. Notice that:

a) If you are working with 2D systems, not our case, we have to add the flag ''assume_isolated="2D"'' in such a way correct 2D phonons.

b) If the cell is an FCC, set manually the cell parameters by using the flag ''ibrav=0'' in your scf input file. This allows to generate correctly the uniform q grid over which phonons and electron-phonon databases are calculated, for example for Silicon you can use:

&system
......
ibrav= 0,
celldm(1) =5.09150
.....
/
.....
CELL_PARAMETERS alat
0.0 1.0 1.0
1.0 0.0 1.0
1.0 1.0 0.0

2. Plug into '''nscf''' folder, and then copy the ${PREFIX}.save folder from '''scf''' to '''nscf''', in the present example just do ''cp -r ../scf/si.save ./''.
In the nscf input you have to choose the number of k-points and bands you will use for the electron-phonon coupling and Yambo calculations, in our case we will use a 4x4x4 grid and 12 bands.

3. Read the q-points list. In the '''nscf''' folder, enter in the ${PREFIX}.save then run ''p2y'' to read the wave-functions.

4. Generate the setup file with the command ''yambo_ph -i -V all'' and uncomment the flag ''BSEscatt'' then run the setup.

5. Generate the input file to read the electron-phonon matrix elements with the command ''ypp_ph -k q'':

bzgrids # [R] BZ Grid generator
Q_grid # [R] Q-grid analysis
OutputAlat= 0.000000 # [a.u.] Lattice constant used for "alat" ouput format
#NoWeights # Do not print points weight
cooIn= "rlu" # Points coordinates (in) cc/rlu/iku/alat
cooOut= "alat" # Points coordinates (out) cc/rlu/iku/alat
ListPts # List the internal q/k points also in the parser format
#ExpandPts # Expand the internal q/k points in the BZ
#ForceUserPts # Do not check the correcteness of the user points
%Qpts # Q points list
0.000000| 0.000000| 0.000000|
%
and uncomment the flag '''ListPts''' and q-point coordinates units in '''alat''', the units used by QuantumEspresso. Now if you run ypp_ph it will generate the list of q-points for the phonon calculations:

.....
<---> Q-points (IBZ) PW-formatted
0.000000000 0.000000000 0.000000000 1
0.124999978 0.124999978 -0.124999993 1
-0.249999955 -0.249999955 0.249999985 1
0.249999955 0.000000000 0.000000000 1
0.375000060 0.125000060 -0.125000060 1
0.000000000 -0.249999955 0.249999985 1
-0.499999911 0.000000000 0.000000000 1
-0.499999911 0.249999985 0.000000000 1
<---> [08] Timing Overview
......

4. Plug into '''phonon''' directory. You have to copy the self-consistent calculation in this folder
with the command ''cp -r ../scf/si.save ./ ''. Then you can prepare an input file for phonons using the q-points list you generated in the previous step mutiplied by -1,
the final input will be:

&inputph
verbosity = 'high'
tr2_ph = 1e-12h
prefix = 'si'
fildvscf = 'si-dvscf'
fildyn = 'si.dyn',
electron_phonon = 'dvscf',
epsil = .true.
trans = .true.
ldisp = .false.
qplot = .true.
/
8
-0.0 -0.0 -0.0 1
-0.124999978 -0.124999978 0.124999993 1
0.249999955 0.249999955 -0.249999985 1
-0.249999955 -0.0 -0.0 1
-0.37500006 -0.12500006 0.12500006 1
-0.0 0.249999955 -0.249999985 1
0.499999911 -0.0 -0.0 1
0.499999911 -0.249999985 -0.0 1

5. Plug into '''dvscf''' folder. From the nscf folder copy density and wave-functions (''cp -r ../nscf/si.save ./''), from the phonon folder copy the dynamical matrices and the dvscf files (''cp -r ../phonon/_ph0 ../phonon/*.dyn* ./''). Then modify the phonon input to generate electron-phonon matrix elements for Yambo, by changing epsil = .false., trans = .false. and electron_phonon = yambo. You do not need to specify the k-point grid because it is read from the nscf wave-functions. In this way we will not recalculate phonons, but only the electron-phonon matrix elements for the number of bands present in the nscf input file, in our case 8 bands:

&inputph
verbosity = 'high'
tr2_ph = 1e-12
prefix = 'si'
fildvscf = 'si-dvscf'
fildyn = 'si.dyn'
electron_phonon = 'yambo',
epsil = .false.
trans = .false.
ldisp = .false.
qplot = .true.
/
8
-0.0 -0.0 -0.0 1
-0.124999978 -0.124999978 0.124999993 1
0.249999955 0.249999955 -0.249999985 1
-0.249999955 -0.0 -0.0 1
-0.37500006 -0.12500006 0.12500006 1
-0.0 0.249999955 -0.249999985 1
0.499999911 -0.0 -0.0 1
0.499999911 -0.249999985 -0.0 1

this run will generate a new folder ''elph_dir'' with all electron-phonon matrix elements in a format compatible with Yambo. 
Nota bene: use the same parallelization in the '''phonon''' and '''dvscf''' calculation to avoid problem reading wave-functions.

6. Now you have to read the electron-phonon matrix elements. Go in the ''dvscf/si.save'' folder, and use ypp_ph to import electron-phonon coupling, by doing ''ypp_ph -g g'' and the PW el-ph folder:

gkkp # [R] gkkp databases
DBsPATH= "../elph_dir/" # Path to the PW el-ph databases
PHfreqF= "none" # PWscf format file containing the phonon frequencies
PHmodeF= "none" # PWscf format file containing the phonon modes
#GkkpExpand # Expand the gkkp in the whole BZ
#GkkpConvert # Convert the gkkp to new I/O format

run ypp_ph, and if everything went well you will get in output

.....
-> [06] == Electron-Phonon Interface: PW->Yambo Databases ==
<---> PW(ELPH) databases ...[PHONON] ...found 8 Q-grid compatible
<---> ELPH databases (WRITE) |########################################| [100%] --(E) --(X)
<---> Modes : 6
<---> Bands range : 12
.....

== Quasi-particle band structure ==
The first quantity we will calculate is the correction to the band structure induced by the electron-phonon coupling. In order to generate the corresponding input do "'''yambo_ph -g n -p fan -c ep -V gen'''". In the input we require the correction only at gamma point:

dyson # [R] Dyson Equation solver
gw0 # [R] GW approximation
el_ph_corr # [R] Electron-Phonon Correlation
Nelectro= 8.000000 # Electrons number
ElecTemp= 0.000000 eV # Electronic Temperature
BoseTemp= 0.000000 eV # Bosonic Temperature
OccTresh= 0.100000E-4 # Occupation treshold (metallic bands)
SE_Threads=0 # [OPENMP/GW] Number of threads for self-energy
DysSolver= "n" # [GW] Dyson Equation solver ("n","s","g")
% GphBRnge
1 | 12 | # [ELPH] G[W] bands range
%
% ElPhModes
1 | 6 | # [ELPH] Phonon modes included
%
GDamping= 0.0100000 eV # [GW] G[W] damping
RandQpts=0 # [RIM] Number of random q-points in the BZ
#WRgFsq # [ELPH] Dump on file gFsq coefficients
%QPkrange # [GW] QP generalized Kpoint/Band indices
1|1|2|8|
%
If you run yambo_ph -J T0 you will get correction at zero kelvin to the band structure. You can change the temperature to 300 K by doing:

dyson # [R] Dyson Equation solver
gw0 # [R] GW approximation
el_ph_corr # [R] Electron-Phonon Correlation
Nelectro= 8.000000 # Electrons number
ElecTemp= 0.000000 eV # Electronic Temperature
BoseTemp= 300.0 Kn # Bosonic Temperature
OccTresh= 0.100000E-4 # Occupation treshold (metallic bands)
SE_Threads=0 # [OPENMP/GW] Number of threads for self-energy
DysSolver= "n" # [GW] Dyson Equation solver ("n","s","g")
% GphBRnge
1 | 12 | # [ELPH] G[W] bands range
%
% ElPhModes
1 | 6 | # [ELPH] Phonon modes included
%
GDamping= 0.0100000 eV # [GW] G[W] damping
RandQpts=0 # [RIM] Number of random q-points in the BZ
#WRgFsq # [ELPH] Dump on file gFsq coefficients
%QPkrange # [GW] QP generalized Kpoint/Band indices
1|1|2|8|
%
run again ''yambo_ph -J T300'' and compare the two output file o-T0.qp and o-T300.qp, to find how much the gap change with the temperature.
If you repeat the calculation for different temperature you can obtain the trend of the gap vs temperature. The figure below report the Silicon gap at Gamma Point at different temperature obtained in this tutorial:
[[File:Si_gap_finite_t.png|600px|center]]
If you uncomment the flag WRgFsq the code saves information about the Eliashberg functions that can be plotted using the ''ypp_ph'', see below. 
Finally if you add ''-V qp'' in the input generation a new flag appears OnMassShell, if you un-comment this flag calculation will be performed in the "on mass shell" approximation, namely the static limit the Quasi-Particle approximation, for a discussion see reference <ref>H. Kawai et al. [https://arxiv.org/abs/1310.2038 Phys. Rev. B '''89''', 085202 (2014)]</ref>

Notice that the last column in the quasi-particle file "o.QP" contains the '''quasi-particle width''', that is related to their life-time. You can plot the band structure including this width to get quasi-particle spectra
similar to the one measured in ARPES experiments, see Fig. 2 in ref. <ref> G. Antonius, S. Poncé, E. Lantagne-Hurtubise, G. Auclair, X. Gonze, and M. Côté
[https://arxiv.org/abs/1505.07738 Phys. Rev. B 92, 085137 (2015)] </ref>.
This parameter will be used in the next tutorial on [http://www.yambo-code.org/wiki/index.php?title=Optical_properties_at_finite_temperature optical properties at finite temperature].
 WARNING: Yambo average the electron-phonon correction on the degenerate states, please include all degenerate states in your calculations. For example in the silicon case you need correction from the 2nd band to the 8th band.

== Convergence ==

The results of this tutorial are not converged. This is due to the poor parameters used in this tutorial to make the calculations fast. In order to have converged results, first of all you have to be sure to have converged phonons, in order to do that increase plane-wave cutoff, number of k-points and if necessary reduce ''tr2_ph''.
Then change the parameters for the Yambo calculations, increasing the number of '''k''' and '''q''' points and the number of bands. If you want to increase only the number of bands, just repeat the '''nscf''' and '''dvscf''' calculations without recalculate '''phonons'''. In the following section we will describe a smart way to accelerate convergence. 
Nota bene: At present Yambo neither implements the Fröhlich term at q=0<ref>Carla Verdi and Feliciano Giustino
[https://arxiv.org/abs/1510.06373 Phys. Rev. Lett. '''115''', 176401 (2015)] </ref> nor the quadrupolar correction,<ref>G. Brunin et al. [https://arxiv.org/abs/2002.00628 Phys. Rev. Lett. '''125''', 136601 (2020)]</ref> therefore convergence in polar material can be very slow with the number of q-points.

== Double-grid method for the electron-phonon coupling (only in Yambo 5.x) ==

Simplifying at most the matrix elements of the electron-phonon self-energy have the structure:

[[File:Self elph.png|center|Yambo tutorial image | 270px ]]

where we omitted the electronic band and the phonon branches indexes. In order to speed up calculation one can average the denominators on an additional fine grid around each '''q''' points as:

[[File:Formula dbgrid.png|center|Yambo tutorial image| 500px]]

In order to exploit the double-grid tool we need the phonon energies calculated on a fine grid. For a general tutorial on phonon calculation with Quantum Espresso you can have a look at [https://www.quantum-espresso.org/wp-content/uploads/phonons_tutorial_shanghai1.pdf Hands on phonons]. 
Starting from a well converged phonon calculation ''matdyn.x'' can interpolate phonon dispersion on a given q-sampling (for example a regular 14x14x14 grid, as shown in the input file below) and give the desired phonon energies.

&input
asr='simple',
flfrc='si.fc',
flfrq='si.freq',
dos=.true.,
fldos='si.dos',
deltaE=1.d0,
nk1=14, nk2=14, nk3=14
/
Alternatively you can generate a random q-sampling using Yambo (''ypp -k r'') and insert the corresponding q points list into a matdyn file.

Once you generated the phonon energies you can read them with the command ''ypp_ph -g d'':

gkkp # [R] gkkp databases
gkkp_dg # [R] GKKP double grid
PHfreqF= "si.freq" # PWscf format file containing the phonon frequencies
PHmodeF= "none" # PWscf format file containing the phonon modes
FineGd_mode= "mixed" # Fine Grid mode. Symmetry expanded, unexpanded or mixed.
#SkipBorderPts # Skip points in the Fine Grid that are on the surface of coarse gride smal BZ`s
EkplusQmode= "interp" # E(k+q) energies calculation mode (interp | dftp )
#TestPHDGrid # Test double-grid: set all values of the fine grid equal to the couse ones

then run ''ypp_ph'' an it will generate a new file ''SAVE/ndb.PH_Double_Grid''. 
In the calculation the new phonon energies will be expanded
using the symmetries of the systems, while the electronic energies at '''k+q''' will be interpolated using a smooth Fourier interpolation<ref>Warren E. Pickett, Henry Krakauer, and Philip B. Allen,
Phys. Rev. B '''38''', 2721(1988)</ref>.
In order to perform calculation with the double grid remove the ''SAVE/ndb.QP'' file and repeat the calculation. 
The best strategy to converge electron-phonon coupling calculations is to converge the double-grid for a fixed course grid and the increase the second one. Hereafter an example of Silicon band gap correction convergence versus the number of '''q'''-points in the course grid, using a double-grid with 4096 random '''q'''-points.

[[File:Gap conv.png|center|Yambo tutorial image | 750px]]



== Miscellaneous and post-processing ==
'''Automatic generation of electron-phonon matrix elements''' 
Getting electron-phonon matrix elements from QuantumEspresso to Yambo is a complicated process, 
we advice you to create a script to automatize the procedure, here an example of a bash script for the silicon case: [http://www.yambo-code.org/educational/tutorials/files/SILICON_CONV.tgz SILICON-SCRIPT].

There are a list of utilities to analyze electron-phonon coupling results:

'''Phonon density of states''' 
You can plot phonon density of states with the command: ''ypp_ph -p d''. In order to get a nice plot set in the input

phonons # [R] Phononic properties
dos # [R] DOS
PhBroad= 0.0005000 eV # Phonon broadening (Eliashberg & DOS)
PhStps=1000 # Energy steps

notice that this is an easy quantity to check for the convergence in q-points.

[[File:Ph_dos.png|600px|center| Phonon Density of States]]

'''Eliashberg Functions''' 
You can plot Eliashberg functions<ref>F. Marsiglio, J.P. Carbotte [https://arxiv.org/abs/cond-mat/0106143 Electron - Phonon Superconductivity]</ref> for both electrons and excitons. In order to plot Eliashberg functions you must have calculated Quasi-Particle correction with the flag WRgFsq, see above.
The command ''ypp_ph -s e'' generate the input for the electronic Eliashberg functions:

electrons # [R] Electronic properties
eliashberg # [R] Eliashberg
PhBroad= 0.0010000 eV # Phonon broadening (Eliashberg & DOS)
PhStps= 200 # Energy steps
%QPkrange # generalized Kpoint/Band indices
1|1|4|5|
%

in this example we plot Eliashberg functions for the top valence and bottom conduction band at Gamma point:

[[File:Eliashberg functions.png|600px|center| Eliashberg functions]]

For a discussion on how to interprete Eliashberg functions and use them to understand the different phonon contribution you can have a look to ref.<ref>E. Cannuccia and A. Gali
[https://arxiv.org/abs/1907.06089 Phys. Rev. Materials 4, 014601 (2020)] </ref>

'''Atomic displacement amplitudes''' 
Running ''ypp_ph -p a'' will plot the atomic displacement for each atom in the cell each direction.

''' Other variables in the input files ''' 
In the input files of the present tutorial there are other variable not used in this tutorial.
In particular ''GkkpExpand'' is used for other calculations not present in the GPL, while ''GkkpConvert'' is used to checking purpose the IO for different versions
of the databases.

==References==
<references />

Electron Phonon Coupling

2022-02-21T13:29:44Z

ElenaCannuccia:

[[File:Electron phonon.png|thumb|200px| Electron-phonon coupling]]
Here we show step-by-step how to use [https://www.quantum-espresso.org/ Quantum Espresso] to calculate phonons and electron-phonon matrix-elements on a regular q-grid.
The final aim is to allow Yambo to read them and calculate the temperature-dependent correction to the electronic states.
This tutorial<ref> This tutorial is based on [http://www.attaccalite.com/elena/news/ Elena Cannuccia blog]</ref> is quite articulated, take your time to do it patiently.

== Electron-phonon matrix elements ==

In this first section we will explain how to generate electron-phonon matrix elements in Quantum-Espresso, and how to import them in Yambo.
Calculations will be divided in different folders:

* '''pseudo''' the pseudo potential folder
* '''scf''' for the self-consistent calculation
* '''nscf''' for the non-self-consistent calculation with a larger number of bands
* '''phonon''' for the phonon calculations
* '''dvscf''' for the calculation of the electron-phonon matrix elements

In this tutorial we will show how to calculate electron-phonon induced corrections to the bands and optical properties for bulk silicon.
All input file are availabe in the following tgz file: [http://www.yambo-code.org/educational/tutorials/files/si.epc.tgz si.epc.tgz]

1. In '''scf''' we run a standard scf calculation choosing a large k-grid in such a way to converge density. Do not forget to set ''force_symmorphic=.true.'', because not symmorphic symmetries are not supported yet in Yambo. Notice that:

a) If you are working with 2D systems, not our case, we have to add the flag ''assume_isolated="2D"'' in such a way correct 2D phonons.

b) If the cell is an FCC, set manually the cell parameters by using the flag ''ibrav=0'' in your scf input file. This allows to generate correctly the uniform q grid over which phonons and electron-phonon databases are calculated, for example for Silicon you can use:

&system
......
ibrav= 0,
celldm(1) =5.09150
.....
/
.....
CELL_PARAMETERS alat
0.0 1.0 1.0
1.0 0.0 1.0
1.0 1.0 0.0

2. Plug into '''nscf''' folder, and then copy the ${PREFIX}.save folder from '''scf''' to '''nscf''', in the present example just do ''cp -r ../scf/si.save ./''.
In the nscf input you have to choose the number of k-points and bands you will use for the electron-phonon coupling and Yambo calculations, in our case we will use a 4x4x4 grid and 12 bands.

3. Read the q-points list. In the '''nscf''' folder, enter in the ${PREFIX}.save then run ''p2y'' to read the wave-functions.

4. Generate the setup file with the command ''yambo_ph -i -V all'' and uncomment the flag ''BSEscatt'' then run the setup.

5. Generate the input file to read the electron-phonon matrix elements with the command ''ypp_ph -k q'':

bzgrids # [R] BZ Grid generator
Q_grid # [R] Q-grid analysis
OutputAlat= 0.000000 # [a.u.] Lattice constant used for "alat" ouput format
#NoWeights # Do not print points weight
cooIn= "rlu" # Points coordinates (in) cc/rlu/iku/alat
cooOut= "alat" # Points coordinates (out) cc/rlu/iku/alat
ListPts # List the internal q/k points also in the parser format
#ExpandPts # Expand the internal q/k points in the BZ
#ForceUserPts # Do not check the correcteness of the user points
%Qpts # Q points list
0.000000| 0.000000| 0.000000|
%
and uncomment the flag '''ListPts''' and q-point coordinates units in '''alat''', the units used by QuantumEspresso. Now if you run ypp_ph it will generate the list of q-points for the phonon calculations:

.....
<---> Q-points (IBZ) PW-formatted
0.000000000 0.000000000 0.000000000 1
0.124999978 0.124999978 -0.124999993 1
-0.249999955 -0.249999955 0.249999985 1
0.249999955 0.000000000 0.000000000 1
0.375000060 0.125000060 -0.125000060 1
0.000000000 -0.249999955 0.249999985 1
-0.499999911 0.000000000 0.000000000 1
-0.499999911 0.249999985 0.000000000 1
<---> [08] Timing Overview
......

4. Plug into '''phonon''' directory. You have to copy the self-consistent calculation in this folder
with the command ''cp -r ../scf/si.save ./ ''. Then you can prepare an input file for phonons using the q-points list you generated in the previous step mutiplied by -1,
the final input will be:

&inputph
verbosity = 'high'
tr2_ph = 1e-12h
prefix = 'si'
fildvscf = 'si-dvscf'
fildyn = 'si.dyn',
electron_phonon = 'dvscf',
epsil = .true.
trans = .true.
ldisp = .false.
qplot = .true.
/
8
-0.0 -0.0 -0.0 1
-0.124999978 -0.124999978 0.124999993 1
0.249999955 0.249999955 -0.249999985 1
-0.249999955 -0.0 -0.0 1
-0.37500006 -0.12500006 0.12500006 1
-0.0 0.249999955 -0.249999985 1
0.499999911 -0.0 -0.0 1
0.499999911 -0.249999985 -0.0 1

5. Plug into '''dvscf''' folder. From the nscf folder copy density and wave-functions (''cp -r ../nscf/si.save ./''), from the phonon folder copy the dynamical matrices and the dvscf files (''cp -r ../phonon/_ph0 ../phonon/*.dyn* ./''). Then modify the phonon input to generate electron-phonon matrix elements for Yambo, by changing epsil = .false., trans = .false. and electron_phonon = yambo. You do not need to specify the k-point grid because it is read from the nscf wave-functions. In this way we will not recalculate phonons, but only the electron-phonon matrix elements for the number of bands present in the nscf input file, in our case 8 bands:

&inputph
verbosity = 'high'
tr2_ph = 1e-12
prefix = 'si'
fildvscf = 'si-dvscf'
fildyn = 'si.dyn'
electron_phonon = 'yambo',
epsil = .false.
trans = .false.
ldisp = .false.
qplot = .true.
/
8
-0.0 -0.0 -0.0 1
-0.124999978 -0.124999978 0.124999993 1
0.249999955 0.249999955 -0.249999985 1
-0.249999955 -0.0 -0.0 1
-0.37500006 -0.12500006 0.12500006 1
-0.0 0.249999955 -0.249999985 1
0.499999911 -0.0 -0.0 1
0.499999911 -0.249999985 -0.0 1

this run will generate a new folder ''elph_dir'' with all electron-phonon matrix elements in a format compatible with Yambo. 
Nota bene: use the same parallelization in the '''phonon''' and '''dvscf''' calculation to avoid problem reading wave-functions.

6. Now you have to read the electron-phonon matrix elements. Go in the ''dvscf/si.save'' folder, and use ypp_ph to import electron-phonon coupling, by doing ''ypp_ph -g'' and the PW el-ph folder:

gkkp # [R] gkkp databases
DBsPATH= "../elph_dir/" # Path to the PW el-ph databases
PHfreqF= "none" # PWscf format file containing the phonon frequencies
PHmodeF= "none" # PWscf format file containing the phonon modes
#GkkpExpand # Expand the gkkp in the whole BZ
#GkkpConvert # Convert the gkkp to new I/O format

run ypp_ph, and if everything went well you will get in output

.....
-> [06] == Electron-Phonon Interface: PW->Yambo Databases ==
<---> PW(ELPH) databases ...[PHONON] ...found 8 Q-grid compatible
<---> ELPH databases (WRITE) |########################################| [100%] --(E) --(X)
<---> Modes : 6
<---> Bands range : 12
.....

== Quasi-particle band structure ==
The first quantity we will calculate is the correction to the band structure induced by the electron-phonon coupling. In order to generate the corresponding input do "'''yambo_ph -g n -p fan -c ep -V gen'''". In the input we require the correction only at gamma point:

dyson # [R] Dyson Equation solver
gw0 # [R] GW approximation
el_ph_corr # [R] Electron-Phonon Correlation
Nelectro= 8.000000 # Electrons number
ElecTemp= 0.000000 eV # Electronic Temperature
BoseTemp= 0.000000 eV # Bosonic Temperature
OccTresh= 0.100000E-4 # Occupation treshold (metallic bands)
SE_Threads=0 # [OPENMP/GW] Number of threads for self-energy
DysSolver= "n" # [GW] Dyson Equation solver ("n","s","g")
% GphBRnge
1 | 12 | # [ELPH] G[W] bands range
%
% ElPhModes
1 | 6 | # [ELPH] Phonon modes included
%
GDamping= 0.0100000 eV # [GW] G[W] damping
RandQpts=0 # [RIM] Number of random q-points in the BZ
#WRgFsq # [ELPH] Dump on file gFsq coefficients
%QPkrange # [GW] QP generalized Kpoint/Band indices
1|1|2|8|
%
If you run yambo_ph -J T0 you will get correction at zero kelvin to the band structure. You can change the temperature to 300 K by doing:

dyson # [R] Dyson Equation solver
gw0 # [R] GW approximation
el_ph_corr # [R] Electron-Phonon Correlation
Nelectro= 8.000000 # Electrons number
ElecTemp= 0.000000 eV # Electronic Temperature
BoseTemp= 300.0 Kn # Bosonic Temperature
OccTresh= 0.100000E-4 # Occupation treshold (metallic bands)
SE_Threads=0 # [OPENMP/GW] Number of threads for self-energy
DysSolver= "n" # [GW] Dyson Equation solver ("n","s","g")
% GphBRnge
1 | 12 | # [ELPH] G[W] bands range
%
% ElPhModes
1 | 6 | # [ELPH] Phonon modes included
%
GDamping= 0.0100000 eV # [GW] G[W] damping
RandQpts=0 # [RIM] Number of random q-points in the BZ
#WRgFsq # [ELPH] Dump on file gFsq coefficients
%QPkrange # [GW] QP generalized Kpoint/Band indices
1|1|2|8|
%
run again ''yambo_ph -J T300'' and compare the two output file o-T0.qp and o-T300.qp, to find how much the gap change with the temperature.
If you repeat the calculation for different temperature you can obtain the trend of the gap vs temperature. The figure below report the Silicon gap at Gamma Point at different temperature obtained in this tutorial:
[[File:Si_gap_finite_t.png|600px|center]]
If you uncomment the flag WRgFsq the code saves information about the Eliashberg functions that can be plotted using the ''ypp_ph'', see below. 
Finally if you add ''-V qp'' in the input generation a new flag appears OnMassShell, if you un-comment this flag calculation will be performed in the "on mass shell" approximation, namely the static limit the Quasi-Particle approximation, for a discussion see reference <ref>H. Kawai et al. [https://arxiv.org/abs/1310.2038 Phys. Rev. B '''89''', 085202 (2014)]</ref>

Notice that the last column in the quasi-particle file "o.QP" contains the '''quasi-particle width''', that is related to their life-time. You can plot the band structure including this width to get quasi-particle spectra
similar to the one measured in ARPES experiments, see Fig. 2 in ref. <ref> G. Antonius, S. Poncé, E. Lantagne-Hurtubise, G. Auclair, X. Gonze, and M. Côté
[https://arxiv.org/abs/1505.07738 Phys. Rev. B 92, 085137 (2015)] </ref>.
This parameter will be used in the next tutorial on [http://www.yambo-code.org/wiki/index.php?title=Optical_properties_at_finite_temperature optical properties at finite temperature].
 WARNING: Yambo average the electron-phonon correction on the degenerate states, please include all degenerate states in your calculations. For example in the silicon case you need correction from the 2nd band to the 8th band.

== Convergence ==

The results of this tutorial are not converged. This is due to the poor parameters used in this tutorial to make the calculations fast. In order to have converged results, first of all you have to be sure to have converged phonons, in order to do that increase plane-wave cutoff, number of k-points and if necessary reduce ''tr2_ph''.
Then change the parameters for the Yambo calculations, increasing the number of '''k''' and '''q''' points and the number of bands. If you want to increase only the number of bands, just repeat the '''nscf''' and '''dvscf''' calculations without recalculate '''phonons'''. In the following section we will describe a smart way to accelerate convergence. 
Nota bene: At present Yambo neither implements the Fröhlich term at q=0<ref>Carla Verdi and Feliciano Giustino
[https://arxiv.org/abs/1510.06373 Phys. Rev. Lett. '''115''', 176401 (2015)] </ref> nor the quadrupolar correction,<ref>G. Brunin et al. [https://arxiv.org/abs/2002.00628 Phys. Rev. Lett. '''125''', 136601 (2020)]</ref> therefore convergence in polar material can be very slow with the number of q-points.

== Double-grid method for the electron-phonon coupling (only in Yambo 5.x) ==

Simplifying at most the matrix elements of the electron-phonon self-energy have the structure:

[[File:Self elph.png|center|Yambo tutorial image | 270px ]]

where we omitted the electronic band and the phonon branches indexes. In order to speed up calculation one can average the denominators on an additional fine grid around each '''q''' points as:

[[File:Formula dbgrid.png|center|Yambo tutorial image| 500px]]

In order to exploit the double-grid tool we need the phonon energies calculated on a fine grid. Starting from a well converged phonon calculation ''matdyn.x'' can interpolate phonon dispersion on a given q-sampling (for example a regular 14x14x14 grid, as shown in the input file below) and give the desired phonon energies.

&input
asr='simple',
flfrc='si.fc',
flfrq='si.freq',
dos=.true.,
fldos='si.dos',
deltaE=1.d0,
nk1=14, nk2=14, nk3=14
/
Alternatively you can generate a random q-sampling using Yambo (''ypp -k r'') and insert the corresponding q points list into a matdyn file.

Once you generated the phonon energies you can read them with the command ''ypp_ph -g d'':

gkkp # [R] gkkp databases
gkkp_dg # [R] GKKP double grid
PHfreqF= "si.freq" # PWscf format file containing the phonon frequencies
PHmodeF= "none" # PWscf format file containing the phonon modes
FineGd_mode= "mixed" # Fine Grid mode. Symmetry expanded, unexpanded or mixed.
#SkipBorderPts # Skip points in the Fine Grid that are on the surface of coarse gride smal BZ`s
EkplusQmode= "interp" # E(k+q) energies calculation mode (interp | dftp )
#TestPHDGrid # Test double-grid: set all values of the fine grid equal to the couse ones

then run ''ypp_ph'' an it will generate a new file ''SAVE/ndb.PH_Double_Grid''. 
In the calculation the new phonon energies will be expanded
using the symmetries of the systems, while the electronic energies at '''k+q''' will be interpolated using a smooth Fourier interpolation<ref>Warren E. Pickett, Henry Krakauer, and Philip B. Allen,
Phys. Rev. B '''38''', 2721(1988)</ref>.
In order to perform calculation with the double grid remove the ''SAVE/ndb.QP'' file and repeat the calculation. 
The best strategy to converge electron-phonon coupling calculations is to converge the double-grid for a fixed course grid and the increase the second one. Hereafter an example of Silicon band gap correction convergence versus the number of '''q'''-points in the course grid, using a double-grid with 4096 random '''q'''-points.

[[File:Gap conv.png|center|Yambo tutorial image | 750px]]



== Miscellaneous and post-processing ==
'''Automatic generation of electron-phonon matrix elements''' 
Getting electron-phonon matrix elements from QuantumEspresso to Yambo is a complicated process, 
we advice you to create a script to automatize the procedure, here an example of a bash script for the silicon case: [http://www.yambo-code.org/educational/tutorials/files/SILICON_CONV.tgz SILICON-SCRIPT].

There are a list of utilities to analyze electron-phonon coupling results:

'''Phonon density of states''' 
You can plot phonon density of states with the command: ''ypp_ph -p d''. In order to get a nice plot set in the input

phonons # [R] Phononic properties
dos # [R] DOS
PhBroad= 0.0005000 eV # Phonon broadening (Eliashberg & DOS)
PhStps=1000 # Energy steps

notice that this is an easy quantity to check for the convergence in q-points.

[[File:Ph_dos.png|600px|center| Phonon Density of States]]

'''Eliashberg Functions''' 
You can plot Eliashberg functions<ref>F. Marsiglio, J.P. Carbotte [https://arxiv.org/abs/cond-mat/0106143 Electron - Phonon Superconductivity]</ref> for both electrons and excitons. In order to plot Eliashberg functions you must have calculated Quasi-Particle correction with the flag WRgFsq, see above.
The command ''ypp_ph -s e'' generate the input for the electronic Eliashberg functions:

electrons # [R] Electronic properties
eliashberg # [R] Eliashberg
PhBroad= 0.0010000 eV # Phonon broadening (Eliashberg & DOS)
PhStps= 200 # Energy steps
%QPkrange # generalized Kpoint/Band indices
1|1|4|5|
%

in this example we plot Eliashberg functions for the top valence and bottom conduction band at Gamma point:

[[File:Eliashberg functions.png|600px|center| Eliashberg functions]]

For a discussion on how to interprete Eliashberg functions and use them to understand the different phonon contribution you can have a look to ref.<ref>E. Cannuccia and A. Gali
[https://arxiv.org/abs/1907.06089 Phys. Rev. Materials 4, 014601 (2020)] </ref>

'''Atomic displacement amplitudes''' 
Running ''ypp_ph -p a'' will plot the atomic displacement for each atom in the cell each direction.

''' Other variables in the input files ''' 
In the input files of the present tutorial there are other variable not used in this tutorial.
In particular ''GkkpExpand'' is used for other calculations not present in the GPL, while ''GkkpConvert'' is used to checking purpose the IO for different versions
of the databases.

==References==
<references />

Electron Phonon Coupling

2022-02-15T16:23:42Z

ElenaCannuccia:

[[File:Electron phonon.png|thumb|200px| Electron-phonon coupling]]
Here we show step-by-step how to use [https://www.quantum-espresso.org/ Quantum Espresso] to calculate phonons and electron-phonon matrix-elements on a regular q-grid,
with the final aim to allow Yambo to read these databases and calculate the temperature-dependent correction to the electronic states.
This tutorial<ref> This tutorial is based on [http://www.attaccalite.com/elena/news/ Elena Cannuccia blog]</ref> is quite articulated, take your time to follow all the steps.

== Electron-phonon matrix elements ==

In this first section we will explain how to generate electron-phonon matrix elements in Quantum-Espresso, and how to import them in Yambo.
Calculations will be divided in different folders:

* '''pseudo''' the pseudo potential folder
* '''scf''' for the self-consistent calculation
* '''nscf''' for the non-self-consistent calculation with a larger number of bands
* '''phonon''' for the phonons calculations
* '''dvscf''' for the calculation of the electron-phonon matrix elements

In this tutorial we will show how to calculate electron-phonon induced corrections to the bands and optical properties for bulk silicon.
All input file are availabe in the following tgz file: [http://www.yambo-code.org/educational/tutorials/files/si.epc.tgz si.epc.tgz]

1. In '''scf''' we run a standard scf calculation choosing a large k-grid in such a way to converge density. Do not forget to set ''force_symmorphic=.true.'', because not symmorphic symmetries are not supported yet in Yambo. Notice that:

a) If you are working with 2D systems, not our case, we have to add the flag ''assume_isolated="2D"'' in such a way correct 2D phonons.

b) If the cell is an FCC, set manually the cell parameters by using the flag ibrav=0 in your scf input file. This allows to generate correctly the unform q grid over which phonons and electron-phonon databases are calculated.

2. Go in the '''nscf''' folder, and then copy the ${PREFIX}.save folder from '''scf''' to '''nscf''', in the present example just do ''cp -r ../scf/si.save ./''.
In the nscf input you have to choose the number of k-points and bands you will use for the electron-phonon coupling and Yambo calculations, in our case we will a 4x4x4 grid and 12 bands.

3. Read the q-points list. In the '''nscf''' folder, enter in the ${PREFIX}.save then run ''p2y'' to read the wave-functions.

4. Generate the setup file with the command ''yambo_ph -i -V all'' and uncomment the flag ''BSEscatt'' then run the setup.

5. Generate the input file to read the electron-phonon matrix elements with the command ''ypp_ph -k q'':

bzgrids # [R] BZ Grid generator
Q_grid # [R] Q-grid analysis
OutputAlat= 0.000000 # [a.u.] Lattice constant used for "alat" ouput format
#NoWeights # Do not print points weight
cooIn= "rlu" # Points coordinates (in) cc/rlu/iku/alat
cooOut= "alat" # Points coordinates (out) cc/rlu/iku/alat
ListPts # List the internal q/k points also in the parser format
#ExpandPts # Expand the internal q/k points in the BZ
#ForceUserPts # Do not check the correcteness of the user points
%Qpts # Q points list
0.000000| 0.000000| 0.000000|
%
and uncomment the flag '''ListPts''' and q-point coordinates units in '''alat''', the units used by QuantumEspresso. Now if you run ypp_ph it will generate the list of q-points for the phonon calculations:

.....
<---> Q-points (IBZ) PW-formatted
0.000000000 0.000000000 0.000000000 1
0.124999978 0.124999978 -0.124999993 1
-0.249999955 -0.249999955 0.249999985 1
0.249999955 0.000000000 0.000000000 1
0.375000060 0.125000060 -0.125000060 1
0.000000000 -0.249999955 0.249999985 1
-0.499999911 0.000000000 0.000000000 1
-0.499999911 0.249999985 0.000000000 1
<---> [08] Timing Overview
......

4. Go in the '''phonon''' directory. You have to copy the self-consistent calculation in this folder
with the command ''cp -r ../scf/si.save ./ ''. Then you can prepare and input file for phonons using the q-points list you generated in the previous step mutiplied by -1,
the final input will be:

&inputph
verbosity = 'high'
tr2_ph = 1e-12h
prefix = 'si'
fildvscf = 'si-dvscf'
fildyn = 'si.dyn',
electron_phonon = 'dvscf',
epsil = .true.
trans = .true.
ldisp = .false.
qplot = .true.
/
8
-0.0 -0.0 -0.0 1
-0.124999978 -0.124999978 0.124999993 1
0.249999955 0.249999955 -0.249999985 1
-0.249999955 -0.0 -0.0 1
-0.37500006 -0.12500006 0.12500006 1
-0.0 0.249999955 -0.249999985 1
0.499999911 -0.0 -0.0 1
0.499999911 -0.249999985 -0.0 1

5. Go in the '''dvscf''' folder. From the nscf folder copy density and wave-functions and from the phonon folder copy the dynamical matrices and the dvscf matrix elements: ''cp -r ../nscf/si.save ./'' and ''cp -r ../phonon/_ph0 ../phonon/*.dyn* ./''. Then modify the phonon input to generate electron-phonon matrix elements for Yambo, by changing trans = .false. and electron_phonon = yambo. You do not need to specify the k-point grid because it is read from the nscf wave-functions. In this way we will not recalculate phonons, but only the electron-phonon matrix elements for the number of bands present in the nscf input file, in our case 8 bands:

&inputph
verbosity = 'high'
tr2_ph = 1e-12
prefix = 'si'
fildvscf = 'si-dvscf'
fildyn = 'si.dyn'
electron_phonon = 'yambo',
epsil = .false.
trans = .false.
ldisp = .false.
qplot = .true.
/
8
-0.0 -0.0 -0.0 1
-0.124999978 -0.124999978 0.124999993 1
0.249999955 0.249999955 -0.249999985 1
-0.249999955 -0.0 -0.0 1
-0.37500006 -0.12500006 0.12500006 1
-0.0 0.249999955 -0.249999985 1
0.499999911 -0.0 -0.0 1
0.499999911 -0.249999985 -0.0 1

this run will generate a new folder ''elph_dir'' with all electron-phonon matrix elements in a format compatible with Yambo. 
Nota bene: use the same parallelization in the '''phonon''' and '''dvscf''' calculation to avoid problem reading wave-functions.

6. Now you have to read the electron-phonon matrix elements. Go in the ''dvscf/si.save'' folder, and use ypp_ph to import electron-phonon coupling, by doing ''ypp_ph -g'' and the the PW el-ph folder:

gkkp # [R] gkkp databases
DBsPATH= "../elph_dir/" # Path to the PW el-ph databases
PHfreqF= "none" # PWscf format file containing the phonon frequencies
PHmodeF= "none" # PWscf format file containing the phonon modes
#GkkpExpand # Expand the gkkp in the whole BZ
#GkkpConvert # Convert the gkkp to new I/O format

run ypp_ph, and if everything went well you will get in output

.....
-> [06] == Electron-Phonon Interface: PW->Yambo Databases ==
<---> PW(ELPH) databases ...[PHONON] ...found 8 Q-grid compatible
<---> ELPH databases (WRITE) |########################################| [100%] --(E) --(X)
<---> Modes : 6
<---> Bands range : 12
.....
<---> :: Uniform sampling :yes

== Quasi-particle band structure ==
The first quantity we will calculate is the correction to the band structure induced by the electron-phonon coupling. In order to generate the corresponding input do "'''yambo_ph -g n -p fan -c ep -V gen'''". In the input we require the correction only at gamma point:

dyson # [R] Dyson Equation solver
gw0 # [R] GW approximation
el_ph_corr # [R] Electron-Phonon Correlation
Nelectro= 8.000000 # Electrons number
ElecTemp= 0.000000 eV # Electronic Temperature
BoseTemp= 0.000000 eV # Bosonic Temperature
OccTresh= 0.100000E-4 # Occupation treshold (metallic bands)
SE_Threads=0 # [OPENMP/GW] Number of threads for self-energy
DysSolver= "n" # [GW] Dyson Equation solver ("n","s","g")
% GphBRnge
1 | 12 | # [ELPH] G[W] bands range
%
% ElPhModes
1 | 6 | # [ELPH] Phonon modes included
%
GDamping= 0.0100000 eV # [GW] G[W] damping
RandQpts=0 # [RIM] Number of random q-points in the BZ
#WRgFsq # [ELPH] Dump on file gFsq coefficients
%QPkrange # [GW] QP generalized Kpoint/Band indices
1|1|2|8|
%
If you run yambo_ph -J T0 you will get correction at zero kelvin to the band structure. You can change the temperature to 300 K by doing:

dyson # [R] Dyson Equation solver
gw0 # [R] GW approximation
el_ph_corr # [R] Electron-Phonon Correlation
Nelectro= 8.000000 # Electrons number
ElecTemp= 0.000000 eV # Electronic Temperature
BoseTemp= 300.0 Kn # Bosonic Temperature
OccTresh= 0.100000E-4 # Occupation treshold (metallic bands)
SE_Threads=0 # [OPENMP/GW] Number of threads for self-energy
DysSolver= "n" # [GW] Dyson Equation solver ("n","s","g")
% GphBRnge
1 | 12 | # [ELPH] G[W] bands range
%
% ElPhModes
1 | 6 | # [ELPH] Phonon modes included
%
GDamping= 0.0100000 eV # [GW] G[W] damping
RandQpts=0 # [RIM] Number of random q-points in the BZ
#WRgFsq # [ELPH] Dump on file gFsq coefficients
%QPkrange # [GW] QP generalized Kpoint/Band indices
1|1|2|8|
%
run again ''yambo_ph -J T300'' and compare the two output file o-T0.qp and o-T300.qp, to find how much the gap change with the temperature.
If you repeat the calculation for different temperature you can obtain the trend of the gap vs temperature. The figure below report the Silicon gap at Gamma Point at different temperature obtained in this tutorial:
[[File:Si_gap_finite_t.png|600px|center]]
If you uncomment the flag WRgFsq the code saves information about the Eliashberg functions that can be plotted using the ''ypp_ph'', see below. 
Finally if you add ''-V qp'' in the input generation a new flag appears OnMassShell, if you un-comment this flag calculation will be performed in the "on mass shell" approximation, namely the static limit the Quasi-Particle approximation, for a discussion see reference <ref>H. Kawai et al. [https://arxiv.org/abs/1310.2038 Phys. Rev. B '''89''', 085202 (2014)]</ref>

Notice that the last column in the quasi-particle file "o.QP" contains the '''quasi-particle width''', that is related to their life-time. You can plot the band structure including this width to get quasi-particle spectra
similar to the one measured in ARPES experiments, see Fig. 2 in ref. <ref> G. Antonius, S. Poncé, E. Lantagne-Hurtubise, G. Auclair, X. Gonze, and M. Côté
[https://arxiv.org/abs/1505.07738 Phys. Rev. B 92, 085137 (2015)] </ref>.
This parameter will be used in the next tutorial on [http://www.yambo-code.org/wiki/index.php?title=Optical_properties_at_finite_temperature optical properties at finite temperature].
 WARNING: Yambo average the electron-phonon correction on the degenerate states, please include all degenerate states in your calculations. For example in the silicon case you need correction from the 2nd band to the 8th band.

== Convergence ==

The results of this tutorial are not converged. This is due to the poor parameters used in this tutorial to make the calculations fast. In order to have converged results, first of all you have to be sure to have converged phonons, in order to do that increase plane-wave cutoff, number of k-points and if necessary reduce ''tr2_ph''.
Then change the parameters for the Yambo calculations, increasing the number of '''k''' and '''q''' points and the number of bands. If you want to increase only the number of bands, just repeat the '''nscf''' and '''dvscf''' calculations without recalculate '''phonons'''. In the following section we will describe a smart way to accelerate convergence. 
Nota bene: At present Yambo neither implements the Fröhlich term at q=0<ref>Carla Verdi and Feliciano Giustino
[https://arxiv.org/abs/1510.06373 Phys. Rev. Lett. '''115''', 176401 (2015)] </ref> nor the quadrupolar correction,<ref>G. Brunin et al. [https://arxiv.org/abs/2002.00628 Phys. Rev. Lett. '''125''', 136601 (2020)]</ref> therefore convergence in polar material can be very slow with the number of q-points.

== Double-grid method for the electron-phonon coupling (only in Yambo 5.x) ==

In general the matrix elements of the electron-phonon self-energy have the structure:

[[File:Self elph.png|center|Yambo tutorial image | 270px ]]

where we omitted the band and phonon indexes. In order to speed up calculation one can average the denominators on an additional fine grid around each '''q''' points as:

[[File:Formula dbgrid.png|center|Yambo tutorial image| 500px]]

In order to get the double-grid we need the phonon energies calculated on a fine grid. These energies can be obtained using the ''matdyn.x'' tool in QuantumEspresso.
Staring from a converged phonon calculation ''matdyn.x'' can interpolate phonon dispersion on a given q-sampling. You can choose to generate a random q-sampling
using ''ypp -k r'' or a regular double-grid directly generated by ''matdyn.x'' with the input:

&input
asr='simple',
flfrc='si.fc',
flfrq='si.freq',
dos=.true.,
fldos='si.dos',
deltaE=1.d0,
nk1=14, nk2=14, nk3=14
/

Once you generated the phonon energies you can read them with the command ''ypp_ph -g d'':

gkkp # [R] gkkp databases
gkkp_dg # [R] GKKP double grid
PHfreqF= "si.freq" # PWscf format file containing the phonon frequencies
PHmodeF= "none" # PWscf format file containing the phonon modes
FineGd_mode= "mixed" # Fine Grid mode. Symmetry expanded, unexpanded or mixed.
#SkipBorderPts # Skip points in the Fine Grid that are on the surface of coarse gride smal BZ`s
EkplusQmode= "interp" # E(k+q) energies calculation mode (interp | dftp )
#TestPHDGrid # Test double-grid: set all values of the fine grid equal to the couse ones

then run ''ypp_ph'' an it will generate a new file ''SAVE/ndb.PH_Double_Grid''. 
In the calculation the new phonon energies will be expanded
using the symmetries of the systems, while the electronic energies at '''k+q''' will be interpolated using a smooth Fourier interpolation.
In order to perform calculation with the double grid remove the ''SAVE/ndb.QP'' file and repeat the calculation. 
The best strategy to converge electron-phonon coupling calculations is to converge the double-grid for a fixed course grid and the increase the second one. Hereafter an example of Silicon band gap correction convergence versus the number of '''q'''-points in the course grid, using a double-grid with 4096 random '''q'''-points.

[[File:Gap conv.png|center|Yambo tutorial image | 750px]]



== Miscellaneous and post-processing ==
'''Automatic generation of electron-phonon matrix elements''' 
Getting electron-phonon matrix elements from QuantumEspresso to Yambo is a complicated process, 
we advice you to create a script to automatize the procedure, here an example of a bash script for the silicon case: [http://www.yambo-code.org/educational/tutorials/files/SILICON_CONV.tgz SILICON-SCRIPT].

There are a list of utilities to analyze electron-phonon coupling results:

'''Phonon density of states''' 
You can plot phonon density of states with the command: ''ypp_ph -p d''. In order to get a nice plot set in the input

phonons # [R] Phononic properties
dos # [R] DOS
PhBroad= 0.0005000 eV # Phonon broadening (Eliashberg & DOS)
PhStps=1000 # Energy steps

notice that this is an easy quantity to check for the convergence in q-points.

[[File:Ph_dos.png|600px|center| Phonon Density of States]]

'''Eliashberg Functions''' 
You can plot Eliashberg functions<ref>F. Marsiglio, J.P. Carbotte [https://arxiv.org/abs/cond-mat/0106143 Electron - Phonon Superconductivity]</ref> for both electrons and excitons. In order to plot Eliashberg functions you must have calculated Quasi-Particle correction with the flag WRgFsq, see above.
The command ''ypp_ph -s e'' generate the input for the electronic Eliashberg functions:

electrons # [R] Electronic properties
eliashberg # [R] Eliashberg
PhBroad= 0.0010000 eV # Phonon broadening (Eliashberg & DOS)
PhStps= 200 # Energy steps
%QPkrange # generalized Kpoint/Band indices
1|1|4|5|
%

in this example we plot Eliashberg functions for the top valence and bottom conduction band at Gamma point:

[[File:Eliashberg functions.png|600px|center| Eliashberg functions]]

For a discussion on how to interprete Eliashberg functions and use them to understand the different phonon contribution you can have a look to ref.<ref>E. Cannuccia and A. Gali
[https://arxiv.org/abs/1907.06089 Phys. Rev. Materials 4, 014601 (2020)] </ref>

'''Atomic displacement amplitudes''' 
Running ''ypp_ph -p a'' will plot the atomic displacement for each atom in the cell each direction.

''' Other variables in the input files ''' 
In the input files of the present tutorial there are other variable not used in this tutorial.
In particular ''GkkpExpand'' is used for other calculations not present in the GPL, while ''GkkpConvert'' is used to checking purpose the IO for different versions
of the databases.

==References==
<references />

Electron Phonon Coupling

2022-02-15T16:23:14Z

ElenaCannuccia:

[[File:Electron phonon.png|thumb|200px| Electron-phonon coupling]]
Here we show step-by-step how to use [https://www.quantum-espresso.org/ Quantum Espresso] to calculate phonons and electron-phonon matrix-elements on a regular q-grid,
with the final aim to allow Yambo to read these databases and calculate the temperature-dependent correction to the electronic states.
This tutorial<ref> This tutorial is based on [http://www.attaccalite.com/elena/news/ Elena Cannuccia blog]</ref> is quite articulated, take your time to follow all the steps.

== Electron-phonon matrix elements ==

In this first section we will explain how to generate electron-phonon matrix elements in Quantum-Espresso, and how to import them in Yambo.
Calculations will be divided in different folders:

* '''pseudo''' the pseudo potential folder
* '''scf''' for the self-consistent calculation
* '''nscf''' for the non-self-consistent calculation with a larger number of bands
* '''phonon''' for the phonons calculations
* '''dvscf''' for the calculation of the electron-phonon matrix elements

In this tutorial we will show how to calculate electron-phonon induced corrections to the bands and optical properties for bulk silicon.
All input file are availabe in the following tgz file: [http://www.yambo-code.org/educational/tutorials/files/si.epc.tgz si.epc.tgz]

1. In '''scf''' we run a standard scf calculation choosing a large k-grid in such a way to converge density. Do not forget to set ''force_symmorphic=.true.'', because not symmorphic symmetries are not supported yet in Yambo. Notice that:

a) If you are working with 2D systems, not our case, we have to add the flag ''assume_isolated="2D"'' in such a way correct 2D phonons.

b) If the cell is an FCC, set manually the cell parameters by using the flag ibrav=0 in your scf input file. This allows to generate correctly the unform q grid over which phonons and electron-phonon databasis are calculated.

2. Go in the '''nscf''' folder, and then copy the ${PREFIX}.save folder from '''scf''' to '''nscf''', in the present example just do ''cp -r ../scf/si.save ./''.
In the nscf input you have to choose the number of k-points and bands you will use for the electron-phonon coupling and Yambo calculations, in our case we will a 4x4x4 grid and 12 bands.

3. Read the q-points list. In the '''nscf''' folder, enter in the ${PREFIX}.save then run ''p2y'' to read the wave-functions.

4. Generate the setup file with the command ''yambo_ph -i -V all'' and uncomment the flag ''BSEscatt'' then run the setup.

5. Generate the input file to read the electron-phonon matrix elements with the command ''ypp_ph -k q'':

bzgrids # [R] BZ Grid generator
Q_grid # [R] Q-grid analysis
OutputAlat= 0.000000 # [a.u.] Lattice constant used for "alat" ouput format
#NoWeights # Do not print points weight
cooIn= "rlu" # Points coordinates (in) cc/rlu/iku/alat
cooOut= "alat" # Points coordinates (out) cc/rlu/iku/alat
ListPts # List the internal q/k points also in the parser format
#ExpandPts # Expand the internal q/k points in the BZ
#ForceUserPts # Do not check the correcteness of the user points
%Qpts # Q points list
0.000000| 0.000000| 0.000000|
%
and uncomment the flag '''ListPts''' and q-point coordinates units in '''alat''', the units used by QuantumEspresso. Now if you run ypp_ph it will generate the list of q-points for the phonon calculations:

.....
<---> Q-points (IBZ) PW-formatted
0.000000000 0.000000000 0.000000000 1
0.124999978 0.124999978 -0.124999993 1
-0.249999955 -0.249999955 0.249999985 1
0.249999955 0.000000000 0.000000000 1
0.375000060 0.125000060 -0.125000060 1
0.000000000 -0.249999955 0.249999985 1
-0.499999911 0.000000000 0.000000000 1
-0.499999911 0.249999985 0.000000000 1
<---> [08] Timing Overview
......

4. Go in the '''phonon''' directory. You have to copy the self-consistent calculation in this folder
with the command ''cp -r ../scf/si.save ./ ''. Then you can prepare and input file for phonons using the q-points list you generated in the previous step mutiplied by -1,
the final input will be:

&inputph
verbosity = 'high'
tr2_ph = 1e-12h
prefix = 'si'
fildvscf = 'si-dvscf'
fildyn = 'si.dyn',
electron_phonon = 'dvscf',
epsil = .true.
trans = .true.
ldisp = .false.
qplot = .true.
/
8
-0.0 -0.0 -0.0 1
-0.124999978 -0.124999978 0.124999993 1
0.249999955 0.249999955 -0.249999985 1
-0.249999955 -0.0 -0.0 1
-0.37500006 -0.12500006 0.12500006 1
-0.0 0.249999955 -0.249999985 1
0.499999911 -0.0 -0.0 1
0.499999911 -0.249999985 -0.0 1

5. Go in the '''dvscf''' folder. From the nscf folder copy density and wave-functions and from the phonon folder copy the dynamical matrices and the dvscf matrix elements: ''cp -r ../nscf/si.save ./'' and ''cp -r ../phonon/_ph0 ../phonon/*.dyn* ./''. Then modify the phonon input to generate electron-phonon matrix elements for Yambo, by changing trans = .false. and electron_phonon = yambo. You do not need to specify the k-point grid because it is read from the nscf wave-functions. In this way we will not recalculate phonons, but only the electron-phonon matrix elements for the number of bands present in the nscf input file, in our case 8 bands:

&inputph
verbosity = 'high'
tr2_ph = 1e-12
prefix = 'si'
fildvscf = 'si-dvscf'
fildyn = 'si.dyn'
electron_phonon = 'yambo',
epsil = .false.
trans = .false.
ldisp = .false.
qplot = .true.
/
8
-0.0 -0.0 -0.0 1
-0.124999978 -0.124999978 0.124999993 1
0.249999955 0.249999955 -0.249999985 1
-0.249999955 -0.0 -0.0 1
-0.37500006 -0.12500006 0.12500006 1
-0.0 0.249999955 -0.249999985 1
0.499999911 -0.0 -0.0 1
0.499999911 -0.249999985 -0.0 1

this run will generate a new folder ''elph_dir'' with all electron-phonon matrix elements in a format compatible with Yambo. 
Nota bene: use the same parallelization in the '''phonon''' and '''dvscf''' calculation to avoid problem reading wave-functions.

6. Now you have to read the electron-phonon matrix elements. Go in the ''dvscf/si.save'' folder, and use ypp_ph to import electron-phonon coupling, by doing ''ypp_ph -g'' and the the PW el-ph folder:

gkkp # [R] gkkp databases
DBsPATH= "../elph_dir/" # Path to the PW el-ph databases
PHfreqF= "none" # PWscf format file containing the phonon frequencies
PHmodeF= "none" # PWscf format file containing the phonon modes
#GkkpExpand # Expand the gkkp in the whole BZ
#GkkpConvert # Convert the gkkp to new I/O format

run ypp_ph, and if everything went well you will get in output

.....
-> [06] == Electron-Phonon Interface: PW->Yambo Databases ==
<---> PW(ELPH) databases ...[PHONON] ...found 8 Q-grid compatible
<---> ELPH databases (WRITE) |########################################| [100%] --(E) --(X)
<---> Modes : 6
<---> Bands range : 12
.....
<---> :: Uniform sampling :yes

== Quasi-particle band structure ==
The first quantity we will calculate is the correction to the band structure induced by the electron-phonon coupling. In order to generate the corresponding input do "'''yambo_ph -g n -p fan -c ep -V gen'''". In the input we require the correction only at gamma point:

dyson # [R] Dyson Equation solver
gw0 # [R] GW approximation
el_ph_corr # [R] Electron-Phonon Correlation
Nelectro= 8.000000 # Electrons number
ElecTemp= 0.000000 eV # Electronic Temperature
BoseTemp= 0.000000 eV # Bosonic Temperature
OccTresh= 0.100000E-4 # Occupation treshold (metallic bands)
SE_Threads=0 # [OPENMP/GW] Number of threads for self-energy
DysSolver= "n" # [GW] Dyson Equation solver ("n","s","g")
% GphBRnge
1 | 12 | # [ELPH] G[W] bands range
%
% ElPhModes
1 | 6 | # [ELPH] Phonon modes included
%
GDamping= 0.0100000 eV # [GW] G[W] damping
RandQpts=0 # [RIM] Number of random q-points in the BZ
#WRgFsq # [ELPH] Dump on file gFsq coefficients
%QPkrange # [GW] QP generalized Kpoint/Band indices
1|1|2|8|
%
If you run yambo_ph -J T0 you will get correction at zero kelvin to the band structure. You can change the temperature to 300 K by doing:

dyson # [R] Dyson Equation solver
gw0 # [R] GW approximation
el_ph_corr # [R] Electron-Phonon Correlation
Nelectro= 8.000000 # Electrons number
ElecTemp= 0.000000 eV # Electronic Temperature
BoseTemp= 300.0 Kn # Bosonic Temperature
OccTresh= 0.100000E-4 # Occupation treshold (metallic bands)
SE_Threads=0 # [OPENMP/GW] Number of threads for self-energy
DysSolver= "n" # [GW] Dyson Equation solver ("n","s","g")
% GphBRnge
1 | 12 | # [ELPH] G[W] bands range
%
% ElPhModes
1 | 6 | # [ELPH] Phonon modes included
%
GDamping= 0.0100000 eV # [GW] G[W] damping
RandQpts=0 # [RIM] Number of random q-points in the BZ
#WRgFsq # [ELPH] Dump on file gFsq coefficients
%QPkrange # [GW] QP generalized Kpoint/Band indices
1|1|2|8|
%
run again ''yambo_ph -J T300'' and compare the two output file o-T0.qp and o-T300.qp, to find how much the gap change with the temperature.
If you repeat the calculation for different temperature you can obtain the trend of the gap vs temperature. The figure below report the Silicon gap at Gamma Point at different temperature obtained in this tutorial:
[[File:Si_gap_finite_t.png|600px|center]]
If you uncomment the flag WRgFsq the code saves information about the Eliashberg functions that can be plotted using the ''ypp_ph'', see below. 
Finally if you add ''-V qp'' in the input generation a new flag appears OnMassShell, if you un-comment this flag calculation will be performed in the "on mass shell" approximation, namely the static limit the Quasi-Particle approximation, for a discussion see reference <ref>H. Kawai et al. [https://arxiv.org/abs/1310.2038 Phys. Rev. B '''89''', 085202 (2014)]</ref>

Notice that the last column in the quasi-particle file "o.QP" contains the '''quasi-particle width''', that is related to their life-time. You can plot the band structure including this width to get quasi-particle spectra
similar to the one measured in ARPES experiments, see Fig. 2 in ref. <ref> G. Antonius, S. Poncé, E. Lantagne-Hurtubise, G. Auclair, X. Gonze, and M. Côté
[https://arxiv.org/abs/1505.07738 Phys. Rev. B 92, 085137 (2015)] </ref>.
This parameter will be used in the next tutorial on [http://www.yambo-code.org/wiki/index.php?title=Optical_properties_at_finite_temperature optical properties at finite temperature].
 WARNING: Yambo average the electron-phonon correction on the degenerate states, please include all degenerate states in your calculations. For example in the silicon case you need correction from the 2nd band to the 8th band.

== Convergence ==

The results of this tutorial are not converged. This is due to the poor parameters used in this tutorial to make the calculations fast. In order to have converged results, first of all you have to be sure to have converged phonons, in order to do that increase plane-wave cutoff, number of k-points and if necessary reduce ''tr2_ph''.
Then change the parameters for the Yambo calculations, increasing the number of '''k''' and '''q''' points and the number of bands. If you want to increase only the number of bands, just repeat the '''nscf''' and '''dvscf''' calculations without recalculate '''phonons'''. In the following section we will describe a smart way to accelerate convergence. 
Nota bene: At present Yambo neither implements the Fröhlich term at q=0<ref>Carla Verdi and Feliciano Giustino
[https://arxiv.org/abs/1510.06373 Phys. Rev. Lett. '''115''', 176401 (2015)] </ref> nor the quadrupolar correction,<ref>G. Brunin et al. [https://arxiv.org/abs/2002.00628 Phys. Rev. Lett. '''125''', 136601 (2020)]</ref> therefore convergence in polar material can be very slow with the number of q-points.

== Double-grid method for the electron-phonon coupling (only in Yambo 5.x) ==

In general the matrix elements of the electron-phonon self-energy have the structure:

[[File:Self elph.png|center|Yambo tutorial image | 270px ]]

where we omitted the band and phonon indexes. In order to speed up calculation one can average the denominators on an additional fine grid around each '''q''' points as:

[[File:Formula dbgrid.png|center|Yambo tutorial image| 500px]]

In order to get the double-grid we need the phonon energies calculated on a fine grid. These energies can be obtained using the ''matdyn.x'' tool in QuantumEspresso.
Staring from a converged phonon calculation ''matdyn.x'' can interpolate phonon dispersion on a given q-sampling. You can choose to generate a random q-sampling
using ''ypp -k r'' or a regular double-grid directly generated by ''matdyn.x'' with the input:

&input
asr='simple',
flfrc='si.fc',
flfrq='si.freq',
dos=.true.,
fldos='si.dos',
deltaE=1.d0,
nk1=14, nk2=14, nk3=14
/

Once you generated the phonon energies you can read them with the command ''ypp_ph -g d'':

gkkp # [R] gkkp databases
gkkp_dg # [R] GKKP double grid
PHfreqF= "si.freq" # PWscf format file containing the phonon frequencies
PHmodeF= "none" # PWscf format file containing the phonon modes
FineGd_mode= "mixed" # Fine Grid mode. Symmetry expanded, unexpanded or mixed.
#SkipBorderPts # Skip points in the Fine Grid that are on the surface of coarse gride smal BZ`s
EkplusQmode= "interp" # E(k+q) energies calculation mode (interp | dftp )
#TestPHDGrid # Test double-grid: set all values of the fine grid equal to the couse ones

then run ''ypp_ph'' an it will generate a new file ''SAVE/ndb.PH_Double_Grid''. 
In the calculation the new phonon energies will be expanded
using the symmetries of the systems, while the electronic energies at '''k+q''' will be interpolated using a smooth Fourier interpolation.
In order to perform calculation with the double grid remove the ''SAVE/ndb.QP'' file and repeat the calculation. 
The best strategy to converge electron-phonon coupling calculations is to converge the double-grid for a fixed course grid and the increase the second one. Hereafter an example of Silicon band gap correction convergence versus the number of '''q'''-points in the course grid, using a double-grid with 4096 random '''q'''-points.

[[File:Gap conv.png|center|Yambo tutorial image | 750px]]



== Miscellaneous and post-processing ==
'''Automatic generation of electron-phonon matrix elements''' 
Getting electron-phonon matrix elements from QuantumEspresso to Yambo is a complicated process, 
we advice you to create a script to automatize the procedure, here an example of a bash script for the silicon case: [http://www.yambo-code.org/educational/tutorials/files/SILICON_CONV.tgz SILICON-SCRIPT].

There are a list of utilities to analyze electron-phonon coupling results:

'''Phonon density of states''' 
You can plot phonon density of states with the command: ''ypp_ph -p d''. In order to get a nice plot set in the input

phonons # [R] Phononic properties
dos # [R] DOS
PhBroad= 0.0005000 eV # Phonon broadening (Eliashberg & DOS)
PhStps=1000 # Energy steps

notice that this is an easy quantity to check for the convergence in q-points.

[[File:Ph_dos.png|600px|center| Phonon Density of States]]

'''Eliashberg Functions''' 
You can plot Eliashberg functions<ref>F. Marsiglio, J.P. Carbotte [https://arxiv.org/abs/cond-mat/0106143 Electron - Phonon Superconductivity]</ref> for both electrons and excitons. In order to plot Eliashberg functions you must have calculated Quasi-Particle correction with the flag WRgFsq, see above.
The command ''ypp_ph -s e'' generate the input for the electronic Eliashberg functions:

electrons # [R] Electronic properties
eliashberg # [R] Eliashberg
PhBroad= 0.0010000 eV # Phonon broadening (Eliashberg & DOS)
PhStps= 200 # Energy steps
%QPkrange # generalized Kpoint/Band indices
1|1|4|5|
%

in this example we plot Eliashberg functions for the top valence and bottom conduction band at Gamma point:

[[File:Eliashberg functions.png|600px|center| Eliashberg functions]]

For a discussion on how to interprete Eliashberg functions and use them to understand the different phonon contribution you can have a look to ref.<ref>E. Cannuccia and A. Gali
[https://arxiv.org/abs/1907.06089 Phys. Rev. Materials 4, 014601 (2020)] </ref>

'''Atomic displacement amplitudes''' 
Running ''ypp_ph -p a'' will plot the atomic displacement for each atom in the cell each direction.

''' Other variables in the input files ''' 
In the input files of the present tutorial there are other variable not used in this tutorial.
In particular ''GkkpExpand'' is used for other calculations not present in the GPL, while ''GkkpConvert'' is used to checking purpose the IO for different versions
of the databases.

==References==
<references />

Electron Phonon Coupling

2022-02-15T16:22:33Z

ElenaCannuccia:

[[File:Electron phonon.png|thumb|200px| Electron-phonon coupling]]
Here we show step-by-step how to use [https://www.quantum-espresso.org/ Quantum Espresso] to calculate phonons and electron-phonon matrix-elements on a regular q-grid,
with the final aim to allow Yambo to read these databases and calculate the temperature-dependent correction to the electronic states.
This tutorial<ref> This tutorial is based on [http://www.attaccalite.com/elena/news/ Elena Cannuccia blog]</ref> is quite articulated, take your time to follow all the steps.

== Electron-phonon matrix elements ==

In this first section we will explain how to generate electron-phonon matrix elements in Quantum-Espresso, and how to import them in Yambo.
Calculations will be divided in different folders:

* '''pseudo''' the pseudo potential folder
* '''scf''' for the self-consistent calculation
* '''nscf''' for the non-self-consistent calculation with a larger number of bands
* '''phonon''' for the phonons calculations
* '''dvscf''' for the calculation of the electron-phonon matrix elements

In this tutorial we will show how to calculate electron-phonon induced corrections to the bands and optical properties for bulk silicon.
All input file are availabe in the following tgz file: [http://www.yambo-code.org/educational/tutorials/files/si.epc.tgz si.epc.tgz]

1. In '''scf''' we run a standard scf calculation choosing a large k-grid in such a way to converge density. Do not forget to set ''force_symmorphic=.true.'', because not symmorphic symmetries are not supported yet in Yambo. Notice that:
a) If you are working with 2D systems, not our case, we have to add the flag ''assume_isolated="2D"'' in such a way correct 2D phonons.
b) If the cell is an FCC, set manually the cell parameters by using the flag ibrav=0 in your scf input file. This allows to generate correctly the unform q grid over which phonons and electron-phonon databasis are calculated.

2. Go in the '''nscf''' folder, and then copy the ${PREFIX}.save folder from '''scf''' to '''nscf''', in the present example just do ''cp -r ../scf/si.save ./''.
In the nscf input you have to choose the number of k-points and bands you will use for the electron-phonon coupling and Yambo calculations, in our case we will a 4x4x4 grid and 12 bands.

3. Read the q-points list. In the '''nscf''' folder, enter in the ${PREFIX}.save then run ''p2y'' to read the wave-functions.

4. Generate the setup file with the command ''yambo_ph -i -V all'' and uncomment the flag ''BSEscatt'' then run the setup.

5. Generate the input file to read the electron-phonon matrix elements with the command ''ypp_ph -k q'':

bzgrids # [R] BZ Grid generator
Q_grid # [R] Q-grid analysis
OutputAlat= 0.000000 # [a.u.] Lattice constant used for "alat" ouput format
#NoWeights # Do not print points weight
cooIn= "rlu" # Points coordinates (in) cc/rlu/iku/alat
cooOut= "alat" # Points coordinates (out) cc/rlu/iku/alat
ListPts # List the internal q/k points also in the parser format
#ExpandPts # Expand the internal q/k points in the BZ
#ForceUserPts # Do not check the correcteness of the user points
%Qpts # Q points list
0.000000| 0.000000| 0.000000|
%
and uncomment the flag '''ListPts''' and q-point coordinates units in '''alat''', the units used by QuantumEspresso. Now if you run ypp_ph it will generate the list of q-points for the phonon calculations:

.....
<---> Q-points (IBZ) PW-formatted
0.000000000 0.000000000 0.000000000 1
0.124999978 0.124999978 -0.124999993 1
-0.249999955 -0.249999955 0.249999985 1
0.249999955 0.000000000 0.000000000 1
0.375000060 0.125000060 -0.125000060 1
0.000000000 -0.249999955 0.249999985 1
-0.499999911 0.000000000 0.000000000 1
-0.499999911 0.249999985 0.000000000 1
<---> [08] Timing Overview
......

4. Go in the '''phonon''' directory. You have to copy the self-consistent calculation in this folder
with the command ''cp -r ../scf/si.save ./ ''. Then you can prepare and input file for phonons using the q-points list you generated in the previous step mutiplied by -1,
the final input will be:

&inputph
verbosity = 'high'
tr2_ph = 1e-12h
prefix = 'si'
fildvscf = 'si-dvscf'
fildyn = 'si.dyn',
electron_phonon = 'dvscf',
epsil = .true.
trans = .true.
ldisp = .false.
qplot = .true.
/
8
-0.0 -0.0 -0.0 1
-0.124999978 -0.124999978 0.124999993 1
0.249999955 0.249999955 -0.249999985 1
-0.249999955 -0.0 -0.0 1
-0.37500006 -0.12500006 0.12500006 1
-0.0 0.249999955 -0.249999985 1
0.499999911 -0.0 -0.0 1
0.499999911 -0.249999985 -0.0 1

5. Go in the '''dvscf''' folder. From the nscf folder copy density and wave-functions and from the phonon folder copy the dynamical matrices and the dvscf matrix elements: ''cp -r ../nscf/si.save ./'' and ''cp -r ../phonon/_ph0 ../phonon/*.dyn* ./''. Then modify the phonon input to generate electron-phonon matrix elements for Yambo, by changing trans = .false. and electron_phonon = yambo. You do not need to specify the k-point grid because it is read from the nscf wave-functions. In this way we will not recalculate phonons, but only the electron-phonon matrix elements for the number of bands present in the nscf input file, in our case 8 bands:

&inputph
verbosity = 'high'
tr2_ph = 1e-12
prefix = 'si'
fildvscf = 'si-dvscf'
fildyn = 'si.dyn'
electron_phonon = 'yambo',
epsil = .false.
trans = .false.
ldisp = .false.
qplot = .true.
/
8
-0.0 -0.0 -0.0 1
-0.124999978 -0.124999978 0.124999993 1
0.249999955 0.249999955 -0.249999985 1
-0.249999955 -0.0 -0.0 1
-0.37500006 -0.12500006 0.12500006 1
-0.0 0.249999955 -0.249999985 1
0.499999911 -0.0 -0.0 1
0.499999911 -0.249999985 -0.0 1

this run will generate a new folder ''elph_dir'' with all electron-phonon matrix elements in a format compatible with Yambo. 
Nota bene: use the same parallelization in the '''phonon''' and '''dvscf''' calculation to avoid problem reading wave-functions.

6. Now you have to read the electron-phonon matrix elements. Go in the ''dvscf/si.save'' folder, and use ypp_ph to import electron-phonon coupling, by doing ''ypp_ph -g'' and the the PW el-ph folder:

gkkp # [R] gkkp databases
DBsPATH= "../elph_dir/" # Path to the PW el-ph databases
PHfreqF= "none" # PWscf format file containing the phonon frequencies
PHmodeF= "none" # PWscf format file containing the phonon modes
#GkkpExpand # Expand the gkkp in the whole BZ
#GkkpConvert # Convert the gkkp to new I/O format

run ypp_ph, and if everything went well you will get in output

.....
-> [06] == Electron-Phonon Interface: PW->Yambo Databases ==
<---> PW(ELPH) databases ...[PHONON] ...found 8 Q-grid compatible
<---> ELPH databases (WRITE) |########################################| [100%] --(E) --(X)
<---> Modes : 6
<---> Bands range : 12
.....
<---> :: Uniform sampling :yes

== Quasi-particle band structure ==
The first quantity we will calculate is the correction to the band structure induced by the electron-phonon coupling. In order to generate the corresponding input do "'''yambo_ph -g n -p fan -c ep -V gen'''". In the input we require the correction only at gamma point:

dyson # [R] Dyson Equation solver
gw0 # [R] GW approximation
el_ph_corr # [R] Electron-Phonon Correlation
Nelectro= 8.000000 # Electrons number
ElecTemp= 0.000000 eV # Electronic Temperature
BoseTemp= 0.000000 eV # Bosonic Temperature
OccTresh= 0.100000E-4 # Occupation treshold (metallic bands)
SE_Threads=0 # [OPENMP/GW] Number of threads for self-energy
DysSolver= "n" # [GW] Dyson Equation solver ("n","s","g")
% GphBRnge
1 | 12 | # [ELPH] G[W] bands range
%
% ElPhModes
1 | 6 | # [ELPH] Phonon modes included
%
GDamping= 0.0100000 eV # [GW] G[W] damping
RandQpts=0 # [RIM] Number of random q-points in the BZ
#WRgFsq # [ELPH] Dump on file gFsq coefficients
%QPkrange # [GW] QP generalized Kpoint/Band indices
1|1|2|8|
%
If you run yambo_ph -J T0 you will get correction at zero kelvin to the band structure. You can change the temperature to 300 K by doing:

dyson # [R] Dyson Equation solver
gw0 # [R] GW approximation
el_ph_corr # [R] Electron-Phonon Correlation
Nelectro= 8.000000 # Electrons number
ElecTemp= 0.000000 eV # Electronic Temperature
BoseTemp= 300.0 Kn # Bosonic Temperature
OccTresh= 0.100000E-4 # Occupation treshold (metallic bands)
SE_Threads=0 # [OPENMP/GW] Number of threads for self-energy
DysSolver= "n" # [GW] Dyson Equation solver ("n","s","g")
% GphBRnge
1 | 12 | # [ELPH] G[W] bands range
%
% ElPhModes
1 | 6 | # [ELPH] Phonon modes included
%
GDamping= 0.0100000 eV # [GW] G[W] damping
RandQpts=0 # [RIM] Number of random q-points in the BZ
#WRgFsq # [ELPH] Dump on file gFsq coefficients
%QPkrange # [GW] QP generalized Kpoint/Band indices
1|1|2|8|
%
run again ''yambo_ph -J T300'' and compare the two output file o-T0.qp and o-T300.qp, to find how much the gap change with the temperature.
If you repeat the calculation for different temperature you can obtain the trend of the gap vs temperature. The figure below report the Silicon gap at Gamma Point at different temperature obtained in this tutorial:
[[File:Si_gap_finite_t.png|600px|center]]
If you uncomment the flag WRgFsq the code saves information about the Eliashberg functions that can be plotted using the ''ypp_ph'', see below. 
Finally if you add ''-V qp'' in the input generation a new flag appears OnMassShell, if you un-comment this flag calculation will be performed in the "on mass shell" approximation, namely the static limit the Quasi-Particle approximation, for a discussion see reference <ref>H. Kawai et al. [https://arxiv.org/abs/1310.2038 Phys. Rev. B '''89''', 085202 (2014)]</ref>

Notice that the last column in the quasi-particle file "o.QP" contains the '''quasi-particle width''', that is related to their life-time. You can plot the band structure including this width to get quasi-particle spectra
similar to the one measured in ARPES experiments, see Fig. 2 in ref. <ref> G. Antonius, S. Poncé, E. Lantagne-Hurtubise, G. Auclair, X. Gonze, and M. Côté
[https://arxiv.org/abs/1505.07738 Phys. Rev. B 92, 085137 (2015)] </ref>.
This parameter will be used in the next tutorial on [http://www.yambo-code.org/wiki/index.php?title=Optical_properties_at_finite_temperature optical properties at finite temperature].
 WARNING: Yambo average the electron-phonon correction on the degenerate states, please include all degenerate states in your calculations. For example in the silicon case you need correction from the 2nd band to the 8th band.

== Convergence ==

The results of this tutorial are not converged. This is due to the poor parameters used in this tutorial to make the calculations fast. In order to have converged results, first of all you have to be sure to have converged phonons, in order to do that increase plane-wave cutoff, number of k-points and if necessary reduce ''tr2_ph''.
Then change the parameters for the Yambo calculations, increasing the number of '''k''' and '''q''' points and the number of bands. If you want to increase only the number of bands, just repeat the '''nscf''' and '''dvscf''' calculations without recalculate '''phonons'''. In the following section we will describe a smart way to accelerate convergence. 
Nota bene: At present Yambo neither implements the Fröhlich term at q=0<ref>Carla Verdi and Feliciano Giustino
[https://arxiv.org/abs/1510.06373 Phys. Rev. Lett. '''115''', 176401 (2015)] </ref> nor the quadrupolar correction,<ref>G. Brunin et al. [https://arxiv.org/abs/2002.00628 Phys. Rev. Lett. '''125''', 136601 (2020)]</ref> therefore convergence in polar material can be very slow with the number of q-points.

== Double-grid method for the electron-phonon coupling (only in Yambo 5.x) ==

In general the matrix elements of the electron-phonon self-energy have the structure:

[[File:Self elph.png|center|Yambo tutorial image | 270px ]]

where we omitted the band and phonon indexes. In order to speed up calculation one can average the denominators on an additional fine grid around each '''q''' points as:

[[File:Formula dbgrid.png|center|Yambo tutorial image| 500px]]

In order to get the double-grid we need the phonon energies calculated on a fine grid. These energies can be obtained using the ''matdyn.x'' tool in QuantumEspresso.
Staring from a converged phonon calculation ''matdyn.x'' can interpolate phonon dispersion on a given q-sampling. You can choose to generate a random q-sampling
using ''ypp -k r'' or a regular double-grid directly generated by ''matdyn.x'' with the input:

&input
asr='simple',
flfrc='si.fc',
flfrq='si.freq',
dos=.true.,
fldos='si.dos',
deltaE=1.d0,
nk1=14, nk2=14, nk3=14
/

Once you generated the phonon energies you can read them with the command ''ypp_ph -g d'':

gkkp # [R] gkkp databases
gkkp_dg # [R] GKKP double grid
PHfreqF= "si.freq" # PWscf format file containing the phonon frequencies
PHmodeF= "none" # PWscf format file containing the phonon modes
FineGd_mode= "mixed" # Fine Grid mode. Symmetry expanded, unexpanded or mixed.
#SkipBorderPts # Skip points in the Fine Grid that are on the surface of coarse gride smal BZ`s
EkplusQmode= "interp" # E(k+q) energies calculation mode (interp | dftp )
#TestPHDGrid # Test double-grid: set all values of the fine grid equal to the couse ones

then run ''ypp_ph'' an it will generate a new file ''SAVE/ndb.PH_Double_Grid''. 
In the calculation the new phonon energies will be expanded
using the symmetries of the systems, while the electronic energies at '''k+q''' will be interpolated using a smooth Fourier interpolation.
In order to perform calculation with the double grid remove the ''SAVE/ndb.QP'' file and repeat the calculation. 
The best strategy to converge electron-phonon coupling calculations is to converge the double-grid for a fixed course grid and the increase the second one. Hereafter an example of Silicon band gap correction convergence versus the number of '''q'''-points in the course grid, using a double-grid with 4096 random '''q'''-points.

[[File:Gap conv.png|center|Yambo tutorial image | 750px]]



== Miscellaneous and post-processing ==
'''Automatic generation of electron-phonon matrix elements''' 
Getting electron-phonon matrix elements from QuantumEspresso to Yambo is a complicated process, 
we advice you to create a script to automatize the procedure, here an example of a bash script for the silicon case: [http://www.yambo-code.org/educational/tutorials/files/SILICON_CONV.tgz SILICON-SCRIPT].

There are a list of utilities to analyze electron-phonon coupling results:

'''Phonon density of states''' 
You can plot phonon density of states with the command: ''ypp_ph -p d''. In order to get a nice plot set in the input

phonons # [R] Phononic properties
dos # [R] DOS
PhBroad= 0.0005000 eV # Phonon broadening (Eliashberg & DOS)
PhStps=1000 # Energy steps

notice that this is an easy quantity to check for the convergence in q-points.

[[File:Ph_dos.png|600px|center| Phonon Density of States]]

'''Eliashberg Functions''' 
You can plot Eliashberg functions<ref>F. Marsiglio, J.P. Carbotte [https://arxiv.org/abs/cond-mat/0106143 Electron - Phonon Superconductivity]</ref> for both electrons and excitons. In order to plot Eliashberg functions you must have calculated Quasi-Particle correction with the flag WRgFsq, see above.
The command ''ypp_ph -s e'' generate the input for the electronic Eliashberg functions:

electrons # [R] Electronic properties
eliashberg # [R] Eliashberg
PhBroad= 0.0010000 eV # Phonon broadening (Eliashberg & DOS)
PhStps= 200 # Energy steps
%QPkrange # generalized Kpoint/Band indices
1|1|4|5|
%

in this example we plot Eliashberg functions for the top valence and bottom conduction band at Gamma point:

[[File:Eliashberg functions.png|600px|center| Eliashberg functions]]

For a discussion on how to interprete Eliashberg functions and use them to understand the different phonon contribution you can have a look to ref.<ref>E. Cannuccia and A. Gali
[https://arxiv.org/abs/1907.06089 Phys. Rev. Materials 4, 014601 (2020)] </ref>

'''Atomic displacement amplitudes''' 
Running ''ypp_ph -p a'' will plot the atomic displacement for each atom in the cell each direction.

''' Other variables in the input files ''' 
In the input files of the present tutorial there are other variable not used in this tutorial.
In particular ''GkkpExpand'' is used for other calculations not present in the GPL, while ''GkkpConvert'' is used to checking purpose the IO for different versions
of the databases.

==References==
<references />

Silicon

2022-02-08T22:42:47Z

ElenaCannuccia: /* COHSEX without empty bands */

= Basic concepts of the GW approximation =

[[File:GW0.png|x300px|center|]]

In this tutorial you will learn the basic concepts of the [[Hartree-Fock]] and of the GW<ref name="gw"/> approximation. In particular we will illustrate how to calculate [http://en.wikipedia.org/wiki/Quasiparticle Quasi-Particle] energies with a single shot G0W0 approximation. Different lecture notes on the GW approach are available in the [[Lectures|Lectures section]].

The tutorial is split in different sections. In the first part we will deal with Hartree-Fock (HF) and the Coulomb-hole and screened-exchange (COHSEX) approximation. Finally in the last section we will discuss dynamical correlation with a Plasmon Pole Approximation (PPA).

= The material: Silicon =

* [http://cst-www.nrl.navy.mil/lattice/struk/a1.html FCC] lattice
* Two atoms per cell (8 electrons)
* Lattice constant 10.183 [a.u.]
* Plane waves cutoff 15 Rydberg

===Band gap===

*Direct gap 3.4 eV at Gamma
*Indirect gap 1.1 eV betweeb Gamma and X'
*Gamma= (0 0 0)
*X' is a point close to X=(0 1 0)

[[File:si_banddiagram.gif|thumb|x400px|Silicon Band Structure]]

= The Tutorial files =
Follow the instructions in [[Tutorials#Files]] and download/unpack the <code>Silicon.tar.gz</code>.

= The Tutorial structure =

Once the tutorial archive file is unzipped the following folder structure will appear

COPYING README Silicon/

with the Solid_Si folder containing

> ls Silicon/
PWSCF/ YAMBO/

In the Pwscf folder the student will find an input/output directory with input/output files for pw.x. The Silicon pseudopotential file is also provided.

> ls PWSCF/
convergence_scripts input output psps

In the <code>convergence_scripts</code> you will find some useful shell scripts to run the ground state convergence runs for Silicon.

The YAMBO folder contains the Yambo input/output files and core databases.

> ls YAMBO/
2x2x2/ 4x4x4/ 6x6x6/ 8x8x8/ Convergence_Plots_and_Scripts/ GAMMA/

The core databases are provided for several k-points grids. In addition the folder <code>Convergence_Plots_and_Scripts</code> contains some scripts to extract informations from the report files useful for the tutorial.

= Hartree-Fock =

Now we will study the convergence of the [http://en.wikipedia.org/wiki/Hartree%E2%80%93Fock_method Hartree-Fock] self energy, respect to the number of '''G'''-vectors and '''k'''-points. Yambo is a plane-wave code, therefore all the operators and wave-functions are expanded as:

[[File:orbital.png|Orbital in plane wave]]

Before you start any calculations we can decide how many '''G'''-vectors you want use to represent your wave-function. By default Yambo will use all of them, and for the present tutorial this is fine, however if you are studying larger systems you would like to reduce them in order to speed-up calculations, you can do it with <code> yambo -i -V RL</code> and then changing the variable <code>MaxGvecs</code> that referees to Ng in the previous formula.

Now we will proceed in the calculation of the [[Hartree-Fock|Hartree-Fock]] exchange. This is composed of two terms, that Hartree and the Fock (or exchange) one:

[[File:hf.png|Hartree Fock]]

In this tutorial we will calculate only the first order correction to the Kohn-Sham Hamiltonian due to the exchange term. Because of we are working in periodic system, the most appropriate basis to represent the Coulomb potential, appearing in the Fock term, is a plane-wave basis:

[[File:v_q_plus_G.png|Coulomb potential in plane wave]]

In order to generate the input file for the exchange type <code>yambo -x</code>. The variable that governs the number of '''G''' vectors Nex in the Coulomb potential is <code>EXXRLvcs</code>. In addition notice that in the previous formula for V('''r'''-'''r'''') we have an integral on the '''q''' vector, that in the code is discretized on a regular '''q'''-grid generated from the '''k'''-point one, '''q'''='''k'''-'''k''''.

== G-vectors convergence ==

Enter the <code>4x4x4</code> folder

> cd 4x4x4

Now edit the <code>01HF_corrections</code> file changing the field <code>EXXRLvcs=</code>3,6,7 and 15 Ry. For each case run

> yambo -F Inputs/01HF_corrections -J HF_???Ry

with <code>???</code>=3,6,7 and 15

Now plot the HF corrections by using the [[Gnuplot_scripts|hf_vs_cutoff.gnuplot]] script. Launch it via

> gnuplot
gnuplot>load "hf_vs_cutoff.gnuplot"

[[File:HF_parameters.png|Hartree-Fock corrections versus energy cutoff]]

== K-points convergence==

Enter each grid folder (<code>GAMMA,2x2x2,4x4x4,...</code>) and run
> yambo
without options. Then type

> yambo -x -F Inputs/01HF_corrections -J 01HF_corrections

and edit the 01HF_corrections file

HF_and_locXC # [R XX] Hartree-Fock Self-energy and Vxc
EXXRLvcs= 15 Ry # [XX] Exchange RL components
%QPkrange # [GW] QP generalized Kpoint/Band indices
1| 8| 1| 15|
%
%QPerange # [GW] QP generalized Kpoint/Energy indices
1| 8| 0.0|-1.0|
%

setting

<code> EXXRLvcs=15 Ry</code>

Then run in each k-point folder

<code> > yambo -F Inputs/01HF_corrections -J 01HF_corrections</code>

Note that after each run Yambo produces three output file, one starting with <code>r_...</code> , another with <code>l_...</code> and a third one starting with <code>o_...</code>. The first one is a ''report'' of the actual calculation with all the details of the system, input, and results, while the second is a ''log'' with the running time of each process.

The file we are most interested in is the output file, <code>o-01HF_corrections.hf</code>. This file contains several columns. The fourth, labelled with <code>Ehf</code> represents the Hartree-Fock energy. This is the quantity we have to look at.

Use the [[Bash_scripts|parse_gap_hf.sh]] to parse the output files and adapt the gnuplot script provided earlier to print the values by using gnuplot

> cd ../
> ./parse_gap.sh o-01HF_corrections.hf hf_direct_gap_vs_kpoints.dat

[[File:Hf gap vs kpts.png|Direct gap vs k-points]]

= COHSEX without empty bands =

The Hartree-Fock self-energy just described in the previous section, although successful on some molecular systems, miserably fails in extended systems. The reason of this failure lies in the fact that electrons can screen the Coulomb potential, and therefore one electron feels a screened potential instead of the bare one. A common approximation for this screened potential is the so-called Random Phase Approximation:

[[File:gw.png|Hartree Fock]]

where the bare Coulomb potential V('''r''') is replaced by a non-local and frequency dependent one W('''r''','''r'''',ω). Subsequently it is possible to redefine all the perturbation theory in term of this screened potential, and disregarding the additional corrections coming from the vertex part, one obtains the so-called [[GW|GW]] approximation.

However the substantial complexity associated with calculating the non-local, energy dependent Σ=GW operator inspired early efforts to find simplifying approximations as the static COHSEX approximation prosed by Hedin<ref name="hedin"/>. The Coulomb Hole plus Screened Exchange (COHSEX) approximation[[[#march|2]],[[#fardi|3]]] eliminates the summation over empty states for the self energy operator and has the added benefit of being a static operator, a particular simplification for self consistent calculations. With the COHSEX approximation the self-energy is composed of two parts:

[[File:gw_sex.png|Screened Exchange]]

[[File:gw_coh.png|Cuolomb Hole]]

where Wp=W - V.

In order to calculate the COHSEX self-energy with yambo you need first the static screened interaction <code>yambo -X s -k hartree</code>. As for the V('''r''') case, also W('''r''','''r'''',E=0) will depend from the number of '''G'''-vectors, and the '''k'''-grid, but this time also the number of conduction bands <code>BndsRnXs</code> will enter in the screening calculation through the polarization function, see [http://www.yambo-code.org/theory/docs/doc_Xd.php The Interacting response function: Many-Body and TDDFT] section. Notice however that there are not any additional dependence of the self-energy operator from the conduction bands. After you obtained the screened interaction you are ready to build the self-energy operator and solve the corresponding Dyson equation, have a look to the [[GW|Dyson Equation solvers]] in Yambo. In order to get the quasi-particle energies, just do <code>yambo -X s -g n -k hartree</code>. After calculation are completed Yambo will produce an output file <code>o.qp</code> which contains the values of the bare and re-normalized energy levels.

== K-points convergence ==

Follow the same strategy of the HF case. Enter each k-point folder and type

> yambo -X s -k hartree -g n -p c -F Inputs/02Cohsex

edit the input file and change the values of the fields

EXXRLvcs=7 Ry
%BndsRnXs
1 | 10 | # [Xs] Polarization function bands
%
NGsBlkXs= 1 RL # [Xs] Response block size
#UseEbands # [GW] Force COHSEX to use empty bands
%QPkrange # [GW] QP generalized Kpoint/Band indices
1| 8| 1| 10|
%

leaving the other parameters unchanged. Now, in each k-point folder, run

> yambo -F Inputs/02Cohsex -J Cohsex_HF7Ry_X0Ry-nb10

Adapt the shell script provided earlier to plot the direct gap dependence on the k-points grid

[[File:Cohsex_HF7Ry_X0Ry-nb10_gap_vs_kpoints.png]]

== W size convergence ==

Enter the <code>4x4x4</code> folder and edit the <code>02Cohsex_corrections</code> file changing the field <code>NGsBlkXs=</code>3,6,7 Ry. Run

> yambo -F Inputs/02Cohsex -J Cohsex_HF7Ry_X???Ry-nb10

with <code>???</code>=3,6,7 and 15.

[[File:COHSEX_no_empties_W_size.png]]

== W bands ==

Open your input file and change only the input variable <code>NGsBlkXs=1 Ry</code>. Then change

%BndsRnXs 1 | 20 | # [Xs] Polarization function bands

and run <code>yambo -F Inputs/02Cohsex -J Cohsex_HF7Ry_X1Ry-nb20</code>.
Repeat the calculations using 30 and 40 bands changing <code>nb???</code> in the job string identifier. Finally check how the Chosex Direct and Indirect band gap behave as a function of the number of bands in the screening.

[[File:COHSEX_no_empties_W_bands.png]]

== COHSEX with empty bands ==

While the Screened Exchange(SEX) part of the COHSEX self-energy has a structure similar to the Hartree-Fock exchange term, the Coulomb Hole(COH) acts as static external potential on the electrons. In the COH part the delta function δ('''r'''-'''r'''') comes from the completeness relation:

[[File:completeness.png|Completeness relation]]

Now we avoid the use of this relation in such a way to have a self-energy that depends from the conduction bands too. This can be done uncommenting flags <code>UseEbands</code> and setting the number of bands in the Green's function:

% GbndRnge 1 | 10 | # [GW] G[W] bands range

Repeat the previous calculations with different <code>GbndRnge</code> for instance, 10 20 30 40, and check how the COHSEX direct and indirect band gap behave as a function of the number of bands in the Green's function.

[[File:COHSEX_empties_G_bands.png]]

= GW within the plasmon pole approximation (PPA) =

Even the static COHSEX approximation is very appealing, it was clear from the first calculation that dynamical effects cannot be disregarded in solids. This fact motivated the research for approximated way to deal with a frequency dependent interaction, and one of the first proposal was the so-called Plasmon-Pole Approximation (PPA).

Now we will proceed to the calculation of the silicon band gap in G0W0 within PPA. In each section you will be asked to perform several calculations varying the value of the relevant variables involved. More specifically let's consider a typical Yambo input file to calculate GW corrections in the PPA.

gw0 # [R GW] GoWo Quasiparticle energy levels
ppa # [R Xp] Plasmon Pole Approximation
HF_and_locXC # [R XX] Hartree-Fock Self-energy and Vxc
em1d # [R Xd] Dynamical Inverse Dielectric Matrix
EXXRLvcs= 7 Ry # [XX] Exchange RL components
% QpntsRXp
1 | 8 | # [Xp] Transferred momenta
%
% BndsRnXp
1 | 10 | # [Xp] Polarization function bands
%
NGsBlkXp= 1 RL # [Xp] Response block size
% LongDrXp
1.000000 | 0.000000 | 0.000000 | # [Xp] [cc] Electric Field
%
PPAPntXp= 27.21138 eV # [Xp] PPA imaginary energy
% GbndRnge
1 | 10 | # [GW] G[W] bands range
%
GDamping= 0.10000 eV # [GW] G[W] damping
dScStep= 0.10000 eV # [GW] Energy step to evalute Z factors
DysSolver= n # [GW] Dyson Equation solver (`n`,`s`,`g`)
%QPkrange # [GW] QP generalized Kpoint/Band indices
1| 8| 1| 10|
%
%QPerange # [GW] QP generalized Kpoint/Energy indices
1| 8| 0.0|-1.0|
%

The variables are the same of the COHSEX case plus a new one <code>PPAPntXp</code> that describes the imaginary energy used to fit the Plasmon Pole model. 
Follow the same strategy of the COHSEX case. Enter each k-point folder and type:

> yambo -d -k hartree -g n -p p -F Inputs/03GoWo_PPA_corrections

otherwise you can use the existent file <code>Input/03GoWo_PPA_corrections</code>. Now you have to study the convergence of the G0W0 gap versus the number of k-points, the number of bands in χ <code>BndsRnXs</code>, the size of the dielectric constant <code>NGsBlkXs</code> and the number of bands in the Green's function <code>GbndRnge</code>.

Please follow the same strategy of the COHSEX case running yambo using

> yambo -F Inputs/03GoWo_PPA_corrections -J GoWo_PPA_HF7Ry_X???Ry-nb???_nb???</code>

The final convergence plots should look like these (the plots are done using as a basis the above code).

[[File:PPA W size.png]]

[[File:PPA W bands.png]]

[[File:PPA G bands.png]]

[[File:PPA gap vs kpts.png]]

Final runs!! Now you know how to converge a G0W0 calculation so you can decide which are the parameters needed for full convergence. First do a COHSEX and then a GoWo (PPA) run at convergence, and you should obtain results similar to the following graph:

[[File:Si_gap.png|Final Gap Silicon]]

= References =
<references>
<ref name="gw">H. N. Rojas, R. W. Godby, and R. J. Needs, Phys. Rev. Lett. '''74''', 1827 (1995)</ref>
<ref name="hedin"> L. Hedin, Phys. Rev. '''139''', A796 (1965)</ref>
</references>

Silicon

2022-02-08T12:36:51Z

ElenaCannuccia: /* K-points convergence */

= Basic concepts of the GW approximation =

[[File:GW0.png|x300px|center|]]

In this tutorial you will learn the basic concepts of the [[Hartree-Fock]] and of the GW<ref name="gw"/> approximation. In particular we will illustrate how to calculate [http://en.wikipedia.org/wiki/Quasiparticle Quasi-Particle] energies with a single shot G0W0 approximation. Different lecture notes on the GW approach are available in the [[Lectures|Lectures section]].

The tutorial is split in different sections. In the first part we will deal with Hartree-Fock (HF) and the Coulomb-hole and screened-exchange (COHSEX) approximation. Finally in the last section we will discuss dynamical correlation with a Plasmon Pole Approximation (PPA).

= The material: Silicon =

* [http://cst-www.nrl.navy.mil/lattice/struk/a1.html FCC] lattice
* Two atoms per cell (8 electrons)
* Lattice constant 10.183 [a.u.]
* Plane waves cutoff 15 Rydberg

===Band gap===

*Direct gap 3.4 eV at Gamma
*Indirect gap 1.1 eV betweeb Gamma and X'
*Gamma= (0 0 0)
*X' is a point close to X=(0 1 0)

[[File:si_banddiagram.gif|thumb|x400px|Silicon Band Structure]]

= The Tutorial files =
Follow the instructions in [[Tutorials#Files]] and download/unpack the <code>Silicon.tar.gz</code>.

= The Tutorial structure =

Once the tutorial archive file is unzipped the following folder structure will appear

COPYING README Silicon/

with the Solid_Si folder containing

> ls Silicon/
PWSCF/ YAMBO/

In the Pwscf folder the student will find an input/output directory with input/output files for pw.x. The Silicon pseudopotential file is also provided.

> ls PWSCF/
convergence_scripts input output psps

In the <code>convergence_scripts</code> you will find some useful shell scripts to run the ground state convergence runs for Silicon.

The YAMBO folder contains the Yambo input/output files and core databases.

> ls YAMBO/
2x2x2/ 4x4x4/ 6x6x6/ 8x8x8/ Convergence_Plots_and_Scripts/ GAMMA/

The core databases are provided for several k-points grids. In addition the folder <code>Convergence_Plots_and_Scripts</code> contains some scripts to extract informations from the report files useful for the tutorial.

= Hartree-Fock =

Now we will study the convergence of the [http://en.wikipedia.org/wiki/Hartree%E2%80%93Fock_method Hartree-Fock] self energy, respect to the number of '''G'''-vectors and '''k'''-points. Yambo is a plane-wave code, therefore all the operators and wave-functions are expanded as:

[[File:orbital.png|Orbital in plane wave]]

Before you start any calculations we can decide how many '''G'''-vectors you want use to represent your wave-function. By default Yambo will use all of them, and for the present tutorial this is fine, however if you are studying larger systems you would like to reduce them in order to speed-up calculations, you can do it with <code> yambo -i -V RL</code> and then changing the variable <code>MaxGvecs</code> that referees to Ng in the previous formula.

Now we will proceed in the calculation of the [[Hartree-Fock|Hartree-Fock]] exchange. This is composed of two terms, that Hartree and the Fock (or exchange) one:

[[File:hf.png|Hartree Fock]]

In this tutorial we will calculate only the first order correction to the Kohn-Sham Hamiltonian due to the exchange term. Because of we are working in periodic system, the most appropriate basis to represent the Coulomb potential, appearing in the Fock term, is a plane-wave basis:

[[File:v_q_plus_G.png|Coulomb potential in plane wave]]

In order to generate the input file for the exchange type <code>yambo -x</code>. The variable that governs the number of '''G''' vectors Nex in the Coulomb potential is <code>EXXRLvcs</code>. In addition notice that in the previous formula for V('''r'''-'''r'''') we have an integral on the '''q''' vector, that in the code is discretized on a regular '''q'''-grid generated from the '''k'''-point one, '''q'''='''k'''-'''k''''.

== G-vectors convergence ==

Enter the <code>4x4x4</code> folder

> cd 4x4x4

Now edit the <code>01HF_corrections</code> file changing the field <code>EXXRLvcs=</code>3,6,7 and 15 Ry. For each case run

> yambo -F Inputs/01HF_corrections -J HF_???Ry

with <code>???</code>=3,6,7 and 15

Now plot the HF corrections by using the [[Gnuplot_scripts|hf_vs_cutoff.gnuplot]] script. Launch it via

> gnuplot
gnuplot>load "hf_vs_cutoff.gnuplot"

[[File:HF_parameters.png|Hartree-Fock corrections versus energy cutoff]]

== K-points convergence==

Enter each grid folder (<code>GAMMA,2x2x2,4x4x4,...</code>) and run
> yambo
without options. Then type

> yambo -x -F Inputs/01HF_corrections -J 01HF_corrections

and edit the 01HF_corrections file

HF_and_locXC # [R XX] Hartree-Fock Self-energy and Vxc
EXXRLvcs= 15 Ry # [XX] Exchange RL components
%QPkrange # [GW] QP generalized Kpoint/Band indices
1| 8| 1| 15|
%
%QPerange # [GW] QP generalized Kpoint/Energy indices
1| 8| 0.0|-1.0|
%

setting

<code> EXXRLvcs=15 Ry</code>

Then run in each k-point folder

<code> > yambo -F Inputs/01HF_corrections -J 01HF_corrections</code>

Note that after each run Yambo produces three output file, one starting with <code>r_...</code> , another with <code>l_...</code> and a third one starting with <code>o_...</code>. The first one is a ''report'' of the actual calculation with all the details of the system, input, and results, while the second is a ''log'' with the running time of each process.

The file we are most interested in is the output file, <code>o-01HF_corrections.hf</code>. This file contains several columns. The fourth, labelled with <code>Ehf</code> represents the Hartree-Fock energy. This is the quantity we have to look at.

Use the [[Bash_scripts|parse_gap_hf.sh]] to parse the output files and adapt the gnuplot script provided earlier to print the values by using gnuplot

> cd ../
> ./parse_gap.sh o-01HF_corrections.hf hf_direct_gap_vs_kpoints.dat

[[File:Hf gap vs kpts.png|Direct gap vs k-points]]

= COHSEX without empty bands =

The Hartree-Fock self-energy just described in the previous section, although successful on some molecular systems, miserably fails in extended systems. The reason of this failure lies in the fact that electrons can screen the Coulomb potential, and therefore one electron feels a screened potential instead of the bare one. A common approximation for this screened potential is the so-called Random Phase Approximation:

[[File:gw.png|Hartree Fock]]

where the bare Coulomb potential V('''r''') is replaced by a non-local and frequency dependent one W('''r''','''r'''',ω). Subsequently it is possible to redefine all the perturbation theory in term of this screened potential, and disregarding the additional corrections coming from the vertex part, one obtains the so-called [[GW|GW]] approximation.

However the substantial complexity associated with calculating the non-local, energy dependent Σ=GW operator inspired early efforts to find simplifying approximations as the static COHSEX approximation prosed by Hedin<ref name="hedin"/>. The Coulomb Hole plus Screened Exchange (COHSEX) approximation[[[#march|2]],[[#fardi|3]]] eliminates the summation over empty states for the self energy operator and has the added benefit of being a static operator, a particular simplification for self consistent calculations. With the COHSEX approximation the self-energy is composed of two parts:

[[File:gw_sex.png|Screened Exchange]]

[[File:gw_coh.png|Cuolomb Hole]]

where Wp=W - V.

In order to calculate the COHSEX self-energy with yambo you need first the static screened interaction <code>yambo -X s -k hartree</code>. As for the V('''r''') case, also W('''r''','''r'''',E=0) will depend from the number of '''G'''-vectors, and the '''k'''-grid, but this time also the number of conduction bands <code>BndsRnXs</code> will enter in the screening calculation through the polarization function, see [http://www.yambo-code.org/theory/docs/doc_Xd.php The Interacting response function: Many-Body and TDDFT] section. Notice however that there are not any additional dependence of the self-energy operator from the conduction bands. After you obtained the screened interaction you are ready to build the self-energy operator and solve the corresponding Dyson equation, have a look to the [[GW|Dyson Equation solvers]] in Yambo. In order to get the quasi-particle energies, just do <code>yambo -b -g n -k hartree</code>. After calculation are completed Yambo will produce an output file <code>o.qp</code> which contains the values of the bare and re-normalized energy levels.

== K-points convergence ==

Follow the same strategy of the HF case. Enter each k-point folder and type

> yambo -b -k hartree -g n -p c -F Inputs/02Cohsex

edit the input file and change the values of the fields

EXXRLvcs=7 Ry
%BndsRnXs
1 | 10 | # [Xs] Polarization function bands
%
NGsBlkXs= 1 RL # [Xs] Response block size
#UseEbands # [GW] Force COHSEX to use empty bands
%QPkrange # [GW] QP generalized Kpoint/Band indices
1| 8| 1| 10|
%

leaving the other parameters unchanged. Now, in each k-point folder, run

> yambo -F Inputs/02Cohsex -J Cohsex_HF7Ry_X0Ry-nb10

Adapt the shell script provided earlier to plot the direct gap dependence on the k-points grid

[[File:Cohsex_HF7Ry_X0Ry-nb10_gap_vs_kpoints.png]]

== W size convergence ==

Enter the <code>4x4x4</code> folder and edit the <code>02Cohsex_corrections</code> file changing the field <code>NGsBlkXs=</code>3,6,7 Ry. Run

> yambo -F Inputs/02Cohsex -J Cohsex_HF7Ry_X???Ry-nb10

with <code>???</code>=3,6,7 and 15.

[[File:COHSEX_no_empties_W_size.png]]

== W bands ==

Open your input file and change only the input variable <code>NGsBlkXs=1 Ry</code>. Then change

%BndsRnXs 1 | 20 | # [Xs] Polarization function bands

and run <code>yambo -F Inputs/02Cohsex -J Cohsex_HF7Ry_X1Ry-nb20</code>.
Repeat the calculations using 30 and 40 bands changing <code>nb???</code> in the job string identifier. Finally check how the Chosex Direct and Indirect band gap behave as a function of the number of bands in the screening.

[[File:COHSEX_no_empties_W_bands.png]]

== COHSEX with empty bands ==

While the Screened Exchange(SEX) part of the COHSEX self-energy has a structure similar to the Hartree-Fock exchange term, the Coulomb Hole(COH) acts as static external potential on the electrons. In the COH part the delta function δ('''r'''-'''r'''') comes from the completeness relation:

[[File:completeness.png|Completeness relation]]

Now we avoid the use of this relation in such a way to have a self-energy that depends from the conduction bands too. This can be done uncommenting flags <code>UseEbands</code> and setting the number of bands in the Green's function:

% GbndRnge 1 | 10 | # [GW] G[W] bands range

Repeat the previous calculations with different <code>GbndRnge</code> for instance, 10 20 30 40, and check how the COHSEX direct and indirect band gap behave as a function of the number of bands in the Green's function.

[[File:COHSEX_empties_G_bands.png]]

= GW within the plasmon pole approximation (PPA) =

Even the static COHSEX approximation is very appealing, it was clear from the first calculation that dynamical effects cannot be disregarded in solids. This fact motivated the research for approximated way to deal with a frequency dependent interaction, and one of the first proposal was the so-called Plasmon-Pole Approximation (PPA).

Now we will proceed to the calculation of the silicon band gap in G0W0 within PPA. In each section you will be asked to perform several calculations varying the value of the relevant variables involved. More specifically let's consider a typical Yambo input file to calculate GW corrections in the PPA.

gw0 # [R GW] GoWo Quasiparticle energy levels
ppa # [R Xp] Plasmon Pole Approximation
HF_and_locXC # [R XX] Hartree-Fock Self-energy and Vxc
em1d # [R Xd] Dynamical Inverse Dielectric Matrix
EXXRLvcs= 7 Ry # [XX] Exchange RL components
% QpntsRXp
1 | 8 | # [Xp] Transferred momenta
%
% BndsRnXp
1 | 10 | # [Xp] Polarization function bands
%
NGsBlkXp= 1 RL # [Xp] Response block size
% LongDrXp
1.000000 | 0.000000 | 0.000000 | # [Xp] [cc] Electric Field
%
PPAPntXp= 27.21138 eV # [Xp] PPA imaginary energy
% GbndRnge
1 | 10 | # [GW] G[W] bands range
%
GDamping= 0.10000 eV # [GW] G[W] damping
dScStep= 0.10000 eV # [GW] Energy step to evalute Z factors
DysSolver= n # [GW] Dyson Equation solver (`n`,`s`,`g`)
%QPkrange # [GW] QP generalized Kpoint/Band indices
1| 8| 1| 10|
%
%QPerange # [GW] QP generalized Kpoint/Energy indices
1| 8| 0.0|-1.0|
%

The variables are the same of the COHSEX case plus a new one <code>PPAPntXp</code> that describes the imaginary energy used to fit the Plasmon Pole model. 
Follow the same strategy of the COHSEX case. Enter each k-point folder and type:

> yambo -d -k hartree -g n -p p -F Inputs/03GoWo_PPA_corrections

otherwise you can use the existent file <code>Input/03GoWo_PPA_corrections</code>. Now you have to study the convergence of the G0W0 gap versus the number of k-points, the number of bands in χ <code>BndsRnXs</code>, the size of the dielectric constant <code>NGsBlkXs</code> and the number of bands in the Green's function <code>GbndRnge</code>.

Please follow the same strategy of the COHSEX case running yambo using

> yambo -F Inputs/03GoWo_PPA_corrections -J GoWo_PPA_HF7Ry_X???Ry-nb???_nb???</code>

The final convergence plots should look like these (the plots are done using as a basis the above code).

[[File:PPA W size.png]]

[[File:PPA W bands.png]]

[[File:PPA G bands.png]]

[[File:PPA gap vs kpts.png]]

Final runs!! Now you know how to converge a G0W0 calculation so you can decide which are the parameters needed for full convergence. First do a COHSEX and then a GoWo (PPA) run at convergence, and you should obtain results similar to the following graph:

[[File:Si_gap.png|Final Gap Silicon]]

= References =
<references>
<ref name="gw">H. N. Rojas, R. W. Godby, and R. J. Needs, Phys. Rev. Lett. '''74''', 1827 (1995)</ref>
<ref name="hedin"> L. Hedin, Phys. Rev. '''139''', A796 (1965)</ref>
</references>

Silicon

2022-02-08T12:36:11Z

ElenaCannuccia: /* K-points convergence */

= Basic concepts of the GW approximation =

[[File:GW0.png|x300px|center|]]

In this tutorial you will learn the basic concepts of the [[Hartree-Fock]] and of the GW<ref name="gw"/> approximation. In particular we will illustrate how to calculate [http://en.wikipedia.org/wiki/Quasiparticle Quasi-Particle] energies with a single shot G0W0 approximation. Different lecture notes on the GW approach are available in the [[Lectures|Lectures section]].

The tutorial is split in different sections. In the first part we will deal with Hartree-Fock (HF) and the Coulomb-hole and screened-exchange (COHSEX) approximation. Finally in the last section we will discuss dynamical correlation with a Plasmon Pole Approximation (PPA).

= The material: Silicon =

* [http://cst-www.nrl.navy.mil/lattice/struk/a1.html FCC] lattice
* Two atoms per cell (8 electrons)
* Lattice constant 10.183 [a.u.]
* Plane waves cutoff 15 Rydberg

===Band gap===

*Direct gap 3.4 eV at Gamma
*Indirect gap 1.1 eV betweeb Gamma and X'
*Gamma= (0 0 0)
*X' is a point close to X=(0 1 0)

[[File:si_banddiagram.gif|thumb|x400px|Silicon Band Structure]]

= The Tutorial files =
Follow the instructions in [[Tutorials#Files]] and download/unpack the <code>Silicon.tar.gz</code>.

= The Tutorial structure =

Once the tutorial archive file is unzipped the following folder structure will appear

COPYING README Silicon/

with the Solid_Si folder containing

> ls Silicon/
PWSCF/ YAMBO/

In the Pwscf folder the student will find an input/output directory with input/output files for pw.x. The Silicon pseudopotential file is also provided.

> ls PWSCF/
convergence_scripts input output psps

In the <code>convergence_scripts</code> you will find some useful shell scripts to run the ground state convergence runs for Silicon.

The YAMBO folder contains the Yambo input/output files and core databases.

> ls YAMBO/
2x2x2/ 4x4x4/ 6x6x6/ 8x8x8/ Convergence_Plots_and_Scripts/ GAMMA/

The core databases are provided for several k-points grids. In addition the folder <code>Convergence_Plots_and_Scripts</code> contains some scripts to extract informations from the report files useful for the tutorial.

= Hartree-Fock =

Now we will study the convergence of the [http://en.wikipedia.org/wiki/Hartree%E2%80%93Fock_method Hartree-Fock] self energy, respect to the number of '''G'''-vectors and '''k'''-points. Yambo is a plane-wave code, therefore all the operators and wave-functions are expanded as:

[[File:orbital.png|Orbital in plane wave]]

Before you start any calculations we can decide how many '''G'''-vectors you want use to represent your wave-function. By default Yambo will use all of them, and for the present tutorial this is fine, however if you are studying larger systems you would like to reduce them in order to speed-up calculations, you can do it with <code> yambo -i -V RL</code> and then changing the variable <code>MaxGvecs</code> that referees to Ng in the previous formula.

Now we will proceed in the calculation of the [[Hartree-Fock|Hartree-Fock]] exchange. This is composed of two terms, that Hartree and the Fock (or exchange) one:

[[File:hf.png|Hartree Fock]]

In this tutorial we will calculate only the first order correction to the Kohn-Sham Hamiltonian due to the exchange term. Because of we are working in periodic system, the most appropriate basis to represent the Coulomb potential, appearing in the Fock term, is a plane-wave basis:

[[File:v_q_plus_G.png|Coulomb potential in plane wave]]

In order to generate the input file for the exchange type <code>yambo -x</code>. The variable that governs the number of '''G''' vectors Nex in the Coulomb potential is <code>EXXRLvcs</code>. In addition notice that in the previous formula for V('''r'''-'''r'''') we have an integral on the '''q''' vector, that in the code is discretized on a regular '''q'''-grid generated from the '''k'''-point one, '''q'''='''k'''-'''k''''.

== G-vectors convergence ==

Enter the <code>4x4x4</code> folder

> cd 4x4x4

Now edit the <code>01HF_corrections</code> file changing the field <code>EXXRLvcs=</code>3,6,7 and 15 Ry. For each case run

> yambo -F Inputs/01HF_corrections -J HF_???Ry

with <code>???</code>=3,6,7 and 15

Now plot the HF corrections by using the [[Gnuplot_scripts|hf_vs_cutoff.gnuplot]] script. Launch it via

> gnuplot
gnuplot>load "hf_vs_cutoff.gnuplot"

[[File:HF_parameters.png|Hartree-Fock corrections versus energy cutoff]]

== K-points convergence==

Enter each grid folder (<code>GAMMA,2x2x2,4x4x4,...</code>) and run
> yambo
without options. Then type

> yambo -x -F Inputs/01HF_corrections -J 01HF_corrections

and edit the 01HF_corrections file

HF_and_locXC # [R XX] Hartree-Fock Self-energy and Vxc
EXXRLvcs= 15 Ry # [XX] Exchange RL components
%QPkrange # [GW] QP generalized Kpoint/Band indices
1| 8| 1| 15|
%
%QPerange # [GW] QP generalized Kpoint/Energy indices
1| 8| 0.0|-1.0|
%

setting

<code> EXXRLvcs=15 Ry</code>

Then run in each k-point folder

<code> > yambo -F Inputs/01HF_corrections -J 01HF_corrections</code>

Note that after each run Yambo produces three output file, one starting with <code>r_...</code> , another with <code>l_...</code> and a third one starting with <code>o_...</code>. The first one is a ''report'' of the actual calculation with all the details of the system, input, and results, while the second is a ''log'' with the running time of each process.

The file we are most interested in is the output file, <code>o-01HF_corrections.hf</code>. This file contains several columns. The fourth, labelled with <code>Ehf</code> represents the Hartree-Fock energy. This is the quantity we have to look at.

Use the [[Bash_scripts|parse_gap_hf.sh]] to parse the output files and adapt the gnuplot script provided earlier to print the values by using gnuplot

> cd ../
> ./parse_gap.sh o-01HF_corrections.hf hf_direct_gap_vs_kpoints.dat

[[File:Hf gap vs kpts.png|Direct gap vs k-points]]

= COHSEX without empty bands =

The Hartree-Fock self-energy just described in the previous section, although successful on some molecular systems, miserably fails in extended systems. The reason of this failure lies in the fact that electrons can screen the Coulomb potential, and therefore one electron feels a screened potential instead of the bare one. A common approximation for this screened potential is the so-called Random Phase Approximation:

[[File:gw.png|Hartree Fock]]

where the bare Coulomb potential V('''r''') is replaced by a non-local and frequency dependent one W('''r''','''r'''',ω). Subsequently it is possible to redefine all the perturbation theory in term of this screened potential, and disregarding the additional corrections coming from the vertex part, one obtains the so-called [[GW|GW]] approximation.

However the substantial complexity associated with calculating the non-local, energy dependent Σ=GW operator inspired early efforts to find simplifying approximations as the static COHSEX approximation prosed by Hedin<ref name="hedin"/>. The Coulomb Hole plus Screened Exchange (COHSEX) approximation[[[#march|2]],[[#fardi|3]]] eliminates the summation over empty states for the self energy operator and has the added benefit of being a static operator, a particular simplification for self consistent calculations. With the COHSEX approximation the self-energy is composed of two parts:

[[File:gw_sex.png|Screened Exchange]]

[[File:gw_coh.png|Cuolomb Hole]]

where Wp=W - V.

In order to calculate the COHSEX self-energy with yambo you need first the static screened interaction <code>yambo -X s -k hartree</code>. As for the V('''r''') case, also W('''r''','''r'''',E=0) will depend from the number of '''G'''-vectors, and the '''k'''-grid, but this time also the number of conduction bands <code>BndsRnXs</code> will enter in the screening calculation through the polarization function, see [http://www.yambo-code.org/theory/docs/doc_Xd.php The Interacting response function: Many-Body and TDDFT] section. Notice however that there are not any additional dependence of the self-energy operator from the conduction bands. After you obtained the screened interaction you are ready to build the self-energy operator and solve the corresponding Dyson equation, have a look to the [[GW|Dyson Equation solvers]] in Yambo. In order to get the quasi-particle energies, just do <code>yambo -b -g n -k hartree</code>. After calculation are completed Yambo will produce an output file <code>o.qp</code> which contains the values of the bare and re-normalized energy levels.

== K-points convergence ==

Follow the same strategy of the HF case. Enter each k-point folder and type

> yambo -b -k hartree -g n -p c -F Inputs/02Cohsex

edit the input file and change the values of the fields

EXXRLvcs=7 Ry
%BndsRnXs
1 | 10 | # [Xs] Polarization function bands
%
NGsBlkXs= 1 RL # [Xs] Response block size
#UseEbands # [GW] Force COHSEX to use empty bands
%QPkrange # [GW] QP generalized Kpoint/Band indices
1| 8| 1| 10|
%

leaving the other parameters unchanged. Now, in each k-point folder, run

> yambo -F Inputs/02Cohsex -J Cohsex_HF7Ry_X0Ry-nb10

Adapt the shell script provided earlier to plot the direct gap dependence on the k-points grid

[[File:Cohsex_HF7Ry_X0Ry-nb10_gap_vs_kpoints.png]]

== W size convergence ==

Enter the <code>4x4x4</code> folder and edit the <code>02Cohsex_corrections</code> file changing the field <code>NGsBlkXs=</code>3,6,7 Ry. Run

> yambo -F Inputs/02Cohsex -J Cohsex_HF7Ry_X???Ry-nb10

with <code>???</code>=3,6,7 and 15.

[[File:COHSEX_no_empties_W_size.png]]

== W bands ==

Open your input file and change only the input variable <code>NGsBlkXs=1 Ry</code>. Then change

%BndsRnXs 1 | 20 | # [Xs] Polarization function bands

and run <code>yambo -F Inputs/02Cohsex -J Cohsex_HF7Ry_X1Ry-nb20</code>.
Repeat the calculations using 30 and 40 bands changing <code>nb???</code> in the job string identifier. Finally check how the Chosex Direct and Indirect band gap behave as a function of the number of bands in the screening.

[[File:COHSEX_no_empties_W_bands.png]]

== COHSEX with empty bands ==

While the Screened Exchange(SEX) part of the COHSEX self-energy has a structure similar to the Hartree-Fock exchange term, the Coulomb Hole(COH) acts as static external potential on the electrons. In the COH part the delta function δ('''r'''-'''r'''') comes from the completeness relation:

[[File:completeness.png|Completeness relation]]

Now we avoid the use of this relation in such a way to have a self-energy that depends from the conduction bands too. This can be done uncommenting flags <code>UseEbands</code> and setting the number of bands in the Green's function:

% GbndRnge 1 | 10 | # [GW] G[W] bands range

Repeat the previous calculations with different <code>GbndRnge</code> for instance, 10 20 30 40, and check how the COHSEX direct and indirect band gap behave as a function of the number of bands in the Green's function.

[[File:COHSEX_empties_G_bands.png]]

= GW within the plasmon pole approximation (PPA) =

Even the static COHSEX approximation is very appealing, it was clear from the first calculation that dynamical effects cannot be disregarded in solids. This fact motivated the research for approximated way to deal with a frequency dependent interaction, and one of the first proposal was the so-called Plasmon-Pole Approximation (PPA).

Now we will proceed to the calculation of the silicon band gap in G0W0 within PPA. In each section you will be asked to perform several calculations varying the value of the relevant variables involved. More specifically let's consider a typical Yambo input file to calculate GW corrections in the PPA.

gw0 # [R GW] GoWo Quasiparticle energy levels
ppa # [R Xp] Plasmon Pole Approximation
HF_and_locXC # [R XX] Hartree-Fock Self-energy and Vxc
em1d # [R Xd] Dynamical Inverse Dielectric Matrix
EXXRLvcs= 7 Ry # [XX] Exchange RL components
% QpntsRXp
1 | 8 | # [Xp] Transferred momenta
%
% BndsRnXp
1 | 10 | # [Xp] Polarization function bands
%
NGsBlkXp= 1 RL # [Xp] Response block size
% LongDrXp
1.000000 | 0.000000 | 0.000000 | # [Xp] [cc] Electric Field
%
PPAPntXp= 27.21138 eV # [Xp] PPA imaginary energy
% GbndRnge
1 | 10 | # [GW] G[W] bands range
%
GDamping= 0.10000 eV # [GW] G[W] damping
dScStep= 0.10000 eV # [GW] Energy step to evalute Z factors
DysSolver= n # [GW] Dyson Equation solver (`n`,`s`,`g`)
%QPkrange # [GW] QP generalized Kpoint/Band indices
1| 8| 1| 10|
%
%QPerange # [GW] QP generalized Kpoint/Energy indices
1| 8| 0.0|-1.0|
%

The variables are the same of the COHSEX case plus a new one <code>PPAPntXp</code> that describes the imaginary energy used to fit the Plasmon Pole model. 
Follow the same strategy of the COHSEX case. Enter each k-point folder and type:

> yambo -d -k hartree -g n -p p -F Inputs/03GoWo_PPA_corrections

otherwise you can use the existent file <code>Input/03GoWo_PPA_corrections</code>. Now you have to study the convergence of the G0W0 gap versus the number of k-points, the number of bands in χ <code>BndsRnXs</code>, the size of the dielectric constant <code>NGsBlkXs</code> and the number of bands in the Green's function <code>GbndRnge</code>.

Please follow the same strategy of the COHSEX case running yambo using

> yambo -F Inputs/03GoWo_PPA_corrections -J GoWo_PPA_HF7Ry_X???Ry-nb???_nb???</code>

The final convergence plots should look like these (the plots are done using as a basis the above code).

[[File:PPA W size.png]]

[[File:PPA W bands.png]]

[[File:PPA G bands.png]]

[[File:PPA gap vs kpts.png]]

Final runs!! Now you know how to converge a G0W0 calculation so you can decide which are the parameters needed for full convergence. First do a COHSEX and then a GoWo (PPA) run at convergence, and you should obtain results similar to the following graph:

[[File:Si_gap.png|Final Gap Silicon]]

= References =
<references>
<ref name="gw">H. N. Rojas, R. W. Godby, and R. J. Needs, Phys. Rev. Lett. '''74''', 1827 (1995)</ref>
<ref name="hedin"> L. Hedin, Phys. Rev. '''139''', A796 (1965)</ref>
</references>

Silicon

2022-02-08T10:50:03Z

ElenaCannuccia: /* COHSEX without empty bands */

= Basic concepts of the GW approximation =

[[File:GW0.png|x300px|center|]]

In this tutorial you will learn the basic concepts of the [[Hartree-Fock]] and of the GW<ref name="gw"/> approximation. In particular we will illustrate how to calculate [http://en.wikipedia.org/wiki/Quasiparticle Quasi-Particle] energies with a single shot G0W0 approximation. Different lecture notes on the GW approach are available in the [[Lectures|Lectures section]].

The tutorial is split in different sections. In the first part we will deal with Hartree-Fock (HF) and the Coulomb-hole and screened-exchange (COHSEX) approximation. Finally in the last section we will discuss dynamical correlation with a Plasmon Pole Approximation (PPA).

= The material: Silicon =

* [http://cst-www.nrl.navy.mil/lattice/struk/a1.html FCC] lattice
* Two atoms per cell (8 electrons)
* Lattice constant 10.183 [a.u.]
* Plane waves cutoff 15 Rydberg

===Band gap===

*Direct gap 3.4 eV at Gamma
*Indirect gap 1.1 eV betweeb Gamma and X'
*Gamma= (0 0 0)
*X' is a point close to X=(0 1 0)

[[File:si_banddiagram.gif|thumb|x400px|Silicon Band Structure]]

= The Tutorial files =
Follow the instructions in [[Tutorials#Files]] and download/unpack the <code>Silicon.tar.gz</code>.

= The Tutorial structure =

Once the tutorial archive file is unzipped the following folder structure will appear

COPYING README Silicon/

with the Solid_Si folder containing

> ls Silicon/
PWSCF/ YAMBO/

In the Pwscf folder the student will find an input/output directory with input/output files for pw.x. The Silicon pseudopotential file is also provided.

> ls PWSCF/
convergence_scripts input output psps

In the <code>convergence_scripts</code> you will find some useful shell scripts to run the ground state convergence runs for Silicon.

The YAMBO folder contains the Yambo input/output files and core databases.

> ls YAMBO/
2x2x2/ 4x4x4/ 6x6x6/ 8x8x8/ Convergence_Plots_and_Scripts/ GAMMA/

The core databases are provided for several k-points grids. In addition the folder <code>Convergence_Plots_and_Scripts</code> contains some scripts to extract informations from the report files useful for the tutorial.

= Hartree-Fock =

Now we will study the convergence of the [http://en.wikipedia.org/wiki/Hartree%E2%80%93Fock_method Hartree-Fock] self energy, respect to the number of '''G'''-vectors and '''k'''-points. Yambo is a plane-wave code, therefore all the operators and wave-functions are expanded as:

[[File:orbital.png|Orbital in plane wave]]

Before you start any calculations we can decide how many '''G'''-vectors you want use to represent your wave-function. By default Yambo will use all of them, and for the present tutorial this is fine, however if you are studying larger systems you would like to reduce them in order to speed-up calculations, you can do it with <code> yambo -i -V RL</code> and then changing the variable <code>MaxGvecs</code> that referees to Ng in the previous formula.

Now we will proceed in the calculation of the [[Hartree-Fock|Hartree-Fock]] exchange. This is composed of two terms, that Hartree and the Fock (or exchange) one:

[[File:hf.png|Hartree Fock]]

In this tutorial we will calculate only the first order correction to the Kohn-Sham Hamiltonian due to the exchange term. Because of we are working in periodic system, the most appropriate basis to represent the Coulomb potential, appearing in the Fock term, is a plane-wave basis:

[[File:v_q_plus_G.png|Coulomb potential in plane wave]]

In order to generate the input file for the exchange type <code>yambo -x</code>. The variable that governs the number of '''G''' vectors Nex in the Coulomb potential is <code>EXXRLvcs</code>. In addition notice that in the previous formula for V('''r'''-'''r'''') we have an integral on the '''q''' vector, that in the code is discretized on a regular '''q'''-grid generated from the '''k'''-point one, '''q'''='''k'''-'''k''''.

== G-vectors convergence ==

Enter the <code>4x4x4</code> folder

> cd 4x4x4

Now edit the <code>01HF_corrections</code> file changing the field <code>EXXRLvcs=</code>3,6,7 and 15 Ry. For each case run

> yambo -F Inputs/01HF_corrections -J HF_???Ry

with <code>???</code>=3,6,7 and 15

Now plot the HF corrections by using the [[Gnuplot_scripts|hf_vs_cutoff.gnuplot]] script. Launch it via

> gnuplot
gnuplot>load "hf_vs_cutoff.gnuplot"

[[File:HF_parameters.png|Hartree-Fock corrections versus energy cutoff]]

== K-points convergence==

Enter each grid folder (<code>GAMMA,2x2x2,4x4x4,...</code>) and run
> yambo
without options. Then type

> yambo -x -F Inputs/01HF_corrections -J 01HF_corrections

and edit the 01HF_corrections file

HF_and_locXC # [R XX] Hartree-Fock Self-energy and Vxc
EXXRLvcs= 15 Ry # [XX] Exchange RL components
%QPkrange # [GW] QP generalized Kpoint/Band indices
1| 8| 1| 15|
%
%QPerange # [GW] QP generalized Kpoint/Energy indices
1| 8| 0.0|-1.0|
%

setting

<code> EXXRLvcs=15 Ry</code>

Then run in each k-point folder

<code> > yambo -F Inputs/01HF_corrections -J 01HF_corrections</code>

Note that after each run Yambo produces three output file, one starting with <code>r_...</code> , another with <code>l_...</code> and a third one starting with <code>o_...</code>. The first one is a ''report'' of the actual calculation with all the details of the system, input, and results, while the second is a ''log'' with the running time of each process.

The file we are most interested in is the output file, <code>o-01HF_corrections.hf</code>. This file contains several columns. The fourth, labelled with <code>Ehf</code> represents the Hartree-Fock energy. This is the quantity we have to look at.

Use the [[Bash_scripts|parse_gap_hf.sh]] to parse the output files and adapt the gnuplot script provided earlier to print the values by using gnuplot

> cd ../
> ./parse_gap.sh o-01HF_corrections.hf hf_direct_gap_vs_kpoints.dat

[[File:Hf gap vs kpts.png|Direct gap vs k-points]]

= COHSEX without empty bands =

The Hartree-Fock self-energy just described in the previous section, although successful on some molecular systems, miserably fails in extended systems. The reason of this failure lies in the fact that electrons can screen the Coulomb potential, and therefore one electron feels a screened potential instead of the bare one. A common approximation for this screened potential is the so-called Random Phase Approximation:

[[File:gw.png|Hartree Fock]]

where the bare Coulomb potential V('''r''') is replaced by a non-local and frequency dependent one W('''r''','''r'''',ω). Subsequently it is possible to redefine all the perturbation theory in term of this screened potential, and disregarding the additional corrections coming from the vertex part, one obtains the so-called [[GW|GW]] approximation.

However the substantial complexity associated with calculating the non-local, energy dependent Σ=GW operator inspired early efforts to find simplifying approximations as the static COHSEX approximation prosed by Hedin<ref name="hedin"/>. The Coulomb Hole plus Screened Exchange (COHSEX) approximation[[[#march|2]],[[#fardi|3]]] eliminates the summation over empty states for the self energy operator and has the added benefit of being a static operator, a particular simplification for self consistent calculations. With the COHSEX approximation the self-energy is composed of two parts:

[[File:gw_sex.png|Screened Exchange]]

[[File:gw_coh.png|Cuolomb Hole]]

where Wp=W - V.

In order to calculate the COHSEX self-energy with yambo you need first the static screened interaction <code>yambo -X s -k hartree</code>. As for the V('''r''') case, also W('''r''','''r'''',E=0) will depend from the number of '''G'''-vectors, and the '''k'''-grid, but this time also the number of conduction bands <code>BndsRnXs</code> will enter in the screening calculation through the polarization function, see [http://www.yambo-code.org/theory/docs/doc_Xd.php The Interacting response function: Many-Body and TDDFT] section. Notice however that there are not any additional dependence of the self-energy operator from the conduction bands. After you obtained the screened interaction you are ready to build the self-energy operator and solve the corresponding Dyson equation, have a look to the [[GW|Dyson Equation solvers]] in Yambo. In order to get the quasi-particle energies, just do <code>yambo -b -g n -k hartree</code>. After calculation are completed Yambo will produce an output file <code>o.qp</code> which contains the values of the bare and re-normalized energy levels.

== K-points convergence ==

Follow the same strategy of the HF case. Enter each k-point folder and type

> yambo -b -k hartree -g n -p c -F Inputs/02Cohsex

edit the input file and change the values of the fields

EXXRLvcs=7 Ry %BndsRnXs 1 | 10 | # [Xs] Polarization function bands
NGsBlkXs= 1 RL # [Xs] Response block size
#UseEbands # [GW] Force COHSEX to use empty bands
%QPkrange # [GW] QP generalized Kpoint/Band indices
1| 8| 1| 10|
%

leaving the other parameters unchanged. Now, in each k-point folder, run

> yambo -F Inputs/02Cohsex -J Cohsex_HF7Ry_X0Ry-nb10

Adapt the shell script provided earlier to plot the direct gap dependence on the k-points grid

[[File:Cohsex_HF7Ry_X0Ry-nb10_gap_vs_kpoints.png]]

== W size convergence ==

Enter the <code>4x4x4</code> folder and edit the <code>02Cohsex_corrections</code> file changing the field <code>NGsBlkXs=</code>3,6,7 Ry. Run

> yambo -F Inputs/02Cohsex -J Cohsex_HF7Ry_X???Ry-nb10

with <code>???</code>=3,6,7 and 15.

[[File:COHSEX_no_empties_W_size.png]]

== W bands ==

Open your input file and change only the input variable <code>NGsBlkXs=1 Ry</code>. Then change

%BndsRnXs 1 | 20 | # [Xs] Polarization function bands

and run <code>yambo -F Inputs/02Cohsex -J Cohsex_HF7Ry_X1Ry-nb20</code>.
Repeat the calculations using 30 and 40 bands changing <code>nb???</code> in the job string identifier. Finally check how the Chosex Direct and Indirect band gap behave as a function of the number of bands in the screening.

[[File:COHSEX_no_empties_W_bands.png]]

== COHSEX with empty bands ==

While the Screened Exchange(SEX) part of the COHSEX self-energy has a structure similar to the Hartree-Fock exchange term, the Coulomb Hole(COH) acts as static external potential on the electrons. In the COH part the delta function δ('''r'''-'''r'''') comes from the completeness relation:

[[File:completeness.png|Completeness relation]]

Now we avoid the use of this relation in such a way to have a self-energy that depends from the conduction bands too. This can be done uncommenting flags <code>UseEbands</code> and setting the number of bands in the Green's function:

% GbndRnge 1 | 10 | # [GW] G[W] bands range

Repeat the previous calculations with different <code>GbndRnge</code> for instance, 10 20 30 40, and check how the COHSEX direct and indirect band gap behave as a function of the number of bands in the Green's function.

[[File:COHSEX_empties_G_bands.png]]

= GW within the plasmon pole approximation (PPA) =

Even the static COHSEX approximation is very appealing, it was clear from the first calculation that dynamical effects cannot be disregarded in solids. This fact motivated the research for approximated way to deal with a frequency dependent interaction, and one of the first proposal was the so-called Plasmon-Pole Approximation (PPA).

Now we will proceed to the calculation of the silicon band gap in G0W0 within PPA. In each section you will be asked to perform several calculations varying the value of the relevant variables involved. More specifically let's consider a typical Yambo input file to calculate GW corrections in the PPA.

gw0 # [R GW] GoWo Quasiparticle energy levels
ppa # [R Xp] Plasmon Pole Approximation
HF_and_locXC # [R XX] Hartree-Fock Self-energy and Vxc
em1d # [R Xd] Dynamical Inverse Dielectric Matrix
EXXRLvcs= 7 Ry # [XX] Exchange RL components
% QpntsRXp
1 | 8 | # [Xp] Transferred momenta
%
% BndsRnXp
1 | 10 | # [Xp] Polarization function bands
%
NGsBlkXp= 1 RL # [Xp] Response block size
% LongDrXp
1.000000 | 0.000000 | 0.000000 | # [Xp] [cc] Electric Field
%
PPAPntXp= 27.21138 eV # [Xp] PPA imaginary energy
% GbndRnge
1 | 10 | # [GW] G[W] bands range
%
GDamping= 0.10000 eV # [GW] G[W] damping
dScStep= 0.10000 eV # [GW] Energy step to evalute Z factors
DysSolver= n # [GW] Dyson Equation solver (`n`,`s`,`g`)
%QPkrange # [GW] QP generalized Kpoint/Band indices
1| 8| 1| 10|
%
%QPerange # [GW] QP generalized Kpoint/Energy indices
1| 8| 0.0|-1.0|
%

The variables are the same of the COHSEX case plus a new one <code>PPAPntXp</code> that describes the imaginary energy used to fit the Plasmon Pole model. 
Follow the same strategy of the COHSEX case. Enter each k-point folder and type:

> yambo -d -k hartree -g n -p p -F Inputs/03GoWo_PPA_corrections

otherwise you can use the existent file <code>Input/03GoWo_PPA_corrections</code>. Now you have to study the convergence of the G0W0 gap versus the number of k-points, the number of bands in χ <code>BndsRnXs</code>, the size of the dielectric constant <code>NGsBlkXs</code> and the number of bands in the Green's function <code>GbndRnge</code>.

Please follow the same strategy of the COHSEX case running yambo using

> yambo -F Inputs/03GoWo_PPA_corrections -J GoWo_PPA_HF7Ry_X???Ry-nb???_nb???</code>

The final convergence plots should look like these (the plots are done using as a basis the above code).

[[File:PPA W size.png]]

[[File:PPA W bands.png]]

[[File:PPA G bands.png]]

[[File:PPA gap vs kpts.png]]

Final runs!! Now you know how to converge a G0W0 calculation so you can decide which are the parameters needed for full convergence. First do a COHSEX and then a GoWo (PPA) run at convergence, and you should obtain results similar to the following graph:

[[File:Si_gap.png|Final Gap Silicon]]

= References =
<references>
<ref name="gw">H. N. Rojas, R. W. Godby, and R. J. Needs, Phys. Rev. Lett. '''74''', 1827 (1995)</ref>
<ref name="hedin"> L. Hedin, Phys. Rev. '''139''', A796 (1965)</ref>
</references>

Silicon

2022-02-08T10:48:51Z

ElenaCannuccia: /* K-points convergence */

= Basic concepts of the GW approximation =

[[File:GW0.png|x300px|center|]]

In this tutorial you will learn the basic concepts of the [[Hartree-Fock]] and of the GW<ref name="gw"/> approximation. In particular we will illustrate how to calculate [http://en.wikipedia.org/wiki/Quasiparticle Quasi-Particle] energies with a single shot G0W0 approximation. Different lecture notes on the GW approach are available in the [[Lectures|Lectures section]].

The tutorial is split in different sections. In the first part we will deal with Hartree-Fock (HF) and the Coulomb-hole and screened-exchange (COHSEX) approximation. Finally in the last section we will discuss dynamical correlation with a Plasmon Pole Approximation (PPA).

= The material: Silicon =

* [http://cst-www.nrl.navy.mil/lattice/struk/a1.html FCC] lattice
* Two atoms per cell (8 electrons)
* Lattice constant 10.183 [a.u.]
* Plane waves cutoff 15 Rydberg

===Band gap===

*Direct gap 3.4 eV at Gamma
*Indirect gap 1.1 eV betweeb Gamma and X'
*Gamma= (0 0 0)
*X' is a point close to X=(0 1 0)

[[File:si_banddiagram.gif|thumb|x400px|Silicon Band Structure]]

= The Tutorial files =
Follow the instructions in [[Tutorials#Files]] and download/unpack the <code>Silicon.tar.gz</code>.

= The Tutorial structure =

Once the tutorial archive file is unzipped the following folder structure will appear

COPYING README Silicon/

with the Solid_Si folder containing

> ls Silicon/
PWSCF/ YAMBO/

In the Pwscf folder the student will find an input/output directory with input/output files for pw.x. The Silicon pseudopotential file is also provided.

> ls PWSCF/
convergence_scripts input output psps

In the <code>convergence_scripts</code> you will find some useful shell scripts to run the ground state convergence runs for Silicon.

The YAMBO folder contains the Yambo input/output files and core databases.

> ls YAMBO/
2x2x2/ 4x4x4/ 6x6x6/ 8x8x8/ Convergence_Plots_and_Scripts/ GAMMA/

The core databases are provided for several k-points grids. In addition the folder <code>Convergence_Plots_and_Scripts</code> contains some scripts to extract informations from the report files useful for the tutorial.

= Hartree-Fock =

Now we will study the convergence of the [http://en.wikipedia.org/wiki/Hartree%E2%80%93Fock_method Hartree-Fock] self energy, respect to the number of '''G'''-vectors and '''k'''-points. Yambo is a plane-wave code, therefore all the operators and wave-functions are expanded as:

[[File:orbital.png|Orbital in plane wave]]

Before you start any calculations we can decide how many '''G'''-vectors you want use to represent your wave-function. By default Yambo will use all of them, and for the present tutorial this is fine, however if you are studying larger systems you would like to reduce them in order to speed-up calculations, you can do it with <code> yambo -i -V RL</code> and then changing the variable <code>MaxGvecs</code> that referees to Ng in the previous formula.

Now we will proceed in the calculation of the [[Hartree-Fock|Hartree-Fock]] exchange. This is composed of two terms, that Hartree and the Fock (or exchange) one:

[[File:hf.png|Hartree Fock]]

In this tutorial we will calculate only the first order correction to the Kohn-Sham Hamiltonian due to the exchange term. Because of we are working in periodic system, the most appropriate basis to represent the Coulomb potential, appearing in the Fock term, is a plane-wave basis:

[[File:v_q_plus_G.png|Coulomb potential in plane wave]]

In order to generate the input file for the exchange type <code>yambo -x</code>. The variable that governs the number of '''G''' vectors Nex in the Coulomb potential is <code>EXXRLvcs</code>. In addition notice that in the previous formula for V('''r'''-'''r'''') we have an integral on the '''q''' vector, that in the code is discretized on a regular '''q'''-grid generated from the '''k'''-point one, '''q'''='''k'''-'''k''''.

== G-vectors convergence ==

Enter the <code>4x4x4</code> folder

> cd 4x4x4

Now edit the <code>01HF_corrections</code> file changing the field <code>EXXRLvcs=</code>3,6,7 and 15 Ry. For each case run

> yambo -F Inputs/01HF_corrections -J HF_???Ry

with <code>???</code>=3,6,7 and 15

Now plot the HF corrections by using the [[Gnuplot_scripts|hf_vs_cutoff.gnuplot]] script. Launch it via

> gnuplot
gnuplot>load "hf_vs_cutoff.gnuplot"

[[File:HF_parameters.png|Hartree-Fock corrections versus energy cutoff]]

== K-points convergence==

Enter each grid folder (<code>GAMMA,2x2x2,4x4x4,...</code>) and run
> yambo
without options. Then type

> yambo -x -F Inputs/01HF_corrections -J 01HF_corrections

and edit the 01HF_corrections file

HF_and_locXC # [R XX] Hartree-Fock Self-energy and Vxc
EXXRLvcs= 15 Ry # [XX] Exchange RL components
%QPkrange # [GW] QP generalized Kpoint/Band indices
1| 8| 1| 15|
%
%QPerange # [GW] QP generalized Kpoint/Energy indices
1| 8| 0.0|-1.0|
%

setting

<code> EXXRLvcs=15 Ry</code>

Then run in each k-point folder

<code> > yambo -F Inputs/01HF_corrections -J 01HF_corrections</code>

Note that after each run Yambo produces three output file, one starting with <code>r_...</code> , another with <code>l_...</code> and a third one starting with <code>o_...</code>. The first one is a ''report'' of the actual calculation with all the details of the system, input, and results, while the second is a ''log'' with the running time of each process.

The file we are most interested in is the output file, <code>o-01HF_corrections.hf</code>. This file contains several columns. The fourth, labelled with <code>Ehf</code> represents the Hartree-Fock energy. This is the quantity we have to look at.

Use the [[Bash_scripts|parse_gap_hf.sh]] to parse the output files and adapt the gnuplot script provided earlier to print the values by using gnuplot

> cd ../
> ./parse_gap.sh o-01HF_corrections.hf hf_direct_gap_vs_kpoints.dat

[[File:Hf gap vs kpts.png|Direct gap vs k-points]]

= COHSEX without empty bands =

The Hartree-Fock self-energy just described in the previous section, although successful on some molecular systems, miserably fails in extended systems. The reason of this failure lies in the fact that electrons can screen the Coulomb potential, and therefore one electron feels a screened potential instead of the bare one. A common approximation for this screened potential is the so-called Random Phase Approximation:

[[File:gw.png|Hartree Fock]]

where the bare Coulomb potential V('''r''') is replaced by a non-local and frequency dependent one W('''r''','''r'''',ω). Subsequently it is possible to redefine all the perturbation theory in term of this screened potential, and disregarding the additional corrections coming from the vertex part, one obtains the so-called [[GW|GW]] approximation.

However the substantial complexity associated with calculating the non-local, energy dependent Σ=GW operator inspired early efforts to find simplifying approximations as the static COHSEX approximation prosed by Hedin<ref name="hedin"/>. The Coulomb Hole plus Screened Exchange (COHSEX) approximation[[[#march|2]],[[#fardi|3]]] eliminates the summation over empty states for the self energy operator and has the added benefit of being a static operator, a particular simplification for self consistent calculations. With the COHSEX approximation the self-energy is composed of two parts:

[[File:gw_sex.png|Screened Exchange]]

[[File:gw_coh.png|Cuolomb Hole]]

where Wp=W - V.

In order to calculate the COHSEX self-energy with yambo you need first the static screened interaction <code>yambo -X s -k hartree</code>. As for the V('''r''') case, also W('''r''','''r'''',E=0) will depend from the number of '''G'''-vectors, and the '''k'''-grid, but this time also the number of conduction bands <code>XsBndsRn</code> will enter in the screening calculation through the polarization function, see [http://www.yambo-code.org/theory/docs/doc_Xd.php The Interacting response function: Many-Body and TDDFT] section. Notice however that there are not any additional dependence of the self-energy operator from the conduction bands. After you obtained the screened interaction you are ready to build the self-energy operator and solve the corresponding Dyson equation, have a look to the [[GW|Dyson Equation solvers]] in Yambo. In order to get the quasi-particle energies, just do <code>yambo -b -g n -k hartree</code>. After calculation are completed Yambo will produce an output file <code>o.qp</code> which contains the values of the bare and re-normalized energy levels.

== K-points convergence ==

Follow the same strategy of the HF case. Enter each k-point folder and type

> yambo -b -k hartree -g n -p c -F Inputs/02Cohsex

edit the input file and change the values of the fields

EXXRLvcs=7 Ry %BndsRnXs 1 | 10 | # [Xs] Polarization function bands
NGsBlkXs= 1 RL # [Xs] Response block size
#UseEbands # [GW] Force COHSEX to use empty bands
%QPkrange # [GW] QP generalized Kpoint/Band indices
1| 8| 1| 10|
%

leaving the other parameters unchanged. Now, in each k-point folder, run

> yambo -F Inputs/02Cohsex -J Cohsex_HF7Ry_X0Ry-nb10

Adapt the shell script provided earlier to plot the direct gap dependence on the k-points grid

[[File:Cohsex_HF7Ry_X0Ry-nb10_gap_vs_kpoints.png]]

== W size convergence ==

Enter the <code>4x4x4</code> folder and edit the <code>02Cohsex_corrections</code> file changing the field <code>NGsBlkXs=</code>3,6,7 Ry. Run

> yambo -F Inputs/02Cohsex -J Cohsex_HF7Ry_X???Ry-nb10

with <code>???</code>=3,6,7 and 15.

[[File:COHSEX_no_empties_W_size.png]]

== W bands ==

Open your input file and change only the input variable <code>NGsBlkXs=1 Ry</code>. Then change

%BndsRnXs 1 | 20 | # [Xs] Polarization function bands

and run <code>yambo -F Inputs/02Cohsex -J Cohsex_HF7Ry_X1Ry-nb20</code>.
Repeat the calculations using 30 and 40 bands changing <code>nb???</code> in the job string identifier. Finally check how the Chosex Direct and Indirect band gap behave as a function of the number of bands in the screening.

[[File:COHSEX_no_empties_W_bands.png]]

== COHSEX with empty bands ==

While the Screened Exchange(SEX) part of the COHSEX self-energy has a structure similar to the Hartree-Fock exchange term, the Coulomb Hole(COH) acts as static external potential on the electrons. In the COH part the delta function δ('''r'''-'''r'''') comes from the completeness relation:

[[File:completeness.png|Completeness relation]]

Now we avoid the use of this relation in such a way to have a self-energy that depends from the conduction bands too. This can be done uncommenting flags <code>UseEbands</code> and setting the number of bands in the Green's function:

% GbndRnge 1 | 10 | # [GW] G[W] bands range

Repeat the previous calculations with different <code>GbndRnge</code> for instance, 10 20 30 40, and check how the COHSEX direct and indirect band gap behave as a function of the number of bands in the Green's function.

[[File:COHSEX_empties_G_bands.png]]

= GW within the plasmon pole approximation (PPA) =

Even the static COHSEX approximation is very appealing, it was clear from the first calculation that dynamical effects cannot be disregarded in solids. This fact motivated the research for approximated way to deal with a frequency dependent interaction, and one of the first proposal was the so-called Plasmon-Pole Approximation (PPA).

Now we will proceed to the calculation of the silicon band gap in G0W0 within PPA. In each section you will be asked to perform several calculations varying the value of the relevant variables involved. More specifically let's consider a typical Yambo input file to calculate GW corrections in the PPA.

gw0 # [R GW] GoWo Quasiparticle energy levels
ppa # [R Xp] Plasmon Pole Approximation
HF_and_locXC # [R XX] Hartree-Fock Self-energy and Vxc
em1d # [R Xd] Dynamical Inverse Dielectric Matrix
EXXRLvcs= 7 Ry # [XX] Exchange RL components
% QpntsRXp
1 | 8 | # [Xp] Transferred momenta
%
% BndsRnXp
1 | 10 | # [Xp] Polarization function bands
%
NGsBlkXp= 1 RL # [Xp] Response block size
% LongDrXp
1.000000 | 0.000000 | 0.000000 | # [Xp] [cc] Electric Field
%
PPAPntXp= 27.21138 eV # [Xp] PPA imaginary energy
% GbndRnge
1 | 10 | # [GW] G[W] bands range
%
GDamping= 0.10000 eV # [GW] G[W] damping
dScStep= 0.10000 eV # [GW] Energy step to evalute Z factors
DysSolver= n # [GW] Dyson Equation solver (`n`,`s`,`g`)
%QPkrange # [GW] QP generalized Kpoint/Band indices
1| 8| 1| 10|
%
%QPerange # [GW] QP generalized Kpoint/Energy indices
1| 8| 0.0|-1.0|
%

The variables are the same of the COHSEX case plus a new one <code>PPAPntXp</code> that describes the imaginary energy used to fit the Plasmon Pole model. 
Follow the same strategy of the COHSEX case. Enter each k-point folder and type:

> yambo -d -k hartree -g n -p p -F Inputs/03GoWo_PPA_corrections

otherwise you can use the existent file <code>Input/03GoWo_PPA_corrections</code>. Now you have to study the convergence of the G0W0 gap versus the number of k-points, the number of bands in χ <code>BndsRnXs</code>, the size of the dielectric constant <code>NGsBlkXs</code> and the number of bands in the Green's function <code>GbndRnge</code>.

Please follow the same strategy of the COHSEX case running yambo using

> yambo -F Inputs/03GoWo_PPA_corrections -J GoWo_PPA_HF7Ry_X???Ry-nb???_nb???</code>

The final convergence plots should look like these (the plots are done using as a basis the above code).

[[File:PPA W size.png]]

[[File:PPA W bands.png]]

[[File:PPA G bands.png]]

[[File:PPA gap vs kpts.png]]

Final runs!! Now you know how to converge a G0W0 calculation so you can decide which are the parameters needed for full convergence. First do a COHSEX and then a GoWo (PPA) run at convergence, and you should obtain results similar to the following graph:

[[File:Si_gap.png|Final Gap Silicon]]

= References =
<references>
<ref name="gw">H. N. Rojas, R. W. Godby, and R. J. Needs, Phys. Rev. Lett. '''74''', 1827 (1995)</ref>
<ref name="hedin"> L. Hedin, Phys. Rev. '''139''', A796 (1965)</ref>
</references>

Silicon

2022-02-08T10:48:01Z

ElenaCannuccia: /* G-vectors convergence */

= Basic concepts of the GW approximation =

[[File:GW0.png|x300px|center|]]

In this tutorial you will learn the basic concepts of the [[Hartree-Fock]] and of the GW<ref name="gw"/> approximation. In particular we will illustrate how to calculate [http://en.wikipedia.org/wiki/Quasiparticle Quasi-Particle] energies with a single shot G0W0 approximation. Different lecture notes on the GW approach are available in the [[Lectures|Lectures section]].

The tutorial is split in different sections. In the first part we will deal with Hartree-Fock (HF) and the Coulomb-hole and screened-exchange (COHSEX) approximation. Finally in the last section we will discuss dynamical correlation with a Plasmon Pole Approximation (PPA).

= The material: Silicon =

* [http://cst-www.nrl.navy.mil/lattice/struk/a1.html FCC] lattice
* Two atoms per cell (8 electrons)
* Lattice constant 10.183 [a.u.]
* Plane waves cutoff 15 Rydberg

===Band gap===

*Direct gap 3.4 eV at Gamma
*Indirect gap 1.1 eV betweeb Gamma and X'
*Gamma= (0 0 0)
*X' is a point close to X=(0 1 0)

[[File:si_banddiagram.gif|thumb|x400px|Silicon Band Structure]]

= The Tutorial files =
Follow the instructions in [[Tutorials#Files]] and download/unpack the <code>Silicon.tar.gz</code>.

= The Tutorial structure =

Once the tutorial archive file is unzipped the following folder structure will appear

COPYING README Silicon/

with the Solid_Si folder containing

> ls Silicon/
PWSCF/ YAMBO/

In the Pwscf folder the student will find an input/output directory with input/output files for pw.x. The Silicon pseudopotential file is also provided.

> ls PWSCF/
convergence_scripts input output psps

In the <code>convergence_scripts</code> you will find some useful shell scripts to run the ground state convergence runs for Silicon.

The YAMBO folder contains the Yambo input/output files and core databases.

> ls YAMBO/
2x2x2/ 4x4x4/ 6x6x6/ 8x8x8/ Convergence_Plots_and_Scripts/ GAMMA/

The core databases are provided for several k-points grids. In addition the folder <code>Convergence_Plots_and_Scripts</code> contains some scripts to extract informations from the report files useful for the tutorial.

= Hartree-Fock =

Now we will study the convergence of the [http://en.wikipedia.org/wiki/Hartree%E2%80%93Fock_method Hartree-Fock] self energy, respect to the number of '''G'''-vectors and '''k'''-points. Yambo is a plane-wave code, therefore all the operators and wave-functions are expanded as:

[[File:orbital.png|Orbital in plane wave]]

Before you start any calculations we can decide how many '''G'''-vectors you want use to represent your wave-function. By default Yambo will use all of them, and for the present tutorial this is fine, however if you are studying larger systems you would like to reduce them in order to speed-up calculations, you can do it with <code> yambo -i -V RL</code> and then changing the variable <code>MaxGvecs</code> that referees to Ng in the previous formula.

Now we will proceed in the calculation of the [[Hartree-Fock|Hartree-Fock]] exchange. This is composed of two terms, that Hartree and the Fock (or exchange) one:

[[File:hf.png|Hartree Fock]]

In this tutorial we will calculate only the first order correction to the Kohn-Sham Hamiltonian due to the exchange term. Because of we are working in periodic system, the most appropriate basis to represent the Coulomb potential, appearing in the Fock term, is a plane-wave basis:

[[File:v_q_plus_G.png|Coulomb potential in plane wave]]

In order to generate the input file for the exchange type <code>yambo -x</code>. The variable that governs the number of '''G''' vectors Nex in the Coulomb potential is <code>EXXRLvcs</code>. In addition notice that in the previous formula for V('''r'''-'''r'''') we have an integral on the '''q''' vector, that in the code is discretized on a regular '''q'''-grid generated from the '''k'''-point one, '''q'''='''k'''-'''k''''.

== G-vectors convergence ==

Enter the <code>4x4x4</code> folder

> cd 4x4x4

Now edit the <code>01HF_corrections</code> file changing the field <code>EXXRLvcs=</code>3,6,7 and 15 Ry. For each case run

> yambo -F Inputs/01HF_corrections -J HF_???Ry

with <code>???</code>=3,6,7 and 15

Now plot the HF corrections by using the [[Gnuplot_scripts|hf_vs_cutoff.gnuplot]] script. Launch it via

> gnuplot
gnuplot>load "hf_vs_cutoff.gnuplot"

[[File:HF_parameters.png|Hartree-Fock corrections versus energy cutoff]]

== K-points convergence==

Enter each grid folder (<code>GAMMA,2x2x2,4x4x4,...</code>) and run
> yambo
without options. Then type

> yambo -x -F Inputs/01HF_corrections -J 01HF_corrections

and edit the 01HF_corrections file

HF_and_locXC # [R XX] Hartree-Fock Self-energy and Vxc
EXXRLvcs= 15 Ry # [XX] Exchange RL components
%QPkrange # [GW] QP generalized Kpoint/Band indices
1| 8| 1| 15|
%
%QPerange # [GW] QP generalized Kpoint/Energy indices
1| 8| 0.0|-1.0|
%

setting

<code> EXXRLvcs=15 Ry</code>

Then run in each k-point folder

<code> > yambo -F Inputs/01HF_corrections -J 01HF_corrections</code>

Note that after the each run Yambo produces three output file, one starting with <code>r_...</code> , another with <code>l_...</code> and a third one starting with <code>o_...</code>. The first one is a ''report'' of the actual calculation with all the details of the system, input, and results, while the second is a ''log'' with the running time of each process.

The file we are most interested in is the output file, <code>o-01HF_corrections.hf</code>. This file contains several columns. The fourth, labelled with <code>Ehf</code> represents the Hartree-Fock energy. This is the quantity we have to look at.

Use the [[Bash_scripts|parse_gap_hf.sh]] to parse the output files and adapt the gnuplot script provided earlier to print the values by using gnuplot

> cd ../
> ./parse_gap.sh o-01HF_corrections.hf hf_direct_gap_vs_kpoints.dat

[[File:Hf gap vs kpts.png|Direct gap vs k-points]]

= COHSEX without empty bands =

The Hartree-Fock self-energy just described in the previous section, although successful on some molecular systems, miserably fails in extended systems. The reason of this failure lies in the fact that electrons can screen the Coulomb potential, and therefore one electron feels a screened potential instead of the bare one. A common approximation for this screened potential is the so-called Random Phase Approximation:

[[File:gw.png|Hartree Fock]]

where the bare Coulomb potential V('''r''') is replaced by a non-local and frequency dependent one W('''r''','''r'''',ω). Subsequently it is possible to redefine all the perturbation theory in term of this screened potential, and disregarding the additional corrections coming from the vertex part, one obtains the so-called [[GW|GW]] approximation.

However the substantial complexity associated with calculating the non-local, energy dependent Σ=GW operator inspired early efforts to find simplifying approximations as the static COHSEX approximation prosed by Hedin<ref name="hedin"/>. The Coulomb Hole plus Screened Exchange (COHSEX) approximation[[[#march|2]],[[#fardi|3]]] eliminates the summation over empty states for the self energy operator and has the added benefit of being a static operator, a particular simplification for self consistent calculations. With the COHSEX approximation the self-energy is composed of two parts:

[[File:gw_sex.png|Screened Exchange]]

[[File:gw_coh.png|Cuolomb Hole]]

where Wp=W - V.

In order to calculate the COHSEX self-energy with yambo you need first the static screened interaction <code>yambo -X s -k hartree</code>. As for the V('''r''') case, also W('''r''','''r'''',E=0) will depend from the number of '''G'''-vectors, and the '''k'''-grid, but this time also the number of conduction bands <code>XsBndsRn</code> will enter in the screening calculation through the polarization function, see [http://www.yambo-code.org/theory/docs/doc_Xd.php The Interacting response function: Many-Body and TDDFT] section. Notice however that there are not any additional dependence of the self-energy operator from the conduction bands. After you obtained the screened interaction you are ready to build the self-energy operator and solve the corresponding Dyson equation, have a look to the [[GW|Dyson Equation solvers]] in Yambo. In order to get the quasi-particle energies, just do <code>yambo -b -g n -k hartree</code>. After calculation are completed Yambo will produce an output file <code>o.qp</code> which contains the values of the bare and re-normalized energy levels.

== K-points convergence ==

Follow the same strategy of the HF case. Enter each k-point folder and type

> yambo -b -k hartree -g n -p c -F Inputs/02Cohsex

edit the input file and change the values of the fields

EXXRLvcs=7 Ry %BndsRnXs 1 | 10 | # [Xs] Polarization function bands
NGsBlkXs= 1 RL # [Xs] Response block size
#UseEbands # [GW] Force COHSEX to use empty bands
%QPkrange # [GW] QP generalized Kpoint/Band indices
1| 8| 1| 10|
%

leaving the other parameters unchanged. Now, in each k-point folder, run

> yambo -F Inputs/02Cohsex -J Cohsex_HF7Ry_X0Ry-nb10

Adapt the shell script provided earlier to plot the direct gap dependence on the k-points grid

[[File:Cohsex_HF7Ry_X0Ry-nb10_gap_vs_kpoints.png]]

== W size convergence ==

Enter the <code>4x4x4</code> folder and edit the <code>02Cohsex_corrections</code> file changing the field <code>NGsBlkXs=</code>3,6,7 Ry. Run

> yambo -F Inputs/02Cohsex -J Cohsex_HF7Ry_X???Ry-nb10

with <code>???</code>=3,6,7 and 15.

[[File:COHSEX_no_empties_W_size.png]]

== W bands ==

Open your input file and change only the input variable <code>NGsBlkXs=1 Ry</code>. Then change

%BndsRnXs 1 | 20 | # [Xs] Polarization function bands

and run <code>yambo -F Inputs/02Cohsex -J Cohsex_HF7Ry_X1Ry-nb20</code>.
Repeat the calculations using 30 and 40 bands changing <code>nb???</code> in the job string identifier. Finally check how the Chosex Direct and Indirect band gap behave as a function of the number of bands in the screening.

[[File:COHSEX_no_empties_W_bands.png]]

== COHSEX with empty bands ==

While the Screened Exchange(SEX) part of the COHSEX self-energy has a structure similar to the Hartree-Fock exchange term, the Coulomb Hole(COH) acts as static external potential on the electrons. In the COH part the delta function δ('''r'''-'''r'''') comes from the completeness relation:

[[File:completeness.png|Completeness relation]]

Now we avoid the use of this relation in such a way to have a self-energy that depends from the conduction bands too. This can be done uncommenting flags <code>UseEbands</code> and setting the number of bands in the Green's function:

% GbndRnge 1 | 10 | # [GW] G[W] bands range

Repeat the previous calculations with different <code>GbndRnge</code> for instance, 10 20 30 40, and check how the COHSEX direct and indirect band gap behave as a function of the number of bands in the Green's function.

[[File:COHSEX_empties_G_bands.png]]

= GW within the plasmon pole approximation (PPA) =

Even the static COHSEX approximation is very appealing, it was clear from the first calculation that dynamical effects cannot be disregarded in solids. This fact motivated the research for approximated way to deal with a frequency dependent interaction, and one of the first proposal was the so-called Plasmon-Pole Approximation (PPA).

Now we will proceed to the calculation of the silicon band gap in G0W0 within PPA. In each section you will be asked to perform several calculations varying the value of the relevant variables involved. More specifically let's consider a typical Yambo input file to calculate GW corrections in the PPA.

gw0 # [R GW] GoWo Quasiparticle energy levels
ppa # [R Xp] Plasmon Pole Approximation
HF_and_locXC # [R XX] Hartree-Fock Self-energy and Vxc
em1d # [R Xd] Dynamical Inverse Dielectric Matrix
EXXRLvcs= 7 Ry # [XX] Exchange RL components
% QpntsRXp
1 | 8 | # [Xp] Transferred momenta
%
% BndsRnXp
1 | 10 | # [Xp] Polarization function bands
%
NGsBlkXp= 1 RL # [Xp] Response block size
% LongDrXp
1.000000 | 0.000000 | 0.000000 | # [Xp] [cc] Electric Field
%
PPAPntXp= 27.21138 eV # [Xp] PPA imaginary energy
% GbndRnge
1 | 10 | # [GW] G[W] bands range
%
GDamping= 0.10000 eV # [GW] G[W] damping
dScStep= 0.10000 eV # [GW] Energy step to evalute Z factors
DysSolver= n # [GW] Dyson Equation solver (`n`,`s`,`g`)
%QPkrange # [GW] QP generalized Kpoint/Band indices
1| 8| 1| 10|
%
%QPerange # [GW] QP generalized Kpoint/Energy indices
1| 8| 0.0|-1.0|
%

The variables are the same of the COHSEX case plus a new one <code>PPAPntXp</code> that describes the imaginary energy used to fit the Plasmon Pole model. 
Follow the same strategy of the COHSEX case. Enter each k-point folder and type:

> yambo -d -k hartree -g n -p p -F Inputs/03GoWo_PPA_corrections

otherwise you can use the existent file <code>Input/03GoWo_PPA_corrections</code>. Now you have to study the convergence of the G0W0 gap versus the number of k-points, the number of bands in χ <code>BndsRnXs</code>, the size of the dielectric constant <code>NGsBlkXs</code> and the number of bands in the Green's function <code>GbndRnge</code>.

Please follow the same strategy of the COHSEX case running yambo using

> yambo -F Inputs/03GoWo_PPA_corrections -J GoWo_PPA_HF7Ry_X???Ry-nb???_nb???</code>

The final convergence plots should look like these (the plots are done using as a basis the above code).

[[File:PPA W size.png]]

[[File:PPA W bands.png]]

[[File:PPA G bands.png]]

[[File:PPA gap vs kpts.png]]

Final runs!! Now you know how to converge a G0W0 calculation so you can decide which are the parameters needed for full convergence. First do a COHSEX and then a GoWo (PPA) run at convergence, and you should obtain results similar to the following graph:

[[File:Si_gap.png|Final Gap Silicon]]

= References =
<references>
<ref name="gw">H. N. Rojas, R. W. Godby, and R. J. Needs, Phys. Rev. Lett. '''74''', 1827 (1995)</ref>
<ref name="hedin"> L. Hedin, Phys. Rev. '''139''', A796 (1965)</ref>
</references>

Silicon

2022-02-08T10:46:25Z

ElenaCannuccia: /* COHSEX without empty bands */

= Basic concepts of the GW approximation =

[[File:GW0.png|x300px|center|]]

In this tutorial you will learn the basic concepts of the [[Hartree-Fock]] and of the GW<ref name="gw"/> approximation. In particular we will illustrate how to calculate [http://en.wikipedia.org/wiki/Quasiparticle Quasi-Particle] energies with a single shot G0W0 approximation. Different lecture notes on the GW approach are available in the [[Lectures|Lectures section]].

The tutorial is split in different sections. In the first part we will deal with Hartree-Fock (HF) and the Coulomb-hole and screened-exchange (COHSEX) approximation. Finally in the last section we will discuss dynamical correlation with a Plasmon Pole Approximation (PPA).

= The material: Silicon =

* [http://cst-www.nrl.navy.mil/lattice/struk/a1.html FCC] lattice
* Two atoms per cell (8 electrons)
* Lattice constant 10.183 [a.u.]
* Plane waves cutoff 15 Rydberg

===Band gap===

*Direct gap 3.4 eV at Gamma
*Indirect gap 1.1 eV betweeb Gamma and X'
*Gamma= (0 0 0)
*X' is a point close to X=(0 1 0)

[[File:si_banddiagram.gif|thumb|x400px|Silicon Band Structure]]

= The Tutorial files =
Follow the instructions in [[Tutorials#Files]] and download/unpack the <code>Silicon.tar.gz</code>.

= The Tutorial structure =

Once the tutorial archive file is unzipped the following folder structure will appear

COPYING README Silicon/

with the Solid_Si folder containing

> ls Silicon/
PWSCF/ YAMBO/

In the Pwscf folder the student will find an input/output directory with input/output files for pw.x. The Silicon pseudopotential file is also provided.

> ls PWSCF/
convergence_scripts input output psps

In the <code>convergence_scripts</code> you will find some useful shell scripts to run the ground state convergence runs for Silicon.

The YAMBO folder contains the Yambo input/output files and core databases.

> ls YAMBO/
2x2x2/ 4x4x4/ 6x6x6/ 8x8x8/ Convergence_Plots_and_Scripts/ GAMMA/

The core databases are provided for several k-points grids. In addition the folder <code>Convergence_Plots_and_Scripts</code> contains some scripts to extract informations from the report files useful for the tutorial.

= Hartree-Fock =

Now we will study the convergence of the [http://en.wikipedia.org/wiki/Hartree%E2%80%93Fock_method Hartree-Fock] self energy, respect to the number of '''G'''-vectors and '''k'''-points. Yambo is a plane-wave code, therefore all the operators and wave-functions are expanded as:

[[File:orbital.png|Orbital in plane wave]]

Before you start any calculations we can decide how many '''G'''-vectors you want use to represent your wave-function. By default Yambo will use all of them, and for the present tutorial this is fine, however if you are studying larger systems you would like to reduce them in order to speed-up calculations, you can do it with <code> yambo -i -V RL</code> and then changing the variable <code>MaxGvecs</code> that referees to Ng in the previous formula.

Now we will proceed in the calculation of the [[Hartree-Fock|Hartree-Fock]] exchange. This is composed of two terms, that Hartree and the Fock (or exchange) one:

[[File:hf.png|Hartree Fock]]

In this tutorial we will calculate only the first order correction to the Kohn-Sham Hamiltonian due to the exchange term. Because of we are working in periodic system, the most appropriate basis to represent the Coulomb potential, appearing in the Fock term, is a plane-wave basis:

[[File:v_q_plus_G.png|Coulomb potential in plane wave]]

In order to generate the input file for the exchange type <code>yambo -x</code>. The variable that governs the number of '''G''' vectors Nex in the Coulomb potential is <code>EXXRLvcs</code>. In addition notice that in the previous formula for V('''r'''-'''r'''') we have an integral on the '''q''' vector, that in the code is discretized on a regular '''q'''-grid generated from the '''k'''-point one, '''q'''='''k'''-'''k''''.

== G-vectors convergence ==

Enter the <code>4x4x4</code> folder

> cd 4x4x4

Enter the and edit the <code>01HF_corrections</code> file changing the field <code>EXXRLvcs=</code>3,6,7 and 15 Ry. For each case run

> yambo -F Inputs/01HF_corrections -J HF_???Ry

with <code>???</code>=3,6,7 and 15

Now plot the HF corrections by using the [[Gnuplot_scripts|hf_vs_cutoff.gnuplot]] script. Launch it via

> gnuplot
gnuplot>load "hf_vs_cutoff.gnuplot"

[[File:HF_parameters.png|Hartree-Fock corrections versus energy cutoff]]

== K-points convergence==

Enter each grid folder (<code>GAMMA,2x2x2,4x4x4,...</code>) and run
> yambo
without options. Then type

> yambo -x -F Inputs/01HF_corrections -J 01HF_corrections

and edit the 01HF_corrections file

HF_and_locXC # [R XX] Hartree-Fock Self-energy and Vxc
EXXRLvcs= 15 Ry # [XX] Exchange RL components
%QPkrange # [GW] QP generalized Kpoint/Band indices
1| 8| 1| 15|
%
%QPerange # [GW] QP generalized Kpoint/Energy indices
1| 8| 0.0|-1.0|
%

setting

<code> EXXRLvcs=15 Ry</code>

Then run in each k-point folder

<code> > yambo -F Inputs/01HF_corrections -J 01HF_corrections</code>

Note that after the each run Yambo produces three output file, one starting with <code>r_...</code> , another with <code>l_...</code> and a third one starting with <code>o_...</code>. The first one is a ''report'' of the actual calculation with all the details of the system, input, and results, while the second is a ''log'' with the running time of each process.

The file we are most interested in is the output file, <code>o-01HF_corrections.hf</code>. This file contains several columns. The fourth, labelled with <code>Ehf</code> represents the Hartree-Fock energy. This is the quantity we have to look at.

Use the [[Bash_scripts|parse_gap_hf.sh]] to parse the output files and adapt the gnuplot script provided earlier to print the values by using gnuplot

> cd ../
> ./parse_gap.sh o-01HF_corrections.hf hf_direct_gap_vs_kpoints.dat

[[File:Hf gap vs kpts.png|Direct gap vs k-points]]

= COHSEX without empty bands =

The Hartree-Fock self-energy just described in the previous section, although successful on some molecular systems, miserably fails in extended systems. The reason of this failure lies in the fact that electrons can screen the Coulomb potential, and therefore one electron feels a screened potential instead of the bare one. A common approximation for this screened potential is the so-called Random Phase Approximation:

[[File:gw.png|Hartree Fock]]

where the bare Coulomb potential V('''r''') is replaced by a non-local and frequency dependent one W('''r''','''r'''',ω). Subsequently it is possible to redefine all the perturbation theory in term of this screened potential, and disregarding the additional corrections coming from the vertex part, one obtains the so-called [[GW|GW]] approximation.

However the substantial complexity associated with calculating the non-local, energy dependent Σ=GW operator inspired early efforts to find simplifying approximations as the static COHSEX approximation prosed by Hedin<ref name="hedin"/>. The Coulomb Hole plus Screened Exchange (COHSEX) approximation[[[#march|2]],[[#fardi|3]]] eliminates the summation over empty states for the self energy operator and has the added benefit of being a static operator, a particular simplification for self consistent calculations. With the COHSEX approximation the self-energy is composed of two parts:

[[File:gw_sex.png|Screened Exchange]]

[[File:gw_coh.png|Cuolomb Hole]]

where Wp=W - V.

In order to calculate the COHSEX self-energy with yambo you need first the static screened interaction <code>yambo -X s -k hartree</code>. As for the V('''r''') case, also W('''r''','''r'''',E=0) will depend from the number of '''G'''-vectors, and the '''k'''-grid, but this time also the number of conduction bands <code>XsBndsRn</code> will enter in the screening calculation through the polarization function, see [http://www.yambo-code.org/theory/docs/doc_Xd.php The Interacting response function: Many-Body and TDDFT] section. Notice however that there are not any additional dependence of the self-energy operator from the conduction bands. After you obtained the screened interaction you are ready to build the self-energy operator and solve the corresponding Dyson equation, have a look to the [[GW|Dyson Equation solvers]] in Yambo. In order to get the quasi-particle energies, just do <code>yambo -b -g n -k hartree</code>. After calculation are completed Yambo will produce an output file <code>o.qp</code> which contains the values of the bare and re-normalized energy levels.

== K-points convergence ==

Follow the same strategy of the HF case. Enter each k-point folder and type

> yambo -b -k hartree -g n -p c -F Inputs/02Cohsex

edit the input file and change the values of the fields

EXXRLvcs=7 Ry %BndsRnXs 1 | 10 | # [Xs] Polarization function bands
NGsBlkXs= 1 RL # [Xs] Response block size
#UseEbands # [GW] Force COHSEX to use empty bands
%QPkrange # [GW] QP generalized Kpoint/Band indices
1| 8| 1| 10|
%

leaving the other parameters unchanged. Now, in each k-point folder, run

> yambo -F Inputs/02Cohsex -J Cohsex_HF7Ry_X0Ry-nb10

Adapt the shell script provided earlier to plot the direct gap dependence on the k-points grid

[[File:Cohsex_HF7Ry_X0Ry-nb10_gap_vs_kpoints.png]]

== W size convergence ==

Enter the <code>4x4x4</code> folder and edit the <code>02Cohsex_corrections</code> file changing the field <code>NGsBlkXs=</code>3,6,7 Ry. Run

> yambo -F Inputs/02Cohsex -J Cohsex_HF7Ry_X???Ry-nb10

with <code>???</code>=3,6,7 and 15.

[[File:COHSEX_no_empties_W_size.png]]

== W bands ==

Open your input file and change only the input variable <code>NGsBlkXs=1 Ry</code>. Then change

%BndsRnXs 1 | 20 | # [Xs] Polarization function bands

and run <code>yambo -F Inputs/02Cohsex -J Cohsex_HF7Ry_X1Ry-nb20</code>.
Repeat the calculations using 30 and 40 bands changing <code>nb???</code> in the job string identifier. Finally check how the Chosex Direct and Indirect band gap behave as a function of the number of bands in the screening.

[[File:COHSEX_no_empties_W_bands.png]]

== COHSEX with empty bands ==

While the Screened Exchange(SEX) part of the COHSEX self-energy has a structure similar to the Hartree-Fock exchange term, the Coulomb Hole(COH) acts as static external potential on the electrons. In the COH part the delta function δ('''r'''-'''r'''') comes from the completeness relation:

[[File:completeness.png|Completeness relation]]

Now we avoid the use of this relation in such a way to have a self-energy that depends from the conduction bands too. This can be done uncommenting flags <code>UseEbands</code> and setting the number of bands in the Green's function:

% GbndRnge 1 | 10 | # [GW] G[W] bands range

Repeat the previous calculations with different <code>GbndRnge</code> for instance, 10 20 30 40, and check how the COHSEX direct and indirect band gap behave as a function of the number of bands in the Green's function.

[[File:COHSEX_empties_G_bands.png]]

= GW within the plasmon pole approximation (PPA) =

Even the static COHSEX approximation is very appealing, it was clear from the first calculation that dynamical effects cannot be disregarded in solids. This fact motivated the research for approximated way to deal with a frequency dependent interaction, and one of the first proposal was the so-called Plasmon-Pole Approximation (PPA).

Now we will proceed to the calculation of the silicon band gap in G0W0 within PPA. In each section you will be asked to perform several calculations varying the value of the relevant variables involved. More specifically let's consider a typical Yambo input file to calculate GW corrections in the PPA.

gw0 # [R GW] GoWo Quasiparticle energy levels
ppa # [R Xp] Plasmon Pole Approximation
HF_and_locXC # [R XX] Hartree-Fock Self-energy and Vxc
em1d # [R Xd] Dynamical Inverse Dielectric Matrix
EXXRLvcs= 7 Ry # [XX] Exchange RL components
% QpntsRXp
1 | 8 | # [Xp] Transferred momenta
%
% BndsRnXp
1 | 10 | # [Xp] Polarization function bands
%
NGsBlkXp= 1 RL # [Xp] Response block size
% LongDrXp
1.000000 | 0.000000 | 0.000000 | # [Xp] [cc] Electric Field
%
PPAPntXp= 27.21138 eV # [Xp] PPA imaginary energy
% GbndRnge
1 | 10 | # [GW] G[W] bands range
%
GDamping= 0.10000 eV # [GW] G[W] damping
dScStep= 0.10000 eV # [GW] Energy step to evalute Z factors
DysSolver= n # [GW] Dyson Equation solver (`n`,`s`,`g`)
%QPkrange # [GW] QP generalized Kpoint/Band indices
1| 8| 1| 10|
%
%QPerange # [GW] QP generalized Kpoint/Energy indices
1| 8| 0.0|-1.0|
%

The variables are the same of the COHSEX case plus a new one <code>PPAPntXp</code> that describes the imaginary energy used to fit the Plasmon Pole model. 
Follow the same strategy of the COHSEX case. Enter each k-point folder and type:

> yambo -d -k hartree -g n -p p -F Inputs/03GoWo_PPA_corrections

otherwise you can use the existent file <code>Input/03GoWo_PPA_corrections</code>. Now you have to study the convergence of the G0W0 gap versus the number of k-points, the number of bands in χ <code>BndsRnXs</code>, the size of the dielectric constant <code>NGsBlkXs</code> and the number of bands in the Green's function <code>GbndRnge</code>.

Please follow the same strategy of the COHSEX case running yambo using

> yambo -F Inputs/03GoWo_PPA_corrections -J GoWo_PPA_HF7Ry_X???Ry-nb???_nb???</code>

The final convergence plots should look like these (the plots are done using as a basis the above code).

[[File:PPA W size.png]]

[[File:PPA W bands.png]]

[[File:PPA G bands.png]]

[[File:PPA gap vs kpts.png]]

Final runs!! Now you know how to converge a G0W0 calculation so you can decide which are the parameters needed for full convergence. First do a COHSEX and then a GoWo (PPA) run at convergence, and you should obtain results similar to the following graph:

[[File:Si_gap.png|Final Gap Silicon]]

= References =
<references>
<ref name="gw">H. N. Rojas, R. W. Godby, and R. J. Needs, Phys. Rev. Lett. '''74''', 1827 (1995)</ref>
<ref name="hedin"> L. Hedin, Phys. Rev. '''139''', A796 (1965)</ref>
</references>

LiF

2022-01-21T14:34:23Z

ElenaCannuccia: /* The Statically screened Electron-electron interaction (yambo -X s) */

[[File:LiF-crystal.jpg|thumb]]

= Solid LiF: excitons at work =

[[File:LiF_lif_structure.jpg|LiF structure]]

= The material =

* FCC lattice
* Two atoms per cell, Li and F (8 electrons)
* Lattice constant 7.61 [a.u.]
* Plane waves cutoff 40 Hartree (1800 RL vectors)

= The Tutorial files =
Follow the instructions in [[Tutorials#Files]] and download/unpack the <code>LiF.tar.gz</code>.

= From PWscf to the Yambo core databases =

$ cd YAMBO_TUTORIALS/LiF/PWSCF
$ ls
inputs outputs psps

First run the SCF calculation to generate the ground-state charge density, occupations, Fermi level, and so on:
$ pw.x < inputs/scf.in > scf.out

Next run a non-SCF calculation to generate a set of Kohn-Sham eigenvalues and eigenvectors for both occupied and unoccupied states (100 bands):
$ pw.x < inputs/nscf.in > nscf.out

Note the presence of the following flags in the input file:
wf_collect=.true.
force_symmorphic=.true.
diago_full_acc=.true.
which are needed for generating the Yambo databases accurately. Full explanations of these variables are given on the [http://www.quantum-espresso.org/wp-content/uploads/Doc/INPUT_PW.html quantum-ESPRESSO input variables page].

After these two runs, you should have a ''LiF.save'' directory:
$ ls LiF.save
charge-density.dat data-file-schema.xml F.LDA.cpi.UPF Li.LDA.cpi.UPF wfc10.dat wfc1.dat wfc2.dat wfc3.dat wfc4.dat wfc5.dat wfc6.dat wfc7.dat wfc8.dat wfc9.dat

=== Conversion to Yambo format ===
The PWscf ''LiF.save'' output is converted to the Yambo format using the <code>p2y</code> executable (pwscf to yambo), found in the yambo ''bin'' directory.
Enter ''LiF.save'' and launch <code>p2y</code>:

$ cd LiF.save
$ p2y
...
<---> DBs path set to .
<---> Index file set to data-file.xml
<---> Header/K-points/Energies... done
...
<---> == DB1 (Gvecs and more) ...
<---> ... Database done
<---> == DB2 (wavefunctions) ... done ==
<---> == DB3 (PseudoPotential) ... done ==
<---> == P2Y completed ==

This output repeats some information about the system and generates a ''SAVE'' directory:
$ ls SAVE
ns.db1 ns.wf ns.kb_pp_pwscf
ns.wf_fragments_1_1 ...
ns.kb_pp_pwscf_fragment_1 ...
These files, with an ''n'' prefix, indicate that they are in netCDF format, and thus not human readable. However, they are perfectly transferable across different architectures.

In practice we suggest to move the ''SAVE'' folder into a new clean folder.

In this tutorial however, we ask instead that you continue using a ''SAVE'' folder that we prepared previously:
$ cd ../../Optics/YAMBO
$ ls
SAVE

= Introduction =

We will start the TDDFT tutorial exactly where standard local approximations for fxc (like ALDA) do not work at all. The optical spectrum of solid
[[LiF]] <ref name="wikipedia/> is dominated by a strongly bound exciton (3 eV binding energy) <ref name="rholf"/> and will immediately see that any independent particle approximation drastically fails to describe the complex structures that are observed experimentally.

[[File:lif_rholf.png|345x289px|Optical absorption of solid LiF. Dots: experiment. Continuous line: BSE. Dashed line: RPA-QP]]

In the following we will describe in detail the different TDDFT related calculations. For each example you can find a link to the Input file with a brief explanation of the variables meaning.

We will also use this first system to explain in detail some of the most relevant technical aspects of yambo.


= Initialization (yambo -i -V RL) =

This section describes the standard initialization procedure. As this initialization is common to all yambo runs it will be described extensively only in this case.

To run this example enter the ''YAMBO'' directory (where you have previously created the SAVE folder) and type:

<pre> localhost:>yambo -F Inputs/01_init -J 01_init
</pre>
and you will see
<pre> <---> [01] Game Summary
<---> [02] Input variables setup
<---> RL-shells | | [000%] --(E) --(X)
<---> RL-shells |####################| [100%] --(E) --(X)
<---> [02.01] K-grid lattice
<---> [02.02] Input (E)nergies[ev] & Occupations
<---> [03] Transferred momenta grid: Indexes
<---> [04] Game Over & Game summary
</pre>
If now you edit the ''r-01_setup'' you will find a lot of useless ([[File:LiF_smile.gif|60x23px]]) informations about your system like, the Fermi level

<pre> [02.02] Input (E)nergies[ev] & Occupations
========

Fermi Energy[ev] - T[ev/K] :-0.241627 0.000100 1.160400
Bands summary : Full Empty
0001-0004 0005-0050
Indirect Gap [ev][min-max]: 9.11330 14.79631</pre>
confirming that, yes, our bulk LiF is a '''wide''' gap insulator. Then you can see the effect of using
<pre> MaxGvecs= 800 RL # [INI] Max number of G-vectors planned to use
</pre>
in the ''Inputs/01_init'' file. In the report file we notice that
<pre> G-vectors [RL space]: 1807
[wavefunctions]: 1807</pre>
whereas the Reciprocal Space shells found by yambo are
<pre> G-vector (S)hells. Format: [Snn] G`s
[S0030]: 773 [S0029]: 749 [S0028]: 725 [S0027]: 701 [S0026]: 645
[S0025]: 609 [S0024]: 561 [S0023]: 537 [S0022]: 531 [S0021]: 459
[S0020]: 411 [S0019]: 387 [S0018]: 339 [S0017]: 331 [S0016]: 307
[S0015]: 283 [S0014]: 259 [S0013]: 229 [S0012]: 181 [S0011]: 169
[S0010]: 137 [S0009]: 113 [S0008]: 89 [S0007]: 65 [S0006]: 59
[S0005]: 51 [S0004]: 27 [S0003]: 15 [S0002]: 9 [S0001]: 1</pre>
so that the highest number of RL vectors we can use is 773, lower than the charge number given by Abinit and different from the value for ''MaxGvecs'' we provided. This happens because yambo has calculated the Reciprocal Space shells up to 800 to find that the highest closed shell corresponds to 773 RL vectors. Note that, independently of the value you set for any variable that defines a dimension in the RL space, yambo redefines it, in order to match it to the nearest closed shell.



=Random-Phase approximation (yambo -o c) (yambo -o c -k hartree) (yambo -o c -k hartree -V qp) =

The simplest approximation that can be used to calculate the absorption spectrum of LiF is the independent particle approximation. This is done in ''Inputs/02_RPA_no_LF'', that is generated directly by "yambo -o c" command line without specifying an approximation for the kernel (in fact there is no kernel!), To run this example type

<pre> localhost:>yambo -F Inputs/02_RPA_no_LF -J 02_RPA_no_LF
</pre>
The optional ''-J'' flag is used to label the output/report/log files.
In ''Inputs/03_RPA_LF'' we include a kernel in the Hartree approximation. This correspond to the Random-Phase-Approximation (RPA). The response function size is changed to 51 RL. This means including Local Field Effects corresponding to charge oscillations expanded up to the 51st RL component. The converged value for ''NGsBlkXd'' shall be determined by doing several calculations with different values and checking the effect on the final physical result (the absorption spectrum, in this case).

After having run

<pre> localhost:>yambo -F Inputs/03_RPA_LF -J 03_RPA_LF
</pre>
we can compare the result of our calculations with the experimental curve (that you find in the ''Experiment'' folder).

[[File:LiF_02_03.png|512x384px
]]

The comparison with the experiment clearly show that the RPA is not at all adequate in the case of LiF. We notice two main discrepancies between theory and experiment: the RPA absorption onset is too low and the shape lacks the sharp peak observed experimentally at around 12 eV. The onset position can be artificially corrected using a scissor operator (representing the QP gap correction) of 5.19 eV that simply opens rigidly the LDA gap. This is shown in ''Inputs/03_RPA_LF_QP'' with the line

<pre>% XfnQP_E
5.190000 | 1.000000 | 1.000000 | # [EXTQP Xd] E parameters (c/v)
%</pre>
The resulting spectrum fits better with the experiment but now there seems to be an even more serious problem:

[[File:LiF_03.png|512x384px]]

there is an experimental peak well below the QP absorption onset:

an [http://en.wikipedia.org/wiki/Exciton EXCITON!]

[[File:LiF_exciton.jpg|160x202px]]


= ALDA (yambo -o c -k alda) =

Our first attempt to go beyond RPA is using TDDFT in the Adiabatic LDA approximation. Depending on the exchange-correlation(xc) functional used in the ground state calculation yambo will produce a corresponding xc-kernel. In this case, as reported by the ''a2y'' command we are using a Perdew Wang parametrization.

Running

<pre> localhost:>yambo -F Inputs/04_alda_g_space -J 04_alda_g_space</pre>
we get

[[File:LiF_04.png|512x384px]]

Unfortunately ALDA only slightly changes the RPA result. The situation will change in more isolated system (reduced dimensionality).


=The Statically screened Electron-electron interaction (yambo -X s) =

As simple RPA and ALDA approximations have not described correctly the experimental spectrum we have to move towards more elaborate techniques like the Bethe-Salpeter (BS) equation.

A key ingredient in the BS kernel is the electron-electron interaction commonly evaluated in the static approximation. The input file ''Inputs/05_W'' describes how to calculate it. The variables used in this input file have the same physical meaning of those used in the optical absorption calculation. The only difference is that, in general, the response function dimension obtained in the examples (03-04), gives an upper bound to the number of RL vectors needed here. This is because the size of response matrix in an RPA calculation defines also the size of the Hartree potential, whose short-range components are not screened. In the present case, instead, the electron-electron interaction is screened and, for this reason, the RL vectors needed are considerably smaller than in the RPA case. So let's type (no ''-J'' option here) ...

<pre> localhost:>yambo -F Inputs/05_W </pre>
... and after waiting for some minutes the result, that is the database SAVE/ndb.em1s. Do not use the ''-J'' option here as we will need to read this database in the next examples.



=The Bethe-Salpeter equation, Excitons (yambo -o b -k sex -y h) =

The input file ''Inputs/06_BSE'' describes how to calculate an excitonic absorption spectrum, by solving the BS equation using the recursive Haydock Method. Before running ''yambo'' we must have a closer look at the input file:

The line
<pre>% KfnQP_E
5.80000 | 1.000000 | 1.000000 | # [EXTQP BSK BSS] E parameters (c/v)
%</pre>
applies a 5.8 eV scissor in order to open the LDA gap.
<pre>BSKmod= "SEX" # [BSE] IP/Hartree/HF/ALDA/SEX</pre>
Here we are using the screened exchange (SEX) approximation for the kernel that includes both exchange and correlation terms
<pre>% BSEBands
2 | 7 | # [BSK] Bands range
%
BSENGBlk= 51 RL # [BSK] Screened interaction block size
BSENGexx= 773 RL # [BSK] Exchange components</pre>
Here we specify the range of bands to be used and the RL components for the screened interaction (51) (read from the ndb.em1s file) and for the Hartree term (773, the maximal available). '''Remember''' that the BS kernel is written in Bloch space and its size is given by

<pre>BS kernel size = Valence Bands × Conduction Bands × K-points in the whole BZ</pre>
In our case the size is 2304. The BS bands range must be converged with care trying to keep as a few bands as possible.
Running

<pre> localhost:>yambo -F Inputs/06_BSE -J 06_BSE</pre>
will calculate the BS kernel and store in in the ''06_BSE'' folder. Before analyzing the BS absorption spectrum we can edit the log file ''l-06_BSE_optics_bse_bss'' to observe the on-the-fly live timing feature of yambo:

<pre> [...]
<---> BSK | | [000%] --(E) --(X)
<05s> BSK |# | [007%] 05s(E) 01m-07s(X)
<11s> BSK |### | [015%] 10s(E) 01m-06s(X)
[...]
<01m-02s> BSK |################## | [093%] 01m-01s(E) 01m-06s(X)
<01m-07s> BSK |####################| [100%] 01m-06s(E) 01m-06s(X)
[...]</pre>
The two numbers at the end of each line represents the elapsed time(E) and the expected time(X). The latter estimates the time needed to complete that particular section (the BS kernel construction in this case).

Finally we can compare the resulting BS optical absorption with the experimental result. We see how strong is the excitonic effect, if compared to the RPA calculation. The BS equation is, then, able to describe the bound electron-hole state responsible for the peak observed experimentally below the QP gap.

[[File:LiF_06.png|512x384px
]]


=A Bethe-Salpeter based Fxc(yambo -o c -k lrc) =

As for TDDFT we might be a little bit disappointed at this stage as the only method that yields a reasonable absorption spectrum for LiF is based on MBPT. It is possible, however, to extract from the BS kernel a possible approximation for the xc-kernel. This approach is efficient, but is far too complicated, and requires the prior computation of the BS kernel. An alternative possibility is to use a simple Long Range Component model, as introduced in [[#Reining|Reining]]. In this model, the yambo input file ''Inputs/07_LRC'' describes a model where

[[File:LiF_PIC_LiF_equations-14.png|190x55px]]
with F0= ''LRC_alpha''=-8.7.

[[File:LiF_07.png|512x384px
]]

We see from the previous figure that the agreement with the BS calculation is not very good. Nevertheless this simple model captures the presence of an exciton and works quite well for a large number of simple semiconductors, as show in [[#silvana|Botti]]:

[[File:F_silvana.png|371x352px]]


= Additional Exercises =

<ol>
<li>Calculate the absorption spectra like in section [[#02|02]]-[[#03|03]] increasing the polarization RL size, the polarization bands to find the converged values.</li>
<li>Plot the EELS spectrum obtained in section [[#02|02]]-[[#03|03]] and check the effect of increasing the polarization bands. Do a resonant only calculation (using the -V option) to see that the EELS cannot be described using only the resonant part of the response function.</li>
<li>See the effect of using a denser BZ sampling grid running Abinit with, for example
<pre>ngkpt2 6 6 6</pre></li>
<li>Repeat the [[#06|BSE]] calculation increasing the bands.</li>
<li>Calculate the [[#06|BSE]] spectrum using a diagonal only interaction.</li></ol>

= References =

<ref name="wikipedia"> [http://en.wikipedia.org/wiki/Lithium_fluoride LiF on wikipedia].
</ref><ref name="rholf"> M. Rohlfing, S. Louie, Phys. Rev. Lett. '''81''', 2312 (2000).
</ref><ref name="p1"> A. Marini, R. Del Sole, and A. Rubio, Phys. Rev. Lett., '''91''', 256402 (2003),G. Adragna, R. Del Sole, and A. Marini, Phys. Rev. B '''68''', 165108 (2003), F. Sottile, V. Olevano, and L. Reining, Phys. Rev. Lett. '''91''', 056402 (2003).
</ref><ref name="Reining"> Reining, V. Olevano, A. Rubio, and G. Onida, Phys. Rev. Lett. '''88''', 066404 (2002).
</ref><ref name="silvana"> S. Botti, Phys. Rev. B '''69''', 155112 (2004).
</ref>

LiF

2022-01-12T16:46:42Z

ElenaCannuccia: /* From PWscf to the Yambo core databases */

[[File:LiF-crystal.jpg|thumb]]

= Solid LiF: excitons at work =

[[File:LiF_lif_structure.jpg|LiF structure]]

= The material =

* FCC lattice
* Two atoms per cell, Li and F (8 electrons)
* Lattice constant 7.61 [a.u.]
* Plane waves cutoff 40 Hartree (1800 RL vectors)

= The Tutorial files =
Follow the instructions in [[Tutorials#Files]] and download/unpack the <code>LiF.tar.gz</code>.

= From PWscf to the Yambo core databases =

$ cd YAMBO_TUTORIALS/LiF/PWSCF
$ ls
inputs outputs psps

First run the SCF calculation to generate the ground-state charge density, occupations, Fermi level, and so on:
$ pw.x < inputs/scf.in > scf.out

Next run a non-SCF calculation to generate a set of Kohn-Sham eigenvalues and eigenvectors for both occupied and unoccupied states (100 bands):
$ pw.x < inputs/nscf.in > nscf.out

Note the presence of the following flags in the input file:
wf_collect=.true.
force_symmorphic=.true.
diago_full_acc=.true.
which are needed for generating the Yambo databases accurately. Full explanations of these variables are given on the [http://www.quantum-espresso.org/wp-content/uploads/Doc/INPUT_PW.html quantum-ESPRESSO input variables page].

After these two runs, you should have a ''LiF.save'' directory:
$ ls LiF.save
charge-density.dat data-file-schema.xml F.LDA.cpi.UPF Li.LDA.cpi.UPF wfc10.dat wfc1.dat wfc2.dat wfc3.dat wfc4.dat wfc5.dat wfc6.dat wfc7.dat wfc8.dat wfc9.dat

=== Conversion to Yambo format ===
The PWscf ''LiF.save'' output is converted to the Yambo format using the <code>p2y</code> executable (pwscf to yambo), found in the yambo ''bin'' directory.
Enter ''LiF.save'' and launch <code>p2y</code>:

$ cd LiF.save
$ p2y
...
<---> DBs path set to .
<---> Index file set to data-file.xml
<---> Header/K-points/Energies... done
...
<---> == DB1 (Gvecs and more) ...
<---> ... Database done
<---> == DB2 (wavefunctions) ... done ==
<---> == DB3 (PseudoPotential) ... done ==
<---> == P2Y completed ==

This output repeats some information about the system and generates a ''SAVE'' directory:
$ ls SAVE
ns.db1 ns.wf ns.kb_pp_pwscf
ns.wf_fragments_1_1 ...
ns.kb_pp_pwscf_fragment_1 ...
These files, with an ''n'' prefix, indicate that they are in netCDF format, and thus not human readable. However, they are perfectly transferable across different architectures.

In practice we suggest to move the ''SAVE'' folder into a new clean folder.

In this tutorial however, we ask instead that you continue using a ''SAVE'' folder that we prepared previously:
$ cd ../../Optics/YAMBO
$ ls
SAVE

= Introduction =

We will start the TDDFT tutorial exactly where standard local approximations for fxc (like ALDA) do not work at all. The optical spectrum of solid
[[LiF]] <ref name="wikipedia/> is dominated by a strongly bound exciton (3 eV binding energy) <ref name="rholf"/> and will immediately see that any independent particle approximation drastically fails to describe the complex structures that are observed experimentally.

[[File:lif_rholf.png|345x289px|Optical absorption of solid LiF. Dots: experiment. Continuous line: BSE. Dashed line: RPA-QP]]

In the following we will describe in detail the different TDDFT related calculations. For each example you can find a link to the Input file with a brief explanation of the variables meaning.

We will also use this first system to explain in detail some of the most relevant technical aspects of yambo.


= Initialization (yambo -i -V RL) =

This section describes the standard initialization procedure. As this initialization is common to all yambo runs it will be described extensively only in this case.

To run this example enter the ''YAMBO'' directory (where you have previously created the SAVE folder) and type:

<pre> localhost:>yambo -F Inputs/01_init -J 01_init
</pre>
and you will see
<pre> <---> [01] Game Summary
<---> [02] Input variables setup
<---> RL-shells | | [000%] --(E) --(X)
<---> RL-shells |####################| [100%] --(E) --(X)
<---> [02.01] K-grid lattice
<---> [02.02] Input (E)nergies[ev] & Occupations
<---> [03] Transferred momenta grid: Indexes
<---> [04] Game Over & Game summary
</pre>
If now you edit the ''r-01_setup'' you will find a lot of useless ([[File:LiF_smile.gif|60x23px]]) informations about your system like, the Fermi level

<pre> [02.02] Input (E)nergies[ev] & Occupations
========

Fermi Energy[ev] - T[ev/K] :-0.241627 0.000100 1.160400
Bands summary : Full Empty
0001-0004 0005-0050
Indirect Gap [ev][min-max]: 9.11330 14.79631</pre>
confirming that, yes, our bulk LiF is a '''wide''' gap insulator. Then you can see the effect of using
<pre> MaxGvecs= 800 RL # [INI] Max number of G-vectors planned to use
</pre>
in the ''Inputs/01_init'' file. In the report file we notice that
<pre> G-vectors [RL space]: 1807
[wavefunctions]: 1807</pre>
whereas the Reciprocal Space shells found by yambo are
<pre> G-vector (S)hells. Format: [Snn] G`s
[S0030]: 773 [S0029]: 749 [S0028]: 725 [S0027]: 701 [S0026]: 645
[S0025]: 609 [S0024]: 561 [S0023]: 537 [S0022]: 531 [S0021]: 459
[S0020]: 411 [S0019]: 387 [S0018]: 339 [S0017]: 331 [S0016]: 307
[S0015]: 283 [S0014]: 259 [S0013]: 229 [S0012]: 181 [S0011]: 169
[S0010]: 137 [S0009]: 113 [S0008]: 89 [S0007]: 65 [S0006]: 59
[S0005]: 51 [S0004]: 27 [S0003]: 15 [S0002]: 9 [S0001]: 1</pre>
so that the highest number of RL vectors we can use is 773, lower than the charge number given by Abinit and different from the value for ''MaxGvecs'' we provided. This happens because yambo has calculated the Reciprocal Space shells up to 800 to find that the highest closed shell corresponds to 773 RL vectors. Note that, independently of the value you set for any variable that defines a dimension in the RL space, yambo redefines it, in order to match it to the nearest closed shell.



=Random-Phase approximation (yambo -o c) (yambo -o c -k hartree) (yambo -o c -k hartree -V qp) =

The simplest approximation that can be used to calculate the absorption spectrum of LiF is the independent particle approximation. This is done in ''Inputs/02_RPA_no_LF'', that is generated directly by "yambo -o c" command line without specifying an approximation for the kernel (in fact there is no kernel!), To run this example type

<pre> localhost:>yambo -F Inputs/02_RPA_no_LF -J 02_RPA_no_LF
</pre>
The optional ''-J'' flag is used to label the output/report/log files.
In ''Inputs/03_RPA_LF'' we include a kernel in the Hartree approximation. This correspond to the Random-Phase-Approximation (RPA). The response function size is changed to 51 RL. This means including Local Field Effects corresponding to charge oscillations expanded up to the 51st RL component. The converged value for ''NGsBlkXd'' shall be determined by doing several calculations with different values and checking the effect on the final physical result (the absorption spectrum, in this case).

After having run

<pre> localhost:>yambo -F Inputs/03_RPA_LF -J 03_RPA_LF
</pre>
we can compare the result of our calculations with the experimental curve (that you find in the ''Experiment'' folder).

[[File:LiF_02_03.png|512x384px
]]

The comparison with the experiment clearly show that the RPA is not at all adequate in the case of LiF. We notice two main discrepancies between theory and experiment: the RPA absorption onset is too low and the shape lacks the sharp peak observed experimentally at around 12 eV. The onset position can be artificially corrected using a scissor operator (representing the QP gap correction) of 5.19 eV that simply opens rigidly the LDA gap. This is shown in ''Inputs/03_RPA_LF_QP'' with the line

<pre>% XfnQP_E
5.190000 | 1.000000 | 1.000000 | # [EXTQP Xd] E parameters (c/v)
%</pre>
The resulting spectrum fits better with the experiment but now there seems to be an even more serious problem:

[[File:LiF_03.png|512x384px]]

there is an experimental peak well below the QP absorption onset:

an [http://en.wikipedia.org/wiki/Exciton EXCITON!]

[[File:LiF_exciton.jpg|160x202px]]


= ALDA (yambo -o c -k alda) =

Our first attempt to go beyond RPA is using TDDFT in the Adiabatic LDA approximation. Depending on the exchange-correlation(xc) functional used in the ground state calculation yambo will produce a corresponding xc-kernel. In this case, as reported by the ''a2y'' command we are using a Perdew Wang parametrization.

Running

<pre> localhost:>yambo -F Inputs/04_alda_g_space -J 04_alda_g_space</pre>
we get

[[File:LiF_04.png|512x384px]]

Unfortunately ALDA only slightly changes the RPA result. The situation will change in more isolated system (reduced dimensionality).


=The Statically screened Electron-electron interaction(yambo -b) =

As simple RPA and ALDA approximations have not described correctly the experimental spectrum we have to move towards more elaborate techniques like the Bethe-Salpeter (BS) equation.

A key ingredient in the BS kernel is the electron-electron interaction commonly evaluated in the static approximation. The input file ''Inputs/05_W'' describes how to calculate it. The variables used in this input file have the same physical meaning of those used in the optical absorption calculation. The only difference is that, in general, the response function dimension obtained in the examples (03-04), gives an upper bound to the number of RL vectors needed here. This is because the size of response matrix in an RPA calculation defines also the size of the Hartree potential, whose short-range components are not screened. In the present case, instead, the electron-electron interaction is screened and, for this reason, the RL vectors needed are considerably smaller than in the RPA case. So let's type (no ''-J'' option here) ...

<pre> localhost:>yambo -F Inputs/05_W </pre>
... and after waiting for some minutes the result, that is the database SAVE/ndb.em1s. Do not use the ''-J'' option here as we will need to read this database in the next examples.


=The Bethe-Salpeter equation, Excitons (yambo -o b -k sex -y h) =

The input file ''Inputs/06_BSE'' describes how to calculate an excitonic absorption spectrum, by solving the BS equation using the recursive Haydock Method. Before running ''yambo'' we must have a closer look at the input file:

The line
<pre>% KfnQP_E
5.80000 | 1.000000 | 1.000000 | # [EXTQP BSK BSS] E parameters (c/v)
%</pre>
applies a 5.8 eV scissor in order to open the LDA gap.
<pre>BSKmod= "SEX" # [BSE] IP/Hartree/HF/ALDA/SEX</pre>
Here we are using the screened exchange (SEX) approximation for the kernel that includes both exchange and correlation terms
<pre>% BSEBands
2 | 7 | # [BSK] Bands range
%
BSENGBlk= 51 RL # [BSK] Screened interaction block size
BSENGexx= 773 RL # [BSK] Exchange components</pre>
Here we specify the range of bands to be used and the RL components for the screened interaction (51) (read from the ndb.em1s file) and for the Hartree term (773, the maximal available). '''Remember''' that the BS kernel is written in Bloch space and its size is given by

<pre>BS kernel size = Valence Bands × Conduction Bands × K-points in the whole BZ</pre>
In our case the size is 2304. The BS bands range must be converged with care trying to keep as a few bands as possible.
Running

<pre> localhost:>yambo -F Inputs/06_BSE -J 06_BSE</pre>
will calculate the BS kernel and store in in the ''06_BSE'' folder. Before analyzing the BS absorption spectrum we can edit the log file ''l-06_BSE_optics_bse_bss'' to observe the on-the-fly live timing feature of yambo:

<pre> [...]
<---> BSK | | [000%] --(E) --(X)
<05s> BSK |# | [007%] 05s(E) 01m-07s(X)
<11s> BSK |### | [015%] 10s(E) 01m-06s(X)
[...]
<01m-02s> BSK |################## | [093%] 01m-01s(E) 01m-06s(X)
<01m-07s> BSK |####################| [100%] 01m-06s(E) 01m-06s(X)
[...]</pre>
The two numbers at the end of each line represents the elapsed time(E) and the expected time(X). The latter estimates the time needed to complete that particular section (the BS kernel construction in this case).

Finally we can compare the resulting BS optical absorption with the experimental result. We see how strong is the excitonic effect, if compared to the RPA calculation. The BS equation is, then, able to describe the bound electron-hole state responsible for the peak observed experimentally below the QP gap.

[[File:LiF_06.png|512x384px
]]


=A Bethe-Salpeter based Fxc(yambo -o c -k lrc) =

As for TDDFT we might be a little bit disappointed at this stage as the only method that yields a reasonable absorption spectrum for LiF is based on MBPT. It is possible, however, to extract from the BS kernel a possible approximation for the xc-kernel. This approach is efficient, but is far too complicated, and requires the prior computation of the BS kernel. An alternative possibility is to use a simple Long Range Component model, as introduced in [[#Reining|Reining]]. In this model, the yambo input file ''Inputs/07_LRC'' describes a model where

[[File:LiF_PIC_LiF_equations-14.png|190x55px]]
with F0= ''LRC_alpha''=-8.7.

[[File:LiF_07.png|512x384px
]]

We see from the previous figure that the agreement with the BS calculation is not very good. Nevertheless this simple model captures the presence of an exciton and works quite well for a large number of simple semiconductors, as show in [[#silvana|Botti]]:

[[File:F_silvana.png|371x352px]]


= Additional Exercises =

<ol>
<li>Calculate the absorption spectra like in section [[#02|02]]-[[#03|03]] increasing the polarization RL size, the polarization bands to find the converged values.</li>
<li>Plot the EELS spectrum obtained in section [[#02|02]]-[[#03|03]] and check the effect of increasing the polarization bands. Do a resonant only calculation (using the -V option) to see that the EELS cannot be described using only the resonant part of the response function.</li>
<li>See the effect of using a denser BZ sampling grid running Abinit with, for example
<pre>ngkpt2 6 6 6</pre></li>
<li>Repeat the [[#06|BSE]] calculation increasing the bands.</li>
<li>Calculate the [[#06|BSE]] spectrum using a diagonal only interaction.</li></ol>

= References =

<ref name="wikipedia"> [http://en.wikipedia.org/wiki/Lithium_fluoride LiF on wikipedia].
</ref><ref name="rholf"> M. Rohlfing, S. Louie, Phys. Rev. Lett. '''81''', 2312 (2000).
</ref><ref name="p1"> A. Marini, R. Del Sole, and A. Rubio, Phys. Rev. Lett., '''91''', 256402 (2003),G. Adragna, R. Del Sole, and A. Marini, Phys. Rev. B '''68''', 165108 (2003), F. Sottile, V. Olevano, and L. Reining, Phys. Rev. Lett. '''91''', 056402 (2003).
</ref><ref name="Reining"> Reining, V. Olevano, A. Rubio, and G. Onida, Phys. Rev. Lett. '''88''', 066404 (2002).
</ref><ref name="silvana"> S. Botti, Phys. Rev. B '''69''', 155112 (2004).
</ref>

Some hints on github

2022-01-07T10:53:04Z

ElenaCannuccia:

1) The easiest way to switch branch on Git is : git checkout <desired_branch>
2) Before starting working on your own code/branch type '''git pull''', to ensure that your work will be later merged to the updated version of the code.

3) Whenever you edit subroutines and other files, and if you desire that your changes do not get lost, prepare a commit file.
*) In order to set the proper layout for the commit type ./sbin/git_configure_and_hooks.sh
*) Then type: '''git commit -a'''
*) Edit the file accordingly, pointing out your most important changes.

4) '''Git push''', is the command to save a record of your work.

5) If you are interested in comparing your last downloaded version of the branch with a previous one, type
git log | less → you will have a list of modified files and identify the “long alphanumerical string” on the right of the word commit.
git diff "long alphanumerical string” > a → It is better to redirect the outcome to a file called here “a”

How to create a new project in Yambo

2021-06-18T07:31:58Z

ElenaCannuccia:

If you are about to start a new project with Yambo, you will be interested in knowing how to move the first steps in the code:

1) Edit the file config/mk/targets.mk

In the following '''np''' stands for your new project. NP_PROJ = yambo_'''np''' ypp_'''np'''

Choose two letters which will inequivocally identify your project. Example: "df" stands for "defects".
DF_PROJ = yambo_df ypp_df

2) Edit the file <code>config/mk/actions/compile_yambo.mk</code> and <code>config/mk/actions/compile_ypp.mk</code>
by adding the new executables:

yambo_df: ext-libs
@+LIBS2DO="$(INT_LIBS)"; DIR2GO="lib" ; VPATH="$(topdir)/lib" ; $(mk_internal_lib)
@+LIBS2DO="$(YLIBDRIVER)"; NAME="yambo_df_driver_"; DIR2GO="lib/yambo/driver/src"; VPATH="$(topdir)/lib/yambo/driver/src";\
ADF="-D_DF -D_SC -D_yambo"; $(mk_external_yambo_lib)
@+LIBS2DO="$(PJ_DFLIBS)"; XPATH="src"; VPATH="$(topdir)/src"; ADF="-D_DF -D_SC"; $(mk_src)
@+X2DO="yambo_df"; XPATH="driver"; VPATH="$(topdir)/driver"; XLIBS="$(PJ_DFLIBS_LD)" ; DRILIBS="$(YLIBDRIVER_LD)"; \
ADF="-D_DF -D_SC"; $(mk_yambo)

ypp_df: ext-libs
@+LIBS2DO="$(INT_LIBS)"; DIR2GO="lib" ; VPATH="$(topdir)/lib" ; $(mk_internal_lib)
@+LIBS2DO="$(YLIBDRIVER)"; NAME="ypp_df_driver_"; DIR2GO="lib/yambo/driver/src"; VPATH="$(topdir)/lib/yambo/driver/src"; \
ADF="-D_DF -D_SC -D_ypp"; $(mk_external_yambo_lib)
@+LIBS2DO="$(YPPDF_MAIN_LIBS)"; XPATH="src"; VPATH="$(topdir)/src"; ADF="-D_DF -D_SC "; $(mk_src)
@+LIBS2DO="$(YPP_LIBS)"; XPATH="ypp"; VPATH="$(topdir)/ypp"; ADF="-D_YPP_DF -D_YPP_SC"; $(mk_ypp_src)
@+X2DO="ypp_df"; XPATH="driver"; VPATH="$(topdir)/driver"; XLIBS="$(YPPDF_MAIN_LIBS_LD)"; \
X_ypp_LIBS="$(YPP_LIBS_LD)"; DRILIBS="$(YLIBDRIVER_LD)"; ADF="-D_YPP_DF -D_YPP_SC"; $(mk_ypp)

3) Edit the file <code>config/mk/libraries.mk</code> by adding the libraries you need for your project, for example in this example we will use the main libs, plus "hamiltonian" and "sc":

PJ_DFLIBS = $(MAIN_LIBS) collisions hamiltonian sc
PJ_DFLIBS_LD = $(MAIN_LIBS_LD) hamiltonian collisions sc

in the same you set also the libraries for ypp:

YPPDF_MAIN_LIBS = $(YPP_MAIN_LIBS) collisions hamiltonian sc
YPPDF_MAIN_LIBS_LD = $(YPP_MAIN_LIBS_LD) collisions hamiltonian sc

4) edit the file <code>driver/.objects</code>

objs = yambo.o
#if defined _ypp || _ypp_ph || _ypp_rt || _ypp_surf || _ypp_magnetic || _ypp_sc || _ypp_nl '''|| _ypp_df'''
objs = ypp.o
#endif

5) Edit the file: lib/yambo/driver/src/main/tool_init.c

#if defined _YPP_DF || defined _DF
pj="df";
#endif

How to create a new ypp interface

2021-06-18T07:29:57Z

ElenaCannuccia:

The choice for “section” and the “short_opt” comes from an analysis of the outcome of “ypp_df -h”

0) Adding an option in ypp.in input file:
Edit the file src/driver/options_ypp.c

#if defined _DF
*i_opt=*i_opt+1;
options[*i_opt].short_desc="Write_here_a_short_description_of_the_flag";
options[*i_opt].long_opt= "short_name_of_your_new_flag";
options[*i_opt].short_opt='d';
options[*i_opt].bin="associated_executable"; % for example ypp_df
options[*i_opt].yambo_string="short_name_of_your_new_flag";
options[*i_opt].section="Choose_your_section";
#endif

Imagine you want to create a new ypp interface, you will want to make some variables to appear in your new input file.

1) Edit the file ypp/modules/mod_YPP.F

logical :: l_defects
character(lchlen) :: superc_path

2) Initialize the non logical variable in ypp/modules/YPP_SET_defaults.F

#if defined _YPP_DF
!
superc_path='none'
!
#endif

3) Edit ypp/interface/INIT_load_ypp.F in order to instruct the code to switch on the flag in the ypp.in input file

#if defined _YPP_DF
use YPPm, ONLY:superc_path
#endif

#if defined _YPP_DF
call it(defs,'SupercPATH', 'Path to the supercell with defect',superc_path)
#endif

4) Edit ypp/interface/INIT_ypp.F

#if defined _YPP_DF
l_defects = trim(rstr_piece(i1)) == 'dsuperc'
#endif
Notice that ‘dsuperc’ has been introduced in options_ypp.c. So if the code “sees” this flag it associates .true. to the logical l_defects.

#if defined _YPP_DF
if (l_defects) call initactivate(1,'dsuperc')
#endif

#if defined _YPP_DF
l_defects=runlevel_is_on('dsuperc')
#endif

#if defined _YPP_DF
if(l_defects) call initactivate(1,"SupercPATH")
#endif

5) Create directory ypp/defects/ and the file .objects:

#if defined _YPP_DF
DF_objects = DEFECTS_driver.o
#endif
objs = $(DF_objects)

and then DEFECTS_driver.F:

subroutine DEFECTS_driver(en,k)
!
use R_lattice, ONLY:bz_samp
use electrons, ONLY:levels
!
#include<memory.h>
!
type(levels) :: en
type(bz_samp) :: k
end subroutine

Finally "git add defects".

YPPDF_LIBS = $(YPP_LIBS) defects
YPPDF_LIBS_LD = $(YPP_LIBS_LD) defects

Some hints on github

2021-05-17T14:35:55Z

ElenaCannuccia:

1) Before starting working on your own code/branch type '''git pull''', to ensure that your work will be later merged to the updated version of the code.

2) Whenever you edit subroutines and other files, and if you desire that your changes do not get lost, prepare a commit file.
*) In order to set the proper layout for the commit type ./sbin/git_configure_and_hooks.sh
*) Then type: '''git commit -a'''
*) Edit the file accordingly, pointing out your most important changes.

3) '''Git push''', is the command to save a record of your work.

4) If you are interested in comparing your last downloaded version of the branch with a previous one, type
git log | less → you will have a list of modified files and identify the “long alphanumerical string” on the right of the word commit.
git diff "long alphanumerical string” > a → It is better to redirect the outcome to a file called here “a”

Some hints on github

2021-05-17T14:32:42Z

ElenaCannuccia:

1) Whenever you edit subroutines and other files, and if you desire that your changes do not get lost, prepare a commit file.
*) In order to set the proper layout for the commit type ./sbin/git_configure_and_hooks.sh
*) Then type: '''git commit -a'''
*) Edit the file accordingly, pointing out your most important changes.

2) '''Git push''', is the command to save a record of your work.

3) Before starting working on your own code/branch type '''git pull''', to ensure that your work will be later merged to the updated version of the code.

4) If you are interested in comparing your last downloaded version of the branch with a previous one, type
git log | less → you will have a list of modified files and identify the “long alphanumerical string” on the right of the word commit.
git diff "long alphanumerical string” > a → It is better to redirect the outcome to a file called here “a”

Some hints on github

2021-05-17T14:30:59Z

ElenaCannuccia:

1) Whenever you edit subroutines and other files, and if you desire that your changes do not get lost, prepare a commit file.
*) In order to set the proper layout for the commit: ./sbin/git_configure_and_hooks.sh
*) Then type: git commit -a
*) Edit the file accordingly, pointing out your most important changes.

2) Git push, is the command to save a record of your work.

3) Before starting working on your own code/branch please type: git pull, to ensure that your work will be later merged to the updated version of the code.

4) If you are interested in comparing your last downloaded version of the branch with a previous one, type
git log | less → you will have a list of modified files and identify the “long alphanumerical string” on the right of the word commit.
git diff “long alphanumerical string” > a → It is better to redirect the outcome to a file called here “a”

Some hints on github

2021-05-17T14:28:07Z

ElenaCannuccia: Created page with "2) Whenever you edit subroutines and other files, and if you desire that your changes do not get lost, prepare a commit file. *) In order to set the proper layout for the comm..."

2) Whenever you edit subroutines and other files, and if you desire that your changes do not get lost, prepare a commit file.
*) In order to set the proper layout for the commit: ./sbin/git_configure_and_hooks.sh
*) Then type: git commit -a
*) Edit the file accordingly, pointing out your most important changes.

3) Git push, is the command to save a record of your work.

4) Before starting working on your own code/branch please type: git pull, to ensure that your work will be later merged to the updated version of the code.

5) If you are interested in comparing your last downloaded version of the branch with a previous one, type
git log | less → you will have a list of modified files and identify the “long alphanumerical string” on the right of the word commit.
git diff “long alphanumerical string” > a → It is better to redirect the outcome to a file called here “a”

Tutorials

2021-05-17T14:27:40Z

ElenaCannuccia:

If you are starting out with Yambo, or even an experienced user, we recommend that you complete the following tutorials before trying to use Yambo for your system.

The tutorials are meant to give some introductory background to the key concepts behind Yambo. Practical topics such as convergence are also discussed.
Nonetheless, users are invited to first read and study the [[lectures|background material]] in order to get familiar with the fundamental physical quantities.

Two kinds of tutorials are provided: '''stand-alone''' and '''modular'''.

== Tutorial files ==

The tutorial CORE databases can be obtained

* from the [[Yambo_Virtual_Machine|Yambo Virtual Machine]]
* from the Yambo web-page
* from the Yambo GIT tutorial repository

=== From the Yambo Virtual Machine (VM) ===
If you are using the VM, a recent version of the tutorial files is provided.Follow these [[Yambo_Virtual_Machine#Updating_the_Yambo_tutorial_files| instructions]] to update the tutorial files to the most recent version.

=== From the Yambo website ===
If you are using your own installation or the docker, the files needed to run the tutorials can be downloaded from the lists below.

After downloading the tar.gz files just unpack them in '''the YAMBO_TUTORIALS''' folder. For example
$ mkdir YAMBO_TUTORIALS
$ mv hBN.tar.gz YAMBO_TUTORIALS
$ cd YAMBO_TUTORIALS
$ tar -xvfz hBN.tar.gz
$ ls YAMBO_TUTORIALS
hBN

====Files needed for modular tutorials====
All of the following should be downloaded prior to following the modular tutorials: 
[http://www.yambo-code.org/educational/tutorials/files/hBN.tar.gz hBN.tar.gz],
[http://www.yambo-code.org/educational/tutorials/files/hBN-convergence-kpoints.tar.gz hBN-convergence-kpoints.tar.gz],
[http://www.yambo-code.org/educational/tutorials/files/hBN-2D.tar.gz hBN-2D.tar.gz],
[http://www.yambo-code.org/educational/tutorials/files/hBN-2D-para.tar.gz hBN-2D-para.tar.gz],
 
[http://www.yambo-code.org/educational/tutorials/files/hBN_DBs.tar.gz hBN_DBs.tar.gz],
[http://www.yambo-code.org/educational/tutorials/files/hBN-convergence-kpoints_DBs.tar.gz hBN-convergence-kpoints_DBs.tar.gz],
[http://www.yambo-code.org/educational/tutorials/files/hBN-2D_DBs.tar.gz hBN-2D_DBs.tar.gz],
[http://www.yambo-code.org/educational/tutorials/files/hBN-2D-para_DBs.tar.gz hBN-2D-para_DBs.tar.gz]

====Files needed for stand-alone tutorials====
At the start of each tutorial you will be told which specific file needs to be downloaded: 
[http://www.yambo-code.org/educational/tutorials/files/Silicon.tar.gz Silicon.tar.gz],
[http://www.yambo-code.org/educational/tutorials/files/LiF.tar.gz LiF.tar.gz]
 
[http://www.yambo-code.org/educational/tutorials/files/Silicon_DBs.tar.gz Silicon_DBs.tar.gz],
[http://www.yambo-code.org/educational/tutorials/files/LiF_DBs.tar.gz LiF_DBs.tar.gz],

[http://www.yambo-code.org/educational/tutorials/files/Aluminum.tar.gz Aluminum.tar.gz],

[http://www.yambo-code.org/educational/tutorials/files/Hydrogen_Chain.tar.gz Hydrogen_Chain.tar.gz]
 
[http://www.yambo-code.org/educational/tutorials/files/Aluminum_DBs.tar.gz Aluminum_DBs.tar.gz],
[http://www.yambo-code.org/educational/tutorials/files/Hydrogen_Chain_DBs.tar.gz Hydrogen_Chain_DBs.tar.gz]

=== From the Git Tutorial Repository (advanced users) ===
If you are using your own installation or the docker, the [https://github.com/yambo-code/tutorials tutorials repository] contains the updated tutorials CORE databases. To use it
$ git clone https://github.com/yambo-code/tutorials.git YAMBO_TUTORIALS
$ cd YAMBO_TUTORIALS
$ ./setup.pl -install

== Stand-alone tutorials ==

These tutorials are self-contained and cover a variety of mixed topics, both physical and methodological. They are designed to be followed from start to finish in one page and do not require previous knowledge of yambo. Each tutorial requires download of a specific core database, and typically they cover a specific physical system (like bulk GaSb or a hydrogen chain). Ground state input files and pseudopotentials are provided. Output files are also provided for reference.

These tutorials can be accessed directly from this page of from the side bar. They include different kind of subjects:

'''Warning''': These tutorials were prepared using previous version of the Yambo code: some command lines, variables, reports and outputs can be slightly different from the last version of the code. Scripts for parsing output cannot work anymore and should be edited to work with the new outputs. New command lines can be accessed typing <code>yambo -h </code>

=== Basic ===
* [[LiF|Linear Response in 3D. Excitons at work]]

* [[Silicon|GW convergence]]

=== Advanced ===
* [[Hydrogen chain|TDDFT Failure and long range correlations]]
* [[Linear response from real time simulations]]

==== GW and Quasi-particles ====

* [[Real_Axis_and_Lifetimes|Real Axis and Lifetimes]]
* [[Self-consistent GW on eigenvalues only]]

==== Electron phonon coupling ====
* [[Electron Phonon Coupling|Electron Phonon Coupling]]
* [[Optical properties at finite temperature]]

==== Non linear response ====

* [http://www.attaccalite.com/lumen/linear_response.html Linear response using Dynamical Berry phase]
* [[Real time approach to non-linear response]]
* [[Correlation effects in the non-linear response]]
* [http://www.attaccalite.com/lumen/thg_in_silicon.html Third Harmonic Generation]
* [http://www.attaccalite.com/lumen/spin_orbit.html Spin-orbit coupling and non-linear response]

==== Developing Yambo ====

* [[How to create a new project in Yambo]]
* [[How to create a new ypp interface]]
* [[Some hints on github]]




== Modular tutorials ==
These tutorials are designed to provide a deeper understanding of specific yambo tasks and runlevels. They are designed to avoid repetition of common procedures and physical concepts. As such, they make use of the same physical systems: bulk hexagonal boron nitride ''hBN'' and a hBN sheet ''hBN-2D''.

'''Warning''': These tutorials were prepared using previous version of the Yambo code: some command lines, variables, reports and outputs can be slightly different from the last version of the code. Scripts for parsing output cannot work anymore and should be edited to work with the new outputs. New command lines can be accessed typing <code>yambo -h </code>

====Introduction====
* [[First steps: a walk through from DFT to optical properties]]
====Quasiparticles in the GW approximation====
* [[How to obtain the quasi-particle band structure of a bulk material: h-BN]]
====Using Yambo in Parallel====
This modules contains very general discussions of the parallel environment of Yambo. Still the actual run of the code is specific to the CECAM cluster. If you want to run these modules just replace the parallel queue instructions with simple MPI commands.

* [[GW_parallel_strategies|Parallel GW (CECAM specific)]]: strategies for running Yambo in parallel
[[GW_parallel_strategies_CECAM]]
* [[Pushing_convergence_in_parallel|GW convergence (CECAM specific)]]: use Yambo in parallel to converge a GW calculation for a layer of hBN (hBN-2D)

====Excitons and the Bethe-Salpeter Equation====
* [[How to obtain an optical spectrum|Calculating optical spectra including excitonic effects: a step-by-step guide]]
* [[How to choose the input parameters|Obtaining a converged optical spectrum]]
* [[How to treat low dimensional systems|Many-body effects in low-dimensional systems: numerical issues and remedies]]
* [[How to analyse excitons|Analysis of excitonic spectra in a 2D material]]


====Yambo-python driver====
* [[First steps in Yambopy]]
* [[GW tutorial. Convergence and approximations (BN)]]
* [[Bethe-Salpeter equation tutorial. Optical absorption (BN)]]





=== Modules ===
Alternatively, users can learn more about a specific runlevel or task by looking at the individual '''[[Modules|documentation modules]]'''. These provide a focus on the input parameters, run time behaviour, and underlying physics. Although they can be followed separately, non-experts are urged to follow them as part of the more structured tutorials given above.

== Schools ==

* [[ICTP2020]]
* [[CECAM VIRTUAL 2021]]

How to create a new ypp interface

2021-05-07T21:41:33Z

ElenaCannuccia:

The choice for “section” and the “short_opt” comes from an analysis of the outcome of “ypp_df -h”

0) Adding an option in ypp.in input file:
Edit the file src/driver/options_ypp.c

#if defined _YPP_DF
*i_opt=*i_opt+1;
options[*i_opt].short_desc="Write_here_a_short_description_of_the_flag";
options[*i_opt].long_opt= "short_name_of_your_new_flag";
options[*i_opt].short_opt='d';
options[*i_opt].bin="associated_executable"; % for example ypp_df
options[*i_opt].yambo_string="short_name_of_your_new_flag";
options[*i_opt].section="Choose_your_section";
#endif

Imagine you want to create a new ypp interface, you will want to make some variables to appear in your new input file.

1) Edit the file ypp/modules/mod_YPP.F

logical :: l_defects
character(lchlen) :: superc_path

2) Initialize the non logical variable in ypp/modules/YPP_SET_defaults.F

#if defined _YPP_DF
!
superc_path='none'
!
#endif

3) Edit ypp/interface/INIT_load_ypp.F in order to instruct the code to switch on the flag in the ypp.in input file

#if defined _YPP_DF
use YPPm, ONLY:superc_path
#endif

#if defined _YPP_DF
call it(defs,'SupercPATH', 'Path to the supercell with defect',superc_path)
#endif

4) Edit ypp/interface/INIT_ypp.F

#if defined _YPP_DF
l_defects = trim(rstr_piece(i1)) == 'dsuperc'
#endif
Notice that ‘dsuperc’ has been introduced in options_ypp.c. So if the code “sees” this flag it associates .true. to the logical l_defects.

#if defined _YPP_DF
if (l_defects) call initactivate(1,'dsuperc')
#endif

#if defined _YPP_DF
l_defects=runlevel_is_on('dsuperc')
#endif

#if defined _YPP_DF
if(l_defects) call initactivate(1,"SupercPATH")
#endif

5) Create directory ypp/defects/ and the file .objects:

#if defined _YPP_DF
DF_objects = DEFECTS_driver.o
#endif
objs = $(DF_objects)

and then DEFECTS_driver.F:

subroutine DEFECTS_driver(en,k)
!
use R_lattice, ONLY:bz_samp
use electrons, ONLY:levels
!
#include<memory.h>
!
type(levels) :: en
type(bz_samp) :: k
end subroutine

Finally "git add defects".

YPPDF_LIBS = $(YPP_LIBS) defects
YPPDF_LIBS_LD = $(YPP_LIBS_LD) defects

How to create a new ypp interface

2021-05-07T21:40:59Z

ElenaCannuccia:

The choice for “section” and the “short_opt” comes from an analysis of the outcome of “ypp_df -h”

0) Adding an option in ypp.in input file:
Edit the file src/driver/options_ypp.c

#if defined _YPP_DF
*i_opt=*i_opt+1;
options[*i_opt].short_desc="Write_here_a_short_description_of_the_flag";
options[*i_opt].long_opt= "short_name_of_your_new_flag";
options[*i_opt].short_opt='d';
options[*i_opt].bin="associated_executable"; % for example ypp_df
options[*i_opt].yambo_string="short_name_of_your_new_flag";
options[*i_opt].section="Choose_your_section";
#endif

Imagine you want to create a new ypp interface, you will want to make some variables to appear in your new input file.

1) Edit the file ypp/modules/mod_YPP.F

logical :: l_defects
character(lchlen) :: superc_path

2) Initialize the non logical variable in ypp/modules/YPP_SET_defaults.F

#if defined _YPP_DF
!
superc_path='none'
!
#endif

3) Edit ypp/interface/INIT_load_ypp.F in order to instruct the code to switch on the flag in the ypp.in input file

#if defined _YPP_DF
use YPPm, ONLY:superc_path
#endif

#if defined _YPP_DF
call it(defs,'SupercPATH', 'Path to the supercell with defect',superc_path)
#endif

4) Edit ypp/interface/INIT_ypp.F

#if defined _YPP_DF
l_defects = trim(rstr_piece(i1)) == 'dsuperc'
#endif
Notice that ‘dsuperc’ has been introduced in options_ypp.c. So if the code “sees” this flag it associates .true. to the logical l_defects.

#if defined _YPP_DF
if (l_defects) call initactivate(1,'dsuperc')
#endif

#if defined _YPP_DF
l_defects=runlevel_is_on('dsuperc')
#endif

#if defined _YPP_DF
if(l_defects) call initactivate(1,"SupercPATH")
#endif

5) Create directory ypp/defects/ and the file .objects:

#if defined _YPP_DF
DF_objects = DEFECTS_driver.o
#endif
objs = $(DF_objects)

and then DEFECTS_driver.F:

subroutine DEFECTS_driver(en,k)
!
use R_lattice, ONLY:bz_samp
use electrons, ONLY:levels
!
#include<memory.h>
!
type(levels) :: en
type(bz_samp) :: k
end subroutine

Finally "git add defects".

YPPDF_LIBS = $(YPP_LIBS) defects
YPPDF_LIBS_LD = $(YPP_LIBS_LD) defects

How to create a new ypp interface

2021-05-07T21:39:51Z

ElenaCannuccia:

The choice for “section” and the “short_opt” comes from an analysis of the outcome of “ypp_df -h”

0) Adding an option in ypp.in input file:
Edit the file src/driver/options_ypp.c

#if defined _YPP_DF
*i_opt=*i_opt+1;
options[*i_opt].short_desc="Write_here_a_short_description_of_the_flag";
options[*i_opt].long_opt= "short_name_of_your_new_flag";
options[*i_opt].short_opt='d';
options[*i_opt].bin="associated_executable"; % for example ypp_df
options[*i_opt].yambo_string="short_name_of_your_new_flag";
options[*i_opt].section="Choose_your_section";
#endif

Imagine you want to create a new ypp interface, you will want to make some variables to appear in your new input file.

1) Edit the file ypp/modules/mod_YPP.F

logical :: l_defects
character(lchlen) :: superc_path

2) Initialize the non logical variable in ypp/modules/YPP_SET_defaults.F

#if defined _YPP_DF
!
superc_path='none'
!
#endif

3) Edit ypp/interface/INIT_load_ypp.F in order to instruct the code to switch on the flag in the ypp.in input file

#if defined _YPP_DF
use YPPm, ONLY:superc_path
#endif

#if defined _YPP_DF
call it(defs,'SupercPATH', 'Path to the supercell with defect',superc_path)
#endif

4) Edit ypp/interface/INIT_ypp.F

#if defined _YPP_DF
l_defects = trim(rstr_piece(i1)) == 'dsuperc'
#endif
Notice that ‘dsuperc’ has been introduced in options_ypp.c. So if the code “sees” this flag it associates .true. to the logical l_defects.

#if defined _YPP_DF
if (l_defects) call initactivate(1,'dsuperc')
#endif

#if defined _YPP_DF
l_defects=runlevel_is_on('dsuperc')
#endif

#if defined _YPP_DF
if(l_defects) call initactivate(1,"SupercPATH")
#endif

5) Create directory ypp/defects/ and the file .objects:

#if defined _YPP_DF
DF_objects = DEFECTS_driver.o
#endif
objs = $(DF_objects)

and then DEFECTS_driver.F:

subroutine DEFECTS_driver(en,k)
!
use R_lattice, ONLY:bz_samp
use electrons, ONLY:levels
!
#include<memory.h>
!
type(levels) :: en
type(bz_samp) :: k
end subroutine

Finally "git add defects".

YPPDF_LIBS = $(YPP_LIBS) defects
YPPDF_LIBS_LD = $(YPP_LIBS_LD) defects

How to create a new ypp interface

2021-05-07T21:34:37Z

ElenaCannuccia:

Imagine you want to create a new ypp interface, you will want to make some variables to appear in your new input file.

1) Edit the file ypp/modules/mod_YPP.F

logical :: l_defects
character(lchlen) :: superc_path

2) Initialize the non logical variable in ypp/modules/YPP_SET_defaults.F

#if defined _YPP_DF
!
superc_path='none'
!
#endif

3) Edit ypp/interface/INIT_load_ypp.F in order to instruct the code to switch on the flag in the ypp.in input file

#if defined _YPP_DF
use YPPm, ONLY:superc_path
#endif

#if defined _YPP_DF
call it(defs,'SupercPATH', 'Path to the supercell with defect',superc_path)
#endif

4) Edit ypp/interface/INIT_ypp.F

#if defined _YPP_DF
l_defects = trim(rstr_piece(i1)) == 'dsuperc'
#endif
Notice that ‘dsuperc’ has been introduced in options_ypp.c. So if the code “sees” this flag it associates .true. to the logical l_defects.

#if defined _YPP_DF
if (l_defects) call initactivate(1,'dsuperc')
#endif

#if defined _YPP_DF
l_defects=runlevel_is_on('dsuperc')
#endif

#if defined _YPP_DF
if(l_defects) call initactivate(1,"SupercPATH")
#endif

5) Create directory ypp/defects/ and the file .objects:

#if defined _YPP_DF
DF_objects = DEFECTS_driver.o
#endif
objs = $(DF_objects)

and then DEFECTS_driver.F:

subroutine DEFECTS_driver(en,k)
!
use R_lattice, ONLY:bz_samp
use electrons, ONLY:levels
!
#include<memory.h>
!
type(levels) :: en
type(bz_samp) :: k
end subroutine

Finally "git add defects".

YPPDF_LIBS = $(YPP_LIBS) defects
YPPDF_LIBS_LD = $(YPP_LIBS_LD) defects

How to create a new ypp interface

2021-05-07T21:32:21Z

ElenaCannuccia: Created page with "Imagine you want to create a new ypp interface, you will want to make some variables to appear in your new input file. 1) Edit the file ypp/modules/mod_YPP.F logical..."

Imagine you want to create a new ypp interface, you will want to make some variables to appear in your new input file.

1) Edit the file ypp/modules/mod_YPP.F

logical :: l_defects
character(lchlen) :: superc_path

2) Initialize the non logical variable in ypp/modules/YPP_SET_defaults.F

#if defined _YPP_DF
!
superc_path='none'
!
#endif

3) Edit ypp/interface/INIT_load_ypp.F in order to instruct the code to switch on the flag in the ypp.in input file

#if defined _YPP_DF
use YPPm, ONLY:superc_path
#endif

#if defined _YPP_DF
call it(defs,'SupercPATH', 'Path to the supercell with defect',superc_path)
#endif

4) Edit ypp/interface/INIT_ypp.F

#if defined _YPP_DF
l_defects = trim(rstr_piece(i1)) == 'dsuperc'
#endif
Notice that ‘dsuperc’ has been introduced in options_ypp.c. So if the code “sees” this flag it associates .true. to the logical l_defects.

#if defined _YPP_DF
if (l_defects) call initactivate(1,'dsuperc')
#endif

#if defined _YPP_DF
l_defects=runlevel_is_on('dsuperc')
#endif

#if defined _YPP_DF
if(l_defects) call initactivate(1,"SupercPATH")
#endif

5) Create directory ypp/defects/ and the file .objects:

#if defined _YPP_DF
DF_objects = DEFECTS_driver.o
#endif
objs = $(DF_objects)

and then DEFECTS_driver.F

Finally "git add defects".

YPPDF_LIBS = $(YPP_LIBS) defects
YPPDF_LIBS_LD = $(YPP_LIBS_LD) defects

Tutorials

2021-05-07T21:29:13Z

ElenaCannuccia:

If you are starting out with Yambo, or even an experienced user, we recommend that you complete the following tutorials before trying to use Yambo for your system.

The tutorials are meant to give some introductory background to the key concepts behind Yambo. Practical topics such as convergence are also discussed.
Nonetheless, users are invited to first read and study the [[lectures|background material]] in order to get familiar with the fundamental physical quantities.

Two kinds of tutorials are provided: '''stand-alone''' and '''modular'''.

== Tutorial files ==

The tutorial CORE databases can be obtained

* from the [[Yambo_Virtual_Machine|Yambo Virtual Machine]]
* from the Yambo web-page
* from the Yambo GIT tutorial repository

=== From the Yambo Virtual Machine (VM) ===
If you are using the VM, a recent version of the tutorial files is provided.Follow these [[Yambo_Virtual_Machine#Updating_the_Yambo_tutorial_files| instructions]] to update the tutorial files to the most recent version.

=== From the Yambo website ===
If you are using your own installation or the docker, the files needed to run the tutorials can be downloaded from the lists below.

After downloading the tar.gz files just unpack them in '''the YAMBO_TUTORIALS''' folder. For example
$ mkdir YAMBO_TUTORIALS
$ mv hBN.tar.gz YAMBO_TUTORIALS
$ cd YAMBO_TUTORIALS
$ tar -xvfz hBN.tar.gz
$ ls YAMBO_TUTORIALS
hBN

====Files needed for modular tutorials====
All of the following should be downloaded prior to following the modular tutorials: 
[http://www.yambo-code.org/educational/tutorials/files/hBN.tar.gz hBN.tar.gz],
[http://www.yambo-code.org/educational/tutorials/files/hBN-convergence-kpoints.tar.gz hBN-convergence-kpoints.tar.gz],
[http://www.yambo-code.org/educational/tutorials/files/hBN-2D.tar.gz hBN-2D.tar.gz],
[http://www.yambo-code.org/educational/tutorials/files/hBN-2D-para.tar.gz hBN-2D-para.tar.gz],
 
[http://www.yambo-code.org/educational/tutorials/files/hBN_DBs.tar.gz hBN_DBs.tar.gz],
[http://www.yambo-code.org/educational/tutorials/files/hBN-convergence-kpoints_DBs.tar.gz hBN-convergence-kpoints_DBs.tar.gz],
[http://www.yambo-code.org/educational/tutorials/files/hBN-2D_DBs.tar.gz hBN-2D_DBs.tar.gz],
[http://www.yambo-code.org/educational/tutorials/files/hBN-2D-para_DBs.tar.gz hBN-2D-para_DBs.tar.gz]

====Files needed for stand-alone tutorials====
At the start of each tutorial you will be told which specific file needs to be downloaded: 
[http://www.yambo-code.org/educational/tutorials/files/Silicon.tar.gz Silicon.tar.gz],
[http://www.yambo-code.org/educational/tutorials/files/LiF.tar.gz LiF.tar.gz]
 
[http://www.yambo-code.org/educational/tutorials/files/Silicon_DBs.tar.gz Silicon_DBs.tar.gz],
[http://www.yambo-code.org/educational/tutorials/files/LiF_DBs.tar.gz LiF_DBs.tar.gz],

[http://www.yambo-code.org/educational/tutorials/files/Aluminum.tar.gz Aluminum.tar.gz],

[http://www.yambo-code.org/educational/tutorials/files/Hydrogen_Chain.tar.gz Hydrogen_Chain.tar.gz]
 
[http://www.yambo-code.org/educational/tutorials/files/Aluminum_DBs.tar.gz Aluminum_DBs.tar.gz],
[http://www.yambo-code.org/educational/tutorials/files/Hydrogen_Chain_DBs.tar.gz Hydrogen_Chain_DBs.tar.gz]

=== From the Git Tutorial Repository (advanced users) ===
If you are using your own installation or the docker, the [https://github.com/yambo-code/tutorials tutorials repository] contains the updated tutorials CORE databases. To use it
$ git clone https://github.com/yambo-code/tutorials.git YAMBO_TUTORIALS
$ cd YAMBO_TUTORIALS
$ ./setup.pl -install

== Stand-alone tutorials ==

These tutorials are self-contained and cover a variety of mixed topics, both physical and methodological. They are designed to be followed from start to finish in one page and do not require previous knowledge of yambo. Each tutorial requires download of a specific core database, and typically they cover a specific physical system (like bulk GaSb or a hydrogen chain). Ground state input files and pseudopotentials are provided. Output files are also provided for reference.

These tutorials can be accessed directly from this page of from the side bar. They include different kind of subjects:

'''Warning''': These tutorials were prepared using previous version of the Yambo code: some command lines, variables, reports and outputs can be slightly different from the last version of the code. Scripts for parsing output cannot work anymore and should be edited to work with the new outputs. New command lines can be accessed typing <code>yambo -h </code>

=== Basic ===
* [[LiF|Linear Response in 3D. Excitons at work]]

* [[Silicon|GW convergence]]

=== Advanced ===
* [[Hydrogen chain|TDDFT Failure and long range correlations]]
* [[Linear response from real time simulations]]

==== GW and Quasi-particles ====

* [[Real_Axis_and_Lifetimes|Real Axis and Lifetimes]]
* [[Self-consistent GW on eigenvalues only]]

==== Electron phonon coupling ====
* [[Electron Phonon Coupling|Electron Phonon Coupling]]
* [[Optical properties at finite temperature]]

==== Non linear response ====

* [http://www.attaccalite.com/lumen/linear_response.html Linear response using Dynamical Berry phase]
* [[Real time approach to non-linear response]]
* [[Correlation effects in the non-linear response]]
* [http://www.attaccalite.com/lumen/thg_in_silicon.html Third Harmonic Generation]
* [http://www.attaccalite.com/lumen/spin_orbit.html Spin-orbit coupling and non-linear response]

==== Developing Yambo ====

* [[How to create a new project in Yambo]]
* [[How to create a new ypp interface]]




== Modular tutorials ==
These tutorials are designed to provide a deeper understanding of specific yambo tasks and runlevels. They are designed to avoid repetition of common procedures and physical concepts. As such, they make use of the same physical systems: bulk hexagonal boron nitride ''hBN'' and a hBN sheet ''hBN-2D''.

'''Warning''': These tutorials were prepared using previous version of the Yambo code: some command lines, variables, reports and outputs can be slightly different from the last version of the code. Scripts for parsing output cannot work anymore and should be edited to work with the new outputs. New command lines can be accessed typing <code>yambo -h </code>

====Introduction====
* [[First steps: a walk through from DFT to optical properties]]
====Quasiparticles in the GW approximation====
* [[How to obtain the quasi-particle band structure of a bulk material: h-BN]]
====Using Yambo in Parallel====
This modules contains very general discussions of the parallel environment of Yambo. Still the actual run of the code is specific to the CECAM cluster. If you want to run these modules just replace the parallel queue instructions with simple MPI commands.

* [[GW_parallel_strategies|Parallel GW (CECAM specific)]]: strategies for running Yambo in parallel
[[GW_parallel_strategies_CECAM]]
* [[Pushing_convergence_in_parallel|GW convergence (CECAM specific)]]: use Yambo in parallel to converge a GW calculation for a layer of hBN (hBN-2D)

====Excitons and the Bethe-Salpeter Equation====
* [[How to obtain an optical spectrum|Calculating optical spectra including excitonic effects: a step-by-step guide]]
* [[How to choose the input parameters|Obtaining a converged optical spectrum]]
* [[How to treat low dimensional systems|Many-body effects in low-dimensional systems: numerical issues and remedies]]
* [[How to analyse excitons|Analysis of excitonic spectra in a 2D material]]


====Yambo-python driver====
* [[First steps in Yambopy]]
* [[GW tutorial. Convergence and approximations (BN)]]
* [[Bethe-Salpeter equation tutorial. Optical absorption (BN)]]





=== Modules ===
Alternatively, users can learn more about a specific runlevel or task by looking at the individual '''[[Modules|documentation modules]]'''. These provide a focus on the input parameters, run time behaviour, and underlying physics. Although they can be followed separately, non-experts are urged to follow them as part of the more structured tutorials given above.

== Schools ==

* [[ICTP2020]]
* [[CECAM VIRTUAL 2021]]

How to create a new project in Yambo

2021-05-07T12:53:53Z

ElenaCannuccia:

If you are about to start a new project with Yambo, you will be interested in knowing how to move the first steps in the code:

1) Edit the file config/mk/targets.mk

In the following '''np''' stands for your new project. NP_PROJ = yambo_'''np''' ypp_'''np'''

Choose two letters which will inequivocally identify your project. Example: "df" stands for "defects".
DF_PROJ = yambo_df ypp_df

2) Edit the file <code>config/mk/actions/compile_yambo.mk</code> and <code>config/mk/actions/compile_ypp.mk</code>
by adding the new executables:

yambo_df: ext-libs
@+LIBS2DO="$(INT_LIBS)"; DIR2GO="lib" ; VPATH="$(topdir)/lib" ; $(mk_internal_lib)
@+LIBS2DO="$(YLIBDRIVER)"; NAME="yambo_df_driver_"; DIR2GO="lib/yambo/driver/src"; VPATH="$(topdir)/lib/yambo/driver/src";\
ADF="-D_DF -D_SC -D_yambo"; $(mk_external_yambo_lib)
@+LIBS2DO="$(PJ_DFLIBS)"; XPATH="src"; VPATH="$(topdir)/src"; ADF="-D_DF -D_SC"; $(mk_src)
@+X2DO="yambo_df"; XPATH="driver"; VPATH="$(topdir)/driver"; XLIBS="$(PJ_DFLIBS_LD)" ; DRILIBS="$(YLIBDRIVER_LD)"; \
ADF="-D_DF -D_SC"; $(mk_yambo)

ypp_df: ext-libs
@+LIBS2DO="$(INT_LIBS)"; DIR2GO="lib" ; VPATH="$(topdir)/lib" ; $(mk_internal_lib)
@+LIBS2DO="$(YLIBDRIVER)"; NAME="ypp_df_driver_"; DIR2GO="lib/yambo/driver/src"; VPATH="$(topdir)/lib/yambo/driver/src"; \
ADF="-D_DF -D_SC -D_ypp"; $(mk_external_yambo_lib)
@+LIBS2DO="$(YPPDF_MAIN_LIBS)"; XPATH="src"; VPATH="$(topdir)/src"; ADF="-D_DF -D_SC "; $(mk_src)
@+LIBS2DO="$(YPP_LIBS)"; XPATH="ypp"; VPATH="$(topdir)/ypp"; ADF="-D_YPP_DF"; $(mk_ypp_src)
@+X2DO="ypp_df"; XPATH="driver"; VPATH="$(topdir)/driver"; XLIBS="$(YPPDF_MAIN_LIBS_LD)"; \
X_ypp_LIBS="$(YPP_LIBS_LD)"; DRILIBS="$(YLIBDRIVER_LD)"; ADF="-D_YPP_DF"; $(mk_ypp)

3) Edit the file <code>config/mk/libraries.mk</code> by adding the libraries you need for your project, for example in this example we will use the main libs, plus "hamiltonian" and "sc":

PJ_DFLIBS = $(MAIN_LIBS) collisions hamiltonian sc
PJ_DFLIBS_LD = $(MAIN_LIBS_LD) hamiltonian collisions sc

in the same you set also the libraries for ypp:

YPPDF_MAIN_LIBS = $(YPP_MAIN_LIBS) collisions hamiltonian sc
YPPDF_MAIN_LIBS_LD = $(YPP_MAIN_LIBS_LD) collisions hamiltonian sc

4) edit the file <code>driver/.objects</code>

objs = yambo.o
#if defined _ypp || _ypp_ph || _ypp_rt || _ypp_surf || _ypp_magnetic || _ypp_sc || _ypp_nl '''|| _ypp_df'''
objs = ypp.o
#endif

5) Edit the file: lib/yambo/driver/src/main/tool_init.c

#if defined _YPP_DF || defined _DF
pj="df";
#endif

How to create a new project in Yambo

2021-05-07T12:53:27Z

ElenaCannuccia:

If you are about to start a new project with Yambo, you will be interested in knowing how to move the first steps in the code:

1) Edit the file config/mk/targets.mk

In the following '''np''' stands for your new project. NP_PROJ = yambo_'''np''' ypp_'''np'''

Choose two letters which will inequivocally identify your project. Example: "df" stands for "defects".
DF_PROJ = yambo_df ypp_df

2) Edit the file <code>config/mk/actions/compile_yambo.mk</code> and <code>config/mk/actions/compile_ypp.mk</code>
by adding the new executables:

yambo_df: ext-libs
@+LIBS2DO="$(INT_LIBS)"; DIR2GO="lib" ; VPATH="$(topdir)/lib" ; $(mk_internal_lib)
@+LIBS2DO="$(YLIBDRIVER)"; NAME="yambo_df_driver_"; DIR2GO="lib/yambo/driver/src"; VPATH="$(topdir)/lib/yambo/driver/src";\
ADF="-D_DF -D_SC -D_yambo"; $(mk_external_yambo_lib)
@+LIBS2DO="$(PJ_DFLIBS)"; XPATH="src"; VPATH="$(topdir)/src"; ADF="-D_DF -D_SC"; $(mk_src)
@+X2DO="yambo_df"; XPATH="driver"; VPATH="$(topdir)/driver"; XLIBS="$(PJ_DFLIBS_LD)" ; DRILIBS="$(YLIBDRIVER_LD)"; \
ADF="-D_DF -D_SC"; $(mk_yambo)

ypp_df: ext-libs
@+LIBS2DO="$(INT_LIBS)"; DIR2GO="lib" ; VPATH="$(topdir)/lib" ; $(mk_internal_lib)
@+LIBS2DO="$(YLIBDRIVER)"; NAME="ypp_df_driver_"; DIR2GO="lib/yambo/driver/src"; VPATH="$(topdir)/lib/yambo/driver/src"; \
ADF="-D_DF -D_SC -D_ypp"; $(mk_external_yambo_lib)
@+LIBS2DO="$(YPPDF_MAIN_LIBS)"; XPATH="src"; VPATH="$(topdir)/src"; ADF="-D_DF -D_SC "; $(mk_src)
@+LIBS2DO="$(YPP_LIBS)"; XPATH="ypp"; VPATH="$(topdir)/ypp"; ADF="-D_YPP_DF"; $(mk_ypp_src)
@+X2DO="ypp_df"; XPATH="driver"; VPATH="$(topdir)/driver"; XLIBS="$(YPPDF_MAIN_LIBS_LD)"; \
X_ypp_LIBS="$(YPP_LIBS_LD)"; DRILIBS="$(YLIBDRIVER_LD)"; ADF="-D_YPP_DF"; $(mk_ypp)

3) Edit the file <code>config/mk/libraries.mk</code> by adding the libraries you need for your project, for example in this example we will use the main libs, plus "hamiltonian" and "sc":

PJ_DFLIBS = $(MAIN_LIBS) collisions hamiltonian sc
PJ_DFLIBS_LD = $(MAIN_LIBS_LD) hamiltonian collisions sc

in the same you set also the libraries for ypp:

YPPDF_MAIN_LIBS = $(YPP_MAIN_LIBS) collisions hamiltonian sc
YPPDF_MAIN_LIBS_LD = $(YPP_MAIN_LIBS_LD) collisions hamiltonian sc

4) edit the file <code>driver/.objects</code>

objs = yambo.o
#if defined _ypp || _ypp_ph || _ypp_rt || _ypp_surf || _ypp_magnetic || _ypp_sc || _ypp_nl '''|| _ypp_df'''
objs = ypp.o
#endif

5) Edit the file: lib/yambo/driver/src/main/tool_init.c
#if defined _YPP_DF || defined _DF
pj="df";
#endif

How to create a new project in Yambo

2021-05-07T12:50:34Z

ElenaCannuccia:

If you are about to start a new project with Yambo, you will be interested in knowing how to move the first steps in the code:

1) Edit the file config/mk/targets.mk

In the following '''np''' stands for your new project. NP_PROJ = yambo_'''np''' ypp_'''np'''

Choose two letters which will inequivocally identify your project. Example: "df" stands for "defects".
DF_PROJ = yambo_df ypp_df

2) Edit the file <code>config/mk/actions/compile_yambo.mk</code> and <code>config/mk/actions/compile_ypp.mk</code>
by adding the new executables:

yambo_df: ext-libs
@+LIBS2DO="$(INT_LIBS)"; DIR2GO="lib" ; VPATH="$(topdir)/lib" ; $(mk_internal_lib)
@+LIBS2DO="$(YLIBDRIVER)"; NAME="yambo_df_driver_"; DIR2GO="lib/yambo/driver/src"; VPATH="$(topdir)/lib/yambo/driver/src";\
ADF="-D_DF -D_SC -D_yambo"; $(mk_external_yambo_lib)
@+LIBS2DO="$(PJ_DFLIBS)"; XPATH="src"; VPATH="$(topdir)/src"; ADF="-D_DF -D_SC"; $(mk_src)
@+X2DO="yambo_df"; XPATH="driver"; VPATH="$(topdir)/driver"; XLIBS="$(PJ_DFLIBS_LD)" ; DRILIBS="$(YLIBDRIVER_LD)"; \
ADF="-D_DF -D_SC"; $(mk_yambo)

ypp_df: ext-libs
@+LIBS2DO="$(INT_LIBS)"; DIR2GO="lib" ; VPATH="$(topdir)/lib" ; $(mk_internal_lib)
@+LIBS2DO="$(YLIBDRIVER)"; NAME="ypp_df_driver_"; DIR2GO="lib/yambo/driver/src"; VPATH="$(topdir)/lib/yambo/driver/src"; \
ADF="-D_DF -D_SC -D_ypp"; $(mk_external_yambo_lib)
@+LIBS2DO="$(YPPDF_MAIN_LIBS)"; XPATH="src"; VPATH="$(topdir)/src"; ADF="-D_DF -D_SC "; $(mk_src)
@+LIBS2DO="$(YPP_LIBS)"; XPATH="ypp"; VPATH="$(topdir)/ypp"; ADF="-D_YPP_DF"; $(mk_ypp_src)
@+X2DO="ypp_df"; XPATH="driver"; VPATH="$(topdir)/driver"; XLIBS="$(YPPDF_MAIN_LIBS_LD)"; \
X_ypp_LIBS="$(YPP_LIBS_LD)"; DRILIBS="$(YLIBDRIVER_LD)"; ADF="-D_YPP_DF"; $(mk_ypp)

3) Edit the file <code>config/mk/libraries.mk</code> by adding the libraries you need for your project, for example in this example we will use the main libs, plus "hamiltonian" and "sc":

PJ_DFLIBS = $(MAIN_LIBS) collisions hamiltonian sc
PJ_DFLIBS_LD = $(MAIN_LIBS_LD) hamiltonian collisions sc

in the same you set also the libraries for ypp:

YPPDF_MAIN_LIBS = $(YPP_MAIN_LIBS) collisions hamiltonian sc
YPPDF_MAIN_LIBS_LD = $(YPP_MAIN_LIBS_LD) collisions hamiltonian sc

4) edit the file <code>driver/.objects</code>

objs = yambo.o
#if defined _ypp || _ypp_ph || _ypp_rt || _ypp_surf || _ypp_magnetic || _ypp_sc || _ypp_nl '''|| _ypp_df'''
objs = ypp.o
#endif

How to create a new project in Yambo

2021-05-07T12:33:56Z

ElenaCannuccia:

If you are about to start a new project with Yambo, you will be interested in knowing how to move the first steps in the code:

1) Edit the file config/mk/targets.mk

In the following '''np''' stands for your new project. NP_PROJ = yambo_'''np''' ypp_'''np'''

Choose two letters which will inequivocally identify your project. Example: "df" stands for "defects".
DF_PROJ = yambo_df ypp_df

2) Edit the file <code>config/mk/actions/compile_yambo.mk</code> and <code>config/mk/actions/compile_ypp.mk</code>
by adding the new executables:

yambo_df: ext-libs
@+LIBS2DO="$(INT_LIBS)"; DIR2GO="lib" ; VPATH="$(topdir)/lib" ; $(mk_internal_lib)
@+LIBS2DO="$(YLIBDRIVER)"; NAME="yambo_df_driver_"; DIR2GO="lib/yambo/driver/src"; VPATH="$(topdir)/lib/yambo/driver/src";\
ADF="-D_DEFECTS -D_SC -D_yambo"; $(mk_external_yambo_lib)
@+LIBS2DO="$(PJ_DFLIBS)"; XPATH="src"; VPATH="$(topdir)/src"; ADF="-D_DEFECTS -D_SC"; $(mk_src)
@+X2DO="yambo_df"; XPATH="driver"; VPATH="$(topdir)/driver"; XLIBS="$(PJ_DFLIBS_LD)" ; DRILIBS="$(YLIBDRIVER_LD)"; \
ADF="-D_DEFECTS -D_SC"; $(mk_yambo)

ypp_df: ext-libs
@+LIBS2DO="$(INT_LIBS)"; DIR2GO="lib" ; VPATH="$(topdir)/lib" ; $(mk_internal_lib)
@+LIBS2DO="$(YLIBDRIVER)"; NAME="ypp_df_driver_"; DIR2GO="lib/yambo/driver/src"; VPATH="$(topdir)/lib/yambo/driver/src"; \
ADF="-D_DEFECTS -D_SC -D_ypp"; $(mk_external_yambo_lib)
@+LIBS2DO="$(YPPDF_MAIN_LIBS)"; XPATH="src"; VPATH="$(topdir)/src"; ADF="-D_DEFECTS -D_SC "; $(mk_src)
@+LIBS2DO="$(YPP_LIBS)"; XPATH="ypp"; VPATH="$(topdir)/ypp"; ADF="-D_YPP_DEFECTS"; $(mk_ypp_src)
@+X2DO="ypp_df"; XPATH="driver"; VPATH="$(topdir)/driver"; XLIBS="$(YPPDF_MAIN_LIBS_LD)"; \
X_ypp_LIBS="$(YPP_LIBS_LD)"; DRILIBS="$(YLIBDRIVER_LD)"; ADF="-D_YPP_DEFECTS"; $(mk_ypp)

3) Edit the file <code>config/mk/libraries.mk</code> by adding the libraries you need for your project, for example in this example we will use the main libs, plus "hamiltonian" and "sc":

PJ_DFLIBS = $(MAIN_LIBS) collisions hamiltonian sc
PJ_DFLIBS_LD = $(MAIN_LIBS_LD) hamiltonian collisions sc

in the same you set also the libraries for ypp:

YPPDF_MAIN_LIBS = $(YPP_MAIN_LIBS) collisions hamiltonian sc
YPPDF_MAIN_LIBS_LD = $(YPP_MAIN_LIBS_LD) collisions hamiltonian sc

4) edit the file <code>driver/.objects</code>

objs = yambo.o
#if defined _ypp || _ypp_ph || _ypp_rt || _ypp_surf || _ypp_magnetic || _ypp_sc || _ypp_nl '''|| _ypp_df'''
objs = ypp.o
#endif

Developers Corner

2021-05-04T21:08:37Z

ElenaCannuccia: /* Development Repositories */

== Development Repositories ==
** [[Test-suite-simple|Test-suite (for dummies)]]
** [[Test-suite | Test-suite]]
** [[Benchmark-suite | Benchmark-suite]]
** [[Educational]]
* Special pages
** [[Special:AllPages | All Pages]]
** [[MediaWiki:Sidebar | Side Bar]]
** [[under construction | Html2Wiki HOWTO]]
** [[How to create a new project in Yambo]]
** [https://en.wikipedia.org/wiki/Help:Wikitext Wikitext Help]

== Reducing the size of the VM image ==
Open a terminal in the VM and type

sudo dd if=/dev/zero | pv | sudo dd of=/bigemptyfile bs=4096k
sudo rm -rf /bigemptyfile

How2NP

2021-05-04T21:07:57Z

ElenaCannuccia: ElenaCannuccia moved page How2NP to How to create a new project in Yambo: wrong title

#REDIRECT [[How to create a new project in Yambo]]

How to create a new project in Yambo

2021-05-04T21:07:57Z

ElenaCannuccia: ElenaCannuccia moved page How2NP to How to create a new project in Yambo: wrong title

1) Edit the file config/mk/targets.mk

In the following '''np''' stands for your new project. NP_PROJ = yambo_np ypp_np

Choose two letters which will inequivocally identify your project. Example: "df" stands for "defects".
DF_PROJ = yambo_df ypp_df

2) Edit the file '''config/mk/actions/compile_yambo.mk''' and '''config/mk/actions/compile_ypp.mk'''
by adding the new executables:

yambo_df: ext-libs
@+LIBS2DO="$(INT_LIBS)"; DIR2GO="lib" ; VPATH="$(topdir)/lib" ; $(mk_internal_lib)
@+LIBS2DO="$(YLIBDRIVER)"; NAME="yambo_df_driver_"; DIR2GO="lib/yambo/driver/src"; VPATH="$(topdir)/lib/yambo/driver/src";\
ADF="-D_DEFECTS -D_SC -D_yambo"; $(mk_external_yambo_lib)
@+LIBS2DO="$(PJ_DFLIBS)"; XPATH="src"; VPATH="$(topdir)/src"; ADF="-D_DEFECTS -D_SC"; $(mk_src)
@+X2DO="yambo_df"; XPATH="driver"; VPATH="$(topdir)/driver"; XLIBS="$(PJ_DFLIBS_LD)" ; DRILIBS="$(YLIBDRIVER_LD)"; \
ADF="-D_DEFECTS -D_SC"; $(mk_yambo)

ypp_df: ext-libs
@+LIBS2DO="$(INT_LIBS)"; DIR2GO="lib" ; VPATH="$(topdir)/lib" ; $(mk_internal_lib)
@+LIBS2DO="$(YLIBDRIVER)"; NAME="ypp_df_driver_"; DIR2GO="lib/yambo/driver/src"; VPATH="$(topdir)/lib/yambo/driver/src"; \
ADF="-D_DEFECTS -D_SC -D_ypp"; $(mk_external_yambo_lib)
@+LIBS2DO="$(YPPDF_MAIN_LIBS)"; XPATH="src"; VPATH="$(topdir)/src"; ADF="-D_DEFECTS -D_SC "; $(mk_src)
@+LIBS2DO="$(YPP_LIBS)"; XPATH="ypp"; VPATH="$(topdir)/ypp"; ADF="-D_YPP_DEFECTS"; $(mk_ypp_src)
@+X2DO="ypp_df"; XPATH="driver"; VPATH="$(topdir)/driver"; XLIBS="$(YPPDF_MAIN_LIBS_LD)"; \
X_ypp_LIBS="$(YPP_LIBS_LD)"; DRILIBS="$(YLIBDRIVER_LD)"; ADF="-D_YPP_DEFECTS"; $(mk_ypp)

3) Edit the file '''config/mk/libraries.mk''' by adding

YPPDF_MAIN_LIBS = $(YPP_MAIN_LIBS) collisions hamiltonian sc
YPPDF_MAIN_LIBS_LD = $(YPP_MAIN_LIBS_LD) collisions hamiltonian sc

4) Edit the file driver/.objects

objs = yambo.o
#if defined _ypp || _ypp_ph || _ypp_rt || _ypp_surf || _ypp_magnetic || _ypp_sc || _ypp_nl '''|| _ypp_df'''
objs = ypp.o
#endif

Developers Corner

2021-05-04T21:06:57Z

ElenaCannuccia:

== Development Repositories ==
** [[Test-suite-simple|Test-suite (for dummies)]]
** [[Test-suite | Test-suite]]
** [[Benchmark-suite | Benchmark-suite]]
** [[Educational]]
* Special pages
** [[Special:AllPages | All Pages]]
** [[MediaWiki:Sidebar | Side Bar]]
** [[under construction | Html2Wiki HOWTO]]
** [[How2NP | How to create a new project in Yambo]]
** [https://en.wikipedia.org/wiki/Help:Wikitext Wikitext Help]

== Reducing the size of the VM image ==
Open a terminal in the VM and type

sudo dd if=/dev/zero | pv | sudo dd of=/bigemptyfile bs=4096k
sudo rm -rf /bigemptyfile

Developers Corner

2021-05-04T21:06:11Z

ElenaCannuccia:

== Development Repositories ==
** [[Test-suite-simple|Test-suite (for dummies)]]
** [[Test-suite | Test-suite]]
** [[Benchmark-suite | Benchmark-suite]]
** [[Educational]]
* Special pages
** [[Special:AllPages | All Pages]]
** [[MediaWiki:Sidebar | Side Bar]]
** [[under construction | Html2Wiki HOWTO]]
** [[How to create a new project in Yambo | How to create a new project in Yambo]]
** [https://en.wikipedia.org/wiki/Help:Wikitext Wikitext Help]

== Reducing the size of the VM image ==
Open a terminal in the VM and type

sudo dd if=/dev/zero | pv | sudo dd of=/bigemptyfile bs=4096k
sudo rm -rf /bigemptyfile

How to create a new project in Yambo

2021-05-04T21:01:03Z

ElenaCannuccia:

How to create a new project in Yambo

2021-05-04T20:59:08Z

ElenaCannuccia:

1) Edit the file config/mk/targets.mk

In the following '''np''' stands for your new project. Choose two letters which will inequivocally identify your project. Example: "df" stands for "defects".

DF_PROJ = yambo_df ypp_df

2) Edit the file '''config/mk/actions/compile_yambo.mk''' and '''config/mk/actions/compile_ypp.mk'''
by adding the new executables:

yambo_df: ext-libs
@+LIBS2DO="$(INT_LIBS)"; DIR2GO="lib" ; VPATH="$(topdir)/lib" ; $(mk_internal_lib)
@+LIBS2DO="$(YLIBDRIVER)"; NAME="yambo_df_driver_"; DIR2GO="lib/yambo/driver/src"; VPATH="$(topdir)/lib/yambo/driver/src";\
ADF="-D_DEFECTS -D_SC -D_yambo"; $(mk_external_yambo_lib)
@+LIBS2DO="$(PJ_DFLIBS)"; XPATH="src"; VPATH="$(topdir)/src"; ADF="-D_DEFECTS -D_SC"; $(mk_src)
@+X2DO="yambo_df"; XPATH="driver"; VPATH="$(topdir)/driver"; XLIBS="$(PJ_DFLIBS_LD)" ; DRILIBS="$(YLIBDRIVER_LD)"; \
ADF="-D_DEFECTS -D_SC"; $(mk_yambo)

ypp_df: ext-libs
@+LIBS2DO="$(INT_LIBS)"; DIR2GO="lib" ; VPATH="$(topdir)/lib" ; $(mk_internal_lib)
@+LIBS2DO="$(YLIBDRIVER)"; NAME="ypp_df_driver_"; DIR2GO="lib/yambo/driver/src"; VPATH="$(topdir)/lib/yambo/driver/src"; \
ADF="-D_DEFECTS -D_SC -D_ypp"; $(mk_external_yambo_lib)
@+LIBS2DO="$(YPPDF_MAIN_LIBS)"; XPATH="src"; VPATH="$(topdir)/src"; ADF="-D_DEFECTS -D_SC "; $(mk_src)
@+LIBS2DO="$(YPP_LIBS)"; XPATH="ypp"; VPATH="$(topdir)/ypp"; ADF="-D_YPP_DEFECTS"; $(mk_ypp_src)
@+X2DO="ypp_df"; XPATH="driver"; VPATH="$(topdir)/driver"; XLIBS="$(YPPDF_MAIN_LIBS_LD)"; \
X_ypp_LIBS="$(YPP_LIBS_LD)"; DRILIBS="$(YLIBDRIVER_LD)"; ADF="-D_YPP_DEFECTS"; $(mk_ypp)

3) Edit the file '''config/mk/libraries.mk''' by adding

YPPDF_MAIN_LIBS = $(YPP_MAIN_LIBS) collisions hamiltonian sc
YPPDF_MAIN_LIBS_LD = $(YPP_MAIN_LIBS_LD) collisions hamiltonian sc

4) Edit the file driver/.objects

objs = yambo.o
#if defined _ypp || _ypp_ph || _ypp_rt || _ypp_surf || _ypp_magnetic || _ypp_sc || _ypp_nl '''|| _ypp_df'''
objs = ypp.o
#endif

How to create a new project in Yambo

2021-05-04T20:58:05Z

ElenaCannuccia:

How to create a new project in Yambo

2021-05-04T20:54:54Z

ElenaCannuccia:

How to create a new project in Yambo

2021-05-04T20:52:58Z

ElenaCannuccia:

How to create a new project in Yambo

2021-05-04T20:47:19Z

ElenaCannuccia:

1) Edit the file config/mk/targets.mk

In the following '''np''' stands for new project.

NP_PROJ = yambo_np ypp_np

2) Edit the file '''config/mk/actions/compile_yambo.mk''' and '''config/mk/actions/compile_ypp.mk'''
by adding the new executables:

yambo_df: ext-libs
@+LIBS2DO="$(INT_LIBS)"; DIR2GO="lib" ; VPATH="$(topdir)/lib" ; $(mk_internal_lib)
@+LIBS2DO="$(YLIBDRIVER)"; NAME="yambo_df_driver_"; DIR2GO="lib/yambo/driver/src"; VPATH="$(topdir)/lib/yambo/driver/src";\
ADF="-D_DEFECTS -D_SC -D_yambo"; $(mk_external_yambo_lib)
@+LIBS2DO="$(PJ_DFLIBS)"; XPATH="src"; VPATH="$(topdir)/src"; ADF="-D_DEFECTS -D_SC"; $(mk_src)
@+X2DO="yambo_df"; XPATH="driver"; VPATH="$(topdir)/driver"; XLIBS="$(PJ_DFLIBS_LD)" ; DRILIBS="$(YLIBDRIVER_LD)"; \
ADF="-D_DEFECTS -D_SC"; $(mk_yambo)

ypp_df: ext-libs
@+LIBS2DO="$(INT_LIBS)"; DIR2GO="lib" ; VPATH="$(topdir)/lib" ; $(mk_internal_lib)
@+LIBS2DO="$(YLIBDRIVER)"; NAME="ypp_df_driver_"; DIR2GO="lib/yambo/driver/src"; VPATH="$(topdir)/lib/yambo/driver/src"; \
ADF="-D_DEFECTS -D_SC -D_ypp"; $(mk_external_yambo_lib)
@+LIBS2DO="$(YPPDF_MAIN_LIBS)"; XPATH="src"; VPATH="$(topdir)/src"; ADF="-D_DEFECTS -D_SC "; $(mk_src)
@+LIBS2DO="$(YPP_LIBS)"; XPATH="ypp"; VPATH="$(topdir)/ypp"; ADF="-D_YPP_DEFECTS"; $(mk_ypp_src)
@+X2DO="ypp_df"; XPATH="driver"; VPATH="$(topdir)/driver"; XLIBS="$(YPPDF_MAIN_LIBS_LD)"; \
X_ypp_LIBS="$(YPP_LIBS_LD)"; DRILIBS="$(YLIBDRIVER_LD)"; ADF="-D_YPP_DEFECTS"; $(mk_ypp)

How to create a new project in Yambo

2021-05-04T20:45:58Z

ElenaCannuccia: Created page with "1) Edit the file config/mk/targets.mk In the following '''np''' stands for new project. NP_PROJ = yambo_np ypp_np 2) Edit the file '''config/mk/actions/compile_yambo.m..."

1) Edit the file config/mk/targets.mk

In the following '''np''' stands for new project.

NP_PROJ = yambo_np ypp_np

2) Edit the file '''config/mk/actions/compile_yambo.mk''' and '''config/mk/actions/compile_ypp.mk'''
by adding the new executables:

yambo_df: ext-libs
@+LIBS2DO="$(INT_LIBS)"; DIR2GO="lib" ; VPATH="$(topdir)/lib" ; $(mk_internal_lib)
@+LIBS2DO="$(YLIBDRIVER)"; NAME="yambo_df_driver_"; DIR2GO="lib/yambo/driver/src"; VPATH="$(topdir)/lib/yambo/driver/src"; ADF="-D_DEFECTS -D_SC -D_yambo"; $(mk_external_yambo_lib)
@+LIBS2DO="$(PJ_DFLIBS)"; XPATH="src"; VPATH="$(topdir)/src"; ADF="-D_DEFECTS -D_SC"; $(mk_src)
@+X2DO="yambo_df"; XPATH="driver"; VPATH="$(topdir)/driver"; XLIBS="$(PJ_DFLIBS_LD)" ; DRILIBS="$(YLIBDRIVER_LD)"; ADF="-D_DEFECTS -D_SC"; $(mk_yambo)

ypp_df: ext-libs
@+LIBS2DO="$(INT_LIBS)"; DIR2GO="lib" ; VPATH="$(topdir)/lib" ; $(mk_internal_lib)
@+LIBS2DO="$(YLIBDRIVER)"; NAME="ypp_df_driver_"; DIR2GO="lib/yambo/driver/src"; VPATH="$(topdir)/lib/yambo/driver/src"; ADF="-D_DEFECTS -D_SC -D_ypp"; $(mk_external_yambo_lib)
@+LIBS2DO="$(YPPDF_MAIN_LIBS)"; XPATH="src"; VPATH="$(topdir)/src"; ADF="-D_DEFECTS -D_SC "; $(mk_src)
@+LIBS2DO="$(YPP_LIBS)"; XPATH="ypp"; VPATH="$(topdir)/ypp"; ADF="-D_YPP_DEFECTS"; $(mk_ypp_src)
@+X2DO="ypp_df"; XPATH="driver"; VPATH="$(topdir)/driver"; XLIBS="$(YPPDF_MAIN_LIBS_LD)"; \
X_ypp_LIBS="$(YPP_LIBS_LD)"; DRILIBS="$(YLIBDRIVER_LD)"; ADF="-D_YPP_DEFECTS"; $(mk_ypp)

Developers Corner

2021-05-04T20:37:19Z

ElenaCannuccia:

== Development Repositories ==
** [[Test-suite-simple|Test-suite (for dummies)]]
** [[Test-suite | Test-suite]]
** [[Benchmark-suite | Benchmark-suite]]
** [[Educational]]
* Special pages
** [[Special:AllPages | All Pages]]
** [[MediaWiki:Sidebar | Side Bar]]
** [[under construction | Html2Wiki HOWTO]]
** [[How2NP | How to create a new project in Yambo]]
** [https://en.wikipedia.org/wiki/Help:Wikitext Wikitext Help]

== Reducing the size of the VM image ==
Open a terminal in the VM and type

sudo dd if=/dev/zero | pv | sudo dd of=/bigemptyfile bs=4096k
sudo rm -rf /bigemptyfile

Developers Corner

2021-05-04T14:39:43Z

ElenaCannuccia:

== Development Repositories ==
** [[Test-suite-simple|Test-suite (for dummies)]]
** [[Test-suite | Test-suite]]
** [[Benchmark-suite | Benchmark-suite]]
** [[Educational]]
* Special pages
** [[Special:AllPages | All Pages]]
** [[MediaWiki:Sidebar | Side Bar]]
** [[under construction | Html2Wiki HOWTO]]
** [[How to create a new project in Yambo | All Pages]]
** [https://en.wikipedia.org/wiki/Help:Wikitext Wikitext Help]

== Reducing the size of the VM image ==
Open a terminal in the VM and type

sudo dd if=/dev/zero | pv | sudo dd of=/bigemptyfile bs=4096k
sudo rm -rf /bigemptyfile

Developers Corner

2021-05-04T13:40:23Z

ElenaCannuccia: