The Yambo Project - User contributions [en]

Pump and Probe

2025-12-01T10:25:54Z

Attacc: /* Analysis of the results using YamboPy */

In this tutorial we will show you how to setup two external fields in '''yambo_nl''', to perform pump and probe simulation. <ref name="pnp">[https://arxiv.org/abs/2211.12241 Exciton - Exciton transitions involving strongly bound excitons: an ab-initio approach], D. Sangalli, M. D'Alessandro and C. Attaccalite, Physical Review B '''107''' (20), 205203 (2023) </ref> 
This tutorial is at independent particle level, but the same kind of simulation can be repeated including local field effects,
quasi-particle correction or electron-hole interaction, see for example the tutorials: 
 
[[Correlation effects in the non-linear response]] 
[[Real time Bethe-Salpeter Equation (TDSE)]] 
 
This tutorial supposes that you are already familiar with real-time simulation with Yambo<ref name="dberry">[https://arxiv.org/abs/1609.09639 Non-linear response in extended systems: a real-time approach], C. Attaccalite </ref>
if it is not the case please check these tutorials: [[Tutorials#Non_linear_response]]

We start from the h-BN monolayer with an in place lattice constant a=2.5 Å and a box large 33 a.u. in the z-direction.
Standard DFT input for hBN monolayer for ABINIT or QuantumEspresso can be found here [[Tutorials]]. 
We used a 9x9x1 k-points grid and 8 bands in the non-self consistent calculation and 40 Ry cutoff for the wave-function.

In our example we choose direction [0,1,0] for the pump and [1,0,0] for the probe.
We generate the ypp.in to remove symmetries with the command ypp -y and we modify it as:

fixsyms # [R] Remove symmetries not consistent with an external perturbation
% Efield1
0.000000 | 1.000000 | 0.000000 | # First external Electric Field
%
% Efield2
 1.000000 | 0.000000 | 0.000000 | # Additional external Electric Field
%
BField= 0.000000 T # [MAG] Magnetic field modulus
Bpsi= 0.000000 deg # [MAG] Magnetic field psi angle [degree]
Btheta= 0.000000 deg # [MAG] Magnetic field theta angle [degree]
#RmAllSymm # Remove all symmetries
RmTimeRev # Remove Time Reversal
#RmSpaceInv # Remove Spatial Inversion

then we go in the FixSymm directory and run again the setup. 
We will perform three different real-time calculations: 
* the probe field alone;
* the pump field alone;
* the pump and probe configuration.

== Probe only ==

We can generate the input file for a generic Pump and Probe calculations with the command: yambo_nl -u p -F yambo.in_probe:

nloptics # [R] Non-linear spectroscopy
DIP_Threads=0 # [OPENMP/X] Number of threads for dipoles
NL_Threads=0 # [OPENMP/NL] Number of threads for nl-optics
% NLBands
 3 | 6 | # [NL] Bands range
%
NLverbosity= "high" # [NL] Verbosity level (low | high)
NLtime= 80.000000 fs # [NL] Simulation Time
NLintegrator= " CRANKNIC" # [NL] Integrator ("EULEREXP/RK2/RK4/RK2EXP/HEUN/INVINT/CRANKNIC")
NLCorrelation= "IPA" # [NL] Correlation ("IPA/HARTREE/TDDFT/LRC/LRW/JGM/SEX")
NLLrcAlpha= 0.000000 # [NL] Long Range Correction
NLDamping= 0.000000 eV # [NL] Damping (or dephasing)
RADLifeTime=-1.000000 fs # [RT] Radiative life-time (if negative Yambo sets it equal to Phase_LifeTime in NL)
#EvalCurrent # [NL] Evaluate the current
#FrPolPerdic # [DIP] Force periodicity of polarization respect to the external field
HARRLvcs= 21817 RL # [HA] Hartree RL components
EXXRLvcs= 21817 RL # [XX] Exchange RL components
% Field1_Freq
0.100000 | 0.100000 | eV # [RT Field1] Frequency
%
Field1_NFreqs= 1 # [RT Field1] Frequency
Field1_Int= 1000.00 kWLm2 # [RT Field1] Intensity
Field1_Width= 0.000000 fs # [RT Field1] Width
Field1_kind= " DELTA" # [RT Field1] Kind(SIN|COS|RES|ANTIRES|GAUSS|DELTA|QSSIN)
Field1_pol= "linear" # [RT Field1] Pol(linear|circular)
% Field1_Dir
 1.000000 | 0.000000 | 0.000000 | # [RT Field1] Versor
%
Field1_Tstart= 5.00000 fs # [RT Field1] Initial Time
[......]

In this input we set only the first field that is the probe, we use a DELTA function as field in such a way to probe all the frequencies, and set the starting point of the delta at t=5 fs. Run this job in a separate folder with the command yambo_nl -F yambo.in_probe -J PROBE. Then we can analyze the spectra with ypp -u -J PROBE :

nonlinear # [R] Non-linear response analysis
Xorder= 1 # Max order of the response/exc functions
% TimeRange
-1.000000 |-1.000000 | fs # Time-window where processing is done
%
ETStpsRt= 200 # Total Energy steps
% EnRngeRt
0.00000 | 20.00000 | eV # Energy range
%
DampMode= "LORENTZIAN" # Damping type ( NONE | LORENTZIAN | GAUSSIAN )
DampFactor= 0.100000 eV # Damping parameter
PumpPATH= "none" # Path of the simulation with the Pump only

and get the dielectric response. Notice that we introduce a Lorentzian broadening the post-processing. 
Hereafter we plot the damped polarization along the y-direction and the corresponding dielectric constant:

[[File:Eps probe.png|800px|center | Probe only]]

the arrow indicates the position where we will put the Pump in the next simulation.

==Pump only==

Now we run a simulation with the pump field only. We generate the input in the same way yambo_nl -u p -F yambo.in_pump. 
These result will be our reference field in the final analysis. Here the input file for the pump:

nloptics # [R] Non-linear spectroscopy
DIP_Threads=0 # [OPENMP/X] Number of threads for dipoles
NL_Threads=0 # [OPENMP/NL] Number of threads for nl-optics
% NLBands
3 | 6 | # [NL] Bands range
%
NLverbosity= "high" # [NL] Verbosity level (low | high)
NLtime= 150.0000 fs # [NL] Simulation Time
NLintegrator= "CRANKNIC" # [NL] Integrator ("EULEREXP/RK2/RK4/RK2EXP/HEUN/INVINT/CRANKNIC")
NLCorrelation= "IPA" # [NL] Correlation ("IPA/HARTREE/TDDFT/LRC/LRW/JGM/SEX")
NLLrcAlpha= 0.000000 # [NL] Long Range Correction
NLDamping= 0.000000 eV # [NL] Damping (or dephasing)
RADLifeTime=-1.000000 fs # [RT] Radiative life-time (if negative Yambo sets it equal to Phase_LifeTime in NL)
#EvalCurrent # [NL] Evaluate the current
#FrPolPerdic # [DIP] Force periodicity of polarization respect to the external field
HARRLvcs= 21817 RL # [HA] Hartree RL components
EXXRLvcs= 21817 RL # [XX] Exchange RL components
% Field1_Freq
0.100000 | 0.100000 | eV # [RT Field1] Frequency
%
Field1_NFreqs= 1 # [RT Field1] Frequency
Field1_Int= 10000.00 kWLm2 # [RT Field1] Intensity
Field1_Width= 0.000000 fs # [RT Field1] Width
Field1_kind= "SOFTSIN" # [RT Field1] Kind(SIN|COS|RES|ANTIRES|GAUSS|DELTA|QSSIN)
Field1_pol= "linear" # [RT Field1] Pol(linear|circular)
% Field1_Dir
0.000000 | 0.000000 | 0.000000 | # [RT Field1] Versor
%
Field1_Tstart= 0.010000 fs # [RT Field1] Initial Time
% Field2_Freq
 5.42 | 5.42 | eV # [RT Field2] Frequency
%
Field2_NFreqs= 1 # [RT Field2] Frequency
Field2_Int= 1000.00 kWLm2 # [RT Field2] Intensity
Field2_Width= 10.00000 fs # [RT Field2] Width
Field2_kind= "QSSIN" # [RT Field2] Kind(SIN|COS|RES|ANTIRES|GAUSS|DELTA|QSSIN)
Field2_pol= "linear" # [RT Field2] Pol(linear|circular)
% Field2_Dir
 0.000000 | 1.000000 | 0.000000 | # [RT Field2] Versor
%
Field2_Tstart= 0.010000 fs # [RT Field2] Initial Time
[...]
In this simulation we used as Pump field QSSIN that is sinus with a Guassian envelope[https://demonstrations.wolfram.com/SineGaussianSignals/ sine-Gaussian wave]. For a list of all possible field in Yambo see the file src/modules/mod_fields.F. We centred the field frequency at 5.42 eV that is the energy of the highest peak in the previous figure, see arrow there.
Run the simulation with the command yambo_nl -F yambo.in_pump -J PUMP .
The pump field, column 6th of the file <code>o-PUMP.external_potential_F1</code>, is shown in the figure below:

[[File:Pump only.png|800px|center|Pump field]]

== Pump and probe==

Now we copy the pump in file in a new file cp yambo.in_pump yambo.in_pump_and_probe and turn on the probe field:

nloptics # [R] Non-linear spectroscopy
DIP_Threads=0 # [OPENMP/X] Number of threads for dipoles
NL_Threads=0 # [OPENMP/NL] Number of threads for nl-optics
% NLBands
3 | 6 | # [NL] Bands range
%
NLverbosity= "high" # [NL] Verbosity level (low | high)
NLtime= 150.0000 fs # [NL] Simulation Time
NLintegrator= "CRANKNIC" # [NL] Integrator ("EULEREXP/RK2/RK4/RK2EXP/HEUN/INVINT/CRANKNIC")
NLCorrelation= "IPA" # [NL] Correlation ("IPA/HARTREE/TDDFT/LRC/LRW/JGM/SEX")
NLLrcAlpha= 0.000000 # [NL] Long Range Correction
NLDamping= 0.000000 eV # [NL] Damping (or dephasing)
RADLifeTime=-1.000000 fs # [RT] Radiative life-time (if negative Yambo sets it equal to Phase_LifeTime in NL)
#EvalCurrent # [NL] Evaluate the current
#FrPolPerdic # [DIP] Force periodicity of polarization respect to the external field
HARRLvcs= 21817 RL # [HA] Hartree RL components
EXXRLvcs= 21817 RL # [XX] Exchange RL components
% Field1_Freq
0.100000 | 0.100000 | eV # [RT Field1] Frequency
%
Field1_NFreqs= 1 # [RT Field1] Frequency
Field1_Int= 1.00 kWLm2 # [RT Field1] Intensity
Field1_Width= 0.000000 fs # [RT Field1] Width
Field1_kind= "DELTA" # [RT Field1] Kind(SIN|COS|RES|ANTIRES|GAUSS|DELTA|QSSIN)
Field1_pol= "linear" # [RT Field1] Pol(linear|circular)
% Field1_Dir
 1.000000 | 0.000000 | 0.000000 | # [RT Field1] Versor
%
Field1_Tstart= 90.0000 fs # [RT Field1] Initial Time
% Field2_Freq
5.42 | 5.42 | eV # [RT Field2] Frequency
%
Field2_NFreqs= 1 # [RT Field2] Frequency
Field2_Int= 1000.00 kWLm2 # [RT Field2] Intensity
Field2_Width= 10.00000 fs # [RT Field2] Width
Field2_kind= "QSSIN" # [RT Field2] Kind(SIN|COS|RES|ANTIRES|GAUSS|DELTA|QSSIN)
Field2_pol= "linear" # [RT Field2] Pol(linear|circular)
% Field2_Dir
0.000000 | 1.000000 | 0.000000 | # [RT Field2] Versor
%
Field2_Tstart= 0.010000 fs # [RT Field2] Initial Time

'''Please note:''' by convention in Yambo we consider the first field the probe and the second the pump. 

you run the simulation with the command yambo_nl -F yambo.in_pump_and_probe -J PUMP_AND_PROBE and then we analyze the result using ypp with the command: ypp_nl -u -J PUMP_AND_PROBE :

nonlinear # [R] Non-linear response analysis
Xorder= 1 # Max order of the response/exc functions
% TimeRange
-1.000000 |-1.000000 | fs # Time-window where processing is done
%
ETStpsRt= 500 # Total Energy steps
% EnRngeRt
0.00000 | 3.9000 | eV # Energy range
%
DampMode= "GAUSSIAN" # Damping type ( NONE | LORENTZIAN | GAUSSIAN )
DampFactor= 0.085000 eV # Damping parameter
PumpPATH= "./PUMP/" # Path of the simulation with the Pump only

Notice that in this case we are interested in the spectra below the 4 eV, that is was zero without the presence of the pump. We put in the input the pump path in such way to calculate polarization of the pump&probe minus the one of generate by the pump only <math>\Delta P(t) = P_{PnP}(t) - P_{pump}(t)</math>. Then we analyze the <math>\Delta P(t)</math> and get the new spectra:

[[File:P and p spectrum.png|800px | center|Pump and probe spectrum]]

The peak that you see in this spectrum, that were not present in when the pump was zero, correspond to the transition between the different excited states. The pump field populates the state at 5.42 eV and then the probe excites electrons from this state to higher states. The energy difference between the higher excited states and the peak at 5.42 define the position of the peaks in the pump and probe spectrum, while their intensity is dictated by the dipole matrix elements between the different excited states, see Ref. <ref name="pnp"></ref>. 

'''Additional comments on pump and probe calculations '''
* We used a Gaussian damping factor, this choice is motivated by various tests we have done, and it seems to us that in pump and probe this broadening gives better results. 
* If you plot all spectrum you will notice that the "equilibrium part" is much stronger than the one induced by the pump, this is normal because only a small fraction of electron are promoted in the excited state by the pump.
* All previous simulation can be run also in presence of excitons, see Ref. <ref name="pnp"></ref> and group theory can be used to predict dark/bright transition in the pump and probe spectroscopy.<ref>[https://link.springer.com/book/10.1007/978-3-540-32899-5 Group Theory, Application to the Physics of Condensed Matter], Mildred S. S. Dresselhaus, Gene Dresselhaus, Ado Jorio, Springer Editor</ref>
* In principle is it possible to include damping and radiative life-time in the simulation to study retardation effect between the pump and probe. This approach exact in the independent particle case, but introduces an error when correlation effects are present, see Refs.<ref>[https://arxiv.org/abs/2106.03592 Excitons and carriers in transient absorption and time-resolved ARPES spectroscopy: an abinitio approach], D. Sangalli, Phys. Rev. Materials '''5''', 083803 (2021)</ref> and <ref>[https://arxiv.org/abs/1705.04245 Theory of exciton-phonon coupling], Gabriel Antonius and Steven G. Louie Phys. Rev. B '''105''', 085111 (2022)</ref>for a discussion.
* Non-linear response (SHG, THG, ...) induced by the pump is not implemented yet... if you have a good idea how to do it, please let us know

== Analysis of the results using YamboPy ==
'''This part works only with Yamboo 5.3 or the last version available on Github
 
Results can be analyzed using YamboPy with the following script:

from yambopy import *
from yambopy.plot import *

NLDB_P_and_P=YamboNLDB(calc='P_and_P')
NLDB_Pump =YamboNLDB(calc='PUMP')

pol_pump =NLDB_Pump.Polarization[0]
pol_p_and_p=NLDB_P_and_P.Polarization[0]

time=NLDB_P_and_P.IO_TIME_points
t_initial=NLDB_P_and_P.Efield[0]["initial_time"]

pol_damped=np.empty_like(pol_pump)

for i_d in range(3):
pol_damped[i_d,:]=damp_it(pol_p_and_p[i_d,:]-pol_pump[i_d,:],time,t_initial,damp_type='GAUSSIAN',damp_factor=0.085/ha2ev)

Plot_Pol(time=time, pol=pol_damped, xlim=[0,55], save_file='polarization.pdf')

Linear_Response(time=time,pol=pol_damped,efield=NLDB_P_and_P.Efield[0],plot=False,plot_file='delta_eps.pdf',e_range=[0.0,3.7],n_freqs=500)

== References ==

Pump and Probe

2025-12-01T10:24:12Z

Attacc: /* Analysis of the results using YamboPy */

In this tutorial we will show you how to setup two external fields in '''yambo_nl''', to perform pump and probe simulation. <ref name="pnp">[https://arxiv.org/abs/2211.12241 Exciton - Exciton transitions involving strongly bound excitons: an ab-initio approach], D. Sangalli, M. D'Alessandro and C. Attaccalite, Physical Review B '''107''' (20), 205203 (2023) </ref> 
This tutorial is at independent particle level, but the same kind of simulation can be repeated including local field effects,
quasi-particle correction or electron-hole interaction, see for example the tutorials: 
 
[[Correlation effects in the non-linear response]] 
[[Real time Bethe-Salpeter Equation (TDSE)]] 
 
This tutorial supposes that you are already familiar with real-time simulation with Yambo<ref name="dberry">[https://arxiv.org/abs/1609.09639 Non-linear response in extended systems: a real-time approach], C. Attaccalite </ref>
if it is not the case please check these tutorials: [[Tutorials#Non_linear_response]]

We start from the h-BN monolayer with an in place lattice constant a=2.5 Å and a box large 33 a.u. in the z-direction.
Standard DFT input for hBN monolayer for ABINIT or QuantumEspresso can be found here [[Tutorials]]. 
We used a 9x9x1 k-points grid and 8 bands in the non-self consistent calculation and 40 Ry cutoff for the wave-function.

In our example we choose direction [0,1,0] for the pump and [1,0,0] for the probe.
We generate the ypp.in to remove symmetries with the command ypp -y and we modify it as:

fixsyms # [R] Remove symmetries not consistent with an external perturbation
% Efield1
0.000000 | 1.000000 | 0.000000 | # First external Electric Field
%
% Efield2
 1.000000 | 0.000000 | 0.000000 | # Additional external Electric Field
%
BField= 0.000000 T # [MAG] Magnetic field modulus
Bpsi= 0.000000 deg # [MAG] Magnetic field psi angle [degree]
Btheta= 0.000000 deg # [MAG] Magnetic field theta angle [degree]
#RmAllSymm # Remove all symmetries
RmTimeRev # Remove Time Reversal
#RmSpaceInv # Remove Spatial Inversion

then we go in the FixSymm directory and run again the setup. 
We will perform three different real-time calculations: 
* the probe field alone;
* the pump field alone;
* the pump and probe configuration.

== Probe only ==

We can generate the input file for a generic Pump and Probe calculations with the command: yambo_nl -u p -F yambo.in_probe:

nloptics # [R] Non-linear spectroscopy
DIP_Threads=0 # [OPENMP/X] Number of threads for dipoles
NL_Threads=0 # [OPENMP/NL] Number of threads for nl-optics
% NLBands
 3 | 6 | # [NL] Bands range
%
NLverbosity= "high" # [NL] Verbosity level (low | high)
NLtime= 80.000000 fs # [NL] Simulation Time
NLintegrator= " CRANKNIC" # [NL] Integrator ("EULEREXP/RK2/RK4/RK2EXP/HEUN/INVINT/CRANKNIC")
NLCorrelation= "IPA" # [NL] Correlation ("IPA/HARTREE/TDDFT/LRC/LRW/JGM/SEX")
NLLrcAlpha= 0.000000 # [NL] Long Range Correction
NLDamping= 0.000000 eV # [NL] Damping (or dephasing)
RADLifeTime=-1.000000 fs # [RT] Radiative life-time (if negative Yambo sets it equal to Phase_LifeTime in NL)
#EvalCurrent # [NL] Evaluate the current
#FrPolPerdic # [DIP] Force periodicity of polarization respect to the external field
HARRLvcs= 21817 RL # [HA] Hartree RL components
EXXRLvcs= 21817 RL # [XX] Exchange RL components
% Field1_Freq
0.100000 | 0.100000 | eV # [RT Field1] Frequency
%
Field1_NFreqs= 1 # [RT Field1] Frequency
Field1_Int= 1000.00 kWLm2 # [RT Field1] Intensity
Field1_Width= 0.000000 fs # [RT Field1] Width
Field1_kind= " DELTA" # [RT Field1] Kind(SIN|COS|RES|ANTIRES|GAUSS|DELTA|QSSIN)
Field1_pol= "linear" # [RT Field1] Pol(linear|circular)
% Field1_Dir
 1.000000 | 0.000000 | 0.000000 | # [RT Field1] Versor
%
Field1_Tstart= 5.00000 fs # [RT Field1] Initial Time
[......]

In this input we set only the first field that is the probe, we use a DELTA function as field in such a way to probe all the frequencies, and set the starting point of the delta at t=5 fs. Run this job in a separate folder with the command yambo_nl -F yambo.in_probe -J PROBE. Then we can analyze the spectra with ypp -u -J PROBE :

nonlinear # [R] Non-linear response analysis
Xorder= 1 # Max order of the response/exc functions
% TimeRange
-1.000000 |-1.000000 | fs # Time-window where processing is done
%
ETStpsRt= 200 # Total Energy steps
% EnRngeRt
0.00000 | 20.00000 | eV # Energy range
%
DampMode= "LORENTZIAN" # Damping type ( NONE | LORENTZIAN | GAUSSIAN )
DampFactor= 0.100000 eV # Damping parameter
PumpPATH= "none" # Path of the simulation with the Pump only

and get the dielectric response. Notice that we introduce a Lorentzian broadening the post-processing. 
Hereafter we plot the damped polarization along the y-direction and the corresponding dielectric constant:

[[File:Eps probe.png|800px|center | Probe only]]

the arrow indicates the position where we will put the Pump in the next simulation.

==Pump only==

Now we run a simulation with the pump field only. We generate the input in the same way yambo_nl -u p -F yambo.in_pump. 
These result will be our reference field in the final analysis. Here the input file for the pump:

nloptics # [R] Non-linear spectroscopy
DIP_Threads=0 # [OPENMP/X] Number of threads for dipoles
NL_Threads=0 # [OPENMP/NL] Number of threads for nl-optics
% NLBands
3 | 6 | # [NL] Bands range
%
NLverbosity= "high" # [NL] Verbosity level (low | high)
NLtime= 150.0000 fs # [NL] Simulation Time
NLintegrator= "CRANKNIC" # [NL] Integrator ("EULEREXP/RK2/RK4/RK2EXP/HEUN/INVINT/CRANKNIC")
NLCorrelation= "IPA" # [NL] Correlation ("IPA/HARTREE/TDDFT/LRC/LRW/JGM/SEX")
NLLrcAlpha= 0.000000 # [NL] Long Range Correction
NLDamping= 0.000000 eV # [NL] Damping (or dephasing)
RADLifeTime=-1.000000 fs # [RT] Radiative life-time (if negative Yambo sets it equal to Phase_LifeTime in NL)
#EvalCurrent # [NL] Evaluate the current
#FrPolPerdic # [DIP] Force periodicity of polarization respect to the external field
HARRLvcs= 21817 RL # [HA] Hartree RL components
EXXRLvcs= 21817 RL # [XX] Exchange RL components
% Field1_Freq
0.100000 | 0.100000 | eV # [RT Field1] Frequency
%
Field1_NFreqs= 1 # [RT Field1] Frequency
Field1_Int= 10000.00 kWLm2 # [RT Field1] Intensity
Field1_Width= 0.000000 fs # [RT Field1] Width
Field1_kind= "SOFTSIN" # [RT Field1] Kind(SIN|COS|RES|ANTIRES|GAUSS|DELTA|QSSIN)
Field1_pol= "linear" # [RT Field1] Pol(linear|circular)
% Field1_Dir
0.000000 | 0.000000 | 0.000000 | # [RT Field1] Versor
%
Field1_Tstart= 0.010000 fs # [RT Field1] Initial Time
% Field2_Freq
 5.42 | 5.42 | eV # [RT Field2] Frequency
%
Field2_NFreqs= 1 # [RT Field2] Frequency
Field2_Int= 1000.00 kWLm2 # [RT Field2] Intensity
Field2_Width= 10.00000 fs # [RT Field2] Width
Field2_kind= "QSSIN" # [RT Field2] Kind(SIN|COS|RES|ANTIRES|GAUSS|DELTA|QSSIN)
Field2_pol= "linear" # [RT Field2] Pol(linear|circular)
% Field2_Dir
 0.000000 | 1.000000 | 0.000000 | # [RT Field2] Versor
%
Field2_Tstart= 0.010000 fs # [RT Field2] Initial Time
[...]
In this simulation we used as Pump field QSSIN that is sinus with a Guassian envelope[https://demonstrations.wolfram.com/SineGaussianSignals/ sine-Gaussian wave]. For a list of all possible field in Yambo see the file src/modules/mod_fields.F. We centred the field frequency at 5.42 eV that is the energy of the highest peak in the previous figure, see arrow there.
Run the simulation with the command yambo_nl -F yambo.in_pump -J PUMP .
The pump field, column 6th of the file <code>o-PUMP.external_potential_F1</code>, is shown in the figure below:

[[File:Pump only.png|800px|center|Pump field]]

== Pump and probe==

Now we copy the pump in file in a new file cp yambo.in_pump yambo.in_pump_and_probe and turn on the probe field:

nloptics # [R] Non-linear spectroscopy
DIP_Threads=0 # [OPENMP/X] Number of threads for dipoles
NL_Threads=0 # [OPENMP/NL] Number of threads for nl-optics
% NLBands
3 | 6 | # [NL] Bands range
%
NLverbosity= "high" # [NL] Verbosity level (low | high)
NLtime= 150.0000 fs # [NL] Simulation Time
NLintegrator= "CRANKNIC" # [NL] Integrator ("EULEREXP/RK2/RK4/RK2EXP/HEUN/INVINT/CRANKNIC")
NLCorrelation= "IPA" # [NL] Correlation ("IPA/HARTREE/TDDFT/LRC/LRW/JGM/SEX")
NLLrcAlpha= 0.000000 # [NL] Long Range Correction
NLDamping= 0.000000 eV # [NL] Damping (or dephasing)
RADLifeTime=-1.000000 fs # [RT] Radiative life-time (if negative Yambo sets it equal to Phase_LifeTime in NL)
#EvalCurrent # [NL] Evaluate the current
#FrPolPerdic # [DIP] Force periodicity of polarization respect to the external field
HARRLvcs= 21817 RL # [HA] Hartree RL components
EXXRLvcs= 21817 RL # [XX] Exchange RL components
% Field1_Freq
0.100000 | 0.100000 | eV # [RT Field1] Frequency
%
Field1_NFreqs= 1 # [RT Field1] Frequency
Field1_Int= 1.00 kWLm2 # [RT Field1] Intensity
Field1_Width= 0.000000 fs # [RT Field1] Width
Field1_kind= "DELTA" # [RT Field1] Kind(SIN|COS|RES|ANTIRES|GAUSS|DELTA|QSSIN)
Field1_pol= "linear" # [RT Field1] Pol(linear|circular)
% Field1_Dir
 1.000000 | 0.000000 | 0.000000 | # [RT Field1] Versor
%
Field1_Tstart= 90.0000 fs # [RT Field1] Initial Time
% Field2_Freq
5.42 | 5.42 | eV # [RT Field2] Frequency
%
Field2_NFreqs= 1 # [RT Field2] Frequency
Field2_Int= 1000.00 kWLm2 # [RT Field2] Intensity
Field2_Width= 10.00000 fs # [RT Field2] Width
Field2_kind= "QSSIN" # [RT Field2] Kind(SIN|COS|RES|ANTIRES|GAUSS|DELTA|QSSIN)
Field2_pol= "linear" # [RT Field2] Pol(linear|circular)
% Field2_Dir
0.000000 | 1.000000 | 0.000000 | # [RT Field2] Versor
%
Field2_Tstart= 0.010000 fs # [RT Field2] Initial Time

'''Please note:''' by convention in Yambo we consider the first field the probe and the second the pump. 

you run the simulation with the command yambo_nl -F yambo.in_pump_and_probe -J PUMP_AND_PROBE and then we analyze the result using ypp with the command: ypp_nl -u -J PUMP_AND_PROBE :

nonlinear # [R] Non-linear response analysis
Xorder= 1 # Max order of the response/exc functions
% TimeRange
-1.000000 |-1.000000 | fs # Time-window where processing is done
%
ETStpsRt= 500 # Total Energy steps
% EnRngeRt
0.00000 | 3.9000 | eV # Energy range
%
DampMode= "GAUSSIAN" # Damping type ( NONE | LORENTZIAN | GAUSSIAN )
DampFactor= 0.085000 eV # Damping parameter
PumpPATH= "./PUMP/" # Path of the simulation with the Pump only

Notice that in this case we are interested in the spectra below the 4 eV, that is was zero without the presence of the pump. We put in the input the pump path in such way to calculate polarization of the pump&probe minus the one of generate by the pump only <math>\Delta P(t) = P_{PnP}(t) - P_{pump}(t)</math>. Then we analyze the <math>\Delta P(t)</math> and get the new spectra:

[[File:P and p spectrum.png|800px | center|Pump and probe spectrum]]

The peak that you see in this spectrum, that were not present in when the pump was zero, correspond to the transition between the different excited states. The pump field populates the state at 5.42 eV and then the probe excites electrons from this state to higher states. The energy difference between the higher excited states and the peak at 5.42 define the position of the peaks in the pump and probe spectrum, while their intensity is dictated by the dipole matrix elements between the different excited states, see Ref. <ref name="pnp"></ref>. 

'''Additional comments on pump and probe calculations '''
* We used a Gaussian damping factor, this choice is motivated by various tests we have done, and it seems to us that in pump and probe this broadening gives better results. 
* If you plot all spectrum you will notice that the "equilibrium part" is much stronger than the one induced by the pump, this is normal because only a small fraction of electron are promoted in the excited state by the pump.
* All previous simulation can be run also in presence of excitons, see Ref. <ref name="pnp"></ref> and group theory can be used to predict dark/bright transition in the pump and probe spectroscopy.<ref>[https://link.springer.com/book/10.1007/978-3-540-32899-5 Group Theory, Application to the Physics of Condensed Matter], Mildred S. S. Dresselhaus, Gene Dresselhaus, Ado Jorio, Springer Editor</ref>
* In principle is it possible to include damping and radiative life-time in the simulation to study retardation effect between the pump and probe. This approach exact in the independent particle case, but introduces an error when correlation effects are present, see Refs.<ref>[https://arxiv.org/abs/2106.03592 Excitons and carriers in transient absorption and time-resolved ARPES spectroscopy: an abinitio approach], D. Sangalli, Phys. Rev. Materials '''5''', 083803 (2021)</ref> and <ref>[https://arxiv.org/abs/1705.04245 Theory of exciton-phonon coupling], Gabriel Antonius and Steven G. Louie Phys. Rev. B '''105''', 085111 (2022)</ref>for a discussion.
* Non-linear response (SHG, THG, ...) induced by the pump is not implemented yet... if you have a good idea how to do it, please let us know

== Analysis of the results using YamboPy ==
'''This part works only with Lumen 2.0 or the last version available on GitLab:''' [https://gitlab.com/lumen-code https://gitlab.com/lumen-code]
 
Results can be analyzed using YamboPy with the following script:

from yambopy import *
from yambopy.plot import *

NLDB_P_and_P=YamboNLDB(calc='P_and_P')
NLDB_Pump =YamboNLDB(calc='PUMP')

pol_pump =NLDB_Pump.Polarization[0]
pol_p_and_p=NLDB_P_and_P.Polarization[0]

time=NLDB_P_and_P.IO_TIME_points
t_initial=NLDB_P_and_P.Efield[0]["initial_time"]

pol_damped=np.empty_like(pol_pump)

for i_d in range(3):
pol_damped[i_d,:]=damp_it(pol_p_and_p[i_d,:]-pol_pump[i_d,:],time,t_initial,damp_type='GAUSSIAN',damp_factor=0.085/ha2ev)

Plot_Pol(time=time, pol=pol_damped, xlim=[0,55], save_file='polarization.pdf')

Linear_Response(time=time,pol=pol_damped,efield=NLDB_P_and_P.Efield[0],plot=False,plot_file='delta_eps.pdf',e_range=[0.0,3.7],n_freqs=500)

== References ==

Pump and Probe

2025-12-01T10:23:58Z

Attacc: /* Analysis of the results using YamboPy */

In this tutorial we will show you how to setup two external fields in '''yambo_nl''', to perform pump and probe simulation. <ref name="pnp">[https://arxiv.org/abs/2211.12241 Exciton - Exciton transitions involving strongly bound excitons: an ab-initio approach], D. Sangalli, M. D'Alessandro and C. Attaccalite, Physical Review B '''107''' (20), 205203 (2023) </ref> 
This tutorial is at independent particle level, but the same kind of simulation can be repeated including local field effects,
quasi-particle correction or electron-hole interaction, see for example the tutorials: 
 
[[Correlation effects in the non-linear response]] 
[[Real time Bethe-Salpeter Equation (TDSE)]] 
 
This tutorial supposes that you are already familiar with real-time simulation with Yambo<ref name="dberry">[https://arxiv.org/abs/1609.09639 Non-linear response in extended systems: a real-time approach], C. Attaccalite </ref>
if it is not the case please check these tutorials: [[Tutorials#Non_linear_response]]

We start from the h-BN monolayer with an in place lattice constant a=2.5 Å and a box large 33 a.u. in the z-direction.
Standard DFT input for hBN monolayer for ABINIT or QuantumEspresso can be found here [[Tutorials]]. 
We used a 9x9x1 k-points grid and 8 bands in the non-self consistent calculation and 40 Ry cutoff for the wave-function.

In our example we choose direction [0,1,0] for the pump and [1,0,0] for the probe.
We generate the ypp.in to remove symmetries with the command ypp -y and we modify it as:

fixsyms # [R] Remove symmetries not consistent with an external perturbation
% Efield1
0.000000 | 1.000000 | 0.000000 | # First external Electric Field
%
% Efield2
 1.000000 | 0.000000 | 0.000000 | # Additional external Electric Field
%
BField= 0.000000 T # [MAG] Magnetic field modulus
Bpsi= 0.000000 deg # [MAG] Magnetic field psi angle [degree]
Btheta= 0.000000 deg # [MAG] Magnetic field theta angle [degree]
#RmAllSymm # Remove all symmetries
RmTimeRev # Remove Time Reversal
#RmSpaceInv # Remove Spatial Inversion

then we go in the FixSymm directory and run again the setup. 
We will perform three different real-time calculations: 
* the probe field alone;
* the pump field alone;
* the pump and probe configuration.

== Probe only ==

We can generate the input file for a generic Pump and Probe calculations with the command: yambo_nl -u p -F yambo.in_probe:

nloptics # [R] Non-linear spectroscopy
DIP_Threads=0 # [OPENMP/X] Number of threads for dipoles
NL_Threads=0 # [OPENMP/NL] Number of threads for nl-optics
% NLBands
 3 | 6 | # [NL] Bands range
%
NLverbosity= "high" # [NL] Verbosity level (low | high)
NLtime= 80.000000 fs # [NL] Simulation Time
NLintegrator= " CRANKNIC" # [NL] Integrator ("EULEREXP/RK2/RK4/RK2EXP/HEUN/INVINT/CRANKNIC")
NLCorrelation= "IPA" # [NL] Correlation ("IPA/HARTREE/TDDFT/LRC/LRW/JGM/SEX")
NLLrcAlpha= 0.000000 # [NL] Long Range Correction
NLDamping= 0.000000 eV # [NL] Damping (or dephasing)
RADLifeTime=-1.000000 fs # [RT] Radiative life-time (if negative Yambo sets it equal to Phase_LifeTime in NL)
#EvalCurrent # [NL] Evaluate the current
#FrPolPerdic # [DIP] Force periodicity of polarization respect to the external field
HARRLvcs= 21817 RL # [HA] Hartree RL components
EXXRLvcs= 21817 RL # [XX] Exchange RL components
% Field1_Freq
0.100000 | 0.100000 | eV # [RT Field1] Frequency
%
Field1_NFreqs= 1 # [RT Field1] Frequency
Field1_Int= 1000.00 kWLm2 # [RT Field1] Intensity
Field1_Width= 0.000000 fs # [RT Field1] Width
Field1_kind= " DELTA" # [RT Field1] Kind(SIN|COS|RES|ANTIRES|GAUSS|DELTA|QSSIN)
Field1_pol= "linear" # [RT Field1] Pol(linear|circular)
% Field1_Dir
 1.000000 | 0.000000 | 0.000000 | # [RT Field1] Versor
%
Field1_Tstart= 5.00000 fs # [RT Field1] Initial Time
[......]

In this input we set only the first field that is the probe, we use a DELTA function as field in such a way to probe all the frequencies, and set the starting point of the delta at t=5 fs. Run this job in a separate folder with the command yambo_nl -F yambo.in_probe -J PROBE. Then we can analyze the spectra with ypp -u -J PROBE :

nonlinear # [R] Non-linear response analysis
Xorder= 1 # Max order of the response/exc functions
% TimeRange
-1.000000 |-1.000000 | fs # Time-window where processing is done
%
ETStpsRt= 200 # Total Energy steps
% EnRngeRt
0.00000 | 20.00000 | eV # Energy range
%
DampMode= "LORENTZIAN" # Damping type ( NONE | LORENTZIAN | GAUSSIAN )
DampFactor= 0.100000 eV # Damping parameter
PumpPATH= "none" # Path of the simulation with the Pump only

and get the dielectric response. Notice that we introduce a Lorentzian broadening the post-processing. 
Hereafter we plot the damped polarization along the y-direction and the corresponding dielectric constant:

[[File:Eps probe.png|800px|center | Probe only]]

the arrow indicates the position where we will put the Pump in the next simulation.

==Pump only==

Now we run a simulation with the pump field only. We generate the input in the same way yambo_nl -u p -F yambo.in_pump. 
These result will be our reference field in the final analysis. Here the input file for the pump:

nloptics # [R] Non-linear spectroscopy
DIP_Threads=0 # [OPENMP/X] Number of threads for dipoles
NL_Threads=0 # [OPENMP/NL] Number of threads for nl-optics
% NLBands
3 | 6 | # [NL] Bands range
%
NLverbosity= "high" # [NL] Verbosity level (low | high)
NLtime= 150.0000 fs # [NL] Simulation Time
NLintegrator= "CRANKNIC" # [NL] Integrator ("EULEREXP/RK2/RK4/RK2EXP/HEUN/INVINT/CRANKNIC")
NLCorrelation= "IPA" # [NL] Correlation ("IPA/HARTREE/TDDFT/LRC/LRW/JGM/SEX")
NLLrcAlpha= 0.000000 # [NL] Long Range Correction
NLDamping= 0.000000 eV # [NL] Damping (or dephasing)
RADLifeTime=-1.000000 fs # [RT] Radiative life-time (if negative Yambo sets it equal to Phase_LifeTime in NL)
#EvalCurrent # [NL] Evaluate the current
#FrPolPerdic # [DIP] Force periodicity of polarization respect to the external field
HARRLvcs= 21817 RL # [HA] Hartree RL components
EXXRLvcs= 21817 RL # [XX] Exchange RL components
% Field1_Freq
0.100000 | 0.100000 | eV # [RT Field1] Frequency
%
Field1_NFreqs= 1 # [RT Field1] Frequency
Field1_Int= 10000.00 kWLm2 # [RT Field1] Intensity
Field1_Width= 0.000000 fs # [RT Field1] Width
Field1_kind= "SOFTSIN" # [RT Field1] Kind(SIN|COS|RES|ANTIRES|GAUSS|DELTA|QSSIN)
Field1_pol= "linear" # [RT Field1] Pol(linear|circular)
% Field1_Dir
0.000000 | 0.000000 | 0.000000 | # [RT Field1] Versor
%
Field1_Tstart= 0.010000 fs # [RT Field1] Initial Time
% Field2_Freq
 5.42 | 5.42 | eV # [RT Field2] Frequency
%
Field2_NFreqs= 1 # [RT Field2] Frequency
Field2_Int= 1000.00 kWLm2 # [RT Field2] Intensity
Field2_Width= 10.00000 fs # [RT Field2] Width
Field2_kind= "QSSIN" # [RT Field2] Kind(SIN|COS|RES|ANTIRES|GAUSS|DELTA|QSSIN)
Field2_pol= "linear" # [RT Field2] Pol(linear|circular)
% Field2_Dir
 0.000000 | 1.000000 | 0.000000 | # [RT Field2] Versor
%
Field2_Tstart= 0.010000 fs # [RT Field2] Initial Time
[...]
In this simulation we used as Pump field QSSIN that is sinus with a Guassian envelope[https://demonstrations.wolfram.com/SineGaussianSignals/ sine-Gaussian wave]. For a list of all possible field in Yambo see the file src/modules/mod_fields.F. We centred the field frequency at 5.42 eV that is the energy of the highest peak in the previous figure, see arrow there.
Run the simulation with the command yambo_nl -F yambo.in_pump -J PUMP .
The pump field, column 6th of the file <code>o-PUMP.external_potential_F1</code>, is shown in the figure below:

[[File:Pump only.png|800px|center|Pump field]]

== Pump and probe==

Now we copy the pump in file in a new file cp yambo.in_pump yambo.in_pump_and_probe and turn on the probe field:

nloptics # [R] Non-linear spectroscopy
DIP_Threads=0 # [OPENMP/X] Number of threads for dipoles
NL_Threads=0 # [OPENMP/NL] Number of threads for nl-optics
% NLBands
3 | 6 | # [NL] Bands range
%
NLverbosity= "high" # [NL] Verbosity level (low | high)
NLtime= 150.0000 fs # [NL] Simulation Time
NLintegrator= "CRANKNIC" # [NL] Integrator ("EULEREXP/RK2/RK4/RK2EXP/HEUN/INVINT/CRANKNIC")
NLCorrelation= "IPA" # [NL] Correlation ("IPA/HARTREE/TDDFT/LRC/LRW/JGM/SEX")
NLLrcAlpha= 0.000000 # [NL] Long Range Correction
NLDamping= 0.000000 eV # [NL] Damping (or dephasing)
RADLifeTime=-1.000000 fs # [RT] Radiative life-time (if negative Yambo sets it equal to Phase_LifeTime in NL)
#EvalCurrent # [NL] Evaluate the current
#FrPolPerdic # [DIP] Force periodicity of polarization respect to the external field
HARRLvcs= 21817 RL # [HA] Hartree RL components
EXXRLvcs= 21817 RL # [XX] Exchange RL components
% Field1_Freq
0.100000 | 0.100000 | eV # [RT Field1] Frequency
%
Field1_NFreqs= 1 # [RT Field1] Frequency
Field1_Int= 1.00 kWLm2 # [RT Field1] Intensity
Field1_Width= 0.000000 fs # [RT Field1] Width
Field1_kind= "DELTA" # [RT Field1] Kind(SIN|COS|RES|ANTIRES|GAUSS|DELTA|QSSIN)
Field1_pol= "linear" # [RT Field1] Pol(linear|circular)
% Field1_Dir
 1.000000 | 0.000000 | 0.000000 | # [RT Field1] Versor
%
Field1_Tstart= 90.0000 fs # [RT Field1] Initial Time
% Field2_Freq
5.42 | 5.42 | eV # [RT Field2] Frequency
%
Field2_NFreqs= 1 # [RT Field2] Frequency
Field2_Int= 1000.00 kWLm2 # [RT Field2] Intensity
Field2_Width= 10.00000 fs # [RT Field2] Width
Field2_kind= "QSSIN" # [RT Field2] Kind(SIN|COS|RES|ANTIRES|GAUSS|DELTA|QSSIN)
Field2_pol= "linear" # [RT Field2] Pol(linear|circular)
% Field2_Dir
0.000000 | 1.000000 | 0.000000 | # [RT Field2] Versor
%
Field2_Tstart= 0.010000 fs # [RT Field2] Initial Time

'''Please note:''' by convention in Yambo we consider the first field the probe and the second the pump. 

you run the simulation with the command yambo_nl -F yambo.in_pump_and_probe -J PUMP_AND_PROBE and then we analyze the result using ypp with the command: ypp_nl -u -J PUMP_AND_PROBE :

nonlinear # [R] Non-linear response analysis
Xorder= 1 # Max order of the response/exc functions
% TimeRange
-1.000000 |-1.000000 | fs # Time-window where processing is done
%
ETStpsRt= 500 # Total Energy steps
% EnRngeRt
0.00000 | 3.9000 | eV # Energy range
%
DampMode= "GAUSSIAN" # Damping type ( NONE | LORENTZIAN | GAUSSIAN )
DampFactor= 0.085000 eV # Damping parameter
PumpPATH= "./PUMP/" # Path of the simulation with the Pump only

Notice that in this case we are interested in the spectra below the 4 eV, that is was zero without the presence of the pump. We put in the input the pump path in such way to calculate polarization of the pump&probe minus the one of generate by the pump only <math>\Delta P(t) = P_{PnP}(t) - P_{pump}(t)</math>. Then we analyze the <math>\Delta P(t)</math> and get the new spectra:

[[File:P and p spectrum.png|800px | center|Pump and probe spectrum]]

The peak that you see in this spectrum, that were not present in when the pump was zero, correspond to the transition between the different excited states. The pump field populates the state at 5.42 eV and then the probe excites electrons from this state to higher states. The energy difference between the higher excited states and the peak at 5.42 define the position of the peaks in the pump and probe spectrum, while their intensity is dictated by the dipole matrix elements between the different excited states, see Ref. <ref name="pnp"></ref>. 

'''Additional comments on pump and probe calculations '''
* We used a Gaussian damping factor, this choice is motivated by various tests we have done, and it seems to us that in pump and probe this broadening gives better results. 
* If you plot all spectrum you will notice that the "equilibrium part" is much stronger than the one induced by the pump, this is normal because only a small fraction of electron are promoted in the excited state by the pump.
* All previous simulation can be run also in presence of excitons, see Ref. <ref name="pnp"></ref> and group theory can be used to predict dark/bright transition in the pump and probe spectroscopy.<ref>[https://link.springer.com/book/10.1007/978-3-540-32899-5 Group Theory, Application to the Physics of Condensed Matter], Mildred S. S. Dresselhaus, Gene Dresselhaus, Ado Jorio, Springer Editor</ref>
* In principle is it possible to include damping and radiative life-time in the simulation to study retardation effect between the pump and probe. This approach exact in the independent particle case, but introduces an error when correlation effects are present, see Refs.<ref>[https://arxiv.org/abs/2106.03592 Excitons and carriers in transient absorption and time-resolved ARPES spectroscopy: an abinitio approach], D. Sangalli, Phys. Rev. Materials '''5''', 083803 (2021)</ref> and <ref>[https://arxiv.org/abs/1705.04245 Theory of exciton-phonon coupling], Gabriel Antonius and Steven G. Louie Phys. Rev. B '''105''', 085111 (2022)</ref>for a discussion.
* Non-linear response (SHG, THG, ...) induced by the pump is not implemented yet... if you have a good idea how to do it, please let us know

== Analysis of the results using YamboPy ==
'''This part works only with Lumen 2.0 or the last version available on Github:''' [https://gitlab.com/lumen-code https://gitlab.com/lumen-code]
 
Results can be analyzed using YamboPy with the following script:

from yambopy import *
from yambopy.plot import *

NLDB_P_and_P=YamboNLDB(calc='P_and_P')
NLDB_Pump =YamboNLDB(calc='PUMP')

pol_pump =NLDB_Pump.Polarization[0]
pol_p_and_p=NLDB_P_and_P.Polarization[0]

time=NLDB_P_and_P.IO_TIME_points
t_initial=NLDB_P_and_P.Efield[0]["initial_time"]

pol_damped=np.empty_like(pol_pump)

for i_d in range(3):
pol_damped[i_d,:]=damp_it(pol_p_and_p[i_d,:]-pol_pump[i_d,:],time,t_initial,damp_type='GAUSSIAN',damp_factor=0.085/ha2ev)

Plot_Pol(time=time, pol=pol_damped, xlim=[0,55], save_file='polarization.pdf')

Linear_Response(time=time,pol=pol_damped,efield=NLDB_P_and_P.Efield[0],plot=False,plot_file='delta_eps.pdf',e_range=[0.0,3.7],n_freqs=500)

== References ==

Exciton-phonon coupling and luminescence

2025-11-16T21:49:17Z

Attacc: Undo revision 9239 by Attacc (talk)

[[File:Tdgw-phonon-usc-01-1024x829.jpg| 400px | right]]

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

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

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

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

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

== Requirements ==

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

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

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

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

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

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

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

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

== Step 1: scf calculation ==

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

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

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

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

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

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

== Step 2: nscf calculation for Yambo ==

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

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

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

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

Again, we run the calculation

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

== Step 3: dvscf phonon calculation ==

Now we run the phonon calculation.

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

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

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

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

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

And now we run as

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

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

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

This is just the standard Yambo initialization: run

p2y

and then

yambo

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

== Step 5: run a BSE calculation ==

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

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

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

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

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

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

We can now run the code:

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

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

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

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

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

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

Type:

yambopy l2y

to see the help for the calculation. For example, if we want to do a serial run of LetzElPhC for bands from <math>n_i</math> to <math>n_f</math>, we should type:

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

Here <math>n_i</math> and <math>n_f</math> are integers representing the initial and final band indices.

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

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

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

At the end, check the <code>SAVE</code>

ls SAVE/ndb.elph_gkkp*

to see that it has created the Yambo-compatible electron-phonon databases.

If you saved the <code>lelphc.in</code> input file, you can inspect it:

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

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

Notice the variable <code>convention=yambo</code>: what does it mean? At variance with QE and many other codes, Yambo uses the "backward" momentum transfer convention for electronic scatterings. That is, an electronic transition goes from band <math>n</math> and momentum <math>k-q</math> to band <math>m</math> and momentum <math>k</math>. In the "forward" momentum transfer convention (the more standard one), the transitions go from <math>nk</math> to <math>mk+q</math>. Therefore, this variable ensures that the electron-phonon coupling matrix elements are computed as <math>\langle mk|dV|nk-q\rangle</math>. This will have consequences also in the formulation of the ''exciton''-phonon coupling matrix element.

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

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

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

Our objective is obtaining the following quantity:

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

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

NB:

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

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

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

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

import numpy as np
from yambopy import YamboLatticeDB,YamboWFDB,LetzElphElectronPhononDB
from yambopy.exciton_phonon.excph_matrix_elements import exciton_phonon_matelem

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

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

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

In this script, we can select the number exciton states <math>\lambda</math> with <code>nexc</code>, the single-particle bands range with <code>bands_range</code> (python indexing and last value is excluded). Here we calculate the couplings of the first twelve states at each finite-<math>q</math> point including <math>q=0</math>. We also include all the nine phonon modes of monolayer MoS2. We also need access to the Yambo <code>SAVE</code> directory in order to read the electronic wavefunctions: they are used to compute the electronic representation matrices (<code>dmat</code> in the code). The argument <code>dmat_mode</code> can be set to <code>'load'</code> for subsequent calculations.

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

python calculate_excph.py

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

=== Analysis of the couplings ===

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

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

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

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

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

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

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

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

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

...

Then, we load the data:

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

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

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

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

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

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

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

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

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

In our case, the resulting plot is the following.

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

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

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

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

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

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

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

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

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

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

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

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

=== Running the jobs ===

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

=== Luminescence calculation ===

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

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

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

We import the necessary tools...

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

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

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

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

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

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

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

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

ph_energies, exc_energies, exc_energies_in, G, exc_dipoles = input_data

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

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

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

It is now time to run the whole script:

python luminescence.py

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

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

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

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

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

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

== References ==

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

Exciton-phonon coupling and luminescence

2025-11-16T21:48:41Z

Attacc:

[[File:Tdgw-phonon-usc-01-1024x829.jpg| 400px | right]]

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

This tutorial is based on the following references: theory[1][2][3][4][5][6] and applications[7][8][9][10][11][12][13][14] of exciton-phonon physics.

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

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

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

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

== Requirements ==

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

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

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

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

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

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

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

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

== Step 1: scf calculation ==

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

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

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

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

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

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

== Step 2: nscf calculation for Yambo ==

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

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

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

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

Again, we run the calculation

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

== Step 3: dvscf phonon calculation ==

Now we run the phonon calculation.

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

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

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

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

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

And now we run as

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

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

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

This is just the standard Yambo initialization: run

p2y

and then

yambo

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

== Step 5: run a BSE calculation ==

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

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

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

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

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

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

We can now run the code:

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

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

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

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

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

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

Type:

yambopy l2y

to see the help for the calculation. For example, if we want to do a serial run of LetzElPhC for bands from <math>n_i</math> to <math>n_f</math>, we should type:

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

Here <math>n_i</math> and <math>n_f</math> are integers representing the initial and final band indices.

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

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

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

At the end, check the <code>SAVE</code>

ls SAVE/ndb.elph_gkkp*

to see that it has created the Yambo-compatible electron-phonon databases.

If you saved the <code>lelphc.in</code> input file, you can inspect it:

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

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

Notice the variable <code>convention=yambo</code>: what does it mean? At variance with QE and many other codes, Yambo uses the "backward" momentum transfer convention for electronic scatterings. That is, an electronic transition goes from band <math>n</math> and momentum <math>k-q</math> to band <math>m</math> and momentum <math>k</math>. In the "forward" momentum transfer convention (the more standard one), the transitions go from <math>nk</math> to <math>mk+q</math>. Therefore, this variable ensures that the electron-phonon coupling matrix elements are computed as <math>\langle mk|dV|nk-q\rangle</math>. This will have consequences also in the formulation of the ''exciton''-phonon coupling matrix element.

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

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

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

Our objective is obtaining the following quantity:

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

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

NB:

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

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

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

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

import numpy as np
from yambopy import YamboLatticeDB,YamboWFDB,LetzElphElectronPhononDB
from yambopy.exciton_phonon.excph_matrix_elements import exciton_phonon_matelem

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

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

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

In this script, we can select the number exciton states <math>\lambda</math> with <code>nexc</code>, the single-particle bands range with <code>bands_range</code> (python indexing and last value is excluded). Here we calculate the couplings of the first twelve states at each finite-<math>q</math> point including <math>q=0</math>. We also include all the nine phonon modes of monolayer MoS2. We also need access to the Yambo <code>SAVE</code> directory in order to read the electronic wavefunctions: they are used to compute the electronic representation matrices (<code>dmat</code> in the code). The argument <code>dmat_mode</code> can be set to <code>'load'</code> for subsequent calculations.

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

python calculate_excph.py

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

=== Analysis of the couplings ===

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

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

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

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

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

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

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

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

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

...

Then, we load the data:

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

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

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

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

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

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

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

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

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

In our case, the resulting plot is the following.

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

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

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

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

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

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

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

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

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

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

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

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

=== Running the jobs ===

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

=== Luminescence calculation ===

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

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

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

We import the necessary tools...

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

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

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

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

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

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

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

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

ph_energies, exc_energies, exc_energies_in, G, exc_dipoles = input_data

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

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

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

It is now time to run the whole script:

python luminescence.py

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

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

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

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

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

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

== References ==

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

Tutorials all

2025-10-30T11:37:40Z

Attacc: /* Non-Linear response */

This page contains the full list of available tutorials. These cover a variety of mixed topics, both physical and methodological. Some of these are om "Standalone mode" and are designed to be followed from start to finish in one page. Others have been ported in "Modular form". These are also available under the link [[Tutorials modular]]. The tutorials do not require previous knowledge of yambo, unless explicitly specified. 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 ==
* [[First steps: a walk through from DFT to optical properties]] (modular tutorial)
* [[Silicon|GW on bulk silicon]]
* [[GW on h-BN (standalone)|GW on h-BN]] (standalone version); [[How to obtain the quasi-particle band structure of a bulk material: h-BN|GW on h-BN]] (modular version)
* [[LiF|BSE in lithium-floride]]
* [[BSE tutorial on hBN]]
* [[How to analyse excitons]]

== More on GW and Quasi-particles ==
* [[Real_Axis_and_Lifetimes|Real Axis and Lifetimes]]
* [[Self-consistent GW on eigenvalues only]]
* [[GW parallel strategies|GW parallel strategies v1]]; [[GW parallel strategies CECAM|GW parallel strategies v2]]; [[Pushing convergence in parallel|GW convergence in parallel]] (modular tutorials)
* [[GW tutorial on HPC]] (external tutorial on HackMD)
* [[Quasi-particles and Self-energy within the Multipole Approximation (MPA)]]
* [http://www.attaccalite.com/gw-correction-on-an-arbitrary-point-of-the-brillouin-zone GW on arbitrary k point] (external tutorial on www.attaccalite.com)

== More on Linear response and BSE ==
* [[Hydrogen chain|TDDFT Failure and long range correlations]]
* [[SOC|Spin-orbit coupling in GaSb]]
* [[The magneto-optical Kerr effect|The magneto-optical Kerr effect in bulk iron, RPA]]
* [[The magneto-optical Kerr effect including excitonic effects|The magneto-optical Kerr effect in XXX, excitonic effects]] (todo)
* [[Dichroism in molecules]]
* [[Surface spectroscopy]] (to restore from older version)
* [[Si_Surface|Linear Response of a silicon surface (2D)]]
* [http://www.attaccalite.com/speed-up-dielectric-constant-calculations-using-the-double-grid-method-with-yambo/ Speed up dielectric constant calculations using the double-grid method] (to be imported)
* [[Si_wire|Linear Response from a silicon wire (1D)]] (to restore from old version)
* [[H2|H2 molecule: Linear Response & TDDFT (0D)]] (to restore from old version)
* [[SiH4|SiH4: isolated molecule TDDFT & BSE (0D)]] (restored from old version, still to be finalized)

== Post Processing with ypp ==
* [[Yambo Post Processing (ypp)]]

== Electron phonon coupling ==
* [[Electron Phonon Coupling|Electron Phonon Coupling]]
* [[Optical properties at finite temperature]]
* [[Phonon-assisted luminescence by finite atomic displacements]]
* [[Exciton-phonon coupling and luminescence]]

== Real time & Non linear response ==
=== Linear response ===
* [[Linear response from real time simulations (density matrix only)|Linear response using the density matrix (IP)]]
* [[Linear response using Dynamical Berry Phase|Linear response using wave-functions and Dynamical Berry Phase (IP)]]
* [[Linear response in velocity gauge|Linear response using wave-functions in velocity gauge (IP)]]
* [[Real time Bethe-Salpeter Equation (density_matrix_only)|Linear response using the density matrix (TD-HSEX)]]
* [[Linear response from real time simulations|Linear response from real time simulations (IP & TD-HSEX)]] (modular tutorial)

=== Non-Linear response ===
* [[Real time approach to non-linear response (SHG)]]
* [[Correlation effects in the non-linear response]]
* [[SHG within the TD-HSEX level (also called TD-aGW or TD-BSE)]]

=== Pump and Probe experiments ===
* [[Nonequilibrium absorption in bulk silicon|Pump and Probe: Transient Absorption from BSE with NEQ occupations]]
* [[Pump and Probe|Pump and Probe: Transient Absorption from real time propagation with pump and probe]]
* [[Pump and Probe: Time resolved ARPES|Pump and Probe: Time resolved ARPES from real time propagation with pump]]

== Developing Yambo ==
* [[How to create a new project in Yambo]]
* [[How to create a new ypp interface]]
* [[Some hints on github]]

Tutorials all

2025-10-30T11:29:08Z

Attacc: /* Pump and Probe experiments */

This page contains the full list of available tutorials. These cover a variety of mixed topics, both physical and methodological. Some of these are om "Standalone mode" and are designed to be followed from start to finish in one page. Others have been ported in "Modular form". These are also available under the link [[Tutorials modular]]. The tutorials do not require previous knowledge of yambo, unless explicitly specified. 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 ==
* [[First steps: a walk through from DFT to optical properties]] (modular tutorial)
* [[Silicon|GW on bulk silicon]]
* [[GW on h-BN (standalone)|GW on h-BN]] (standalone version); [[How to obtain the quasi-particle band structure of a bulk material: h-BN|GW on h-BN]] (modular version)
* [[LiF|BSE in lithium-floride]]
* [[BSE tutorial on hBN]]
* [[How to analyse excitons]]

== More on GW and Quasi-particles ==
* [[Real_Axis_and_Lifetimes|Real Axis and Lifetimes]]
* [[Self-consistent GW on eigenvalues only]]
* [[GW parallel strategies|GW parallel strategies v1]]; [[GW parallel strategies CECAM|GW parallel strategies v2]]; [[Pushing convergence in parallel|GW convergence in parallel]] (modular tutorials)
* [[GW tutorial on HPC]] (external tutorial on HackMD)
* [[Quasi-particles and Self-energy within the Multipole Approximation (MPA)]]
* [http://www.attaccalite.com/gw-correction-on-an-arbitrary-point-of-the-brillouin-zone GW on arbitrary k point] (external tutorial on www.attaccalite.com)

== More on Linear response and BSE ==
* [[Hydrogen chain|TDDFT Failure and long range correlations]]
* [[SOC|Spin-orbit coupling in GaSb]]
* [[The magneto-optical Kerr effect|The magneto-optical Kerr effect in bulk iron, RPA]]
* [[The magneto-optical Kerr effect including excitonic effects|The magneto-optical Kerr effect in XXX, excitonic effects]] (todo)
* [[Dichroism in molecules]]
* [[Surface spectroscopy]] (to restore from older version)
* [[Si_Surface|Linear Response of a silicon surface (2D)]]
* [http://www.attaccalite.com/speed-up-dielectric-constant-calculations-using-the-double-grid-method-with-yambo/ Speed up dielectric constant calculations using the double-grid method] (to be imported)
* [[Si_wire|Linear Response from a silicon wire (1D)]] (to restore from old version)
* [[H2|H2 molecule: Linear Response & TDDFT (0D)]] (to restore from old version)
* [[SiH4|SiH4: isolated molecule TDDFT & BSE (0D)]] (restored from old version, still to be finalized)

== Post Processing with ypp ==
* [[Yambo Post Processing (ypp)]]

== Electron phonon coupling ==
* [[Electron Phonon Coupling|Electron Phonon Coupling]]
* [[Optical properties at finite temperature]]
* [[Phonon-assisted luminescence by finite atomic displacements]]
* [[Exciton-phonon coupling and luminescence]]

== Real time & Non linear response ==
=== Linear response ===
* [[Linear response from real time simulations (density matrix only)|Linear response using the density matrix (IP)]]
* [[Linear response using Dynamical Berry Phase|Linear response using wave-functions and Dynamical Berry Phase (IP)]]
* [[Linear response in velocity gauge|Linear response using wave-functions in velocity gauge (IP)]]
* [[Real time Bethe-Salpeter Equation (density_matrix_only)|Linear response using the density matrix (TD-HSEX)]]
* [[Linear response from real time simulations|Linear response from real time simulations (IP & TD-HSEX)]] (modular tutorial)

=== Non-Linear response ===
* [[Real time approach to non-linear response (SHG)]]
* [[Correlation effects in the non-linear response]]
* [[SHG within the TD-HSEX level (also called TD-aGW or TD-BSE)]]
* [[A fast approach to excitonic effects in linear/non-linear response]]
* [[Angular dependence of non-linear response]]
* [[Third Harmonic Generation (THG)]]
* [[Two-photon absorption]]
* [[Parallelization for non-linear response calculations]]

=== Pump and Probe experiments ===
* [[Nonequilibrium absorption in bulk silicon|Pump and Probe: Transient Absorption from BSE with NEQ occupations]]
* [[Pump and Probe|Pump and Probe: Transient Absorption from real time propagation with pump and probe]]
* [[Pump and Probe: Time resolved ARPES|Pump and Probe: Time resolved ARPES from real time propagation with pump]]

== Developing Yambo ==
* [[How to create a new project in Yambo]]
* [[How to create a new ypp interface]]
* [[Some hints on github]]

Tutorials all

2025-10-30T11:25:19Z

Attacc: /* Non-Linear response */

This page contains the full list of available tutorials. These cover a variety of mixed topics, both physical and methodological. Some of these are om "Standalone mode" and are designed to be followed from start to finish in one page. Others have been ported in "Modular form". These are also available under the link [[Tutorials modular]]. The tutorials do not require previous knowledge of yambo, unless explicitly specified. 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 ==
* [[First steps: a walk through from DFT to optical properties]] (modular tutorial)
* [[Silicon|GW on bulk silicon]]
* [[GW on h-BN (standalone)|GW on h-BN]] (standalone version); [[How to obtain the quasi-particle band structure of a bulk material: h-BN|GW on h-BN]] (modular version)
* [[LiF|BSE in lithium-floride]]
* [[BSE tutorial on hBN]]
* [[How to analyse excitons]]

== More on GW and Quasi-particles ==
* [[Real_Axis_and_Lifetimes|Real Axis and Lifetimes]]
* [[Self-consistent GW on eigenvalues only]]
* [[GW parallel strategies|GW parallel strategies v1]]; [[GW parallel strategies CECAM|GW parallel strategies v2]]; [[Pushing convergence in parallel|GW convergence in parallel]] (modular tutorials)
* [[GW tutorial on HPC]] (external tutorial on HackMD)
* [[Quasi-particles and Self-energy within the Multipole Approximation (MPA)]]
* [http://www.attaccalite.com/gw-correction-on-an-arbitrary-point-of-the-brillouin-zone GW on arbitrary k point] (external tutorial on www.attaccalite.com)

== More on Linear response and BSE ==
* [[Hydrogen chain|TDDFT Failure and long range correlations]]
* [[SOC|Spin-orbit coupling in GaSb]]
* [[The magneto-optical Kerr effect|The magneto-optical Kerr effect in bulk iron, RPA]]
* [[The magneto-optical Kerr effect including excitonic effects|The magneto-optical Kerr effect in XXX, excitonic effects]] (todo)
* [[Dichroism in molecules]]
* [[Surface spectroscopy]] (to restore from older version)
* [[Si_Surface|Linear Response of a silicon surface (2D)]]
* [http://www.attaccalite.com/speed-up-dielectric-constant-calculations-using-the-double-grid-method-with-yambo/ Speed up dielectric constant calculations using the double-grid method] (to be imported)
* [[Si_wire|Linear Response from a silicon wire (1D)]] (to restore from old version)
* [[H2|H2 molecule: Linear Response & TDDFT (0D)]] (to restore from old version)
* [[SiH4|SiH4: isolated molecule TDDFT & BSE (0D)]] (restored from old version, still to be finalized)

== Post Processing with ypp ==
* [[Yambo Post Processing (ypp)]]

== Electron phonon coupling ==
* [[Electron Phonon Coupling|Electron Phonon Coupling]]
* [[Optical properties at finite temperature]]
* [[Phonon-assisted luminescence by finite atomic displacements]]
* [[Exciton-phonon coupling and luminescence]]

== Real time & Non linear response ==
=== Linear response ===
* [[Linear response from real time simulations (density matrix only)|Linear response using the density matrix (IP)]]
* [[Linear response using Dynamical Berry Phase|Linear response using wave-functions and Dynamical Berry Phase (IP)]]
* [[Linear response in velocity gauge|Linear response using wave-functions in velocity gauge (IP)]]
* [[Real time Bethe-Salpeter Equation (density_matrix_only)|Linear response using the density matrix (TD-HSEX)]]
* [[Linear response from real time simulations|Linear response from real time simulations (IP & TD-HSEX)]] (modular tutorial)

=== Non-Linear response ===
* [[Real time approach to non-linear response (SHG)]]
* [[Correlation effects in the non-linear response]]
* [[SHG within the TD-HSEX level (also called TD-aGW or TD-BSE)]]
* [[A fast approach to excitonic effects in linear/non-linear response]]
* [[Angular dependence of non-linear response]]
* [[Third Harmonic Generation (THG)]]
* [[Two-photon absorption]]
* [[Parallelization for non-linear response calculations]]

=== Pump and Probe experiments ===
* [[Nonequilibrium absorption in bulk silicon|Pump and Probe: Transient Absorption from BSE with NEQ occupations]]
* [[Pump and Probe|Pump and Probe: Transient Absorption from real time propagation with pump and probe]]
* [[Pump and Probe: Time resolved ARPES|Pump and Probe: Time resolved ARPES from real time propagation with pump]]
* [[Pump and Probe: reading electronic occuations from Perturbo code]]

== Developing Yambo ==
* [[How to create a new project in Yambo]]
* [[How to create a new ypp interface]]
* [[Some hints on github]]

Tutorials all

2025-10-28T08:37:10Z

Attacc: /* Non-Linear response */

This page contains the full list of available tutorials. These cover a variety of mixed topics, both physical and methodological. Some of these are om "Standalone mode" and are designed to be followed from start to finish in one page. Others have been ported in "Modular form". These are also available under the link [[Tutorials modular]]. The tutorials do not require previous knowledge of yambo, unless explicitly specified. 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 ==
* [[First steps: a walk through from DFT to optical properties]] (modular tutorial)
* [[Silicon|GW on bulk silicon]]
* [[GW on h-BN (standalone)|GW on h-BN]] (standalone version); [[How to obtain the quasi-particle band structure of a bulk material: h-BN|GW on h-BN]] (modular version)
* [[LiF|BSE in lithium-floride]]
* [[BSE tutorial on hBN]]
* [[How to analyse excitons]]

== More on GW and Quasi-particles ==
* [[Real_Axis_and_Lifetimes|Real Axis and Lifetimes]]
* [[Self-consistent GW on eigenvalues only]]
* [[GW parallel strategies|GW parallel strategies v1]]; [[GW parallel strategies CECAM|GW parallel strategies v2]]; [[Pushing convergence in parallel|GW convergence in parallel]] (modular tutorials)
* [[GW tutorial on HPC]] (external tutorial on HackMD)
* [[Quasi-particles and Self-energy within the Multipole Approximation (MPA)]]
* [http://www.attaccalite.com/gw-correction-on-an-arbitrary-point-of-the-brillouin-zone GW on arbitrary k point] (external tutorial on www.attaccalite.com)

== More on Linear response and BSE ==
* [[Hydrogen chain|TDDFT Failure and long range correlations]]
* [[SOC|Spin-orbit coupling in GaSb]]
* [[The magneto-optical Kerr effect|The magneto-optical Kerr effect in bulk iron, RPA]]
* [[The magneto-optical Kerr effect including excitonic effects|The magneto-optical Kerr effect in XXX, excitonic effects]] (todo)
* [[Dichroism in molecules]]
* [[Surface spectroscopy]] (to restore from older version)
* [[Si_Surface|Linear Response of a silicon surface (2D)]]
* [http://www.attaccalite.com/speed-up-dielectric-constant-calculations-using-the-double-grid-method-with-yambo/ Speed up dielectric constant calculations using the double-grid method] (to be imported)
* [[Si_wire|Linear Response from a silicon wire (1D)]] (to restore from old version)
* [[H2|H2 molecule: Linear Response & TDDFT (0D)]] (to restore from old version)
* [[SiH4|SiH4: isolated molecule TDDFT & BSE (0D)]] (restored from old version, still to be finalized)

== Post Processing with ypp ==
* [[Yambo Post Processing (ypp)]]

== Electron phonon coupling ==
* [[Electron Phonon Coupling|Electron Phonon Coupling]]
* [[Optical properties at finite temperature]]
* [[Phonon-assisted luminescence by finite atomic displacements]]
* [[Exciton-phonon coupling and luminescence]]

== Real time & Non linear response ==
=== Linear response ===
* [[Linear response from real time simulations (density matrix only)|Linear response using the density matrix (IP)]]
* [[Linear response using Dynamical Berry Phase|Linear response using wave-functions and Dynamical Berry Phase (IP)]]
* [[Linear response in velocity gauge|Linear response using wave-functions in velocity gauge (IP)]]
* [[Real time Bethe-Salpeter Equation (density_matrix_only)|Linear response using the density matrix (TD-HSEX)]]
* [[Linear response from real time simulations|Linear response from real time simulations (IP & TD-HSEX)]] (modular tutorial)

=== Non-Linear response ===
* [[Real time approach to non-linear response (SHG)]]
* [[Correlation effects in the non-linear response]]
* [[SHG within the TD-HSEX level (also called TD-aGW or TD-BSE)]]
* [[A fast approach to excitonic effects in linear/non-linear response]]
* [[Angular dependence of non-linear response]]
* [[Third Harmonic Generation (THG)]]
* [http://www.attaccalite.com/lumen/spin_orbit.html Spin-orbit coupling and non-linear response] (external tutorial on www.attaccalite.com)
* [[Two-photon absorption]]
* [[Parallelization for non-linear response calculations]]

=== Pump and Probe experiments ===
* [[Nonequilibrium absorption in bulk silicon|Pump and Probe: Transient Absorption from BSE with NEQ occupations]]
* [[Pump and Probe|Pump and Probe: Transient Absorption from real time propagation with pump and probe]]
* [[Pump and Probe: Time resolved ARPES|Pump and Probe: Time resolved ARPES from real time propagation with pump]]
* [[Pump and Probe: reading electronic occuations from Perturbo code]]

== Developing Yambo ==
* [[How to create a new project in Yambo]]
* [[How to create a new ypp interface]]
* [[Some hints on github]]

Tutorials all

2025-10-27T18:38:59Z

Attacc: /* Non-Linear response */

This page contains the full list of available tutorials. These cover a variety of mixed topics, both physical and methodological. Some of these are om "Standalone mode" and are designed to be followed from start to finish in one page. Others have been ported in "Modular form". These are also available under the link [[Tutorials modular]]. The tutorials do not require previous knowledge of yambo, unless explicitly specified. 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 ==
* [[First steps: a walk through from DFT to optical properties]] (modular tutorial)
* [[Silicon|GW on bulk silicon]]
* [[GW on h-BN (standalone)|GW on h-BN]] (standalone version); [[How to obtain the quasi-particle band structure of a bulk material: h-BN|GW on h-BN]] (modular version)
* [[LiF|BSE in lithium-floride]]
* [[BSE tutorial on hBN]]
* [[How to analyse excitons]]

== More on GW and Quasi-particles ==
* [[Real_Axis_and_Lifetimes|Real Axis and Lifetimes]]
* [[Self-consistent GW on eigenvalues only]]
* [[GW parallel strategies|GW parallel strategies v1]]; [[GW parallel strategies CECAM|GW parallel strategies v2]]; [[Pushing convergence in parallel|GW convergence in parallel]] (modular tutorials)
* [[GW tutorial on HPC]] (external tutorial on HackMD)
* [[Quasi-particles and Self-energy within the Multipole Approximation (MPA)]]
* [http://www.attaccalite.com/gw-correction-on-an-arbitrary-point-of-the-brillouin-zone GW on arbitrary k point] (external tutorial on www.attaccalite.com)

== More on Linear response and BSE ==
* [[Hydrogen chain|TDDFT Failure and long range correlations]]
* [[SOC|Spin-orbit coupling in GaSb]]
* [[The magneto-optical Kerr effect|The magneto-optical Kerr effect in bulk iron, RPA]]
* [[The magneto-optical Kerr effect including excitonic effects|The magneto-optical Kerr effect in XXX, excitonic effects]] (todo)
* [[Dichroism in molecules]]
* [[Surface spectroscopy]] (to restore from older version)
* [[Si_Surface|Linear Response of a silicon surface (2D)]]
* [http://www.attaccalite.com/speed-up-dielectric-constant-calculations-using-the-double-grid-method-with-yambo/ Speed up dielectric constant calculations using the double-grid method] (to be imported)
* [[Si_wire|Linear Response from a silicon wire (1D)]] (to restore from old version)
* [[H2|H2 molecule: Linear Response & TDDFT (0D)]] (to restore from old version)
* [[SiH4|SiH4: isolated molecule TDDFT & BSE (0D)]] (restored from old version, still to be finalized)

== Post Processing with ypp ==
* [[Yambo Post Processing (ypp)]]

== Electron phonon coupling ==
* [[Electron Phonon Coupling|Electron Phonon Coupling]]
* [[Optical properties at finite temperature]]
* [[Phonon-assisted luminescence by finite atomic displacements]]
* [[Exciton-phonon coupling and luminescence]]

== Real time & Non linear response ==
=== Linear response ===
* [[Linear response from real time simulations (density matrix only)|Linear response using the density matrix (IP)]]
* [[Linear response using Dynamical Berry Phase|Linear response using wave-functions and Dynamical Berry Phase (IP)]]
* [[Linear response in velocity gauge|Linear response using wave-functions in velocity gauge (IP)]]
* [[Real time Bethe-Salpeter Equation (density_matrix_only)|Linear response using the density matrix (TD-HSEX)]]
* [[Linear response from real time simulations|Linear response from real time simulations (IP & TD-HSEX)]] (modular tutorial)

=== Non-Linear response ===
* [[Real time approach to non-linear response (SHG)]]
* [[Correlation effects in the non-linear response]]
* [[SHG within the TD-HSEX level (also called TD-aGW or TD-BSE)]]
* [[A fast approach to excitonic effects in linear/non-linear response]]
* [[Angular dependence of non-linear response]]
* [[Third Harmonic Generation (THG)]]
* [http://www.attaccalite.com/lumen/spin_orbit.html Spin-orbit coupling and non-linear response] (external tutorial on www.attaccalite.com)
* [[Two-photon absorption]]
* [[Sum frequency generation]]
* [[Parallelization for non-linear response calculations]]

=== Pump and Probe experiments ===
* [[Nonequilibrium absorption in bulk silicon|Pump and Probe: Transient Absorption from BSE with NEQ occupations]]
* [[Pump and Probe|Pump and Probe: Transient Absorption from real time propagation with pump and probe]]
* [[Pump and Probe: Time resolved ARPES|Pump and Probe: Time resolved ARPES from real time propagation with pump]]
* [[Pump and Probe: reading electronic occuations from Perturbo code]]

== Developing Yambo ==
* [[How to create a new project in Yambo]]
* [[How to create a new ypp interface]]
* [[Some hints on github]]

Shift current

2025-10-27T18:38:45Z

Attacc: Blanked the page

Tutorials all

2025-10-27T07:44:28Z

Attacc: /* Electron phonon coupling */

This page contains the full list of available tutorials. These cover a variety of mixed topics, both physical and methodological. Some of these are om "Standalone mode" and are designed to be followed from start to finish in one page. Others have been ported in "Modular form". These are also available under the link [[Tutorials modular]]. The tutorials do not require previous knowledge of yambo, unless explicitly specified. 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 ==
* [[First steps: a walk through from DFT to optical properties]] (modular tutorial)
* [[Silicon|GW on bulk silicon]]
* [[GW on h-BN (standalone)|GW on h-BN]] (standalone version); [[How to obtain the quasi-particle band structure of a bulk material: h-BN|GW on h-BN]] (modular version)
* [[LiF|BSE in lithium-floride]]
* [[BSE tutorial on hBN]]
* [[How to analyse excitons]]

== More on GW and Quasi-particles ==
* [[Real_Axis_and_Lifetimes|Real Axis and Lifetimes]]
* [[Self-consistent GW on eigenvalues only]]
* [[GW parallel strategies|GW parallel strategies v1]]; [[GW parallel strategies CECAM|GW parallel strategies v2]]; [[Pushing convergence in parallel|GW convergence in parallel]] (modular tutorials)
* [[GW tutorial on HPC]] (external tutorial on HackMD)
* [[Quasi-particles and Self-energy within the Multipole Approximation (MPA)]]
* [http://www.attaccalite.com/gw-correction-on-an-arbitrary-point-of-the-brillouin-zone GW on arbitrary k point] (external tutorial on www.attaccalite.com)

== More on Linear response and BSE ==
* [[Hydrogen chain|TDDFT Failure and long range correlations]]
* [[SOC|Spin-orbit coupling in GaSb]]
* [[The magneto-optical Kerr effect|The magneto-optical Kerr effect in bulk iron, RPA]]
* [[The magneto-optical Kerr effect including excitonic effects|The magneto-optical Kerr effect in XXX, excitonic effects]] (todo)
* [[Dichroism in molecules]]
* [[Surface spectroscopy]] (to restore from older version)
* [[Si_Surface|Linear Response of a silicon surface (2D)]]
* [http://www.attaccalite.com/speed-up-dielectric-constant-calculations-using-the-double-grid-method-with-yambo/ Speed up dielectric constant calculations using the double-grid method] (to be imported)
* [[Si_wire|Linear Response from a silicon wire (1D)]] (to restore from old version)
* [[H2|H2 molecule: Linear Response & TDDFT (0D)]] (to restore from old version)
* [[SiH4|SiH4: isolated molecule TDDFT & BSE (0D)]] (restored from old version, still to be finalized)

== Post Processing with ypp ==
* [[Yambo Post Processing (ypp)]]

== Electron phonon coupling ==
* [[Electron Phonon Coupling|Electron Phonon Coupling]]
* [[Optical properties at finite temperature]]
* [[Phonon-assisted luminescence by finite atomic displacements]]
* [[Exciton-phonon coupling and luminescence]]

== Real time & Non linear response ==
=== Linear response ===
* [[Linear response from real time simulations (density matrix only)|Linear response using the density matrix (IP)]]
* [[Linear response using Dynamical Berry Phase|Linear response using wave-functions and Dynamical Berry Phase (IP)]]
* [[Linear response in velocity gauge|Linear response using wave-functions in velocity gauge (IP)]]
* [[Real time Bethe-Salpeter Equation (density_matrix_only)|Linear response using the density matrix (TD-HSEX)]]
* [[Linear response from real time simulations|Linear response from real time simulations (IP & TD-HSEX)]] (modular tutorial)

=== Non-Linear response ===
* [[Real time approach to non-linear response (SHG)]]
* [[Correlation effects in the non-linear response]]
* [[SHG within the TD-HSEX level (also called TD-aGW or TD-BSE)]]
* [[A fast approach to excitonic effects in linear/non-linear response]]
* [[Angular dependence of non-linear response]]
* [[Third Harmonic Generation (THG)]]
* [http://www.attaccalite.com/lumen/spin_orbit.html Spin-orbit coupling and non-linear response] (external tutorial on www.attaccalite.com)
* [[Two-photon absorption]]
* [[Sum frequency generation]]
* [[Shift current]]
* [[Parallelization for non-linear response calculations]]

=== Pump and Probe experiments ===
* [[Nonequilibrium absorption in bulk silicon|Pump and Probe: Transient Absorption from BSE with NEQ occupations]]
* [[Pump and Probe|Pump and Probe: Transient Absorption from real time propagation with pump and probe]]
* [[Pump and Probe: Time resolved ARPES|Pump and Probe: Time resolved ARPES from real time propagation with pump]]
* [[Pump and Probe: reading electronic occuations from Perturbo code]]

== Developing Yambo ==
* [[How to create a new project in Yambo]]
* [[How to create a new ypp interface]]
* [[Some hints on github]]

Thermal lines and special displacements with YamboPy

2025-10-27T07:42:23Z

Attacc: Blanked the page

Exciton-phonon coupling and luminescence

2025-10-06T12:25:50Z

Attacc: /* Analysis of the couplings */

[[File:Tdgw-phonon-usc-01-1024x829.jpg| 400px | right]]

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

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

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

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

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

== Requirements ==

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

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

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

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

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

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

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

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

== Step 1: scf calculation ==

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

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

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

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

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

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

== Step 2: nscf calculation for Yambo ==

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

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

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

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

Again, we run the calculation

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

== Step 3: dvscf phonon calculation ==

Now we run the phonon calculation.

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

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

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

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

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

And now we run as

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

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

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

This is just the standard Yambo initialization: run

p2y

and then

yambo

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

== Step 5: run a BSE calculation ==

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

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

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

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

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

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

We can now run the code:

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

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

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

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

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

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

Type:

yambopy l2y

to see the help for the calculation. For example, if we want to do a serial run of LetzElPhC for bands from <math>n_i</math> to <math>n_f</math>, we should type:

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

Here <math>n_i</math> and <math>n_f</math> are integers representing the initial and final band indices.

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

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

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

At the end, check the <code>SAVE</code>

ls SAVE/ndb.elph_gkkp*

to see that it has created the Yambo-compatible electron-phonon databases.

If you saved the <code>lelphc.in</code> input file, you can inspect it:

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

You can also run it as it is, but the code will generate the database <code>ndb.elph</code>. In order to convert it to the <code>ndb.elph_gkkp*</code> databases of Yambo, you still need a couple of lines of python using the Yambopy class <code>ConvertElectronPhononDB</code> in <code>yambopy/letzelph_interface/lelph2y.py</code>.

Notice the variable <code>convention=yambo</code>: what does it mean? At variance with QE and many other codes, Yambo uses the "backward" momentum transfer convention for electronic scatterings. That is, an electronic transition goes from band <math>n</math> and momentum <math>k-q</math> to band <math>m</math> and momentum <math>k</math>. In the "forward" momentum transfer convention (the more standard one), the transitions go from <math>nk</math> to <math>mk+q</math>. Therefore, this variable ensures that the electron-phonon coupling matrix elements are computed as <math>\langle mk|dV|nk-q\rangle</math>. This will have consequences also in the formulation of the ''exciton''-phonon coupling matrix element.

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

Now, we can finally access our basic building block for exciton-phonon physics. This could be done entirely in python (using '''Yambopy'''), or by running '''Yambo'''. In this version of the tutorial we present the latter case.

Our objective is obtaining the following quantity:

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

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

NB:

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

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

We have to write a new yambo input, that we can call <code>excph.in</code>, for this. You can copy (and adapt) the one below, or you can generate one by running from the command line:

yambo_ph -excph o

This generates an input to compute luminescence ("o" is for "optics"). The variables that we are interested in are:

excph # [R] Exction-phonon
ExcGkkp # [R][EXCPH] Exciton-Phonon Matrix Elelements
% ELPhExcStates
1 | 4 | # [EXCPH] Incoming (external) exciton states
%
% ELPhExcSum
1 | 12 | # [EXCPH] Outgoing (virtual) exciton states
%
LoutPath= "./bse_Lfull" # [EXCPH] Path of the outgoing L
% ElPhModes
1 | 9 | # [ELPH] Phonon modes included
%

In this input, we have to select the initial exciton states <math>\lambda</math> with <code>ELPhExcStates</code>, the final exciton states <math>\alpha</math> with <code>ELPhExcSum</code> and the phonon modes <math>\mu</math> with <code>ElPhModes</code>. Here we consider the first four states at <math>Q=0</math> (corresponding to just two excitons because they are both doubly degenerate -- do not break degeneracies when selecting states!) and the first twelve states at each finite-<math>q</math> point. We also include all the nine phonon modes of monolayer MoS2.

What about <code>LoutPath</code>? This variable controls the directory where the databases for the final-state excitons <math>\alpha</math> is located, which can be different from the directory with the initial-state excitons <math>\lambda</math> read as usual with the <code>-J</code> option when running the code. This makes it possible to compute the coupling between different exciton kinds. However, for our tutorial, we stick with the previously computed <code>Lfull</code> in both cases.

When we are satisfied with the input, we run the code using <code>yambo_ph</code>:

yambo_ph -F excph.in -J excph,bse_Lfull -C excph

If you check the output, you should find the <code>ndb.excph*</code> databases in the <code>excph</code> directory.

=== Analysis of the couplings ===

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

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

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

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

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

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

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

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

# Exciton in states
exc_in = [2,3] # A: 2,3 -- B: 6,7
exc_out = [0,1,2,3] # first 4 states (dispersion of triplet state and A)
ph_in = 'all'

# Paths of databases
ns_db1 =f'{path}/SAVE/ns.db1'
ndb_exc=f'{path}/excph'

...

Then, we load the data:

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

# Read exc-ph databases
X = YamboExcitonPhononDB(ylat,save_excph=ndb_exc)
print(X)

The quantity <math>F_A(q)</math> is defined inside the plotting function as

G_squared = excph.excph_sq
G2plt = np.zeros(len(G_squared))

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

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

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

And finally, we have to make a plotting function. For this tutorial we will use the default scatterplot provided by <code>YamboExcitonPhononDB</code>

excph.plot_excph(F_q,plt_cbar=plt_cbar,**kwargs)
...

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

In our case, the resulting plot is the following.

[[File:1L MoS2 ExcPh.png|500px|center]]

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

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

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

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

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

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

<math>I^{(1)}_{PL}(\omega;T) \propto \frac{1}{N_q}\sum_{ s \mu \beta q} \left|\sum_\lambda\frac{D_\lambda \mathcal{G}^{\mu q}_{\alpha q,\lambda}}{E_{\alpha q}-E_\lambda -s\Omega_{\mu q}} \right|^2 N_{\alpha q}(T_{exc}) F^s_{\mu q}(T)\delta(\omega - \left[E_{\alpha q}-s\Omega_{\mu q}\right])</math>

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

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

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

=== Running the jobs ===

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

5. Now we run <code>lelphc</code> with yambopy to get the el-ph matrix elements:

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

6. And finally we generate the exciton-phonon input <code>excph.in</code> using <code>yambo_ph -excph o</code>. Now, we take a look at all the additional variables that we didn't check before, specifying also the details for luminescence the spectrum calculation.

excph # [R] Exction-phonon
ExcGkkp # [R][EXCPH] Exciton-Phonon Matrix Elelements
ExcPhOptics # [R][EXCPH] Exciton-Phonon Optics
BoseTemp=10.000000 Kn # Bosonic Temperature
EXCTemp= 10.000000 Kn # [EXCPH] Excitonic Temperature (for luminescence spectra)
% ELPhExcStates
1 | 4 | # [EXCPH] Incoming (external) exciton states
%
% ELPhExcSum
1 | 12 | # [EXCPH] Outgoing (virtual) exciton states
%
% ElPhModes
1 | 12 | # [ELPH] Phonon modes included
%
LoutPath= "./bse-L_full" # [EXCPH] Path of the outgoing L
FANdEtresh= 0.100000E-5 eV # [ELPH] Energy treshold for Fan denominator
EXCPHdEtresh= 0.100000E-5 eV # [ELPH] Energy treshold for exc-ph denominator
LDamping= 0.500000E-3 eV # [EXCPH] Damping of exc-ph self-energy
# These are the plot parameters, same as in other parts of yambo
% EnRngeXd
4.00000 | 5.00000 | eV # [Xd] Energy range
%
% DmRngeXd
0.00500000 | 0.00500000 | eV # [Xd] Damping range
%
ETStpsXd= 4000 # [Xd] Total Energy steps

Here <code>BoseTemp</code> and <code>EXCTemp</code> are the lattice and excitonic temperature, respectively.

Now we run the calculation with <code>yambo_ph</code>. Here, we read as <math>Q=0</math> excitons with <code>-J</code> the ones without the long-range Coulomb exchange:

yambo_ph -F excph.in -J excph,bse_Lbar -C excph

and we find our outputs in the <code>excph</code> directory.

NB: Step 6 could have been equivalently run in yambopy, limiting the use of the yambo code to just step 4. This latter option is more flexible, as it allows for a greater degree of control by the user. We are in the last stages of the development and it will be available soon.

=== Results ===

If we check the output directory from the step 6 calculation, we find the <code>o-excph.pl_bse_ph_ass</code> output files containing the luminescence spectra. We can plot them with gnuplot or any other tool:

gnuplot
> set xrange[4.2:5]
> p 'o-excph.pl_bse_ph_ass' u 1:2 w l lc rgb 'red' lw 3

[[File:Luminescence plot.png|500px|center]]

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

== References ==

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

Exciton-phonon coupling and luminescence

2025-10-06T12:14:25Z

Attacc:

[[File:Tdgw-phonon-usc-01-1024x829.jpg| 400px | right]]

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

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

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

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

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

== Requirements ==

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

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

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

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

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

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

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

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

== Step 1: scf calculation ==

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

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

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

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

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

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

== Step 2: nscf calculation for Yambo ==

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

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

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

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

Again, we run the calculation

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

== Step 3: dvscf phonon calculation ==

Now we run the phonon calculation.

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

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

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

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

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

And now we run as

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

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

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

This is just the standard Yambo initialization: run

p2y

and then

yambo

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

== Step 5: run a BSE calculation ==

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

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

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

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

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

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

We can now run the code:

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

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

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

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

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

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

Type:

yambopy l2y

to see the help for the calculation. For example, if we want to do a serial run of LetzElPhC for bands from <math>n_i</math> to <math>n_f</math>, we should type:

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

Here <math>n_i</math> and <math>n_f</math> are integers representing the initial and final band indices.

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

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

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

At the end, check the <code>SAVE</code>

ls SAVE/ndb.elph_gkkp*

to see that it has created the Yambo-compatible electron-phonon databases.

If you saved the <code>lelphc.in</code> input file, you can inspect it:

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

You can also run it as it is, but the code will generate the database <code>ndb.elph</code>. In order to convert it to the <code>ndb.elph_gkkp*</code> databases of Yambo, you still need a couple of lines of python using the Yambopy class <code>ConvertElectronPhononDB</code> in <code>yambopy/letzelph_interface/lelph2y.py</code>.

Notice the variable <code>convention=yambo</code>: what does it mean? At variance with QE and many other codes, Yambo uses the "backward" momentum transfer convention for electronic scatterings. That is, an electronic transition goes from band <math>n</math> and momentum <math>k-q</math> to band <math>m</math> and momentum <math>k</math>. In the "forward" momentum transfer convention (the more standard one), the transitions go from <math>nk</math> to <math>mk+q</math>. Therefore, this variable ensures that the electron-phonon coupling matrix elements are computed as <math>\langle mk|dV|nk-q\rangle</math>. This will have consequences also in the formulation of the ''exciton''-phonon coupling matrix element.

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

Now, we can finally access our basic building block for exciton-phonon physics. This could be done entirely in python (using '''Yambopy'''), or by running '''Yambo'''. In this version of the tutorial we present the latter case.

Our objective is obtaining the following quantity:

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

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

NB:

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

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

We have to write a new yambo input, that we can call <code>excph.in</code>, for this. You can copy (and adapt) the one below, or you can generate one by running from the command line:

yambo_ph -excph o

This generates an input to compute luminescence ("o" is for "optics"). The variables that we are interested in are:

excph # [R] Exction-phonon
ExcGkkp # [R][EXCPH] Exciton-Phonon Matrix Elelements
% ELPhExcStates
1 | 4 | # [EXCPH] Incoming (external) exciton states
%
% ELPhExcSum
1 | 12 | # [EXCPH] Outgoing (virtual) exciton states
%
LoutPath= "./bse_Lfull" # [EXCPH] Path of the outgoing L
% ElPhModes
1 | 9 | # [ELPH] Phonon modes included
%

In this input, we have to select the initial exciton states <math>\lambda</math> with <code>ELPhExcStates</code>, the final exciton states <math>\alpha</math> with <code>ELPhExcSum</code> and the phonon modes <math>\mu</math> with <code>ElPhModes</code>. Here we consider the first four states at <math>Q=0</math> (corresponding to just two excitons because they are both doubly degenerate -- do not break degeneracies when selecting states!) and the first twelve states at each finite-<math>q</math> point. We also include all the nine phonon modes of monolayer MoS2.

What about <code>LoutPath</code>? This variable controls the directory where the databases for the final-state excitons <math>\alpha</math> is located, which can be different from the directory with the initial-state excitons <math>\lambda</math> read as usual with the <code>-J</code> option when running the code. This makes it possible to compute the coupling between different exciton kinds. However, for our tutorial, we stick with the previously computed <code>Lfull</code> in both cases.

When we are satisfied with the input, we run the code using <code>yambo_ph</code>:

yambo_ph -F excph.in -J excph,bse_Lfull -C excph

If you check the output, you should find the <code>ndb.excph*</code> databases in the <code>excph</code> directory.

=== Analysis of the couplings ===

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

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

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

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

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

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

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

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

# Exciton in states
exc_in = [2,3] # A: 2,3 -- B: 6,7
exc_out = [0,1,2,3] # first 4 states (dispersion of triplet state and A)
ph_in = 'all'

# Paths of databases
ns_db1 =f'{path}/SAVE/ns.db1'
ndb_exc=f'{path}/excph'

...

Then, we load the data:

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

# Read exc-ph databases
X = YamboExcitonPhononDB(ylat,save_excph=ndb_exc)
print(X)

The quantity <math>F_A(q)</math> is defined inside the plotting function as

G_squared = excph.excph_sq
G2plt = np.zeros(len(G_squared))

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

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

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

And finally, we have to make a plotting function. For this tutorial we will use the default scatterplot provided by <code>YamboExcitonPhononDB</code>

excph.plot_excph(F_q,plt_cbar=plt_cbar,**kwargs)
...

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

In our case, the resulting plot is the following.

[[File:1L MoS2 ExcPh.png|500px|center]]

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

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

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

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

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

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

<math>I^{(1)}_{PL}(\omega;T) \propto \frac{1}{N_q}\sum_{ s \mu \beta q} \left|\sum_\lambda\frac{D_\lambda \mathcal{G}^{\mu q}_{\alpha q,\lambda}}{E_{\alpha q}-E_\lambda -s\Omega_{\mu q}} \right|^2 N_{\alpha q}(T_{exc}) F^s_{\mu q}(T)\delta(\omega - \left[E_{\alpha q}-s\Omega_{\mu q}\right])</math>

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

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

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

=== Running the jobs ===

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

5. Now we run <code>lelphc</code> with yambopy to get the el-ph matrix elements:

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

6. And finally we generate the exciton-phonon input <code>excph.in</code> using <code>yambo_ph -excph o</code>. Now, we take a look at all the additional variables that we didn't check before, specifying also the details for luminescence the spectrum calculation.

excph # [R] Exction-phonon
ExcGkkp # [R][EXCPH] Exciton-Phonon Matrix Elelements
ExcPhOptics # [R][EXCPH] Exciton-Phonon Optics
BoseTemp=10.000000 Kn # Bosonic Temperature
EXCTemp= 10.000000 Kn # [EXCPH] Excitonic Temperature (for luminescence spectra)
% ELPhExcStates
1 | 4 | # [EXCPH] Incoming (external) exciton states
%
% ELPhExcSum
1 | 12 | # [EXCPH] Outgoing (virtual) exciton states
%
% ElPhModes
1 | 12 | # [ELPH] Phonon modes included
%
LoutPath= "./bse-L_full" # [EXCPH] Path of the outgoing L
FANdEtresh= 0.100000E-5 eV # [ELPH] Energy treshold for Fan denominator
EXCPHdEtresh= 0.100000E-5 eV # [ELPH] Energy treshold for exc-ph denominator
LDamping= 0.500000E-3 eV # [EXCPH] Damping of exc-ph self-energy
# These are the plot parameters, same as in other parts of yambo
% EnRngeXd
4.00000 | 5.00000 | eV # [Xd] Energy range
%
% DmRngeXd
0.00500000 | 0.00500000 | eV # [Xd] Damping range
%
ETStpsXd= 4000 # [Xd] Total Energy steps

Here <code>BoseTemp</code> and <code>EXCTemp</code> are the lattice and excitonic temperature, respectively.

Now we run the calculation with <code>yambo_ph</code>. Here, we read as <math>Q=0</math> excitons with <code>-J</code> the ones without the long-range Coulomb exchange:

yambo_ph -F excph.in -J excph,bse_Lbar -C excph

and we find our outputs in the <code>excph</code> directory.

NB: Step 6 could have been equivalently run in yambopy, limiting the use of the yambo code to just step 4. This latter option is more flexible, as it allows for a greater degree of control by the user. We are in the last stages of the development and it will be available soon.

=== Results ===

If we check the output directory from the step 6 calculation, we find the <code>o-excph.pl_bse_ph_ass</code> output files containing the luminescence spectra. We can plot them with gnuplot or any other tool:

gnuplot
> set xrange[4.2:5]
> p 'o-excph.pl_bse_ph_ass' u 1:2 w l lc rgb 'red' lw 3

[[File:Luminescence plot.png|500px|center]]

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

== References ==

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

Exciton-phonon coupling and luminescence

2025-10-06T12:02:17Z

Attacc:

[[File:Tdgw-phonon-usc-01-1024x829.jpg| 400px | right]]

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

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

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

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

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

== Requirements ==

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

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

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

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

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

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

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

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

== Step 1: scf calculation ==

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

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

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

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

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

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

== Step 2: nscf calculation for Yambo ==

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

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

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

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

Again, we run the calculation

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

== Step 3: dvscf phonon calculation ==

Now we run the phonon calculation.

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

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

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

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

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

And now we run as

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

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

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

This is just the standard Yambo initialization: run

p2y

and then

yambo

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

== Step 5: run a BSE calculation ==

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

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

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

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

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

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

We can now run the code:

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

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

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

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

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

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

Type:

yambopy l2y

to see the help for the calculation. For example, if we want to do a serial run of LetzElPhC for bands from <math>n_i</math> to <math>n_f</math>, we should type:

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

Here <math>n_i</math> and <math>n_f</math> are integers representing the initial and final band indices.

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

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

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

At the end, check the <code>SAVE</code>

ls SAVE/ndb.elph_gkkp*

to see that it has created the Yambo-compatible electron-phonon databases.

If you saved the <code>lelphc.in</code> input file, you can inspect it:

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

You can also run it as it is, but the code will generate the database <code>ndb.elph</code>. In order to convert it to the <code>ndb.elph_gkkp*</code> databases of Yambo, you still need a couple of lines of python using the Yambopy class <code>ConvertElectronPhononDB</code> in <code>yambopy/letzelph_interface/lelph2y.py</code>.

Notice the variable <code>convention=yambo</code>: what does it mean? At variance with QE and many other codes, Yambo uses the "backward" momentum transfer convention for electronic scatterings. That is, an electronic transition goes from band <math>n</math> and momentum <math>k-q</math> to band <math>m</math> and momentum <math>k</math>. In the "forward" momentum transfer convention (the more standard one), the transitions go from <math>nk</math> to <math>mk+q</math>. Therefore, this variable ensures that the electron-phonon coupling matrix elements are computed as <math>\langle mk|dV|nk-q\rangle</math>. This will have consequences also in the formulation of the ''exciton''-phonon coupling matrix element.

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

Now, we can finally access our basic building block for exciton-phonon physics. This could be done entirely in python (using '''Yambopy'''), or by running '''Yambo'''. In this version of the tutorial we present the latter case.

Our objective is obtaining the following quantity:

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

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

NB:

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

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

We have to write a new yambo input, that we can call <code>excph.in</code>, for this. You can copy (and adapt) the one below, or you can generate one by running from the command line:

yambo_ph -excph o

This generates an input to compute luminescence ("o" is for "optics"). The variables that we are interested in are:

excph # [R] Exction-phonon
ExcGkkp # [R][EXCPH] Exciton-Phonon Matrix Elelements
% ELPhExcStates
1 | 4 | # [EXCPH] Incoming (external) exciton states
%
% ELPhExcSum
1 | 12 | # [EXCPH] Outgoing (virtual) exciton states
%
LoutPath= "./bse_Lfull" # [EXCPH] Path of the outgoing L
% ElPhModes
1 | 9 | # [ELPH] Phonon modes included
%

In this input, we have to select the initial exciton states <math>\lambda</math> with <code>ELPhExcStates</code>, the final exciton states <math>\alpha</math> with <code>ELPhExcSum</code> and the phonon modes <math>\mu</math> with <code>ElPhModes</code>. Here we consider the first four states at <math>Q=0</math> (corresponding to just two excitons because they are both doubly degenerate -- do not break degeneracies when selecting states!) and the first twelve states at each finite-<math>q</math> point. We also include all the nine phonon modes of monolayer MoS2.

What about <code>LoutPath</code>? This variable controls the directory where the databases for the final-state excitons <math>\alpha</math> is located, which can be different from the directory with the initial-state excitons <math>\lambda</math> read as usual with the <code>-J</code> option when running the code. This makes it possible to compute the coupling between different exciton kinds. However, for our tutorial, we stick with the previously computed <code>Lfull</code> in both cases.

When we are satisfied with the input, we run the code using <code>yambo_ph</code>:

yambo_ph -F excph.in -J excph,bse_Lfull -C excph

If you check the output, you should find the <code>ndb.excph*</code> databases in the <code>excph</code> directory.

=== Analysis of the couplings ===

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

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

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

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

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

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

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

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

# Exciton in states
exc_in = [2,3] # A: 2,3 -- B: 6,7
exc_out = [0,1,2,3] # first 4 states (dispersion of triplet state and A)
ph_in = 'all'

# Paths of databases
ns_db1 =f'{path}/SAVE/ns.db1'
ndb_exc=f'{path}/excph'

...

Then, we load the data:

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

# Read exc-ph databases
X = YamboExcitonPhononDB(ylat,save_excph=ndb_exc)
print(X)

The quantity <math>F_A(q)</math> is defined inside the plotting function as

G_squared = excph.excph_sq
G2plt = np.zeros(len(G_squared))

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

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

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

And finally, we have to make a plotting function. For this tutorial we will use the default scatterplot provided by <code>YamboExcitonPhononDB</code>

excph.plot_excph(F_q,plt_cbar=plt_cbar,**kwargs)
...

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

In our case, the resulting plot is the following.

[[File:1L MoS2 ExcPh.png|500px|center]]

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

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

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

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

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

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

<math>I^{(1)}_{PL}(\omega;T) \propto \frac{1}{N_q}\sum_{ s \mu \beta q} \left|\sum_\lambda\frac{D_\lambda \mathcal{G}^{\mu q}_{\alpha q,\lambda}}{E_{\alpha q}-E_\lambda -s\Omega_{\mu q}} \right|^2 N_{\alpha q}(T_{exc}) F^s_{\mu q}(T)\delta(\omega - \left[E_{\alpha q}-s\Omega_{\mu q}\right])</math>

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

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

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

=== Running the jobs ===

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

5. Now we run <code>lelphc</code> with yambopy to get the el-ph matrix elements:

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

6. And finally we generate the exciton-phonon input <code>excph.in</code> using <code>yambo_ph -excph o</code>. Now, we take a look at all the additional variables that we didn't check before, specifying also the details for luminescence the spectrum calculation.

excph # [R] Exction-phonon
ExcGkkp # [R][EXCPH] Exciton-Phonon Matrix Elelements
ExcPhOptics # [R][EXCPH] Exciton-Phonon Optics
BoseTemp=10.000000 Kn # Bosonic Temperature
EXCTemp= 10.000000 Kn # [EXCPH] Excitonic Temperature (for luminescence spectra)
% ELPhExcStates
1 | 4 | # [EXCPH] Incoming (external) exciton states
%
% ELPhExcSum
1 | 12 | # [EXCPH] Outgoing (virtual) exciton states
%
% ElPhModes
1 | 12 | # [ELPH] Phonon modes included
%
LoutPath= "./bse-L_full" # [EXCPH] Path of the outgoing L
FANdEtresh= 0.100000E-5 eV # [ELPH] Energy treshold for Fan denominator
EXCPHdEtresh= 0.100000E-5 eV # [ELPH] Energy treshold for exc-ph denominator
LDamping= 0.500000E-3 eV # [EXCPH] Damping of exc-ph self-energy
# These are the plot parameters, same as in other parts of yambo
% EnRngeXd
4.00000 | 5.00000 | eV # [Xd] Energy range
%
% DmRngeXd
0.00500000 | 0.00500000 | eV # [Xd] Damping range
%
ETStpsXd= 4000 # [Xd] Total Energy steps

Here <code>BoseTemp</code> and <code>EXCTemp</code> are the lattice and excitonic temperature, respectively.

Now we run the calculation with <code>yambo_ph</code>. Here, we read as <math>Q=0</math> excitons with <code>-J</code> the ones without the long-range Coulomb exchange:

yambo_ph -F excph.in -J excph,bse_Lbar -C excph

and we find our outputs in the <code>excph</code> directory.

NB: Step 6 could have been equivalently run in yambopy, limiting the use of the yambo code to just step 4. This latter option is more flexible, as it allows for a greater degree of control by the user. We are in the last stages of the development and it will be available soon.

=== Results ===

If we check the output directory from the step 6 calculation, we find the <code>o-excph.pl_bse_ph_ass</code> output files containing the luminescence spectra. We can plot them with gnuplot or any other tool:

gnuplot
> set xrange[4.2:5]
> p 'o-excph.pl_bse_ph_ass' u 1:2 w l lc rgb 'red' lw 3

[[File:Luminescence plot.png|500px|center]]

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

== References ==

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

Exciton-phonon coupling and luminescence

2025-10-06T12:02:01Z

Attacc:

[[File:Tdgw-phonon-usc-01-1024x829.jpg| 400px | right]]

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

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

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

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

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

== Requirements ==

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

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

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

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

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

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

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

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

== Step 1: scf calculation ==

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

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

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

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

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

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

== Step 2: nscf calculation for Yambo ==

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

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

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

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

Again, we run the calculation

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

== Step 3: dvscf phonon calculation ==

Now we run the phonon calculation.

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

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

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

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

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

And now we run as

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

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

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

This is just the standard Yambo initialization: run

p2y

and then

yambo

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

== Step 5: run a BSE calculation ==

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

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

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

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

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

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

We can now run the code:

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

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

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

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

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

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

Type:

yambopy l2y

to see the help for the calculation. For example, if we want to do a serial run of LetzElPhC for bands from <math>n_i</math> to <math>n_f</math>, we should type:

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

Here <math>n_i</math> and <math>n_f</math> are integers representing the initial and final band indices.

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

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

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

At the end, check the <code>SAVE</code>

ls SAVE/ndb.elph_gkkp*

to see that it has created the Yambo-compatible electron-phonon databases.

If you saved the <code>lelphc.in</code> input file, you can inspect it:

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

You can also run it as it is, but the code will generate the database <code>ndb.elph</code>. In order to convert it to the <code>ndb.elph_gkkp*</code> databases of Yambo, you still need a couple of lines of python using the Yambopy class <code>ConvertElectronPhononDB</code> in <code>yambopy/letzelph_interface/lelph2y.py</code>.

Notice the variable <code>convention=yambo</code>: what does it mean? At variance with QE and many other codes, Yambo uses the "backward" momentum transfer convention for electronic scatterings. That is, an electronic transition goes from band <math>n</math> and momentum <math>k-q</math> to band <math>m</math> and momentum <math>k</math>. In the "forward" momentum transfer convention (the more standard one), the transitions go from <math>nk</math> to <math>mk+q</math>. Therefore, this variable ensures that the electron-phonon coupling matrix elements are computed as <math>\langle mk|dV|nk-q\rangle</math>. This will have consequences also in the formulation of the ''exciton''-phonon coupling matrix element.

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

Now, we can finally access our basic building block for exciton-phonon physics. This could be done entirely in python (using '''Yambopy'''), or by running '''Yambo'''. In this version of the tutorial we present the latter case.

Our objective is obtaining the following quantity:

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

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

NB:

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

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

We have to write a new yambo input, that we can call <code>excph.in</code>, for this. You can copy (and adapt) the one below, or you can generate one by running from the command line:

yambo_ph -excph o

This generates an input to compute luminescence ("o" is for "optics"). The variables that we are interested in are:

excph # [R] Exction-phonon
ExcGkkp # [R][EXCPH] Exciton-Phonon Matrix Elelements
% ELPhExcStates
1 | 4 | # [EXCPH] Incoming (external) exciton states
%
% ELPhExcSum
1 | 12 | # [EXCPH] Outgoing (virtual) exciton states
%
LoutPath= "./bse_Lfull" # [EXCPH] Path of the outgoing L
% ElPhModes
1 | 9 | # [ELPH] Phonon modes included
%

In this input, we have to select the initial exciton states <math>\lambda</math> with <code>ELPhExcStates</code>, the final exciton states <math>\alpha</math> with <code>ELPhExcSum</code> and the phonon modes <math>\mu</math> with <code>ElPhModes</code>. Here we consider the first four states at <math>Q=0</math> (corresponding to just two excitons because they are both doubly degenerate -- do not break degeneracies when selecting states!) and the first twelve states at each finite-<math>q</math> point. We also include all the nine phonon modes of monolayer MoS2.

What about <code>LoutPath</code>? This variable controls the directory where the databases for the final-state excitons <math>\alpha</math> is located, which can be different from the directory with the initial-state excitons <math>\lambda</math> read as usual with the <code>-J</code> option when running the code. This makes it possible to compute the coupling between different exciton kinds. However, for our tutorial, we stick with the previously computed <code>Lfull</code> in both cases.

When we are satisfied with the input, we run the code using <code>yambo_ph</code>:

yambo_ph -F excph.in -J excph,bse_Lfull -C excph

If you check the output, you should find the <code>ndb.excph*</code> databases in the <code>excph</code> directory.

=== Analysis of the couplings ===

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

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

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

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

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

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

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

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

# Exciton in states
exc_in = [2,3] # A: 2,3 -- B: 6,7
exc_out = [0,1,2,3] # first 4 states (dispersion of triplet state and A)
ph_in = 'all'

# Paths of databases
ns_db1 =f'{path}/SAVE/ns.db1'
ndb_exc=f'{path}/excph'

...

Then, we load the data:

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

# Read exc-ph databases
X = YamboExcitonPhononDB(ylat,save_excph=ndb_exc)
print(X)

The quantity <math>F_A(q)</math> is defined inside the plotting function as

G_squared = excph.excph_sq
G2plt = np.zeros(len(G_squared))

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

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

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

And finally, we have to make a plotting function. For this tutorial we will use the default scatterplot provided by <code>YamboExcitonPhononDB</code>

excph.plot_excph(F_q,plt_cbar=plt_cbar,**kwargs)
...

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

In our case, the resulting plot is the following.

[[File:1L MoS2 ExcPh.png|500px|center]]

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

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

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

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

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

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

<math>I^{(1)}_{PL}(\omega;T) \propto \frac{1}{N_q}\sum_{ s \mu \beta q} \left|\sum_\lambda\frac{D_\lambda \mathcal{G}^{\mu q}_{\alpha q,\lambda}}{E_{\alpha q}-E_\lambda -s\Omega_{\mu q}} \right|^2 N_{\alpha q}(T_{exc}) F^s_{\mu q}(T)\delta(\omega - \left[E_{\alpha q}-s\Omega_{\mu q}\right])</math>

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

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

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

=== Running the jobs ===

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

5. Now we run <code>lelphc</code> with yambopy to get the el-ph matrix elements:

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

6. And finally we generate the exciton-phonon input <code>excph.in</code> using <code>yambo_ph -excph o</code>. Now, we take a look at all the additional variables that we didn't check before, specifying also the details for luminescence the spectrum calculation.

excph # [R] Exction-phonon
ExcGkkp # [R][EXCPH] Exciton-Phonon Matrix Elelements
ExcPhOptics # [R][EXCPH] Exciton-Phonon Optics
BoseTemp=10.000000 Kn # Bosonic Temperature
EXCTemp= 10.000000 Kn # [EXCPH] Excitonic Temperature (for luminescence spectra)
% ELPhExcStates
1 | 4 | # [EXCPH] Incoming (external) exciton states
%
% ELPhExcSum
1 | 12 | # [EXCPH] Outgoing (virtual) exciton states
%
% ElPhModes
1 | 12 | # [ELPH] Phonon modes included
%
LoutPath= "./bse-L_full" # [EXCPH] Path of the outgoing L
FANdEtresh= 0.100000E-5 eV # [ELPH] Energy treshold for Fan denominator
EXCPHdEtresh= 0.100000E-5 eV # [ELPH] Energy treshold for exc-ph denominator
LDamping= 0.500000E-3 eV # [EXCPH] Damping of exc-ph self-energy
# These are the plot parameters, same as in other parts of yambo
% EnRngeXd
4.00000 | 5.00000 | eV # [Xd] Energy range
%
% DmRngeXd
0.00500000 | 0.00500000 | eV # [Xd] Damping range
%
ETStpsXd= 4000 # [Xd] Total Energy steps

Here <code>BoseTemp</code> and <code>EXCTemp</code> are the lattice and excitonic temperature, respectively.

Now we run the calculation with <code>yambo_ph</code>. Here, we read as <math>Q=0</math> excitons with <code>-J</code> the ones without the long-range Coulomb exchange:

yambo_ph -F excph.in -J excph,bse_Lbar -C excph

and we find our outputs in the <code>excph</code> directory.

NB: Step 6 could have been equivalently run in yambopy, limiting the use of the yambo code to just step 4. This latter option is more flexible, as it allows for a greater degree of control by the user. We are in the last stages of the development and it will be available soon.

=== Results ===

If we check the output directory from the step 6 calculation, we find the <code>o-excph.pl_bse_ph_ass</code> output files containing the luminescence spectra. We can plot them with gnuplot or any other tool:

gnuplot
> set xrange[4.2:5]
> p 'o-excph.pl_bse_ph_ass' u 1:2 w l lc rgb 'red' lw 3

[[File:Luminescence plot.png|500px|center]]

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

== References ==

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

Exciton-phonon coupling and luminescence

2025-10-06T12:01:28Z

Attacc:

[[File:Tdgw-phonon-usc-01-1024x829.jpg| 400px | right]]

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

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

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

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

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

== Requirements ==

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

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

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

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

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

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

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

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

== Step 1: scf calculation ==

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

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

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

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

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

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

== Step 2: nscf calculation for Yambo ==

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

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

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

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

Again, we run the calculation

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

== Step 3: dvscf phonon calculation ==

Now we run the phonon calculation.

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

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

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

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

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

And now we run as

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

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

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

This is just the standard Yambo initialization: run

p2y

and then

yambo

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

== Step 5: run a BSE calculation ==

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

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

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

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

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

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

We can now run the code:

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

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

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

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

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

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

Type:

yambopy l2y

to see the help for the calculation. For example, if we want to do a serial run of LetzElPhC for bands from <math>n_i</math> to <math>n_f</math>, we should type:

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

Here <math>n_i</math> and <math>n_f</math> are integers representing the initial and final band indices.

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

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

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

At the end, check the <code>SAVE</code>

ls SAVE/ndb.elph_gkkp*

to see that it has created the Yambo-compatible electron-phonon databases.

If you saved the <code>lelphc.in</code> input file, you can inspect it:

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

You can also run it as it is, but the code will generate the database <code>ndb.elph</code>. In order to convert it to the <code>ndb.elph_gkkp*</code> databases of Yambo, you still need a couple of lines of python using the Yambopy class <code>ConvertElectronPhononDB</code> in <code>yambopy/letzelph_interface/lelph2y.py</code>.

Notice the variable <code>convention=yambo</code>: what does it mean? At variance with QE and many other codes, Yambo uses the "backward" momentum transfer convention for electronic scatterings. That is, an electronic transition goes from band <math>n</math> and momentum <math>k-q</math> to band <math>m</math> and momentum <math>k</math>. In the "forward" momentum transfer convention (the more standard one), the transitions go from <math>nk</math> to <math>mk+q</math>. Therefore, this variable ensures that the electron-phonon coupling matrix elements are computed as <math>\langle mk|dV|nk-q\rangle</math>. This will have consequences also in the formulation of the ''exciton''-phonon coupling matrix element.

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

Now, we can finally access our basic building block for exciton-phonon physics. This could be done entirely in python (using '''Yambopy'''), or by running '''Yambo'''. In this version of the tutorial we present the latter case.

Our objective is obtaining the following quantity:

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

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

NB:

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

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

We have to write a new yambo input, that we can call <code>excph.in</code>, for this. You can copy (and adapt) the one below, or you can generate one by running from the command line:

yambo_ph -excph o

This generates an input to compute luminescence ("o" is for "optics"). The variables that we are interested in are:

excph # [R] Exction-phonon
ExcGkkp # [R][EXCPH] Exciton-Phonon Matrix Elelements
% ELPhExcStates
1 | 4 | # [EXCPH] Incoming (external) exciton states
%
% ELPhExcSum
1 | 12 | # [EXCPH] Outgoing (virtual) exciton states
%
LoutPath= "./bse_Lfull" # [EXCPH] Path of the outgoing L
% ElPhModes
1 | 9 | # [ELPH] Phonon modes included
%

In this input, we have to select the initial exciton states <math>\lambda</math> with <code>ELPhExcStates</code>, the final exciton states <math>\alpha</math> with <code>ELPhExcSum</code> and the phonon modes <math>\mu</math> with <code>ElPhModes</code>. Here we consider the first four states at <math>Q=0</math> (corresponding to just two excitons because they are both doubly degenerate -- do not break degeneracies when selecting states!) and the first twelve states at each finite-<math>q</math> point. We also include all the nine phonon modes of monolayer MoS2.

What about <code>LoutPath</code>? This variable controls the directory where the databases for the final-state excitons <math>\alpha</math> is located, which can be different from the directory with the initial-state excitons <math>\lambda</math> read as usual with the <code>-J</code> option when running the code. This makes it possible to compute the coupling between different exciton kinds. However, for our tutorial, we stick with the previously computed <code>Lfull</code> in both cases.

When we are satisfied with the input, we run the code using <code>yambo_ph</code>:

yambo_ph -F excph.in -J excph,bse_Lfull -C excph

If you check the output, you should find the <code>ndb.excph*</code> databases in the <code>excph</code> directory.

=== Analysis of the couplings ===

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

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

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

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

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

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

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

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

# Exciton in states
exc_in = [2,3] # A: 2,3 -- B: 6,7
exc_out = [0,1,2,3] # first 4 states (dispersion of triplet state and A)
ph_in = 'all'

# Paths of databases
ns_db1 =f'{path}/SAVE/ns.db1'
ndb_exc=f'{path}/excph'

...

Then, we load the data:

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

# Read exc-ph databases
X = YamboExcitonPhononDB(ylat,save_excph=ndb_exc)
print(X)

The quantity <math>F_A(q)</math> is defined inside the plotting function as

G_squared = excph.excph_sq
G2plt = np.zeros(len(G_squared))

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

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

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

And finally, we have to make a plotting function. For this tutorial we will use the default scatterplot provided by <code>YamboExcitonPhononDB</code>

excph.plot_excph(F_q,plt_cbar=plt_cbar,**kwargs)
...

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

In our case, the resulting plot is the following.

[[File:1L MoS2 ExcPh.png|500px|center]]

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

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

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

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

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

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

<math>I^{(1)}_{PL}(\omega;T) \propto \frac{1}{N_q}\sum_{ s \mu \beta q} \left|\sum_\lambda\frac{D_\lambda \mathcal{G}^{\mu q}_{\alpha q,\lambda}}{E_{\alpha q}-E_\lambda -s\Omega_{\mu q}} \right|^2 N_{\alpha q}(T_{exc}) F^s_{\mu q}(T)\delta(\omega - \left[E_{\alpha q}-s\Omega_{\mu q}\right])</math>

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

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

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

=== Running the jobs ===

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

5. Now we run <code>lelphc</code> with yambopy to get the el-ph matrix elements:

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

6. And finally we generate the exciton-phonon input <code>excph.in</code> using <code>yambo_ph -excph o</code>. Now, we take a look at all the additional variables that we didn't check before, specifying also the details for luminescence the spectrum calculation.

excph # [R] Exction-phonon
ExcGkkp # [R][EXCPH] Exciton-Phonon Matrix Elelements
ExcPhOptics # [R][EXCPH] Exciton-Phonon Optics
BoseTemp=10.000000 Kn # Bosonic Temperature
EXCTemp= 10.000000 Kn # [EXCPH] Excitonic Temperature (for luminescence spectra)
% ELPhExcStates
1 | 4 | # [EXCPH] Incoming (external) exciton states
%
% ELPhExcSum
1 | 12 | # [EXCPH] Outgoing (virtual) exciton states
%
% ElPhModes
1 | 12 | # [ELPH] Phonon modes included
%
LoutPath= "./bse-L_full" # [EXCPH] Path of the outgoing L
FANdEtresh= 0.100000E-5 eV # [ELPH] Energy treshold for Fan denominator
EXCPHdEtresh= 0.100000E-5 eV # [ELPH] Energy treshold for exc-ph denominator
LDamping= 0.500000E-3 eV # [EXCPH] Damping of exc-ph self-energy
# These are the plot parameters, same as in other parts of yambo
% EnRngeXd
4.00000 | 5.00000 | eV # [Xd] Energy range
%
% DmRngeXd
0.00500000 | 0.00500000 | eV # [Xd] Damping range
%
ETStpsXd= 4000 # [Xd] Total Energy steps

Here <code>BoseTemp</code> and <code>EXCTemp</code> are the lattice and excitonic temperature, respectively.

Now we run the calculation with <code>yambo_ph</code>. Here, we read as <math>Q=0</math> excitons with <code>-J</code> the ones without the long-range Coulomb exchange:

yambo_ph -F excph.in -J excph,bse_Lbar -C excph

and we find our outputs in the <code>excph</code> directory.

NB: Step 6 could have been equivalently run in yambopy, limiting the use of the yambo code to just step 4. This latter option is more flexible, as it allows for a greater degree of control by the user. We are in the last stages of the development and it will be available soon.

=== Results ===

If we check the output directory from the step 6 calculation, we find the <code>o-excph.pl_bse_ph_ass</code> output files containing the luminescence spectra. We can plot them with gnuplot or any other tool:

gnuplot
> set xrange[4.2:5]
> p 'o-excph.pl_bse_ph_ass' u 1:2 w l lc rgb 'red' lw 3

[[File:Luminescence plot.png|500px|center]]

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

== References ==

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

Exciton-phonon coupling and luminescence

2025-10-06T11:53:39Z

Attacc: /* Step 5: run a BSE calculation */

[[File:Tdgw-phonon-usc-01-1024x829.jpg| 400px | right]]

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

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

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

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

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

== Requirements ==

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

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

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

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

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

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

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

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

== Step 1: scf calculation ==

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

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

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

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

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

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

== Step 2: nscf calculation for Yambo ==

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

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

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

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

Again, we run the calculation

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

== Step 3: dvscf phonon calculation ==

Now we run the phonon calculation.

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

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

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

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

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

And now we run as

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

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

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

This is just the standard Yambo initialization: run

p2y

and then

yambo

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

== Step 5: run a BSE calculation ==

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

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

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

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

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

Second, we change the variable <code>Lkind</code> from <code>bar</code> to <code>full</code>. In Yambo, <code>Lkind="bar"</code>, which is the default for optical absorption, means that we are computing the excitonic response function without the long-range component of the exchange interaction. This cannot be used when computing the exciton momentum dependence, where the long-range exchange interaction can play a role, therefore we have to include it with <code>Lkind="full"</code>. This allows for the calculation of the excitonic longitudinal-transverse splitting (in 3D systems) as well.

We can now run the code:

nohup mpirun -np 8 yambo -F bse.in -J bse_Lfull -C bse_Lfull &

At the end of the calculation, we have obtained the <code>ndb.BS_diago_Q*</code> databases inside the directory <code>bse_Lfull</code>. They contain information on the exciton energies and wavefunctions at each momentum. Do not forget to check the report and logs of your calculation in the same directory to make sure that the code is doing what you want.

== Step 6: obtain the electron-phonon matrix elements ==

We have finished the heavy simulations. Now it's time for the postprocessing. The first order of business is the reconstruction of the electron-phonon coupling matrix elements from the dvscf results and the electronic wavefunctions.

In order to do this, we will run the <code>lelphc</code> executable of the '''LetzElPhC''' code. We will run via command line using yambopy, although it will be instructive to have look at the <code>lelphc</code> input files later.

We run in the same directory where the Yambo <code>SAVE</code> is (remember than you can also virtually move it with a symbolic link).

Type:

yambopy l2y

to see the help for the calculation. For example, if we want to do a serial run of LetzElPhC for bands from <math>n_i</math> to <math>n_f</math>, we should type:

yambopy l2y -ph path/of/ph_input.in -b n_i n_f

Here <math>n_i</math> and <math>n_f</math> are integers representing the initial and final band indices.

These should coincide with those used for the Bethe-Salpeter kernel, i.e. those specified in the <code>BSEBands</code> variable of the BSE input file (this is not strictly necessary, but certainly efficient since these calculations use a lot of disk space).

For our system, we want to do a parallel calculation with 4 qpools and 2 kpools. In addition, we want to explicitly specify the path of the <code>lelphc</code> executable and avoid automatically deleting the LetzElPhC data. So we type:

yambopy l2y -ph path/of/dvscf/mos2.dvscf -b 25 28 -par 4 2 -lelphc path/to/lelphc_exe --debug

At the end, check the <code>SAVE</code>

ls SAVE/ndb.elph_gkkp*

to see that it has created the Yambo-compatible electron-phonon databases.

If you saved the <code>lelphc.in</code> input file, you can inspect it:

# LetzElPhC input for yambo generated by yambopy
nqpool = 2
nkpool = 4
start_bnd = 25
end_bnd = 28
save_dir = ./SAVE
kernel = dfpt
ph_save_dir = dvscf/ph_save
convention = yambo

You can also run it as it is, but the code will generate the database <code>ndb.elph</code>. In order to convert it to the <code>ndb.elph_gkkp*</code> databases of Yambo, you still need a couple of lines of python using the Yambopy class <code>ConvertElectronPhononDB</code> in <code>yambopy/letzelph_interface/lelph2y.py</code>.

Notice the variable <code>convention=yambo</code>: what does it mean? At variance with QE and many other codes, Yambo uses the "backward" momentum transfer convention for electronic scatterings. That is, an electronic transition goes from band <math>n</math> and momentum <math>k-q</math> to band <math>m</math> and momentum <math>k</math>. In the "forward" momentum transfer convention (the more standard one), the transitions go from <math>nk</math> to <math>mk+q</math>. Therefore, this variable ensures that the electron-phonon coupling matrix elements are computed as <math>\langle mk|dV|nk-q\rangle</math>. This will have consequences also in the formulation of the ''exciton''-phonon coupling matrix element.

== Step 7: Obtain the exciton-phonon coupling ==

Now, we can finally access our basic building block for exciton-phonon physics. This could be done entirely in python (using '''Yambopy'''), or by running '''Yambo'''. In this version of the tutorial we present the latter case.

Our objective is obtaining the following quantity:

<math>\mathcal{G}^\mu_{\alpha\lambda}(0,q)=\sum_{vv^\prime c k} A^{\alpha, *}_{cv^\prime} (k, q) g_{vv^\prime}^\mu (k,q) A^{\lambda}_{cv}(k,q) - \sum_{cc^\prime vk} A^{\alpha, *}_{c^\prime v} (k+q, q) g_{c^\prime c}^\mu (k+q,q) A^{\lambda}_{cv}(k,q)</math>

Here, <math>A^{\lambda}_{cv}(k,q)</math> are the exciton coefficients extracted from the eigenvector of the two-particles Hamiltonian during the BSE calculation in step 5, while <math>g_{nm}^\mu (k,q)</math> are the electron-phonon coupling matrix elements obtained in step 6. As you can see, the exciton <math>\lambda</math> undergoes phonon-mediated scattering to state <math>\alpha</math> via phonon mode <math>\mu</math>. The scattering can happen for the hole (valence, <math>v</math>) or for the electron (conduction, <math>c</math>).

NB:

(1) This is written in the "backward" momentum transfer convention used by Yambo. The momentum dependence is different in the "forward" transfer convention.

(2) For simplicity, this is written for zero initial exciton momentum. This means that one of the two states involved in the phonon-mediated scattering process will be in the optical limit (and possibly an optically generated exciton), while the other state can have any momentum: this momentum will be the same as the phonon one. This matrix element can be used to describe phonon-assisted absorption and emission spectra.

We have to write a new yambo input, that we can call <code>excph.in</code>, for this. You can copy (and adapt) the one below, or you can generate one by running from the command line:

yambo_ph -excph o

This generates an input to compute luminescence ("o" is for "optics"). The variables that we are interested in are:

excph # [R] Exction-phonon
ExcGkkp # [R][EXCPH] Exciton-Phonon Matrix Elelements
% ELPhExcStates
1 | 4 | # [EXCPH] Incoming (external) exciton states
%
% ELPhExcSum
1 | 12 | # [EXCPH] Outgoing (virtual) exciton states
%
LoutPath= "./bse_Lfull" # [EXCPH] Path of the outgoing L
% ElPhModes
1 | 9 | # [ELPH] Phonon modes included
%

In this input, we have to select the initial exciton states <math>\lambda</math> with <code>ELPhExcStates</code>, the final exciton states <math>\alpha</math> with <code>ELPhExcSum</code> and the phonon modes <math>\mu</math> with <code>ElPhModes</code>. Here we consider the first four states at <math>Q=0</math> (corresponding to just two excitons because they are both doubly degenerate -- do not break degeneracies when selecting states!) and the first twelve states at each finite-<math>q</math> point. We also include all the nine phonon modes of monolayer MoS2.

What about <code>LoutPath</code>? This variable controls the directory where the databases for the final-state excitons <math>\alpha</math> is located, which can be different from the directory with the initial-state excitons <math>\lambda</math> read as usual with the <code>-J</code> option when running the code. This makes it possible to compute the coupling between different exciton kinds. However, for our tutorial, we stick with the previously computed <code>Lfull</code> in both cases.

When we are satisfied with the input, we run the code using <code>yambo_ph</code>:

yambo_ph -F excph.in -J excph,bse_Lfull -C excph

If you check the output, you should find the <code>ndb.excph*</code> databases in the <code>excph</code> directory.

=== Analysis of the couplings ===

It is a good idea to have a look at what we computed up to now in order to make sure nothing has gone wrong.

It is not easy to know what to expect (apart from symmetry and gauge compliance of the matrix elements), but one can work out the exciton-phonon selection rules in advance, check that the magnitude is reasonable, etc.

It is also not easy to meaningfully plot this quantity. We have to make sure that we are not breaking degenerate states, otherwise the plots will not be invariant.

First of all, we have to know our system: in monolayer MoS2, the first four excitons are all doubly degenerate. The first exciton responsible for a bright peak in the absorption spectrum (the '''A''' peak), is the second state, corresponding to state indices <code>(3,4)</code> in fortran indexing or <code>(2,3)</code> in python indexing.

All these information can be obtained by analyzing the BSE results (this stuff is explained in the BSE tutorials) and by knowledge of the system or class of systems from the literature.

Thus, a good quantity to plot may be the norm of the matrix elements, summed over the degenerate subspace of exciton A, for a certain number of scattered final states mediated by certain phonon modes:

<math>F_A(q)= \sqrt{ \sum_{\alpha \in A,\lambda,\mu} |\mathcal{G}_{\alpha\lambda}^\mu (0,q)|^2 }</math>

In order to do this, we create a python script <code>analyse_excph.py</code> in which we first load the excph dabatases using the <code>YamboExcitonPhononDB</code> from yambopy.
You can find this script in the yambopy directory, in <code>tutorials/exciton-phonon</code>.
First, we select the exciton and phonon states to be included in <code>F_A</code>, together with the path of databases and plot details:

# Exciton in states
exc_in = [2,3] # A: 2,3 -- B: 6,7
exc_out = [0,1,2,3] # first 4 states (dispersion of triplet state and A)
ph_in = 'all'

# Paths of databases
ns_db1 =f'{path}/SAVE/ns.db1'
ndb_exc=f'{path}/excph'

...

Then, we load the data:

# Read lattice and k-space info
ylat = YamboLatticeDB.from_db_file(filename=ns_db1),Expand=True)
print(ylat)

# Read exc-ph databases
X = YamboExcitonPhononDB(ylat,save_excph=ndb_exc)
print(X)

The quantity <math>F_A(q)</math> is defined inside the plotting function as

G_squared = excph.excph_sq
G2plt = np.zeros(len(G_squared))

if exc_in == 'all': exc_in = range(G_squared.shape[2])
if exc_out == 'all': exc_out = range(G_squared.shape[3])
if ph_in == 'all': ph_in = range(G_squared.shape[1])

G_squared = G_squared[:, ph_in, :, :].sum(axis=(1))
G_squared = G_squared[:, exc_in, :].sum(axis=(1))
G_squared = G_squared[:, exc_out].sum(axis=(1))

F_q = np.sqrt( G_squared )*ha2ev # Switch from Ha to eV

And finally, we have to make a plotting function. For this tutorial we will use the default scatterplot provided by <code>YamboExcitonPhononDB</code>

excph.plot_excph(F_q,plt_cbar=plt_cbar,**kwargs)
...

You can get more experience on using Yambopy for these kinds of visualization by following the [https://wiki.yambo-code.eu/wiki/index.php?title=First_steps_in_Yambopy Yambopy tutorials]. In fact, remember that this scripts and all the other yambopy tutorial scripts are just suggestions, not source code written in stone: if you know <code>numpy</code> and <code>matplotlib</code> you can do your own analysis and your own plots, you just need to import the required Yambopy modules to load the data.

In our case, the resulting plot is the following.

[[File:1L MoS2 ExcPh.png|500px|center]]

This can be checked against Fig. 2(d) of reference <ref name="chan2023" />, although you have to keep in mind that our results are badly undersampled in terms of the reciprocal-space grid, as can be easily seen, and the quantity plotted is not exactly the same. However, the main features are already there since they are dictated mostly by crystal symmetries.

Now that we have the exciton-phonon matrix elements, we can use them to build several kinds of observables. Below, we give an example related to phonon-assisted luminescence, but we may update this tutorial in the future to include more cases.

== Step 8: Compute phonon-assisted luminescence ==

[[File:Luminescence scheme.png|250px|right]]

We want to compute the experimental optical signature due to the phonon-assisted recombination of an exciton (as sketched in the figure).

The signal from the phonon replicas can be modeled as a second-order scattering process involving one phonon and one photon:

<math>I^{(1)}_{PL}(\omega;T) \propto \frac{1}{N_q}\sum_{ s \mu \beta q} \left|\sum_\lambda\frac{D_\lambda \mathcal{G}^{\mu q}_{\alpha q,\lambda}}{E_{\alpha q}-E_\lambda -s\Omega_{\mu q}} \right|^2 N_{\alpha q}(T_{exc}) F^s_{\mu q}(T)\delta(\omega - \left[E_{\alpha q}-s\Omega_{\mu q}\right])</math>

In this equation, the oscillator strength of the peak is given by the exciton-phonon coupling matrix elements <math>\mathcal{G}</math> multiplied by the exciton dipoles <math>D</math> (they are called "residuals" in Yambo). Here <math>E_\lambda</math> and <math>E_{\alpha q}</math> are the energies of the optical and finite-momentum excitons, respectively, while <math>\Omega_{\mu q}</math> are the phonon energies.

The occupation function <math>F</math> is <math>F^s_{\mu q}(T)=n_{\mu q}(T)+\frac{1+s}{2}</math>. Here, <math>n(T)</math> is the temperature-dependent phonon Bose-Einstein occupation function. As it can be seen, <math>s=1</math> corresponds to processes of phonon ''emission'' (<math>\propto n(T)+1</math>), while <math>s=-1</math> corresponds to processes of phonon ''absorption'' (<math>\propto n(T)</math>). Therefore, <math>I^{(1)}_{PL}(\omega;T)</math> describes ''light'' emission by recombining excitons mediated by either ''phonon'' absorption or emission.

The quantity <math> N_{\alpha q}(T_{exc})</math> is the exciton occupation function. Luminescence is technically an out-of-equilibrium process, but we can assume that for very low density of excitations and in steady-state conditions, the exciton population can be approximately described by an equilibrium distribution evaluated at an effective temperature. Here, we use the Boltzmann distribution. Experimentally, <math>T_{exc}</math> tends to coincide with the lattice temperature <math>T</math> more or less above 100 K, while at very low temperature (< 10 K), <math>T_{exc}</math> may vary between 10-50 K. It goes without saying that this needs to carefully be checked in your realistic calculations.

=== Running the jobs ===

In order to study luminescence in a paradigmatic system, we switch to bulk hexagonal boron nitride and we repeat the workflow. As you can easily see, one can think about automatizing the execution of all these calculations via scripting or more advanced tools. However, in the case of very large simulations (memory-limited or disk-space limited) or for systems whose electronic and lattice properties are fragile with respect to tiny calculation details, one must be very careful and run many basic tests.

Fortunately, we are running a fast underconverged example. We use LDA pseudopotentials from the pseudo-dojo library and the following are the calculations steps.

1. Input <code>hbn.scf</code>:

&control
calculation='scf',
prefix='hBN',
restart_mode='from_scratch'
pseudo_dir = '$PSEUDO_DIR',
outdir = './tmp'
verbosity = 'high'
wf_collect=.true.
/
&system
ibrav = 4,
celldm(1) = 4.703675849
celldm(3) = 2.603711434
nat= 4,
ntyp= 2,
force_symmorphic=.true.
ecutwfc = 100,
/
&electrons
diago_david_ndim = 2
diago_full_acc=.true.
diago_thr_init=5.0e-6
mixing_mode = 'plain'
mixing_beta = 0.7
conv_thr = 1.0d-16
/
ATOMIC_SPECIES
B 10.81100 B_LDA_dojo.UPF
N 14.00674 N_LDA_dojo.UPF
ATOMIC_POSITIONS {crystal}
N 0.6666666670 0.3333333330 -0.250000000000
B 0.3333333330 0.6666666670 -0.250000000000
B 0.6666666670 0.3333333330 0.25000000000
N 0.3333333330 0.6666666670 0.25000000000
K_POINTS {automatic}
6 6 2 0 0 0

mpirun -np 4 pw.x -inp hbn.scf > scf.out

2. Input <code>hbn.nscf</code>:

&control
calculation='nscf',
prefix='hBN',
restart_mode='from_scratch'
pseudo_dir = '$PSEUDO_DIR'
outdir = './'
verbosity = 'high'
wf_collect=.true.
/
&system
ibrav = 4,
celldm(1) = 4.703675849
celldm(3) = 2.603711434
nat= 4,
ntyp= 2,
force_symmorphic=.true.
ecutwfc = 100,
nbnd = 120
/
&electrons
diago_david_ndim = 2
diago_full_acc=.true.
diago_thr_init=5.0e-6
mixing_mode = 'plain'
mixing_beta = 0.7
conv_thr = 1.0d-16
/
ATOMIC_SPECIES
B 10.81100 B_LDA_dojo.UPF
N 14.00674 N_LDA_dojo.UPF
ATOMIC_POSITIONS {crystal}
N 0.6666666670 0.3333333330 -0.250000000000
B 0.3333333330 0.6666666670 -0.250000000000
B 0.6666666670 0.3333333330 0.25000000000
N 0.3333333330 0.6666666670 0.25000000000
K_POINTS {automatic}
6 6 2 0 0 0

mpirun -np 4 pw.x -inp hbn.nscf > nscf.out

3. Input <code>hbn.dvscf</code>:

hbn_dvscf
&inputph
tr2_ph=1.0d-12,
verbosity='high'
prefix='hBN',
fildvscf = 'hBN-dvscf',
electron_phonon = 'dvscf',
fildyn='hBN.dyn',
epsil=.false.,
ldisp=.true.,
recover=.true.,
nq1=6,
nq2=6,
nq3=2
/

nohup mpirun -np 8 pw.x -inp hbn.dvscf > dvscf.out &

4. Input <code>bse.in</code> (we include 2 valence and 2 conduction bands):

optics # [R] Linear Response optical properties
bss # [R] BSE solver
bse # [R][BSE] Bethe Salpeter Equation.
dipoles # [R] Oscillator strenghts (or dipoles)
em1s
DIP_CPU= "1 8 1" # [PARALLEL] CPUs for each role
DIP_ROLEs= "k c v" # [PARALLEL] CPUs roles (k,c,v)
DIP_Threads=0 # [OPENMP/X] Number of threads for dipoles
X_and_IO_CPU= "1 1 1 8 1" # [PARALLEL] CPUs for each role
X_and_IO_ROLEs= "q g k c v" # [PARALLEL] CPUs roles (q,g,k,c,v)
X_and_IO_nCPU_LinAlg_INV=-1 # [PARALLEL] CPUs for Linear Algebra (if -1 it is automatically set)
X_Threads=0 # [OPENMP/X] Number of threads for response functions
BS_CPU= "8 1 1" # [PARALLEL] CPUs for each role
BS_ROLEs= "k eh t" # [PARALLEL] CPUs roles (k,eh,t)
BS_nCPU_LinAlg_INV=-1 # [PARALLEL] CPUs for Linear Algebra (if -1 it is automatically set)
BS_nCPU_LinAlg_DIAGO=-1 # [PARALLEL] CPUs for Linear Algebra (if -1 it is automatically set)
X_Threads=0 # [OPENMP/X] Number of threads for response functions
K_Threads=0 # [OPENMP/BSK] Number of threads for response functions
% QpntsRXs
1 | 14 | # [Xs] Transferred momenta
%
% BndsRnXs
1 | 120 | # [Xs] Polarization function bands
%
NGsBlkXs= 10 Ry # [Xs] Response block size
% LongDrXs
1.000000 | 1.000000 | 1.000000 | # [Xs] [cc] Electric Field
%
BSEmod= "resonant" # [BSE] resonant/retarded/coupling
BSKmod= "SEX" # [BSE] IP/Hartree/HF/ALDA/SEX/BSfxc
Lkind= "Lfull" # [BSE] Lbar (default) / full
BSSmod= "d" # [BSS] (h)aydock/(d)iagonalization/(s)lepc/(i)nversion/(t)ddft`
% DipBands
1 | 120 | # [DIP] Bands range for dipoles
%
DipApproach= "G-space v" # [DIP] [G-space v/R-space x/Covariant/Shifted grids]
DipComputed= "R V P" # [DIP] [default R P V; extra P2 Spin Orb]
BSENGexx= 30000 Ry # [BSK] Exchange components
#ALLGexx # [BSS] Force the use use all RL vectors for the exchange part
BSENGBlk= 9000 Ry # [BSK] Screened interaction block size [if -1 uses all the G-vectors of W(q,G,Gp)]
% KfnQP_E
1.25997 | 1.08816 | 1.12683 | # [EXTQP BSK BSS] E parameters (c/v) eV|adim|adim
%
% BSEQptR
 1 | 14 | # [BSK] Transferred momenta range
%
% BSEBands
 7 | 10 | # [BSK] Bands range
%
% BEnRange
0.50000 | 8.00000 | eV # [BSS] Energy range
%
% BDmRange
0.050000 | 0.050000 | eV # [BSS] Damping range
%
BEnSteps= 1000 # [BSS] Energy steps
% BLongDir
1.000000 | 1.000000 | 0.000000 | # [BSS] [cc] Electric Field
%
WRbsWF # [BSS] Write to disk excitonic the WFs

nohup mpirun -np 8 yambo -F bse.in -J bse_Lfull -C bse_Lfull &

Importantly, since we want to describe the phonon-assisted recombination process of an *optical* exciton (i.e., emitting a transverse photon), this time we also run an additional calculation at `Q=0` omitting the nonanalytic long-range Coulomb exchange. Make a second input <code>bse_Lbar.in</code> with the following changes:

Lkind= "Lbar" # [BSE] Lbar (default) / full
% BSEQptR
 1 | 1 | # [BSK] Transferred momenta range
%

4b. So now we make a second BSE run in a different directory specified by <code>-J</code>. Here, we also pass to yambo the directory of the previous run as it includes the important screening databases <code>ndb.em1s*</code> that we do not want to recompute from scratch.

mpirun -np 8 yambo -F bse_Lbar.in -J bse_Lbar,bse_Lfull -C bse_Lbar

5. Now we run <code>lelphc</code> with yambopy to get the el-ph matrix elements:

yambopy l2y -ph path/of/dvscf/hbn.dvscf -b 7 10 -par 4 2

6. And finally we generate the exciton-phonon input <code>excph.in</code> using <code>yambo_ph -excph o</code>. Now, we take a look at all the additional variables that we didn't check before, specifying also the details for luminescence the spectrum calculation.

excph # [R] Exction-phonon
ExcGkkp # [R][EXCPH] Exciton-Phonon Matrix Elelements
ExcPhOptics # [R][EXCPH] Exciton-Phonon Optics
BoseTemp=10.000000 Kn # Bosonic Temperature
EXCTemp= 10.000000 Kn # [EXCPH] Excitonic Temperature (for luminescence spectra)
% ELPhExcStates
1 | 4 | # [EXCPH] Incoming (external) exciton states
%
% ELPhExcSum
1 | 12 | # [EXCPH] Outgoing (virtual) exciton states
%
% ElPhModes
1 | 12 | # [ELPH] Phonon modes included
%
LoutPath= "./bse-L_full" # [EXCPH] Path of the outgoing L
FANdEtresh= 0.100000E-5 eV # [ELPH] Energy treshold for Fan denominator
EXCPHdEtresh= 0.100000E-5 eV # [ELPH] Energy treshold for exc-ph denominator
LDamping= 0.500000E-3 eV # [EXCPH] Damping of exc-ph self-energy
# These are the plot parameters, same as in other parts of yambo
% EnRngeXd
4.00000 | 5.00000 | eV # [Xd] Energy range
%
% DmRngeXd
0.00500000 | 0.00500000 | eV # [Xd] Damping range
%
ETStpsXd= 4000 # [Xd] Total Energy steps

Here <code>BoseTemp</code> and <code>EXCTemp</code> are the lattice and excitonic temperature, respectively.

Now we run the calculation with <code>yambo_ph</code>. Here, we read as <math>Q=0</math> excitons with <code>-J</code> the ones without the long-range Coulomb exchange:

yambo_ph -F excph.in -J excph,bse_Lbar -C excph

and we find our outputs in the <code>excph</code> directory.

NB: Step 6 could have been equivalently run in yambopy, limiting the use of the yambo code to just step 4. This latter option is more flexible, as it allows for a greater degree of control by the user. We are in the last stages of the development and it will be available soon.

=== Results ===

If we check the output directory from the step 6 calculation, we find the <code>o-excph.pl_bse_ph_ass</code> output files containing the luminescence spectra. We can plot them with gnuplot or any other tool:

gnuplot
> set xrange[4.2:5]
> p 'o-excph.pl_bse_ph_ass' u 1:2 w l lc rgb 'red' lw 3

[[File:Luminescence plot.png|500px|center]]

Here, the signal corresponds to a finite-momentum exciton that recombines with the help of several different phonon modes, both optical and acoustic. Each phonon mode whose coupling with the exciton is allowed can generate a peak, and the energy shifts of these peaks with respect to the initial exciton energy correspond to the phonon energies. This result is underconverged, but the main features are all there. In the plot, we show a more converged example using a 12x12x4 grid (all the other parameters being equal). These plots can be compared with Fig. 4(a) of reference <ref name="zanfrognini2023" />.

== References ==

<references>
<ref name="toyozawa2003" >[https://m.booksee.org/book/1121964?force_lang=en Optical processes in solids], Toyozawa, Yutaka, and Chris Oxlade. Cambridge University Press, (2003). </ref>
<ref name='lechifflart2023'>P. Lechifflart, F. Paleari, D. Sangalli, C. Attaccalite, ''First-principles study of luminescence in hexagonal boron nitride single layer: Exciton-phonon coupling and the role of substrate'',
[https://doi.org/10.1103/PhysRevMaterials.7.024006 Phys. Rev. M, '''7''' (2), 024006 (2023)]; [https://arxiv.org/abs/2212.10407 arXiv2212.1047]</ref>
<ref name='cannuccia2019'>E. Cannuccia, B. Monserrat and C. Attaccalite, ''Theory of phonon-assisted luminescence in solids: Application to hexagonal boron nitride'', [https://doi.org/10.1103/PhysRevB.99.081109 Phys. Rev. B '''99''', 081109(R) (2019)]; [https://arxiv.org/abs/1807.11797 arXiv1807.11797]</ref>
<ref name='paleari2019'>F. Paleari et al., ''Exciton-Phonon Coupling in the Ultraviolet Absorption and Emission Spectra of Bulk Hexagonal Boron Nitride'', [https://doi.org/10.1103/PhysRevLett.122.187401 Phys. Rev. Lett. '''122''', 187401 (2019)]; [https://arxiv.org/abs/1810.08976 arXiv1810.089776] </ref>
<ref name='chen2020'>''Exciton-Phonon Interaction and Relaxation Times from First Principles'',
Hsiao-Yi Chen, Davide Sangalli, and Marco Bernardi, [https://doi.org/10.1103/PhysRevLett.125.107401 Phys. Rev. Lett. '''125''', 107401 (2020)]; [https://arxiv.org/abs/2002.08913 arXiv 2002.08913 (2020)]</ref>
<ref name="lechifflart2023_PhD">[https://www.yambo-code.eu/wiki/images/5/54/These_final.pdf Exciton-phonon coupling and phonon-assisted luminescence in hexagonal Boron Nitride nanostructures], PhD Thesis, Pierre Lechifflart (2023)</ref>
<ref name='paleari2019_PhD'>F. Paleari, ''First-principles approaches to the description of indirect absorption and luminescence spectroscopy: exciton-phonon coupling in hexagonal boron nitride'', [https://wwwen.uni.lu/research/fstm/dphyms/people/fulvio_paleari PhD thesis, University of Luxembourg (2019)]</ref>
<ref name='zanfrognini2023'>[https://arxiv.org/abs/2305.17554 Distinguishing different stackings in layered materials via luminescence spectroscopy], M. Zanfrognini et al. Phys. Rev. Lett. '''131''', 206902 (2023) </ref>
<ref name='marini2024'>G. Marini, M. Calandra, P. Cudazzo, ''Optical absorption and photoluminescence of single layer boron nitride from a first principles cumulant approach'', [https://doi.org/10.1021/acs.nanolett.4c00669 Nano Lett., '''24''', 20, 6017 (2024)]; [https://arxiv.org/abs/2402.03826 arXiv 2402.03826 (2024)]</ref>
<ref name='antonius2017'>G. Antonius, S. G. Louie, ''Theory of exciton-phonon coupling'', [https://doi.org/10.1103/PhysRevB.105.085111 Phys. Rev. B, '''105''', 085111 (2022)]; [https://arxiv.org/abs/1705.04245 arXiv1705.04245 (2017)]</ref>
<ref name='paleari2022'>[https://arxiv.org/abs/2205.02783 Exciton-phonon interaction calls for a revision of the “exciton” concept], F. Paleari, A. Marini, Phys. Rev. B, '''106''', 125403 (2022)</ref>
<ref name='cudazzo2020'> P. Cudazzo, ''First-principles description of the exciton-phonon interaction: A cumulant approach'', [https://doi.org/10.1103/PhysRevB.102.045136 Phys. Rev. B, '''102''', 045136 (2020)]; [https://orbilu.uni.lu/bitstream/10993/44769/1/main.pdf Open access pdf from Luxembourg University]</ref>
<ref name='chan2023'>Y-h Chan, J. B. Haber, M. H. Naik, J. B. Neaton, D. Y. Qiu, F. H. da Jornada, S. G. Louie, ''Exciton Lifetime and Optical Line Width Profile via Exciton–Phonon Interactions: Theory and First-Principles Calculations for Monolayer MoS2'', [https://doi.org/10.1021/acs.nanolett.3c00732 Nano Lett., '''23''', 9 (2023)]; [https://arxiv.org/abs/2212.08451 arXiv 2212.08451 (2023)]</ref>
<ref name='murali2025'>M. Nalabothula, S. Reichardt, L. Wirtz, ''Origin of Interlayer Exciton–Phonon Coupling in 2D Heterostructures'', [https://doi.org/10.1021/acs.nanolett.5c00355 Nano Lett., '''25''', 15 (2025)], [https://arxiv.org/abs/2407.16111 arXiv 2407.16111 (2025)]</ref>
</references>

Exciton-phonon coupling and luminescence

2025-10-06T11:52:51Z

Attacc: /* Step 5: run a BSE calculation */

[[File:Tdgw-phonon-usc-01-1024x829.jpg| 400px | right]]

In this advanced tutorial, we will calculate exciton-phonon interactions from first principles by interfacing DFPT (for phonon calculations) and BSE (for exciton calculations).

The DFTP calculations are run with Quantum ESPRESSO, while the many-body GW-BSE calculations are run with Yambo. Finally, the exciton-phonon interaction will be obtained by combining and postprocessing the databases computed in the two previous runs. The great advantage of this workflow is that the calculations can be run in the irreducible Brillouin zones both for the electronic momenta (<math>k</math>) and the transfer momenta (<math>Q</math>, <math>q</math>) of excitons and phonons, thus speeding up considerably the jobs while reducing the IO and memory load.

We will first compute the exciton-phonon coupling matrix elements: these are the building blocks needed to construct experimental observables such as phonon-assisted optical spectra (such as luminescence), Raman spectra and exciton lifetimes. We will do this in the case of monolayer MoS2, a 2D system with large spin-orbit interaction.

As an example of application, we will consider the case of phonon-assisted luminescence. We will do this in the case of bulk hBN, a layered indirect insulator with strong electron-phonon coupling.

'''Note:''' this tutorial will be updated when new exc-ph tools become available in Yambopy (including full-python postprocessing, Raman spectra, interpolated lifetimes, etc).

== Requirements ==

This is an advanced topic: we assume that you already know something about the theory<ref name="toyozawa2003" /><ref name="antonius2017" /><ref name="cudazzo2020" /><ref name="paleari2019_PhD" /><ref name="paleari2022" /><ref name="lechifflart2023_PhD" /> and applications<ref name="paleari2019" /><ref name="cannuccia2019" /><ref name="chen2020" /><ref name="zanfrognini2023" /><ref name="lechifflart2023" /><ref name="chan2023" /><ref name="marini2024" /><ref name="murali2025" /> of exciton-phonon physics.

Also, we assume that you already know how to run both a basic '''Yambo''' GW-BSE calculation and a DFPT phonon calculation with '''Quantum ESPRESSO'''.

Besides the QE executables <code>pw.x</code> and <code>ph.x</code>, we also use the yambo phonon-specific executable <code>yambo_ph</code> and the python utility '''Yambopy'''. The auxiliary code '''LetzElPhC''' (executable <code>lelphc</code>) will be used to obtain the electron-phonon matrix elements by reading the same electronic wavefunctions used by Yambo (and stored in the <code>SAVE</code> directory), while also making full use of crystal symmetries. [https://gitlab.com/lumen-code/LetzElPhC LetzElPhC] will be run by Yambopy, but it must nonetheless be installed. Finally, the exciton-phonon properties can be computed either using <code>yambo_ph</code> or using Yambopy itself.

[[File:Workflow scheme.png|800px|center]]

== Step 0: Pseudopotentials, equilibrium structure and convergence ==

In a real calculation, it is important to ensure that both the pseudopotential and the lattice parameters that we are using are compatible and perform well for the electronic excited states and for the lattice vibrations simultaneously. Furthermore, you have to make sure that the wave function cutoff <code>ecutwfc</code> is converged with respect to the DFPT step and not just to the DFT one. This is in addition to the other customary convergence tests for DFT, DFPT, GW and BSE calculations.

This is often the most time-demanding step when starting on a new system.

For the sake of this tutorial, we assume that we have already done all these tests and we are starting the final workflow to get the exciton-phonon properties.

== Step 1: scf calculation ==

First of all, we run a standard scf calculation with <code>pw.x</code> for Yambo. We stick with non-symmorphic symmetries. At the end, we will have the QE <code>save</code> directory.

This is the input <code>mos2.scf</code>:

&control
wf_collect = .true.,
calculation = "scf",
verbosity = 'high',
pseudo_dir = '$PSEUDO_DIR',
prefix = "mos2",
outdir = '.',
/&end
&system
ecutwfc = 100.0,
occupations = 'fixed',
ibrav = 4,
celldm(1) = 5.9000811881,
celldm(3) = 6.7795677253,
nat = 3,
ntyp = 2,
lspinorb = .true.
noncolin = .true.
assume_isolated = '2D'
force_symmorphic = .true.
/&end
&electrons
electron_maxstep = 200,
mixing_beta = 0.7,
conv_thr = 1.d-08,
/&end
ATOMIC_SPECIES
Mo 95.940 Mo_ONCV_PBE_FR-1.0.upf
S 32.065 S_ONCV_PBE_FR-1.1.upf
ATOMIC_POSITIONS { crystal }
Mo 0.333333333 0.666666667 0.000000000
S 0.666666667 0.333333333 0.073413577
S 0.666666667 0.333333333 -0.073413577
K_POINTS { automatic }
6 6 1 0 0 0

Here we are using full relativistic pseudopotentials from the SG-15 database.

We can run it on our machine (for example using 4 MPI tasks) as:

mpirun -np 4 pw.x -inp mos2.scf > scf.out

== Step 2: nscf calculation for Yambo ==

Copy the QE <code>save</code> directory from the scf calculation and run the nscf calculation for any number of empty states, with the correct <code>k</code>-grid we want to use in Yambo. Here we are using a badly underconverged grid of 6x6x1.

This reciprocal-space grid will also match the momentum transfer <code>q</code> grid on which excitons and phonons will be defined!

The electronic wavefunctions computed at this step and stored in the new nscf <code>save</code> directory will be used both by Yambo and by the electron-phonon code: this is important because using different sets of wavefunctions would lead to a phase mismatch issue in the exciton-phonon matrix elements.

The nscf input <code>mos2.nscf</code> is
&control
wf_collect = .true.,
calculation = "nscf",
verbosity = 'high',
pseudo_dir = '$PSEUDO_DIR',
prefix = "mos2",
outdir = '.',
/&end
&system
ecutwfc = 100.0,
occupations = 'fixed',
ibrav = 4,
celldm(1) = 5.9000811881,
celldm(3) = 6.7795677253,
nat = 3,
ntyp = 2,
lspinorb = .true.
noncolin = .true.
nbnd = 250
assume_isolated = '2D'
force_symmorphic = .true.
/&end
&electrons
electron_maxstep = 200,
mixing_beta = 0.7,
conv_thr = 1.d-08,
/&end
ATOMIC_SPECIES
Mo 95.940 Mo_ONCV_PBE_FR-1.0.upf
S 32.065 S_ONCV_PBE_FR-1.1.upf
ATOMIC_POSITIONS { crystal }
Mo 0.333333333 0.666666667 0.000000000
S 0.666666667 0.333333333 0.073413577
S 0.666666667 0.333333333 -0.073413577
K_POINTS { automatic }
6 6 1 0 0 0

Again, we run the calculation

mpirun -np 4 pw.x -inp mos2.nscf > nscf.out

== Step 3: dvscf phonon calculation ==

Now we run the phonon calculation.

Copy the <code>save</code> directory from the '''scf''' calculation and run <code>ph.x</code> for a dvscf calculation with a standard <code>q</code>-grid matching the <code>k</code>-grid we wanna use in Yambo.

At the end, we will have the <code>_ph0</code> directory containing the variation of the self-consistent potential, <math>\Delta V_{SCF}(q)</math>, and the <code>*.dyn</code> files with the phonon energies and eigenvectors.

NB: one could further refine the phonon energies by enforcing the acoustic sum rule, including non-analytic long-range contributions, interpolating to finer grids... all of this can be done within Quantum ESPRESSO and will not be covered in this version of the tutorial.

The input is <code>mos2.dvscf</code>:

mos2_dvscf
&inputph
tr2_ph=1.0d-12,
verbosity='high'
prefix='mos2',
fildvscf = 'mos2-dvscf',
electron_phonon = 'dvscf',
fildyn='mos2.dyn',
epsil=.false.,
ldisp=.true.,
recover=.true.,
nq1=6,
nq2=6,
nq3=1
/

And now we run as

nohup mpirun -np 8 ph.x -inp mos2.dvscf > dvscf.out &

This time we use nohup and more processes because this calculation may take some time. It is a good idea to set <code>recover=.true.</code> as in a real calculation you will easily breach walltime, and in this way you can safely restart.

== Step 4: create Yambo <code>SAVE</code> directory ==

This is just the standard Yambo initialization: run

p2y

and then

yambo

in the '''nscf''' <code>save</code> folder and then move the newly generated <code>SAVE</code> directory to a convenient place.

== Step 5: run a BSE calculation ==

Now we switch from QE to Yambo. Here, we forgo the GW step for simplicity (we can use a scissor operator to open the band gap).

This calculation has a couple of differences with respect to a standard BSE calculation for optical absorption. We can look at the input file <code>bse.in</code>:

# Runlevels
optics # [R OPT] Optics
rim_cut # [R RIM CUT] Coulomb potential
bss # [R BSS] Bethe Salpeter Equation solver
em1s # [R Xs] Static Inverse Dielectric Matrix
bse # [R BSE] Bethe Salpeter Equation.
bsk # [R BSK] Bethe Salpeter Equation kernel
# RIM and cutoff settings
RandQpts=1000000 # [RIM] Number of random q-points in the BZ
RandGvec= 100 RL # [RIM] Coulomb interaction RS components
CUTGeo= "slab z" # [CUT] Coulomb Cutoff geometry: box/cylinder/sphere X/Y/Z/XY..
# Static screening
X_and_IO_CPU= "1 1 4 2 1" # [PARALLEL] CPUs for each role
X_and_IO_ROLEs= "q g k c v" # [PARALLEL] CPUs roles (q,g,k,c,v)
X_and_IO_nCPU_LinAlg_INV=-1 # [PARALLEL] CPUs for Linear Algebra (if -1 it is automatically set)
Chimod= "hartree" # [X] IP/Hartree/ALDA/LRC/BSfxc
% BndsRnXs
1 | 200 | # [Xs] Polarization function bands
%
% LongDrXs
1.000000 | 1.000000 | 1.000000 | # [Xs] [cc] Electric Field
%
NGsBlkXs= 8000 mRy # [Xs] Response block size
# BSE
BS_CPU= "4.1.2" # [PARALLEL] CPUs for each role
BS_ROLEs= "k.eh.t" # [PARALLEL] CPUs roles (k,eh,t)
BS_nCPU_diago=4 # [PARALLEL] CPUs for matrix diagonalization
BSEmod= "causal" # [BSE] resonant/causal/coupling
BSKmod= "SEX" # [BSE] IP/Hartree/HF/ALDA/SEX/BSfxc
BSSmod= "d" # [BSS] (h)aydock/(d)iagonalization/(i)nversion/(t)ddft`
BSENGexx= 40000 mRy # [BSK] Exchange components
ALLGexx # [BSS] Force the use use all RL vectors for the exchange part
BSENGBlk= 8000 mRy # [BSK] Screened interaction block size
Lkind="full" #[BSE,X] bar(default)/full/tilde
% KfnQP_E
1.000000 | 1.000000 | 1.000000 | # [EXTQP BSK BSS] E parameters (c/v) eV|adim|adim
%
% BEnRange
0.00000 | 4.00000 | eV # [BSS] Energy range
%
% BDmRange
0.05000 | 0.05000 | eV # [BSS] Damping range
%
BEnSteps= 2000 # [BSS] Energy steps
% BLongDir
1.000000 | 0.000000 | 0.000000 | # [BSS] [cc] Electric Field
%
% BSEQptR
 1 | 7 | # [BSK] Transferred momenta range
%
% BSEBands
25 | 28 | # [BSK] Bands range
%
WRbsWF # [BSS] Write to disk excitonic the FWs

This file was generated using the command: <code> yambo -X s -o b -k sex -y d -r</code> 

First of all, we compute the excitons for all the momenta in the irreducible Brillouin zone for our discrete grid via the <code>BSEQptR</code> variable. This will be a '''finite-momentum''' BSE calculation, analogous to the phonon one.

Second, we change the variable <code>Lkind</code> from <code>bar</code> to <code>full</code>. In Yambo, <code>Lkind="bar"</code>, which is the default for optical absorption, means that we are computing the excitonic response function without the long-range component of the exchange interaction. This cannot be used when computing the exciton momentum dependence, where the long-range exchange interaction can play a role, therefore we have to include it with <code>Lkind="full"</code>. This allows for the calculation of the excitonic longitudinal-transverse splitting (in 3D systems) as well.

We can now run the code:

nohup mpirun -np 8 yambo -F bse.in -J bse_Lfull -C bse_Lfull &

At the end of the calculation, we have obtained the <code>ndb.BS_diago_Q*</code> databases inside the directory <code>bse_Lfull</code>. They contain information on the exciton energies and wavefunctions at each momentum. Do not forget to check the report and logs of your calculation in the same directory to make sure that the code is doing what you want.

== Step 6: obtain the electron-phonon matrix elements ==

We have finished the heavy simulations. Now it's time for the postprocessing. The first order of business is the reconstruction of the electron-phonon coupling matrix elements from the dvscf results and the electronic wavefunctions.

In order to do this, we will run the <code>lelphc</code> executable of the '''LetzElPhC''' code. We will run via command line using yambopy, although it will be instructive to have look at the <code>lelphc</code> input files later.

We run in the same directory where the Yambo <code>SAVE</code> is (remember than you can also virtually move it with a symbolic link).

Type:

yambopy l2y

to see the help for the calculation. For example, if we want to do a serial run of LetzElPhC for bands from <math>n_i</math> to <math>n_f</math>, we should type:

yambopy l2y -ph path/of/ph_input.in -b n_i n_f

Here <math>n_i</math> and <math>n_f</math> are integers representing the initial and final band indices.

These should coincide with those used for the Bethe-Salpeter kernel, i.e. those specified in the <code>BSEBands</code> variable of the BSE input file (this is not strictly necessary, but certainly efficient since these calculations use a lot of disk space).

For our system, we want to do a parallel calculation with 4 qpools and 2 kpools. In addition, we want to explicitly specify the path of the <code>lelphc</code> executable and avoid automatically deleting the LetzElPhC data. So we type:

yambopy l2y -ph path/of/dvscf/mos2.dvscf -b 25 28 -par 4 2 -lelphc path/to/lelphc_exe --debug

At the end, check the <code>SAVE</code>

ls SAVE/ndb.elph_gkkp*

to see that it has created the Yambo-compatible electron-phonon databases.

If you saved the <code>lelphc.in</code> input file, you can inspect it:

# LetzElPhC input for yambo generated by yambopy
nqpool = 2
nkpool = 4
start_bnd = 25
end_bnd = 28
save_dir = ./SAVE
kernel = dfpt
ph_save_dir = dvscf/ph_save
convention = yambo

You can also run it as it is, but the code will generate the database <code>ndb.elph</code>. In order to convert it to the <code>ndb.elph_gkkp*</code> databases of Yambo, you still need a couple of lines of python using the Yambopy class <code>ConvertElectronPhononDB</code> in <code>yambopy/letzelph_interface/lelph2y.py</code>.

Notice the variable <code>convention=yambo</code>: what does it mean? At variance with QE and many other codes, Yambo uses the "backward" momentum transfer convention for electronic scatterings. That is, an electronic transition goes from band <math>n</math> and momentum <math>k-q</math> to band <math>m</math> and momentum <math>k</math>. In the "forward" momentum transfer convention (the more standard one), the transitions go from <math>nk</math> to <math>mk+q</math>. Therefore, this variable ensures that the electron-phonon coupling matrix elements are computed as <math>\langle mk|dV|nk-q\rangle</math>. This will have consequences also in the formulation of the ''exciton''-phonon coupling matrix element.

== Step 7: Obtain the exciton-phonon coupling ==

Now, we can finally access our basic building block for exciton-phonon physics. This could be done entirely in python (using '''Yambopy'''), or by running '''Yambo'''. In this version of the tutorial we present the latter case.

Our objective is obtaining the following quantity:

<math>\mathcal{G}^\mu_{\alpha\lambda}(0,q)=\sum_{vv^\prime c k} A^{\alpha, *}_{cv^\prime} (k, q) g_{vv^\prime}^\mu (k,q) A^{\lambda}_{cv}(k,q) - \sum_{cc^\prime vk} A^{\alpha, *}_{c^\prime v} (k+q, q) g_{c^\prime c}^\mu (k+q,q) A^{\lambda}_{cv}(k,q)</math>

Here, <math>A^{\lambda}_{cv}(k,q)</math> are the exciton coefficients extracted from the eigenvector of the two-particles Hamiltonian during the BSE calculation in step 5, while <math>g_{nm}^\mu (k,q)</math> are the electron-phonon coupling matrix elements obtained in step 6. As you can see, the exciton <math>\lambda</math> undergoes phonon-mediated scattering to state <math>\alpha</math> via phonon mode <math>\mu</math>. The scattering can happen for the hole (valence, <math>v</math>) or for the electron (conduction, <math>c</math>).

NB:

(1) This is written in the "backward" momentum transfer convention used by Yambo. The momentum dependence is different in the "forward" transfer convention.

(2) For simplicity, this is written for zero initial exciton momentum. This means that one of the two states involved in the phonon-mediated scattering process will be in the optical limit (and possibly an optically generated exciton), while the other state can have any momentum: this momentum will be the same as the phonon one. This matrix element can be used to describe phonon-assisted absorption and emission spectra.

We have to write a new yambo input, that we can call <code>excph.in</code>, for this. You can copy (and adapt) the one below, or you can generate one by running from the command line:

yambo_ph -excph o

This generates an input to compute luminescence ("o" is for "optics"). The variables that we are interested in are:

excph # [R] Exction-phonon
ExcGkkp # [R][EXCPH] Exciton-Phonon Matrix Elelements
% ELPhExcStates
1 | 4 | # [EXCPH] Incoming (external) exciton states
%
% ELPhExcSum
1 | 12 | # [EXCPH] Outgoing (virtual) exciton states
%
LoutPath= "./bse_Lfull" # [EXCPH] Path of the outgoing L
% ElPhModes
1 | 9 | # [ELPH] Phonon modes included
%

In this input, we have to select the initial exciton states <math>\lambda</math> with <code>ELPhExcStates</code>, the final exciton states <math>\alpha</math> with <code>ELPhExcSum</code> and the phonon modes <math>\mu</math> with <code>ElPhModes</code>. Here we consider the first four states at <math>Q=0</math> (corresponding to just two excitons because they are both doubly degenerate -- do not break degeneracies when selecting states!) and the first twelve states at each finite-<math>q</math> point. We also include all the nine phonon modes of monolayer MoS2.

What about <code>LoutPath</code>? This variable controls the directory where the databases for the final-state excitons <math>\alpha</math> is located, which can be different from the directory with the initial-state excitons <math>\lambda</math> read as usual with the <code>-J</code> option when running the code. This makes it possible to compute the coupling between different exciton kinds. However, for our tutorial, we stick with the previously computed <code>Lfull</code> in both cases.

When we are satisfied with the input, we run the code using <code>yambo_ph</code>:

yambo_ph -F excph.in -J excph,bse_Lfull -C excph

If you check the output, you should find the <code>ndb.excph*</code> databases in the <code>excph</code> directory.

=== Analysis of the couplings ===

It is a good idea to have a look at what we computed up to now in order to make sure nothing has gone wrong.

It is not easy to know what to expect (apart from symmetry and gauge compliance of the matrix elements), but one can work out the exciton-phonon selection rules in advance, check that the magnitude is reasonable, etc.

It is also not easy to meaningfully plot this quantity. We have to make sure that we are not breaking degenerate states, otherwise the plots will not be invariant.

First of all, we have to know our system: in monolayer MoS2, the first four excitons are all doubly degenerate. The first exciton responsible for a bright peak in the absorption spectrum (the '''A''' peak), is the second state, corresponding to state indices <code>(3,4)</code> in fortran indexing or <code>(2,3)</code> in python indexing.

All these information can be obtained by analyzing the BSE results (this stuff is explained in the BSE tutorials) and by knowledge of the system or class of systems from the literature.

Thus, a good quantity to plot may be the norm of the matrix elements, summed over the degenerate subspace of exciton A, for a certain number of scattered final states mediated by certain phonon modes:

<math>F_A(q)= \sqrt{ \sum_{\alpha \in A,\lambda,\mu} |\mathcal{G}_{\alpha\lambda}^\mu (0,q)|^2 }</math>

In order to do this, we create a python script <code>analyse_excph.py</code> in which we first load the excph dabatases using the <code>YamboExcitonPhononDB</code> from yambopy.
You can find this script in the yambopy directory, in <code>tutorials/exciton-phonon</code>.
First, we select the exciton and phonon states to be included in <code>F_A</code>, together with the path of databases and plot details:

# Exciton in states
exc_in = [2,3] # A: 2,3 -- B: 6,7
exc_out = [0,1,2,3] # first 4 states (dispersion of triplet state and A)
ph_in = 'all'

# Paths of databases
ns_db1 =f'{path}/SAVE/ns.db1'
ndb_exc=f'{path}/excph'

...

Then, we load the data:

# Read lattice and k-space info
ylat = YamboLatticeDB.from_db_file(filename=ns_db1),Expand=True)
print(ylat)

# Read exc-ph databases
X = YamboExcitonPhononDB(ylat,save_excph=ndb_exc)
print(X)

The quantity <math>F_A(q)</math> is defined inside the plotting function as

G_squared = excph.excph_sq
G2plt = np.zeros(len(G_squared))

if exc_in == 'all': exc_in = range(G_squared.shape[2])
if exc_out == 'all': exc_out = range(G_squared.shape[3])
if ph_in == 'all': ph_in = range(G_squared.shape[1])

G_squared = G_squared[:, ph_in, :, :].sum(axis=(1))
G_squared = G_squared[:, exc_in, :].sum(axis=(1))
G_squared = G_squared[:, exc_out].sum(axis=(1))

F_q = np.sqrt( G_squared )*ha2ev # Switch from Ha to eV

And finally, we have to make a plotting function. For this tutorial we will use the default scatterplot provided by <code>YamboExcitonPhononDB</code>

excph.plot_excph(F_q,plt_cbar=plt_cbar,**kwargs)
...

You can get more experience on using Yambopy for these kinds of visualization by following the [https://wiki.yambo-code.eu/wiki/index.php?title=First_steps_in_Yambopy Yambopy tutorials]. In fact, remember that this scripts and all the other yambopy tutorial scripts are just suggestions, not source code written in stone: if you know <code>numpy</code> and <code>matplotlib</code> you can do your own analysis and your own plots, you just need to import the required Yambopy modules to load the data.

In our case, the resulting plot is the following.

[[File:1L MoS2 ExcPh.png|500px|center]]

This can be checked against Fig. 2(d) of reference <ref name="chan2023" />, although you have to keep in mind that our results are badly undersampled in terms of the reciprocal-space grid, as can be easily seen, and the quantity plotted is not exactly the same. However, the main features are already there since they are dictated mostly by crystal symmetries.

Now that we have the exciton-phonon matrix elements, we can use them to build several kinds of observables. Below, we give an example related to phonon-assisted luminescence, but we may update this tutorial in the future to include more cases.

== Step 8: Compute phonon-assisted luminescence ==

[[File:Luminescence scheme.png|250px|right]]

We want to compute the experimental optical signature due to the phonon-assisted recombination of an exciton (as sketched in the figure).

The signal from the phonon replicas can be modeled as a second-order scattering process involving one phonon and one photon:

<math>I^{(1)}_{PL}(\omega;T) \propto \frac{1}{N_q}\sum_{ s \mu \beta q} \left|\sum_\lambda\frac{D_\lambda \mathcal{G}^{\mu q}_{\alpha q,\lambda}}{E_{\alpha q}-E_\lambda -s\Omega_{\mu q}} \right|^2 N_{\alpha q}(T_{exc}) F^s_{\mu q}(T)\delta(\omega - \left[E_{\alpha q}-s\Omega_{\mu q}\right])</math>

In this equation, the oscillator strength of the peak is given by the exciton-phonon coupling matrix elements <math>\mathcal{G}</math> multiplied by the exciton dipoles <math>D</math> (they are called "residuals" in Yambo). Here <math>E_\lambda</math> and <math>E_{\alpha q}</math> are the energies of the optical and finite-momentum excitons, respectively, while <math>\Omega_{\mu q}</math> are the phonon energies.

The occupation function <math>F</math> is <math>F^s_{\mu q}(T)=n_{\mu q}(T)+\frac{1+s}{2}</math>. Here, <math>n(T)</math> is the temperature-dependent phonon Bose-Einstein occupation function. As it can be seen, <math>s=1</math> corresponds to processes of phonon ''emission'' (<math>\propto n(T)+1</math>), while <math>s=-1</math> corresponds to processes of phonon ''absorption'' (<math>\propto n(T)</math>). Therefore, <math>I^{(1)}_{PL}(\omega;T)</math> describes ''light'' emission by recombining excitons mediated by either ''phonon'' absorption or emission.

The quantity <math> N_{\alpha q}(T_{exc})</math> is the exciton occupation function. Luminescence is technically an out-of-equilibrium process, but we can assume that for very low density of excitations and in steady-state conditions, the exciton population can be approximately described by an equilibrium distribution evaluated at an effective temperature. Here, we use the Boltzmann distribution. Experimentally, <math>T_{exc}</math> tends to coincide with the lattice temperature <math>T</math> more or less above 100 K, while at very low temperature (< 10 K), <math>T_{exc}</math> may vary between 10-50 K. It goes without saying that this needs to carefully be checked in your realistic calculations.

=== Running the jobs ===

In order to study luminescence in a paradigmatic system, we switch to bulk hexagonal boron nitride and we repeat the workflow. As you can easily see, one can think about automatizing the execution of all these calculations via scripting or more advanced tools. However, in the case of very large simulations (memory-limited or disk-space limited) or for systems whose electronic and lattice properties are fragile with respect to tiny calculation details, one must be very careful and run many basic tests.

Fortunately, we are running a fast underconverged example. We use LDA pseudopotentials from the pseudo-dojo library and the following are the calculations steps.

1. Input <code>hbn.scf</code>:

&control
calculation='scf',
prefix='hBN',
restart_mode='from_scratch'
pseudo_dir = '$PSEUDO_DIR',
outdir = './tmp'
verbosity = 'high'
wf_collect=.true.
/
&system
ibrav = 4,
celldm(1) = 4.703675849
celldm(3) = 2.603711434
nat= 4,
ntyp= 2,
force_symmorphic=.true.
ecutwfc = 100,
/
&electrons
diago_david_ndim = 2
diago_full_acc=.true.
diago_thr_init=5.0e-6
mixing_mode = 'plain'
mixing_beta = 0.7
conv_thr = 1.0d-16
/
ATOMIC_SPECIES
B 10.81100 B_LDA_dojo.UPF
N 14.00674 N_LDA_dojo.UPF
ATOMIC_POSITIONS {crystal}
N 0.6666666670 0.3333333330 -0.250000000000
B 0.3333333330 0.6666666670 -0.250000000000
B 0.6666666670 0.3333333330 0.25000000000
N 0.3333333330 0.6666666670 0.25000000000
K_POINTS {automatic}
6 6 2 0 0 0

mpirun -np 4 pw.x -inp hbn.scf > scf.out

2. Input <code>hbn.nscf</code>:

&control
calculation='nscf',
prefix='hBN',
restart_mode='from_scratch'
pseudo_dir = '$PSEUDO_DIR'
outdir = './'
verbosity = 'high'
wf_collect=.true.
/
&system
ibrav = 4,
celldm(1) = 4.703675849
celldm(3) = 2.603711434
nat= 4,
ntyp= 2,
force_symmorphic=.true.
ecutwfc = 100,
nbnd = 120
/
&electrons
diago_david_ndim = 2
diago_full_acc=.true.
diago_thr_init=5.0e-6
mixing_mode = 'plain'
mixing_beta = 0.7
conv_thr = 1.0d-16
/
ATOMIC_SPECIES
B 10.81100 B_LDA_dojo.UPF
N 14.00674 N_LDA_dojo.UPF
ATOMIC_POSITIONS {crystal}
N 0.6666666670 0.3333333330 -0.250000000000
B 0.3333333330 0.6666666670 -0.250000000000
B 0.6666666670 0.3333333330 0.25000000000
N 0.3333333330 0.6666666670 0.25000000000
K_POINTS {automatic}
6 6 2 0 0 0

mpirun -np 4 pw.x -inp hbn.nscf > nscf.out

3. Input <code>hbn.dvscf</code>:

hbn_dvscf
&inputph
tr2_ph=1.0d-12,
verbosity='high'
prefix='hBN',
fildvscf = 'hBN-dvscf',
electron_phonon = 'dvscf',
fildyn='hBN.dyn',
epsil=.false.,
ldisp=.true.,
recover=.true.,
nq1=6,
nq2=6,
nq3=2
/

nohup mpirun -np 8 pw.x -inp hbn.dvscf > dvscf.out &

4. Input <code>bse.in</code> (we include 2 valence and 2 conduction bands):

optics # [R] Linear Response optical properties
bss # [R] BSE solver
bse # [R][BSE] Bethe Salpeter Equation.
dipoles # [R] Oscillator strenghts (or dipoles)
em1s
DIP_CPU= "1 8 1" # [PARALLEL] CPUs for each role
DIP_ROLEs= "k c v" # [PARALLEL] CPUs roles (k,c,v)
DIP_Threads=0 # [OPENMP/X] Number of threads for dipoles
X_and_IO_CPU= "1 1 1 8 1" # [PARALLEL] CPUs for each role
X_and_IO_ROLEs= "q g k c v" # [PARALLEL] CPUs roles (q,g,k,c,v)
X_and_IO_nCPU_LinAlg_INV=-1 # [PARALLEL] CPUs for Linear Algebra (if -1 it is automatically set)
X_Threads=0 # [OPENMP/X] Number of threads for response functions
BS_CPU= "8 1 1" # [PARALLEL] CPUs for each role
BS_ROLEs= "k eh t" # [PARALLEL] CPUs roles (k,eh,t)
BS_nCPU_LinAlg_INV=-1 # [PARALLEL] CPUs for Linear Algebra (if -1 it is automatically set)
BS_nCPU_LinAlg_DIAGO=-1 # [PARALLEL] CPUs for Linear Algebra (if -1 it is automatically set)
X_Threads=0 # [OPENMP/X] Number of threads for response functions
K_Threads=0 # [OPENMP/BSK] Number of threads for response functions
% QpntsRXs
1 | 14 | # [Xs] Transferred momenta
%
% BndsRnXs
1 | 120 | # [Xs] Polarization function bands
%
NGsBlkXs= 10 Ry # [Xs] Response block size
% LongDrXs
1.000000 | 1.000000 | 1.000000 | # [Xs] [cc] Electric Field
%
BSEmod= "resonant" # [BSE] resonant/retarded/coupling
BSKmod= "SEX" # [BSE] IP/Hartree/HF/ALDA/SEX/BSfxc
Lkind= "Lfull" # [BSE] Lbar (default) / full
BSSmod= "d" # [BSS] (h)aydock/(d)iagonalization/(s)lepc/(i)nversion/(t)ddft`
% DipBands
1 | 120 | # [DIP] Bands range for dipoles
%
DipApproach= "G-space v" # [DIP] [G-space v/R-space x/Covariant/Shifted grids]
DipComputed= "R V P" # [DIP] [default R P V; extra P2 Spin Orb]
BSENGexx= 30000 Ry # [BSK] Exchange components
#ALLGexx # [BSS] Force the use use all RL vectors for the exchange part
BSENGBlk= 9000 Ry # [BSK] Screened interaction block size [if -1 uses all the G-vectors of W(q,G,Gp)]
% KfnQP_E
1.25997 | 1.08816 | 1.12683 | # [EXTQP BSK BSS] E parameters (c/v) eV|adim|adim
%
% BSEQptR
 1 | 14 | # [BSK] Transferred momenta range
%
% BSEBands
 7 | 10 | # [BSK] Bands range
%
% BEnRange
0.50000 | 8.00000 | eV # [BSS] Energy range
%
% BDmRange
0.050000 | 0.050000 | eV # [BSS] Damping range
%
BEnSteps= 1000 # [BSS] Energy steps
% BLongDir
1.000000 | 1.000000 | 0.000000 | # [BSS] [cc] Electric Field
%
WRbsWF # [BSS] Write to disk excitonic the WFs

nohup mpirun -np 8 yambo -F bse.in -J bse_Lfull -C bse_Lfull &

Importantly, since we want to describe the phonon-assisted recombination process of an *optical* exciton (i.e., emitting a transverse photon), this time we also run an additional calculation at `Q=0` omitting the nonanalytic long-range Coulomb exchange. Make a second input <code>bse_Lbar.in</code> with the following changes:

Lkind= "Lbar" # [BSE] Lbar (default) / full
% BSEQptR
 1 | 1 | # [BSK] Transferred momenta range
%

4b. So now we make a second BSE run in a different directory specified by <code>-J</code>. Here, we also pass to yambo the directory of the previous run as it includes the important screening databases <code>ndb.em1s*</code> that we do not want to recompute from scratch.

mpirun -np 8 yambo -F bse_Lbar.in -J bse_Lbar,bse_Lfull -C bse_Lbar

5. Now we run <code>lelphc</code> with yambopy to get the el-ph matrix elements:

yambopy l2y -ph path/of/dvscf/hbn.dvscf -b 7 10 -par 4 2

6. And finally we generate the exciton-phonon input <code>excph.in</code> using <code>yambo_ph -excph o</code>. Now, we take a look at all the additional variables that we didn't check before, specifying also the details for luminescence the spectrum calculation.

excph # [R] Exction-phonon
ExcGkkp # [R][EXCPH] Exciton-Phonon Matrix Elelements
ExcPhOptics # [R][EXCPH] Exciton-Phonon Optics
BoseTemp=10.000000 Kn # Bosonic Temperature
EXCTemp= 10.000000 Kn # [EXCPH] Excitonic Temperature (for luminescence spectra)
% ELPhExcStates
1 | 4 | # [EXCPH] Incoming (external) exciton states
%
% ELPhExcSum
1 | 12 | # [EXCPH] Outgoing (virtual) exciton states
%
% ElPhModes
1 | 12 | # [ELPH] Phonon modes included
%
LoutPath= "./bse-L_full" # [EXCPH] Path of the outgoing L
FANdEtresh= 0.100000E-5 eV # [ELPH] Energy treshold for Fan denominator
EXCPHdEtresh= 0.100000E-5 eV # [ELPH] Energy treshold for exc-ph denominator
LDamping= 0.500000E-3 eV # [EXCPH] Damping of exc-ph self-energy
# These are the plot parameters, same as in other parts of yambo
% EnRngeXd
4.00000 | 5.00000 | eV # [Xd] Energy range
%
% DmRngeXd
0.00500000 | 0.00500000 | eV # [Xd] Damping range
%
ETStpsXd= 4000 # [Xd] Total Energy steps

Here <code>BoseTemp</code> and <code>EXCTemp</code> are the lattice and excitonic temperature, respectively.

Now we run the calculation with <code>yambo_ph</code>. Here, we read as <math>Q=0</math> excitons with <code>-J</code> the ones without the long-range Coulomb exchange:

yambo_ph -F excph.in -J excph,bse_Lbar -C excph

and we find our outputs in the <code>excph</code> directory.

NB: Step 6 could have been equivalently run in yambopy, limiting the use of the yambo code to just step 4. This latter option is more flexible, as it allows for a greater degree of control by the user. We are in the last stages of the development and it will be available soon.

=== Results ===

If we check the output directory from the step 6 calculation, we find the <code>o-excph.pl_bse_ph_ass</code> output files containing the luminescence spectra. We can plot them with gnuplot or any other tool:

gnuplot
> set xrange[4.2:5]
> p 'o-excph.pl_bse_ph_ass' u 1:2 w l lc rgb 'red' lw 3

[[File:Luminescence plot.png|500px|center]]

Here, the signal corresponds to a finite-momentum exciton that recombines with the help of several different phonon modes, both optical and acoustic. Each phonon mode whose coupling with the exciton is allowed can generate a peak, and the energy shifts of these peaks with respect to the initial exciton energy correspond to the phonon energies. This result is underconverged, but the main features are all there. In the plot, we show a more converged example using a 12x12x4 grid (all the other parameters being equal). These plots can be compared with Fig. 4(a) of reference <ref name="zanfrognini2023" />.

== References ==

<references>
<ref name="toyozawa2003" >[https://m.booksee.org/book/1121964?force_lang=en Optical processes in solids], Toyozawa, Yutaka, and Chris Oxlade. Cambridge University Press, (2003). </ref>
<ref name='lechifflart2023'>P. Lechifflart, F. Paleari, D. Sangalli, C. Attaccalite, ''First-principles study of luminescence in hexagonal boron nitride single layer: Exciton-phonon coupling and the role of substrate'',
[https://doi.org/10.1103/PhysRevMaterials.7.024006 Phys. Rev. M, '''7''' (2), 024006 (2023)]; [https://arxiv.org/abs/2212.10407 arXiv2212.1047]</ref>
<ref name='cannuccia2019'>E. Cannuccia, B. Monserrat and C. Attaccalite, ''Theory of phonon-assisted luminescence in solids: Application to hexagonal boron nitride'', [https://doi.org/10.1103/PhysRevB.99.081109 Phys. Rev. B '''99''', 081109(R) (2019)]; [https://arxiv.org/abs/1807.11797 arXiv1807.11797]</ref>
<ref name='paleari2019'>F. Paleari et al., ''Exciton-Phonon Coupling in the Ultraviolet Absorption and Emission Spectra of Bulk Hexagonal Boron Nitride'', [https://doi.org/10.1103/PhysRevLett.122.187401 Phys. Rev. Lett. '''122''', 187401 (2019)]; [https://arxiv.org/abs/1810.08976 arXiv1810.089776] </ref>
<ref name='chen2020'>''Exciton-Phonon Interaction and Relaxation Times from First Principles'',
Hsiao-Yi Chen, Davide Sangalli, and Marco Bernardi, [https://doi.org/10.1103/PhysRevLett.125.107401 Phys. Rev. Lett. '''125''', 107401 (2020)]; [https://arxiv.org/abs/2002.08913 arXiv 2002.08913 (2020)]</ref>
<ref name="lechifflart2023_PhD">[https://www.yambo-code.eu/wiki/images/5/54/These_final.pdf Exciton-phonon coupling and phonon-assisted luminescence in hexagonal Boron Nitride nanostructures], PhD Thesis, Pierre Lechifflart (2023)</ref>
<ref name='paleari2019_PhD'>F. Paleari, ''First-principles approaches to the description of indirect absorption and luminescence spectroscopy: exciton-phonon coupling in hexagonal boron nitride'', [https://wwwen.uni.lu/research/fstm/dphyms/people/fulvio_paleari PhD thesis, University of Luxembourg (2019)]</ref>
<ref name='zanfrognini2023'>[https://arxiv.org/abs/2305.17554 Distinguishing different stackings in layered materials via luminescence spectroscopy], M. Zanfrognini et al. Phys. Rev. Lett. '''131''', 206902 (2023) </ref>
<ref name='marini2024'>G. Marini, M. Calandra, P. Cudazzo, ''Optical absorption and photoluminescence of single layer boron nitride from a first principles cumulant approach'', [https://doi.org/10.1021/acs.nanolett.4c00669 Nano Lett., '''24''', 20, 6017 (2024)]; [https://arxiv.org/abs/2402.03826 arXiv 2402.03826 (2024)]</ref>
<ref name='antonius2017'>G. Antonius, S. G. Louie, ''Theory of exciton-phonon coupling'', [https://doi.org/10.1103/PhysRevB.105.085111 Phys. Rev. B, '''105''', 085111 (2022)]; [https://arxiv.org/abs/1705.04245 arXiv1705.04245 (2017)]</ref>
<ref name='paleari2022'>[https://arxiv.org/abs/2205.02783 Exciton-phonon interaction calls for a revision of the “exciton” concept], F. Paleari, A. Marini, Phys. Rev. B, '''106''', 125403 (2022)</ref>
<ref name='cudazzo2020'> P. Cudazzo, ''First-principles description of the exciton-phonon interaction: A cumulant approach'', [https://doi.org/10.1103/PhysRevB.102.045136 Phys. Rev. B, '''102''', 045136 (2020)]; [https://orbilu.uni.lu/bitstream/10993/44769/1/main.pdf Open access pdf from Luxembourg University]</ref>
<ref name='chan2023'>Y-h Chan, J. B. Haber, M. H. Naik, J. B. Neaton, D. Y. Qiu, F. H. da Jornada, S. G. Louie, ''Exciton Lifetime and Optical Line Width Profile via Exciton–Phonon Interactions: Theory and First-Principles Calculations for Monolayer MoS2'', [https://doi.org/10.1021/acs.nanolett.3c00732 Nano Lett., '''23''', 9 (2023)]; [https://arxiv.org/abs/2212.08451 arXiv 2212.08451 (2023)]</ref>
<ref name='murali2025'>M. Nalabothula, S. Reichardt, L. Wirtz, ''Origin of Interlayer Exciton–Phonon Coupling in 2D Heterostructures'', [https://doi.org/10.1021/acs.nanolett.5c00355 Nano Lett., '''25''', 15 (2025)], [https://arxiv.org/abs/2407.16111 arXiv 2407.16111 (2025)]</ref>
</references>

Exciton-phonon coupling and luminescence

2025-10-06T11:52:15Z

Attacc: /* Step 5: run a BSE calculation */

[[File:Tdgw-phonon-usc-01-1024x829.jpg| 400px | right]]

In this advanced tutorial, we will calculate exciton-phonon interactions from first principles by interfacing DFPT (for phonon calculations) and BSE (for exciton calculations).

The DFTP calculations are run with Quantum ESPRESSO, while the many-body GW-BSE calculations are run with Yambo. Finally, the exciton-phonon interaction will be obtained by combining and postprocessing the databases computed in the two previous runs. The great advantage of this workflow is that the calculations can be run in the irreducible Brillouin zones both for the electronic momenta (<math>k</math>) and the transfer momenta (<math>Q</math>, <math>q</math>) of excitons and phonons, thus speeding up considerably the jobs while reducing the IO and memory load.

We will first compute the exciton-phonon coupling matrix elements: these are the building blocks needed to construct experimental observables such as phonon-assisted optical spectra (such as luminescence), Raman spectra and exciton lifetimes. We will do this in the case of monolayer MoS2, a 2D system with large spin-orbit interaction.

As an example of application, we will consider the case of phonon-assisted luminescence. We will do this in the case of bulk hBN, a layered indirect insulator with strong electron-phonon coupling.

'''Note:''' this tutorial will be updated when new exc-ph tools become available in Yambopy (including full-python postprocessing, Raman spectra, interpolated lifetimes, etc).

== Requirements ==

This is an advanced topic: we assume that you already know something about the theory<ref name="toyozawa2003" /><ref name="antonius2017" /><ref name="cudazzo2020" /><ref name="paleari2019_PhD" /><ref name="paleari2022" /><ref name="lechifflart2023_PhD" /> and applications<ref name="paleari2019" /><ref name="cannuccia2019" /><ref name="chen2020" /><ref name="zanfrognini2023" /><ref name="lechifflart2023" /><ref name="chan2023" /><ref name="marini2024" /><ref name="murali2025" /> of exciton-phonon physics.

Also, we assume that you already know how to run both a basic '''Yambo''' GW-BSE calculation and a DFPT phonon calculation with '''Quantum ESPRESSO'''.

Besides the QE executables <code>pw.x</code> and <code>ph.x</code>, we also use the yambo phonon-specific executable <code>yambo_ph</code> and the python utility '''Yambopy'''. The auxiliary code '''LetzElPhC''' (executable <code>lelphc</code>) will be used to obtain the electron-phonon matrix elements by reading the same electronic wavefunctions used by Yambo (and stored in the <code>SAVE</code> directory), while also making full use of crystal symmetries. [https://gitlab.com/lumen-code/LetzElPhC LetzElPhC] will be run by Yambopy, but it must nonetheless be installed. Finally, the exciton-phonon properties can be computed either using <code>yambo_ph</code> or using Yambopy itself.

[[File:Workflow scheme.png|800px|center]]

== Step 0: Pseudopotentials, equilibrium structure and convergence ==

In a real calculation, it is important to ensure that both the pseudopotential and the lattice parameters that we are using are compatible and perform well for the electronic excited states and for the lattice vibrations simultaneously. Furthermore, you have to make sure that the wave function cutoff <code>ecutwfc</code> is converged with respect to the DFPT step and not just to the DFT one. This is in addition to the other customary convergence tests for DFT, DFPT, GW and BSE calculations.

This is often the most time-demanding step when starting on a new system.

For the sake of this tutorial, we assume that we have already done all these tests and we are starting the final workflow to get the exciton-phonon properties.

== Step 1: scf calculation ==

First of all, we run a standard scf calculation with <code>pw.x</code> for Yambo. We stick with non-symmorphic symmetries. At the end, we will have the QE <code>save</code> directory.

This is the input <code>mos2.scf</code>:

&control
wf_collect = .true.,
calculation = "scf",
verbosity = 'high',
pseudo_dir = '$PSEUDO_DIR',
prefix = "mos2",
outdir = '.',
/&end
&system
ecutwfc = 100.0,
occupations = 'fixed',
ibrav = 4,
celldm(1) = 5.9000811881,
celldm(3) = 6.7795677253,
nat = 3,
ntyp = 2,
lspinorb = .true.
noncolin = .true.
assume_isolated = '2D'
force_symmorphic = .true.
/&end
&electrons
electron_maxstep = 200,
mixing_beta = 0.7,
conv_thr = 1.d-08,
/&end
ATOMIC_SPECIES
Mo 95.940 Mo_ONCV_PBE_FR-1.0.upf
S 32.065 S_ONCV_PBE_FR-1.1.upf
ATOMIC_POSITIONS { crystal }
Mo 0.333333333 0.666666667 0.000000000
S 0.666666667 0.333333333 0.073413577
S 0.666666667 0.333333333 -0.073413577
K_POINTS { automatic }
6 6 1 0 0 0

Here we are using full relativistic pseudopotentials from the SG-15 database.

We can run it on our machine (for example using 4 MPI tasks) as:

mpirun -np 4 pw.x -inp mos2.scf > scf.out

== Step 2: nscf calculation for Yambo ==

Copy the QE <code>save</code> directory from the scf calculation and run the nscf calculation for any number of empty states, with the correct <code>k</code>-grid we want to use in Yambo. Here we are using a badly underconverged grid of 6x6x1.

This reciprocal-space grid will also match the momentum transfer <code>q</code> grid on which excitons and phonons will be defined!

The electronic wavefunctions computed at this step and stored in the new nscf <code>save</code> directory will be used both by Yambo and by the electron-phonon code: this is important because using different sets of wavefunctions would lead to a phase mismatch issue in the exciton-phonon matrix elements.

The nscf input <code>mos2.nscf</code> is
&control
wf_collect = .true.,
calculation = "nscf",
verbosity = 'high',
pseudo_dir = '$PSEUDO_DIR',
prefix = "mos2",
outdir = '.',
/&end
&system
ecutwfc = 100.0,
occupations = 'fixed',
ibrav = 4,
celldm(1) = 5.9000811881,
celldm(3) = 6.7795677253,
nat = 3,
ntyp = 2,
lspinorb = .true.
noncolin = .true.
nbnd = 250
assume_isolated = '2D'
force_symmorphic = .true.
/&end
&electrons
electron_maxstep = 200,
mixing_beta = 0.7,
conv_thr = 1.d-08,
/&end
ATOMIC_SPECIES
Mo 95.940 Mo_ONCV_PBE_FR-1.0.upf
S 32.065 S_ONCV_PBE_FR-1.1.upf
ATOMIC_POSITIONS { crystal }
Mo 0.333333333 0.666666667 0.000000000
S 0.666666667 0.333333333 0.073413577
S 0.666666667 0.333333333 -0.073413577
K_POINTS { automatic }
6 6 1 0 0 0

Again, we run the calculation

mpirun -np 4 pw.x -inp mos2.nscf > nscf.out

== Step 3: dvscf phonon calculation ==

Now we run the phonon calculation.

Copy the <code>save</code> directory from the '''scf''' calculation and run <code>ph.x</code> for a dvscf calculation with a standard <code>q</code>-grid matching the <code>k</code>-grid we wanna use in Yambo.

At the end, we will have the <code>_ph0</code> directory containing the variation of the self-consistent potential, <math>\Delta V_{SCF}(q)</math>, and the <code>*.dyn</code> files with the phonon energies and eigenvectors.

NB: one could further refine the phonon energies by enforcing the acoustic sum rule, including non-analytic long-range contributions, interpolating to finer grids... all of this can be done within Quantum ESPRESSO and will not be covered in this version of the tutorial.

The input is <code>mos2.dvscf</code>:

mos2_dvscf
&inputph
tr2_ph=1.0d-12,
verbosity='high'
prefix='mos2',
fildvscf = 'mos2-dvscf',
electron_phonon = 'dvscf',
fildyn='mos2.dyn',
epsil=.false.,
ldisp=.true.,
recover=.true.,
nq1=6,
nq2=6,
nq3=1
/

And now we run as

nohup mpirun -np 8 ph.x -inp mos2.dvscf > dvscf.out &

This time we use nohup and more processes because this calculation may take some time. It is a good idea to set <code>recover=.true.</code> as in a real calculation you will easily breach walltime, and in this way you can safely restart.

== Step 4: create Yambo <code>SAVE</code> directory ==

This is just the standard Yambo initialization: run

p2y

and then

yambo

in the '''nscf''' <code>save</code> folder and then move the newly generated <code>SAVE</code> directory to a convenient place.

== Step 5: run a BSE calculation ==

Now we switch from QE to Yambo. Here, we forgo the GW step for simplicity (we can use a scissor operator to open the band gap).

This calculation has a couple of differences with respect to a standard BSE calculation for optical absorption. We can look at the input file <code>bse.in</code>:

# Runlevels
optics # [R OPT] Optics
rim_cut # [R RIM CUT] Coulomb potential
bss # [R BSS] Bethe Salpeter Equation solver
em1s # [R Xs] Static Inverse Dielectric Matrix
bse # [R BSE] Bethe Salpeter Equation.
bsk # [R BSK] Bethe Salpeter Equation kernel
# RIM and cutoff settings
RandQpts=1000000 # [RIM] Number of random q-points in the BZ
RandGvec= 100 RL # [RIM] Coulomb interaction RS components
CUTGeo= "slab z" # [CUT] Coulomb Cutoff geometry: box/cylinder/sphere X/Y/Z/XY..
# Static screening
X_and_IO_CPU= "1 1 4 2 1" # [PARALLEL] CPUs for each role
X_and_IO_ROLEs= "q g k c v" # [PARALLEL] CPUs roles (q,g,k,c,v)
X_and_IO_nCPU_LinAlg_INV=-1 # [PARALLEL] CPUs for Linear Algebra (if -1 it is automatically set)
Chimod= "hartree" # [X] IP/Hartree/ALDA/LRC/BSfxc
% BndsRnXs
1 | 200 | # [Xs] Polarization function bands
%
% LongDrXs
1.000000 | 1.000000 | 1.000000 | # [Xs] [cc] Electric Field
%
NGsBlkXs= 8 Ry # [Xs] Response block size
# BSE
BS_CPU= "4.1.2" # [PARALLEL] CPUs for each role
BS_ROLEs= "k.eh.t" # [PARALLEL] CPUs roles (k,eh,t)
BS_nCPU_diago=4 # [PARALLEL] CPUs for matrix diagonalization
BSEmod= "causal" # [BSE] resonant/causal/coupling
BSKmod= "SEX" # [BSE] IP/Hartree/HF/ALDA/SEX/BSfxc
BSSmod= "d" # [BSS] (h)aydock/(d)iagonalization/(i)nversion/(t)ddft`
BSENGexx= 40000 mRy # [BSK] Exchange components
ALLGexx # [BSS] Force the use use all RL vectors for the exchange part
BSENGBlk= 8000 mRy # [BSK] Screened interaction block size
Lkind="full" #[BSE,X] bar(default)/full/tilde
% KfnQP_E
1.000000 | 1.000000 | 1.000000 | # [EXTQP BSK BSS] E parameters (c/v) eV|adim|adim
%
% BEnRange
0.00000 | 4.00000 | eV # [BSS] Energy range
%
% BDmRange
0.05000 | 0.05000 | eV # [BSS] Damping range
%
BEnSteps= 2000 # [BSS] Energy steps
% BLongDir
1.000000 | 0.000000 | 0.000000 | # [BSS] [cc] Electric Field
%
% BSEQptR
 1 | 7 | # [BSK] Transferred momenta range
%
% BSEBands
25 | 28 | # [BSK] Bands range
%
WRbsWF # [BSS] Write to disk excitonic the FWs

This file was generated using the command: <code> yambo -X s -o b -k sex -y d -r</code> 

First of all, we compute the excitons for all the momenta in the irreducible Brillouin zone for our discrete grid via the <code>BSEQptR</code> variable. This will be a '''finite-momentum''' BSE calculation, analogous to the phonon one.

Second, we change the variable <code>Lkind</code> from <code>bar</code> to <code>full</code>. In Yambo, <code>Lkind="bar"</code>, which is the default for optical absorption, means that we are computing the excitonic response function without the long-range component of the exchange interaction. This cannot be used when computing the exciton momentum dependence, where the long-range exchange interaction can play a role, therefore we have to include it with <code>Lkind="full"</code>. This allows for the calculation of the excitonic longitudinal-transverse splitting (in 3D systems) as well.

We can now run the code:

nohup mpirun -np 8 yambo -F bse.in -J bse_Lfull -C bse_Lfull &

At the end of the calculation, we have obtained the <code>ndb.BS_diago_Q*</code> databases inside the directory <code>bse_Lfull</code>. They contain information on the exciton energies and wavefunctions at each momentum. Do not forget to check the report and logs of your calculation in the same directory to make sure that the code is doing what you want.

== Step 6: obtain the electron-phonon matrix elements ==

We have finished the heavy simulations. Now it's time for the postprocessing. The first order of business is the reconstruction of the electron-phonon coupling matrix elements from the dvscf results and the electronic wavefunctions.

In order to do this, we will run the <code>lelphc</code> executable of the '''LetzElPhC''' code. We will run via command line using yambopy, although it will be instructive to have look at the <code>lelphc</code> input files later.

We run in the same directory where the Yambo <code>SAVE</code> is (remember than you can also virtually move it with a symbolic link).

Type:

yambopy l2y

to see the help for the calculation. For example, if we want to do a serial run of LetzElPhC for bands from <math>n_i</math> to <math>n_f</math>, we should type:

yambopy l2y -ph path/of/ph_input.in -b n_i n_f

Here <math>n_i</math> and <math>n_f</math> are integers representing the initial and final band indices.

These should coincide with those used for the Bethe-Salpeter kernel, i.e. those specified in the <code>BSEBands</code> variable of the BSE input file (this is not strictly necessary, but certainly efficient since these calculations use a lot of disk space).

For our system, we want to do a parallel calculation with 4 qpools and 2 kpools. In addition, we want to explicitly specify the path of the <code>lelphc</code> executable and avoid automatically deleting the LetzElPhC data. So we type:

yambopy l2y -ph path/of/dvscf/mos2.dvscf -b 25 28 -par 4 2 -lelphc path/to/lelphc_exe --debug

At the end, check the <code>SAVE</code>

ls SAVE/ndb.elph_gkkp*

to see that it has created the Yambo-compatible electron-phonon databases.

If you saved the <code>lelphc.in</code> input file, you can inspect it:

# LetzElPhC input for yambo generated by yambopy
nqpool = 2
nkpool = 4
start_bnd = 25
end_bnd = 28
save_dir = ./SAVE
kernel = dfpt
ph_save_dir = dvscf/ph_save
convention = yambo

You can also run it as it is, but the code will generate the database <code>ndb.elph</code>. In order to convert it to the <code>ndb.elph_gkkp*</code> databases of Yambo, you still need a couple of lines of python using the Yambopy class <code>ConvertElectronPhononDB</code> in <code>yambopy/letzelph_interface/lelph2y.py</code>.

Notice the variable <code>convention=yambo</code>: what does it mean? At variance with QE and many other codes, Yambo uses the "backward" momentum transfer convention for electronic scatterings. That is, an electronic transition goes from band <math>n</math> and momentum <math>k-q</math> to band <math>m</math> and momentum <math>k</math>. In the "forward" momentum transfer convention (the more standard one), the transitions go from <math>nk</math> to <math>mk+q</math>. Therefore, this variable ensures that the electron-phonon coupling matrix elements are computed as <math>\langle mk|dV|nk-q\rangle</math>. This will have consequences also in the formulation of the ''exciton''-phonon coupling matrix element.

== Step 7: Obtain the exciton-phonon coupling ==

Now, we can finally access our basic building block for exciton-phonon physics. This could be done entirely in python (using '''Yambopy'''), or by running '''Yambo'''. In this version of the tutorial we present the latter case.

Our objective is obtaining the following quantity:

<math>\mathcal{G}^\mu_{\alpha\lambda}(0,q)=\sum_{vv^\prime c k} A^{\alpha, *}_{cv^\prime} (k, q) g_{vv^\prime}^\mu (k,q) A^{\lambda}_{cv}(k,q) - \sum_{cc^\prime vk} A^{\alpha, *}_{c^\prime v} (k+q, q) g_{c^\prime c}^\mu (k+q,q) A^{\lambda}_{cv}(k,q)</math>

Here, <math>A^{\lambda}_{cv}(k,q)</math> are the exciton coefficients extracted from the eigenvector of the two-particles Hamiltonian during the BSE calculation in step 5, while <math>g_{nm}^\mu (k,q)</math> are the electron-phonon coupling matrix elements obtained in step 6. As you can see, the exciton <math>\lambda</math> undergoes phonon-mediated scattering to state <math>\alpha</math> via phonon mode <math>\mu</math>. The scattering can happen for the hole (valence, <math>v</math>) or for the electron (conduction, <math>c</math>).

NB:

(1) This is written in the "backward" momentum transfer convention used by Yambo. The momentum dependence is different in the "forward" transfer convention.

(2) For simplicity, this is written for zero initial exciton momentum. This means that one of the two states involved in the phonon-mediated scattering process will be in the optical limit (and possibly an optically generated exciton), while the other state can have any momentum: this momentum will be the same as the phonon one. This matrix element can be used to describe phonon-assisted absorption and emission spectra.

We have to write a new yambo input, that we can call <code>excph.in</code>, for this. You can copy (and adapt) the one below, or you can generate one by running from the command line:

yambo_ph -excph o

This generates an input to compute luminescence ("o" is for "optics"). The variables that we are interested in are:

excph # [R] Exction-phonon
ExcGkkp # [R][EXCPH] Exciton-Phonon Matrix Elelements
% ELPhExcStates
1 | 4 | # [EXCPH] Incoming (external) exciton states
%
% ELPhExcSum
1 | 12 | # [EXCPH] Outgoing (virtual) exciton states
%
LoutPath= "./bse_Lfull" # [EXCPH] Path of the outgoing L
% ElPhModes
1 | 9 | # [ELPH] Phonon modes included
%

In this input, we have to select the initial exciton states <math>\lambda</math> with <code>ELPhExcStates</code>, the final exciton states <math>\alpha</math> with <code>ELPhExcSum</code> and the phonon modes <math>\mu</math> with <code>ElPhModes</code>. Here we consider the first four states at <math>Q=0</math> (corresponding to just two excitons because they are both doubly degenerate -- do not break degeneracies when selecting states!) and the first twelve states at each finite-<math>q</math> point. We also include all the nine phonon modes of monolayer MoS2.

What about <code>LoutPath</code>? This variable controls the directory where the databases for the final-state excitons <math>\alpha</math> is located, which can be different from the directory with the initial-state excitons <math>\lambda</math> read as usual with the <code>-J</code> option when running the code. This makes it possible to compute the coupling between different exciton kinds. However, for our tutorial, we stick with the previously computed <code>Lfull</code> in both cases.

When we are satisfied with the input, we run the code using <code>yambo_ph</code>:

yambo_ph -F excph.in -J excph,bse_Lfull -C excph

If you check the output, you should find the <code>ndb.excph*</code> databases in the <code>excph</code> directory.

=== Analysis of the couplings ===

It is a good idea to have a look at what we computed up to now in order to make sure nothing has gone wrong.

It is not easy to know what to expect (apart from symmetry and gauge compliance of the matrix elements), but one can work out the exciton-phonon selection rules in advance, check that the magnitude is reasonable, etc.

It is also not easy to meaningfully plot this quantity. We have to make sure that we are not breaking degenerate states, otherwise the plots will not be invariant.

First of all, we have to know our system: in monolayer MoS2, the first four excitons are all doubly degenerate. The first exciton responsible for a bright peak in the absorption spectrum (the '''A''' peak), is the second state, corresponding to state indices <code>(3,4)</code> in fortran indexing or <code>(2,3)</code> in python indexing.

All these information can be obtained by analyzing the BSE results (this stuff is explained in the BSE tutorials) and by knowledge of the system or class of systems from the literature.

Thus, a good quantity to plot may be the norm of the matrix elements, summed over the degenerate subspace of exciton A, for a certain number of scattered final states mediated by certain phonon modes:

<math>F_A(q)= \sqrt{ \sum_{\alpha \in A,\lambda,\mu} |\mathcal{G}_{\alpha\lambda}^\mu (0,q)|^2 }</math>

In order to do this, we create a python script <code>analyse_excph.py</code> in which we first load the excph dabatases using the <code>YamboExcitonPhononDB</code> from yambopy.
You can find this script in the yambopy directory, in <code>tutorials/exciton-phonon</code>.
First, we select the exciton and phonon states to be included in <code>F_A</code>, together with the path of databases and plot details:

# Exciton in states
exc_in = [2,3] # A: 2,3 -- B: 6,7
exc_out = [0,1,2,3] # first 4 states (dispersion of triplet state and A)
ph_in = 'all'

# Paths of databases
ns_db1 =f'{path}/SAVE/ns.db1'
ndb_exc=f'{path}/excph'

...

Then, we load the data:

# Read lattice and k-space info
ylat = YamboLatticeDB.from_db_file(filename=ns_db1),Expand=True)
print(ylat)

# Read exc-ph databases
X = YamboExcitonPhononDB(ylat,save_excph=ndb_exc)
print(X)

The quantity <math>F_A(q)</math> is defined inside the plotting function as

G_squared = excph.excph_sq
G2plt = np.zeros(len(G_squared))

if exc_in == 'all': exc_in = range(G_squared.shape[2])
if exc_out == 'all': exc_out = range(G_squared.shape[3])
if ph_in == 'all': ph_in = range(G_squared.shape[1])

G_squared = G_squared[:, ph_in, :, :].sum(axis=(1))
G_squared = G_squared[:, exc_in, :].sum(axis=(1))
G_squared = G_squared[:, exc_out].sum(axis=(1))

F_q = np.sqrt( G_squared )*ha2ev # Switch from Ha to eV

And finally, we have to make a plotting function. For this tutorial we will use the default scatterplot provided by <code>YamboExcitonPhononDB</code>

excph.plot_excph(F_q,plt_cbar=plt_cbar,**kwargs)
...

You can get more experience on using Yambopy for these kinds of visualization by following the [https://wiki.yambo-code.eu/wiki/index.php?title=First_steps_in_Yambopy Yambopy tutorials]. In fact, remember that this scripts and all the other yambopy tutorial scripts are just suggestions, not source code written in stone: if you know <code>numpy</code> and <code>matplotlib</code> you can do your own analysis and your own plots, you just need to import the required Yambopy modules to load the data.

In our case, the resulting plot is the following.

[[File:1L MoS2 ExcPh.png|500px|center]]

This can be checked against Fig. 2(d) of reference <ref name="chan2023" />, although you have to keep in mind that our results are badly undersampled in terms of the reciprocal-space grid, as can be easily seen, and the quantity plotted is not exactly the same. However, the main features are already there since they are dictated mostly by crystal symmetries.

Now that we have the exciton-phonon matrix elements, we can use them to build several kinds of observables. Below, we give an example related to phonon-assisted luminescence, but we may update this tutorial in the future to include more cases.

== Step 8: Compute phonon-assisted luminescence ==

[[File:Luminescence scheme.png|250px|right]]

We want to compute the experimental optical signature due to the phonon-assisted recombination of an exciton (as sketched in the figure).

The signal from the phonon replicas can be modeled as a second-order scattering process involving one phonon and one photon:

<math>I^{(1)}_{PL}(\omega;T) \propto \frac{1}{N_q}\sum_{ s \mu \beta q} \left|\sum_\lambda\frac{D_\lambda \mathcal{G}^{\mu q}_{\alpha q,\lambda}}{E_{\alpha q}-E_\lambda -s\Omega_{\mu q}} \right|^2 N_{\alpha q}(T_{exc}) F^s_{\mu q}(T)\delta(\omega - \left[E_{\alpha q}-s\Omega_{\mu q}\right])</math>

In this equation, the oscillator strength of the peak is given by the exciton-phonon coupling matrix elements <math>\mathcal{G}</math> multiplied by the exciton dipoles <math>D</math> (they are called "residuals" in Yambo). Here <math>E_\lambda</math> and <math>E_{\alpha q}</math> are the energies of the optical and finite-momentum excitons, respectively, while <math>\Omega_{\mu q}</math> are the phonon energies.

The occupation function <math>F</math> is <math>F^s_{\mu q}(T)=n_{\mu q}(T)+\frac{1+s}{2}</math>. Here, <math>n(T)</math> is the temperature-dependent phonon Bose-Einstein occupation function. As it can be seen, <math>s=1</math> corresponds to processes of phonon ''emission'' (<math>\propto n(T)+1</math>), while <math>s=-1</math> corresponds to processes of phonon ''absorption'' (<math>\propto n(T)</math>). Therefore, <math>I^{(1)}_{PL}(\omega;T)</math> describes ''light'' emission by recombining excitons mediated by either ''phonon'' absorption or emission.

The quantity <math> N_{\alpha q}(T_{exc})</math> is the exciton occupation function. Luminescence is technically an out-of-equilibrium process, but we can assume that for very low density of excitations and in steady-state conditions, the exciton population can be approximately described by an equilibrium distribution evaluated at an effective temperature. Here, we use the Boltzmann distribution. Experimentally, <math>T_{exc}</math> tends to coincide with the lattice temperature <math>T</math> more or less above 100 K, while at very low temperature (< 10 K), <math>T_{exc}</math> may vary between 10-50 K. It goes without saying that this needs to carefully be checked in your realistic calculations.

=== Running the jobs ===

In order to study luminescence in a paradigmatic system, we switch to bulk hexagonal boron nitride and we repeat the workflow. As you can easily see, one can think about automatizing the execution of all these calculations via scripting or more advanced tools. However, in the case of very large simulations (memory-limited or disk-space limited) or for systems whose electronic and lattice properties are fragile with respect to tiny calculation details, one must be very careful and run many basic tests.

Fortunately, we are running a fast underconverged example. We use LDA pseudopotentials from the pseudo-dojo library and the following are the calculations steps.

1. Input <code>hbn.scf</code>:

&control
calculation='scf',
prefix='hBN',
restart_mode='from_scratch'
pseudo_dir = '$PSEUDO_DIR',
outdir = './tmp'
verbosity = 'high'
wf_collect=.true.
/
&system
ibrav = 4,
celldm(1) = 4.703675849
celldm(3) = 2.603711434
nat= 4,
ntyp= 2,
force_symmorphic=.true.
ecutwfc = 100,
/
&electrons
diago_david_ndim = 2
diago_full_acc=.true.
diago_thr_init=5.0e-6
mixing_mode = 'plain'
mixing_beta = 0.7
conv_thr = 1.0d-16
/
ATOMIC_SPECIES
B 10.81100 B_LDA_dojo.UPF
N 14.00674 N_LDA_dojo.UPF
ATOMIC_POSITIONS {crystal}
N 0.6666666670 0.3333333330 -0.250000000000
B 0.3333333330 0.6666666670 -0.250000000000
B 0.6666666670 0.3333333330 0.25000000000
N 0.3333333330 0.6666666670 0.25000000000
K_POINTS {automatic}
6 6 2 0 0 0

mpirun -np 4 pw.x -inp hbn.scf > scf.out

2. Input <code>hbn.nscf</code>:

&control
calculation='nscf',
prefix='hBN',
restart_mode='from_scratch'
pseudo_dir = '$PSEUDO_DIR'
outdir = './'
verbosity = 'high'
wf_collect=.true.
/
&system
ibrav = 4,
celldm(1) = 4.703675849
celldm(3) = 2.603711434
nat= 4,
ntyp= 2,
force_symmorphic=.true.
ecutwfc = 100,
nbnd = 120
/
&electrons
diago_david_ndim = 2
diago_full_acc=.true.
diago_thr_init=5.0e-6
mixing_mode = 'plain'
mixing_beta = 0.7
conv_thr = 1.0d-16
/
ATOMIC_SPECIES
B 10.81100 B_LDA_dojo.UPF
N 14.00674 N_LDA_dojo.UPF
ATOMIC_POSITIONS {crystal}
N 0.6666666670 0.3333333330 -0.250000000000
B 0.3333333330 0.6666666670 -0.250000000000
B 0.6666666670 0.3333333330 0.25000000000
N 0.3333333330 0.6666666670 0.25000000000
K_POINTS {automatic}
6 6 2 0 0 0

mpirun -np 4 pw.x -inp hbn.nscf > nscf.out

3. Input <code>hbn.dvscf</code>:

hbn_dvscf
&inputph
tr2_ph=1.0d-12,
verbosity='high'
prefix='hBN',
fildvscf = 'hBN-dvscf',
electron_phonon = 'dvscf',
fildyn='hBN.dyn',
epsil=.false.,
ldisp=.true.,
recover=.true.,
nq1=6,
nq2=6,
nq3=2
/

nohup mpirun -np 8 pw.x -inp hbn.dvscf > dvscf.out &

4. Input <code>bse.in</code> (we include 2 valence and 2 conduction bands):

optics # [R] Linear Response optical properties
bss # [R] BSE solver
bse # [R][BSE] Bethe Salpeter Equation.
dipoles # [R] Oscillator strenghts (or dipoles)
em1s
DIP_CPU= "1 8 1" # [PARALLEL] CPUs for each role
DIP_ROLEs= "k c v" # [PARALLEL] CPUs roles (k,c,v)
DIP_Threads=0 # [OPENMP/X] Number of threads for dipoles
X_and_IO_CPU= "1 1 1 8 1" # [PARALLEL] CPUs for each role
X_and_IO_ROLEs= "q g k c v" # [PARALLEL] CPUs roles (q,g,k,c,v)
X_and_IO_nCPU_LinAlg_INV=-1 # [PARALLEL] CPUs for Linear Algebra (if -1 it is automatically set)
X_Threads=0 # [OPENMP/X] Number of threads for response functions
BS_CPU= "8 1 1" # [PARALLEL] CPUs for each role
BS_ROLEs= "k eh t" # [PARALLEL] CPUs roles (k,eh,t)
BS_nCPU_LinAlg_INV=-1 # [PARALLEL] CPUs for Linear Algebra (if -1 it is automatically set)
BS_nCPU_LinAlg_DIAGO=-1 # [PARALLEL] CPUs for Linear Algebra (if -1 it is automatically set)
X_Threads=0 # [OPENMP/X] Number of threads for response functions
K_Threads=0 # [OPENMP/BSK] Number of threads for response functions
% QpntsRXs
1 | 14 | # [Xs] Transferred momenta
%
% BndsRnXs
1 | 120 | # [Xs] Polarization function bands
%
NGsBlkXs= 10 Ry # [Xs] Response block size
% LongDrXs
1.000000 | 1.000000 | 1.000000 | # [Xs] [cc] Electric Field
%
BSEmod= "resonant" # [BSE] resonant/retarded/coupling
BSKmod= "SEX" # [BSE] IP/Hartree/HF/ALDA/SEX/BSfxc
Lkind= "Lfull" # [BSE] Lbar (default) / full
BSSmod= "d" # [BSS] (h)aydock/(d)iagonalization/(s)lepc/(i)nversion/(t)ddft`
% DipBands
1 | 120 | # [DIP] Bands range for dipoles
%
DipApproach= "G-space v" # [DIP] [G-space v/R-space x/Covariant/Shifted grids]
DipComputed= "R V P" # [DIP] [default R P V; extra P2 Spin Orb]
BSENGexx= 30000 Ry # [BSK] Exchange components
#ALLGexx # [BSS] Force the use use all RL vectors for the exchange part
BSENGBlk= 9000 Ry # [BSK] Screened interaction block size [if -1 uses all the G-vectors of W(q,G,Gp)]
% KfnQP_E
1.25997 | 1.08816 | 1.12683 | # [EXTQP BSK BSS] E parameters (c/v) eV|adim|adim
%
% BSEQptR
 1 | 14 | # [BSK] Transferred momenta range
%
% BSEBands
 7 | 10 | # [BSK] Bands range
%
% BEnRange
0.50000 | 8.00000 | eV # [BSS] Energy range
%
% BDmRange
0.050000 | 0.050000 | eV # [BSS] Damping range
%
BEnSteps= 1000 # [BSS] Energy steps
% BLongDir
1.000000 | 1.000000 | 0.000000 | # [BSS] [cc] Electric Field
%
WRbsWF # [BSS] Write to disk excitonic the WFs

nohup mpirun -np 8 yambo -F bse.in -J bse_Lfull -C bse_Lfull &

Importantly, since we want to describe the phonon-assisted recombination process of an *optical* exciton (i.e., emitting a transverse photon), this time we also run an additional calculation at `Q=0` omitting the nonanalytic long-range Coulomb exchange. Make a second input <code>bse_Lbar.in</code> with the following changes:

Lkind= "Lbar" # [BSE] Lbar (default) / full
% BSEQptR
 1 | 1 | # [BSK] Transferred momenta range
%

4b. So now we make a second BSE run in a different directory specified by <code>-J</code>. Here, we also pass to yambo the directory of the previous run as it includes the important screening databases <code>ndb.em1s*</code> that we do not want to recompute from scratch.

mpirun -np 8 yambo -F bse_Lbar.in -J bse_Lbar,bse_Lfull -C bse_Lbar

5. Now we run <code>lelphc</code> with yambopy to get the el-ph matrix elements:

yambopy l2y -ph path/of/dvscf/hbn.dvscf -b 7 10 -par 4 2

6. And finally we generate the exciton-phonon input <code>excph.in</code> using <code>yambo_ph -excph o</code>. Now, we take a look at all the additional variables that we didn't check before, specifying also the details for luminescence the spectrum calculation.

excph # [R] Exction-phonon
ExcGkkp # [R][EXCPH] Exciton-Phonon Matrix Elelements
ExcPhOptics # [R][EXCPH] Exciton-Phonon Optics
BoseTemp=10.000000 Kn # Bosonic Temperature
EXCTemp= 10.000000 Kn # [EXCPH] Excitonic Temperature (for luminescence spectra)
% ELPhExcStates
1 | 4 | # [EXCPH] Incoming (external) exciton states
%
% ELPhExcSum
1 | 12 | # [EXCPH] Outgoing (virtual) exciton states
%
% ElPhModes
1 | 12 | # [ELPH] Phonon modes included
%
LoutPath= "./bse-L_full" # [EXCPH] Path of the outgoing L
FANdEtresh= 0.100000E-5 eV # [ELPH] Energy treshold for Fan denominator
EXCPHdEtresh= 0.100000E-5 eV # [ELPH] Energy treshold for exc-ph denominator
LDamping= 0.500000E-3 eV # [EXCPH] Damping of exc-ph self-energy
# These are the plot parameters, same as in other parts of yambo
% EnRngeXd
4.00000 | 5.00000 | eV # [Xd] Energy range
%
% DmRngeXd
0.00500000 | 0.00500000 | eV # [Xd] Damping range
%
ETStpsXd= 4000 # [Xd] Total Energy steps

Here <code>BoseTemp</code> and <code>EXCTemp</code> are the lattice and excitonic temperature, respectively.

Now we run the calculation with <code>yambo_ph</code>. Here, we read as <math>Q=0</math> excitons with <code>-J</code> the ones without the long-range Coulomb exchange:

yambo_ph -F excph.in -J excph,bse_Lbar -C excph

and we find our outputs in the <code>excph</code> directory.

NB: Step 6 could have been equivalently run in yambopy, limiting the use of the yambo code to just step 4. This latter option is more flexible, as it allows for a greater degree of control by the user. We are in the last stages of the development and it will be available soon.

=== Results ===

If we check the output directory from the step 6 calculation, we find the <code>o-excph.pl_bse_ph_ass</code> output files containing the luminescence spectra. We can plot them with gnuplot or any other tool:

gnuplot
> set xrange[4.2:5]
> p 'o-excph.pl_bse_ph_ass' u 1:2 w l lc rgb 'red' lw 3

[[File:Luminescence plot.png|500px|center]]

Here, the signal corresponds to a finite-momentum exciton that recombines with the help of several different phonon modes, both optical and acoustic. Each phonon mode whose coupling with the exciton is allowed can generate a peak, and the energy shifts of these peaks with respect to the initial exciton energy correspond to the phonon energies. This result is underconverged, but the main features are all there. In the plot, we show a more converged example using a 12x12x4 grid (all the other parameters being equal). These plots can be compared with Fig. 4(a) of reference <ref name="zanfrognini2023" />.

== References ==

<references>
<ref name="toyozawa2003" >[https://m.booksee.org/book/1121964?force_lang=en Optical processes in solids], Toyozawa, Yutaka, and Chris Oxlade. Cambridge University Press, (2003). </ref>
<ref name='lechifflart2023'>P. Lechifflart, F. Paleari, D. Sangalli, C. Attaccalite, ''First-principles study of luminescence in hexagonal boron nitride single layer: Exciton-phonon coupling and the role of substrate'',
[https://doi.org/10.1103/PhysRevMaterials.7.024006 Phys. Rev. M, '''7''' (2), 024006 (2023)]; [https://arxiv.org/abs/2212.10407 arXiv2212.1047]</ref>
<ref name='cannuccia2019'>E. Cannuccia, B. Monserrat and C. Attaccalite, ''Theory of phonon-assisted luminescence in solids: Application to hexagonal boron nitride'', [https://doi.org/10.1103/PhysRevB.99.081109 Phys. Rev. B '''99''', 081109(R) (2019)]; [https://arxiv.org/abs/1807.11797 arXiv1807.11797]</ref>
<ref name='paleari2019'>F. Paleari et al., ''Exciton-Phonon Coupling in the Ultraviolet Absorption and Emission Spectra of Bulk Hexagonal Boron Nitride'', [https://doi.org/10.1103/PhysRevLett.122.187401 Phys. Rev. Lett. '''122''', 187401 (2019)]; [https://arxiv.org/abs/1810.08976 arXiv1810.089776] </ref>
<ref name='chen2020'>''Exciton-Phonon Interaction and Relaxation Times from First Principles'',
Hsiao-Yi Chen, Davide Sangalli, and Marco Bernardi, [https://doi.org/10.1103/PhysRevLett.125.107401 Phys. Rev. Lett. '''125''', 107401 (2020)]; [https://arxiv.org/abs/2002.08913 arXiv 2002.08913 (2020)]</ref>
<ref name="lechifflart2023_PhD">[https://www.yambo-code.eu/wiki/images/5/54/These_final.pdf Exciton-phonon coupling and phonon-assisted luminescence in hexagonal Boron Nitride nanostructures], PhD Thesis, Pierre Lechifflart (2023)</ref>
<ref name='paleari2019_PhD'>F. Paleari, ''First-principles approaches to the description of indirect absorption and luminescence spectroscopy: exciton-phonon coupling in hexagonal boron nitride'', [https://wwwen.uni.lu/research/fstm/dphyms/people/fulvio_paleari PhD thesis, University of Luxembourg (2019)]</ref>
<ref name='zanfrognini2023'>[https://arxiv.org/abs/2305.17554 Distinguishing different stackings in layered materials via luminescence spectroscopy], M. Zanfrognini et al. Phys. Rev. Lett. '''131''', 206902 (2023) </ref>
<ref name='marini2024'>G. Marini, M. Calandra, P. Cudazzo, ''Optical absorption and photoluminescence of single layer boron nitride from a first principles cumulant approach'', [https://doi.org/10.1021/acs.nanolett.4c00669 Nano Lett., '''24''', 20, 6017 (2024)]; [https://arxiv.org/abs/2402.03826 arXiv 2402.03826 (2024)]</ref>
<ref name='antonius2017'>G. Antonius, S. G. Louie, ''Theory of exciton-phonon coupling'', [https://doi.org/10.1103/PhysRevB.105.085111 Phys. Rev. B, '''105''', 085111 (2022)]; [https://arxiv.org/abs/1705.04245 arXiv1705.04245 (2017)]</ref>
<ref name='paleari2022'>[https://arxiv.org/abs/2205.02783 Exciton-phonon interaction calls for a revision of the “exciton” concept], F. Paleari, A. Marini, Phys. Rev. B, '''106''', 125403 (2022)</ref>
<ref name='cudazzo2020'> P. Cudazzo, ''First-principles description of the exciton-phonon interaction: A cumulant approach'', [https://doi.org/10.1103/PhysRevB.102.045136 Phys. Rev. B, '''102''', 045136 (2020)]; [https://orbilu.uni.lu/bitstream/10993/44769/1/main.pdf Open access pdf from Luxembourg University]</ref>
<ref name='chan2023'>Y-h Chan, J. B. Haber, M. H. Naik, J. B. Neaton, D. Y. Qiu, F. H. da Jornada, S. G. Louie, ''Exciton Lifetime and Optical Line Width Profile via Exciton–Phonon Interactions: Theory and First-Principles Calculations for Monolayer MoS2'', [https://doi.org/10.1021/acs.nanolett.3c00732 Nano Lett., '''23''', 9 (2023)]; [https://arxiv.org/abs/2212.08451 arXiv 2212.08451 (2023)]</ref>
<ref name='murali2025'>M. Nalabothula, S. Reichardt, L. Wirtz, ''Origin of Interlayer Exciton–Phonon Coupling in 2D Heterostructures'', [https://doi.org/10.1021/acs.nanolett.5c00355 Nano Lett., '''25''', 15 (2025)], [https://arxiv.org/abs/2407.16111 arXiv 2407.16111 (2025)]</ref>
</references>

Exciton-phonon coupling and luminescence

2025-10-06T11:48:31Z

Attacc: /* Step 5: run a BSE calculation */

[[File:Tdgw-phonon-usc-01-1024x829.jpg| 400px | right]]

In this advanced tutorial, we will calculate exciton-phonon interactions from first principles by interfacing DFPT (for phonon calculations) and BSE (for exciton calculations).

The DFTP calculations are run with Quantum ESPRESSO, while the many-body GW-BSE calculations are run with Yambo. Finally, the exciton-phonon interaction will be obtained by combining and postprocessing the databases computed in the two previous runs. The great advantage of this workflow is that the calculations can be run in the irreducible Brillouin zones both for the electronic momenta (<math>k</math>) and the transfer momenta (<math>Q</math>, <math>q</math>) of excitons and phonons, thus speeding up considerably the jobs while reducing the IO and memory load.

We will first compute the exciton-phonon coupling matrix elements: these are the building blocks needed to construct experimental observables such as phonon-assisted optical spectra (such as luminescence), Raman spectra and exciton lifetimes. We will do this in the case of monolayer MoS2, a 2D system with large spin-orbit interaction.

As an example of application, we will consider the case of phonon-assisted luminescence. We will do this in the case of bulk hBN, a layered indirect insulator with strong electron-phonon coupling.

'''Note:''' this tutorial will be updated when new exc-ph tools become available in Yambopy (including full-python postprocessing, Raman spectra, interpolated lifetimes, etc).

== Requirements ==

This is an advanced topic: we assume that you already know something about the theory<ref name="toyozawa2003" /><ref name="antonius2017" /><ref name="cudazzo2020" /><ref name="paleari2019_PhD" /><ref name="paleari2022" /><ref name="lechifflart2023_PhD" /> and applications<ref name="paleari2019" /><ref name="cannuccia2019" /><ref name="chen2020" /><ref name="zanfrognini2023" /><ref name="lechifflart2023" /><ref name="chan2023" /><ref name="marini2024" /><ref name="murali2025" /> of exciton-phonon physics.

Also, we assume that you already know how to run both a basic '''Yambo''' GW-BSE calculation and a DFPT phonon calculation with '''Quantum ESPRESSO'''.

Besides the QE executables <code>pw.x</code> and <code>ph.x</code>, we also use the yambo phonon-specific executable <code>yambo_ph</code> and the python utility '''Yambopy'''. The auxiliary code '''LetzElPhC''' (executable <code>lelphc</code>) will be used to obtain the electron-phonon matrix elements by reading the same electronic wavefunctions used by Yambo (and stored in the <code>SAVE</code> directory), while also making full use of crystal symmetries. [https://gitlab.com/lumen-code/LetzElPhC LetzElPhC] will be run by Yambopy, but it must nonetheless be installed. Finally, the exciton-phonon properties can be computed either using <code>yambo_ph</code> or using Yambopy itself.

[[File:Workflow scheme.png|800px|center]]

== Step 0: Pseudopotentials, equilibrium structure and convergence ==

In a real calculation, it is important to ensure that both the pseudopotential and the lattice parameters that we are using are compatible and perform well for the electronic excited states and for the lattice vibrations simultaneously. Furthermore, you have to make sure that the wave function cutoff <code>ecutwfc</code> is converged with respect to the DFPT step and not just to the DFT one. This is in addition to the other customary convergence tests for DFT, DFPT, GW and BSE calculations.

This is often the most time-demanding step when starting on a new system.

For the sake of this tutorial, we assume that we have already done all these tests and we are starting the final workflow to get the exciton-phonon properties.

== Step 1: scf calculation ==

First of all, we run a standard scf calculation with <code>pw.x</code> for Yambo. We stick with non-symmorphic symmetries. At the end, we will have the QE <code>save</code> directory.

This is the input <code>mos2.scf</code>:

&control
wf_collect = .true.,
calculation = "scf",
verbosity = 'high',
pseudo_dir = '$PSEUDO_DIR',
prefix = "mos2",
outdir = '.',
/&end
&system
ecutwfc = 100.0,
occupations = 'fixed',
ibrav = 4,
celldm(1) = 5.9000811881,
celldm(3) = 6.7795677253,
nat = 3,
ntyp = 2,
lspinorb = .true.
noncolin = .true.
assume_isolated = '2D'
force_symmorphic = .true.
/&end
&electrons
electron_maxstep = 200,
mixing_beta = 0.7,
conv_thr = 1.d-08,
/&end
ATOMIC_SPECIES
Mo 95.940 Mo_ONCV_PBE_FR-1.0.upf
S 32.065 S_ONCV_PBE_FR-1.1.upf
ATOMIC_POSITIONS { crystal }
Mo 0.333333333 0.666666667 0.000000000
S 0.666666667 0.333333333 0.073413577
S 0.666666667 0.333333333 -0.073413577
K_POINTS { automatic }
6 6 1 0 0 0

Here we are using full relativistic pseudopotentials from the SG-15 database.

We can run it on our machine (for example using 4 MPI tasks) as:

mpirun -np 4 pw.x -inp mos2.scf > scf.out

== Step 2: nscf calculation for Yambo ==

Copy the QE <code>save</code> directory from the scf calculation and run the nscf calculation for any number of empty states, with the correct <code>k</code>-grid we want to use in Yambo. Here we are using a badly underconverged grid of 6x6x1.

This reciprocal-space grid will also match the momentum transfer <code>q</code> grid on which excitons and phonons will be defined!

The electronic wavefunctions computed at this step and stored in the new nscf <code>save</code> directory will be used both by Yambo and by the electron-phonon code: this is important because using different sets of wavefunctions would lead to a phase mismatch issue in the exciton-phonon matrix elements.

The nscf input <code>mos2.nscf</code> is
&control
wf_collect = .true.,
calculation = "nscf",
verbosity = 'high',
pseudo_dir = '$PSEUDO_DIR',
prefix = "mos2",
outdir = '.',
/&end
&system
ecutwfc = 100.0,
occupations = 'fixed',
ibrav = 4,
celldm(1) = 5.9000811881,
celldm(3) = 6.7795677253,
nat = 3,
ntyp = 2,
lspinorb = .true.
noncolin = .true.
nbnd = 250
assume_isolated = '2D'
force_symmorphic = .true.
/&end
&electrons
electron_maxstep = 200,
mixing_beta = 0.7,
conv_thr = 1.d-08,
/&end
ATOMIC_SPECIES
Mo 95.940 Mo_ONCV_PBE_FR-1.0.upf
S 32.065 S_ONCV_PBE_FR-1.1.upf
ATOMIC_POSITIONS { crystal }
Mo 0.333333333 0.666666667 0.000000000
S 0.666666667 0.333333333 0.073413577
S 0.666666667 0.333333333 -0.073413577
K_POINTS { automatic }
6 6 1 0 0 0

Again, we run the calculation

mpirun -np 4 pw.x -inp mos2.nscf > nscf.out

== Step 3: dvscf phonon calculation ==

Now we run the phonon calculation.

Copy the <code>save</code> directory from the '''scf''' calculation and run <code>ph.x</code> for a dvscf calculation with a standard <code>q</code>-grid matching the <code>k</code>-grid we wanna use in Yambo.

At the end, we will have the <code>_ph0</code> directory containing the variation of the self-consistent potential, <math>\Delta V_{SCF}(q)</math>, and the <code>*.dyn</code> files with the phonon energies and eigenvectors.

NB: one could further refine the phonon energies by enforcing the acoustic sum rule, including non-analytic long-range contributions, interpolating to finer grids... all of this can be done within Quantum ESPRESSO and will not be covered in this version of the tutorial.

The input is <code>mos2.dvscf</code>:

mos2_dvscf
&inputph
tr2_ph=1.0d-12,
verbosity='high'
prefix='mos2',
fildvscf = 'mos2-dvscf',
electron_phonon = 'dvscf',
fildyn='mos2.dyn',
epsil=.false.,
ldisp=.true.,
recover=.true.,
nq1=6,
nq2=6,
nq3=1
/

And now we run as

nohup mpirun -np 8 ph.x -inp mos2.dvscf > dvscf.out &

This time we use nohup and more processes because this calculation may take some time. It is a good idea to set <code>recover=.true.</code> as in a real calculation you will easily breach walltime, and in this way you can safely restart.

== Step 4: create Yambo <code>SAVE</code> directory ==

This is just the standard Yambo initialization: run

p2y

and then

yambo

in the '''nscf''' <code>save</code> folder and then move the newly generated <code>SAVE</code> directory to a convenient place.

== Step 5: run a BSE calculation ==

Now we switch from QE to Yambo. Here, we forgo the GW step for simplicity (we can use a scissor operator to open the band gap).

This calculation has a couple of differences with respect to a standard BSE calculation for optical absorption. We can look at the input file <code>bse.in</code>:

# Runlevels
optics # [R OPT] Optics
rim_cut # [R RIM CUT] Coulomb potential
bss # [R BSS] Bethe Salpeter Equation solver
em1s # [R Xs] Static Inverse Dielectric Matrix
bse # [R BSE] Bethe Salpeter Equation.
bsk # [R BSK] Bethe Salpeter Equation kernel
# RIM and cutoff settings
RandQpts=1000000 # [RIM] Number of random q-points in the BZ
RandGvec= 100 RL # [RIM] Coulomb interaction RS components
CUTGeo= "slab z" # [CUT] Coulomb Cutoff geometry: box/cylinder/sphere X/Y/Z/XY..
# Static screening
X_and_IO_CPU= "1 1 4 2 1" # [PARALLEL] CPUs for each role
X_and_IO_ROLEs= "q g k c v" # [PARALLEL] CPUs roles (q,g,k,c,v)
X_and_IO_nCPU_LinAlg_INV=-1 # [PARALLEL] CPUs for Linear Algebra (if -1 it is automatically set)
Chimod= "hartree" # [X] IP/Hartree/ALDA/LRC/BSfxc
% QpntsRXs
1 | 7 | # [Xs] Transferred momenta
%
% BndsRnXs
1 | 200 | # [Xs] Polarization function bands
%
% LongDrXs
1.000000 | 1.000000 | 1.000000 | # [Xs] [cc] Electric Field
%
NGsBlkXs= 8 Ry # [Xs] Response block size
# BSE
BS_CPU= "4.1.2" # [PARALLEL] CPUs for each role
BS_ROLEs= "k.eh.t" # [PARALLEL] CPUs roles (k,eh,t)
BS_nCPU_diago=4 # [PARALLEL] CPUs for matrix diagonalization
BSEmod= "causal" # [BSE] resonant/causal/coupling
BSKmod= "SEX" # [BSE] IP/Hartree/HF/ALDA/SEX/BSfxc
BSSmod= "d" # [BSS] (h)aydock/(d)iagonalization/(i)nversion/(t)ddft`
BSENGexx= 40000 mRy # [BSK] Exchange components
ALLGexx # [BSS] Force the use use all RL vectors for the exchange part
BSENGBlk= 8000 mRy # [BSK] Screened interaction block size
Lkind="full" #[BSE,X] bar(default)/full/tilde
% KfnQP_E
1.000000 | 1.000000 | 1.000000 | # [EXTQP BSK BSS] E parameters (c/v) eV|adim|adim
%
% BEnRange
0.00000 | 4.00000 | eV # [BSS] Energy range
%
% BDmRange
0.05000 | 0.05000 | eV # [BSS] Damping range
%
BEnSteps= 2000 # [BSS] Energy steps
% BLongDir
1.000000 | 0.000000 | 0.000000 | # [BSS] [cc] Electric Field
%
% BSEQptR
 1 | 7 | # [BSK] Transferred momenta range
%
% BSEBands
25 | 28 | # [BSK] Bands range
%
WRbsWF # [BSS] Write to disk excitonic the FWs

This file was generated using the command: <code> yambo -X s -o b -k sex -y d -r</code> 

First of all, we compute the excitons for all the momenta in the irreducible Brillouin zone for our discrete grid via the <code>BSEQptR</code> variable. This will be a '''finite-momentum''' BSE calculation, analogous to the phonon one.

Second, we change the variable <code>Lkind</code> from <code>bar</code> to <code>full</code>. In Yambo, <code>Lkind="bar"</code>, which is the default for optical absorption, means that we are computing the excitonic response function without the long-range component of the exchange interaction. This cannot be used when computing the exciton momentum dependence, where the long-range exchange interaction can play a role, therefore we have to include it with <code>Lkind="full"</code>. This allows for the calculation of the excitonic longitudinal-transverse splitting (in 3D systems) as well.

We can now run the code:

nohup mpirun -np 8 yambo -F bse.in -J bse_Lfull -C bse_Lfull &

At the end of the calculation, we have obtained the <code>ndb.BS_diago_Q*</code> databases inside the directory <code>bse_Lfull</code>. They contain information on the exciton energies and wavefunctions at each momentum. Do not forget to check the report and logs of your calculation in the same directory to make sure that the code is doing what you want.

== Step 6: obtain the electron-phonon matrix elements ==

We have finished the heavy simulations. Now it's time for the postprocessing. The first order of business is the reconstruction of the electron-phonon coupling matrix elements from the dvscf results and the electronic wavefunctions.

In order to do this, we will run the <code>lelphc</code> executable of the '''LetzElPhC''' code. We will run via command line using yambopy, although it will be instructive to have look at the <code>lelphc</code> input files later.

We run in the same directory where the Yambo <code>SAVE</code> is (remember than you can also virtually move it with a symbolic link).

Type:

yambopy l2y

to see the help for the calculation. For example, if we want to do a serial run of LetzElPhC for bands from <math>n_i</math> to <math>n_f</math>, we should type:

yambopy l2y -ph path/of/ph_input.in -b n_i n_f

Here <math>n_i</math> and <math>n_f</math> are integers representing the initial and final band indices.

These should coincide with those used for the Bethe-Salpeter kernel, i.e. those specified in the <code>BSEBands</code> variable of the BSE input file (this is not strictly necessary, but certainly efficient since these calculations use a lot of disk space).

For our system, we want to do a parallel calculation with 4 qpools and 2 kpools. In addition, we want to explicitly specify the path of the <code>lelphc</code> executable and avoid automatically deleting the LetzElPhC data. So we type:

yambopy l2y -ph path/of/dvscf/mos2.dvscf -b 25 28 -par 4 2 -lelphc path/to/lelphc_exe --debug

At the end, check the <code>SAVE</code>

ls SAVE/ndb.elph_gkkp*

to see that it has created the Yambo-compatible electron-phonon databases.

If you saved the <code>lelphc.in</code> input file, you can inspect it:

# LetzElPhC input for yambo generated by yambopy
nqpool = 2
nkpool = 4
start_bnd = 25
end_bnd = 28
save_dir = ./SAVE
kernel = dfpt
ph_save_dir = dvscf/ph_save
convention = yambo

You can also run it as it is, but the code will generate the database <code>ndb.elph</code>. In order to convert it to the <code>ndb.elph_gkkp*</code> databases of Yambo, you still need a couple of lines of python using the Yambopy class <code>ConvertElectronPhononDB</code> in <code>yambopy/letzelph_interface/lelph2y.py</code>.

Notice the variable <code>convention=yambo</code>: what does it mean? At variance with QE and many other codes, Yambo uses the "backward" momentum transfer convention for electronic scatterings. That is, an electronic transition goes from band <math>n</math> and momentum <math>k-q</math> to band <math>m</math> and momentum <math>k</math>. In the "forward" momentum transfer convention (the more standard one), the transitions go from <math>nk</math> to <math>mk+q</math>. Therefore, this variable ensures that the electron-phonon coupling matrix elements are computed as <math>\langle mk|dV|nk-q\rangle</math>. This will have consequences also in the formulation of the ''exciton''-phonon coupling matrix element.

== Step 7: Obtain the exciton-phonon coupling ==

Now, we can finally access our basic building block for exciton-phonon physics. This could be done entirely in python (using '''Yambopy'''), or by running '''Yambo'''. In this version of the tutorial we present the latter case.

Our objective is obtaining the following quantity:

<math>\mathcal{G}^\mu_{\alpha\lambda}(0,q)=\sum_{vv^\prime c k} A^{\alpha, *}_{cv^\prime} (k, q) g_{vv^\prime}^\mu (k,q) A^{\lambda}_{cv}(k,q) - \sum_{cc^\prime vk} A^{\alpha, *}_{c^\prime v} (k+q, q) g_{c^\prime c}^\mu (k+q,q) A^{\lambda}_{cv}(k,q)</math>

Here, <math>A^{\lambda}_{cv}(k,q)</math> are the exciton coefficients extracted from the eigenvector of the two-particles Hamiltonian during the BSE calculation in step 5, while <math>g_{nm}^\mu (k,q)</math> are the electron-phonon coupling matrix elements obtained in step 6. As you can see, the exciton <math>\lambda</math> undergoes phonon-mediated scattering to state <math>\alpha</math> via phonon mode <math>\mu</math>. The scattering can happen for the hole (valence, <math>v</math>) or for the electron (conduction, <math>c</math>).

NB:

(1) This is written in the "backward" momentum transfer convention used by Yambo. The momentum dependence is different in the "forward" transfer convention.

(2) For simplicity, this is written for zero initial exciton momentum. This means that one of the two states involved in the phonon-mediated scattering process will be in the optical limit (and possibly an optically generated exciton), while the other state can have any momentum: this momentum will be the same as the phonon one. This matrix element can be used to describe phonon-assisted absorption and emission spectra.

We have to write a new yambo input, that we can call <code>excph.in</code>, for this. You can copy (and adapt) the one below, or you can generate one by running from the command line:

yambo_ph -excph o

This generates an input to compute luminescence ("o" is for "optics"). The variables that we are interested in are:

excph # [R] Exction-phonon
ExcGkkp # [R][EXCPH] Exciton-Phonon Matrix Elelements
% ELPhExcStates
1 | 4 | # [EXCPH] Incoming (external) exciton states
%
% ELPhExcSum
1 | 12 | # [EXCPH] Outgoing (virtual) exciton states
%
LoutPath= "./bse_Lfull" # [EXCPH] Path of the outgoing L
% ElPhModes
1 | 9 | # [ELPH] Phonon modes included
%

In this input, we have to select the initial exciton states <math>\lambda</math> with <code>ELPhExcStates</code>, the final exciton states <math>\alpha</math> with <code>ELPhExcSum</code> and the phonon modes <math>\mu</math> with <code>ElPhModes</code>. Here we consider the first four states at <math>Q=0</math> (corresponding to just two excitons because they are both doubly degenerate -- do not break degeneracies when selecting states!) and the first twelve states at each finite-<math>q</math> point. We also include all the nine phonon modes of monolayer MoS2.

What about <code>LoutPath</code>? This variable controls the directory where the databases for the final-state excitons <math>\alpha</math> is located, which can be different from the directory with the initial-state excitons <math>\lambda</math> read as usual with the <code>-J</code> option when running the code. This makes it possible to compute the coupling between different exciton kinds. However, for our tutorial, we stick with the previously computed <code>Lfull</code> in both cases.

When we are satisfied with the input, we run the code using <code>yambo_ph</code>:

yambo_ph -F excph.in -J excph,bse_Lfull -C excph

If you check the output, you should find the <code>ndb.excph*</code> databases in the <code>excph</code> directory.

=== Analysis of the couplings ===

It is a good idea to have a look at what we computed up to now in order to make sure nothing has gone wrong.

It is not easy to know what to expect (apart from symmetry and gauge compliance of the matrix elements), but one can work out the exciton-phonon selection rules in advance, check that the magnitude is reasonable, etc.

It is also not easy to meaningfully plot this quantity. We have to make sure that we are not breaking degenerate states, otherwise the plots will not be invariant.

First of all, we have to know our system: in monolayer MoS2, the first four excitons are all doubly degenerate. The first exciton responsible for a bright peak in the absorption spectrum (the '''A''' peak), is the second state, corresponding to state indices <code>(3,4)</code> in fortran indexing or <code>(2,3)</code> in python indexing.

All these information can be obtained by analyzing the BSE results (this stuff is explained in the BSE tutorials) and by knowledge of the system or class of systems from the literature.

Thus, a good quantity to plot may be the norm of the matrix elements, summed over the degenerate subspace of exciton A, for a certain number of scattered final states mediated by certain phonon modes:

<math>F_A(q)= \sqrt{ \sum_{\alpha \in A,\lambda,\mu} |\mathcal{G}_{\alpha\lambda}^\mu (0,q)|^2 }</math>

In order to do this, we create a python script <code>analyse_excph.py</code> in which we first load the excph dabatases using the <code>YamboExcitonPhononDB</code> from yambopy.
You can find this script in the yambopy directory, in <code>tutorials/exciton-phonon</code>.
First, we select the exciton and phonon states to be included in <code>F_A</code>, together with the path of databases and plot details:

# Exciton in states
exc_in = [2,3] # A: 2,3 -- B: 6,7
exc_out = [0,1,2,3] # first 4 states (dispersion of triplet state and A)
ph_in = 'all'

# Paths of databases
ns_db1 =f'{path}/SAVE/ns.db1'
ndb_exc=f'{path}/excph'

...

Then, we load the data:

# Read lattice and k-space info
ylat = YamboLatticeDB.from_db_file(filename=ns_db1),Expand=True)
print(ylat)

# Read exc-ph databases
X = YamboExcitonPhononDB(ylat,save_excph=ndb_exc)
print(X)

The quantity <math>F_A(q)</math> is defined inside the plotting function as

G_squared = excph.excph_sq
G2plt = np.zeros(len(G_squared))

if exc_in == 'all': exc_in = range(G_squared.shape[2])
if exc_out == 'all': exc_out = range(G_squared.shape[3])
if ph_in == 'all': ph_in = range(G_squared.shape[1])

G_squared = G_squared[:, ph_in, :, :].sum(axis=(1))
G_squared = G_squared[:, exc_in, :].sum(axis=(1))
G_squared = G_squared[:, exc_out].sum(axis=(1))

F_q = np.sqrt( G_squared )*ha2ev # Switch from Ha to eV

And finally, we have to make a plotting function. For this tutorial we will use the default scatterplot provided by <code>YamboExcitonPhononDB</code>

excph.plot_excph(F_q,plt_cbar=plt_cbar,**kwargs)
...

You can get more experience on using Yambopy for these kinds of visualization by following the [https://wiki.yambo-code.eu/wiki/index.php?title=First_steps_in_Yambopy Yambopy tutorials]. In fact, remember that this scripts and all the other yambopy tutorial scripts are just suggestions, not source code written in stone: if you know <code>numpy</code> and <code>matplotlib</code> you can do your own analysis and your own plots, you just need to import the required Yambopy modules to load the data.

In our case, the resulting plot is the following.

[[File:1L MoS2 ExcPh.png|500px|center]]

This can be checked against Fig. 2(d) of reference <ref name="chan2023" />, although you have to keep in mind that our results are badly undersampled in terms of the reciprocal-space grid, as can be easily seen, and the quantity plotted is not exactly the same. However, the main features are already there since they are dictated mostly by crystal symmetries.

Now that we have the exciton-phonon matrix elements, we can use them to build several kinds of observables. Below, we give an example related to phonon-assisted luminescence, but we may update this tutorial in the future to include more cases.

== Step 8: Compute phonon-assisted luminescence ==

[[File:Luminescence scheme.png|250px|right]]

We want to compute the experimental optical signature due to the phonon-assisted recombination of an exciton (as sketched in the figure).

The signal from the phonon replicas can be modeled as a second-order scattering process involving one phonon and one photon:

<math>I^{(1)}_{PL}(\omega;T) \propto \frac{1}{N_q}\sum_{ s \mu \beta q} \left|\sum_\lambda\frac{D_\lambda \mathcal{G}^{\mu q}_{\alpha q,\lambda}}{E_{\alpha q}-E_\lambda -s\Omega_{\mu q}} \right|^2 N_{\alpha q}(T_{exc}) F^s_{\mu q}(T)\delta(\omega - \left[E_{\alpha q}-s\Omega_{\mu q}\right])</math>

In this equation, the oscillator strength of the peak is given by the exciton-phonon coupling matrix elements <math>\mathcal{G}</math> multiplied by the exciton dipoles <math>D</math> (they are called "residuals" in Yambo). Here <math>E_\lambda</math> and <math>E_{\alpha q}</math> are the energies of the optical and finite-momentum excitons, respectively, while <math>\Omega_{\mu q}</math> are the phonon energies.

The occupation function <math>F</math> is <math>F^s_{\mu q}(T)=n_{\mu q}(T)+\frac{1+s}{2}</math>. Here, <math>n(T)</math> is the temperature-dependent phonon Bose-Einstein occupation function. As it can be seen, <math>s=1</math> corresponds to processes of phonon ''emission'' (<math>\propto n(T)+1</math>), while <math>s=-1</math> corresponds to processes of phonon ''absorption'' (<math>\propto n(T)</math>). Therefore, <math>I^{(1)}_{PL}(\omega;T)</math> describes ''light'' emission by recombining excitons mediated by either ''phonon'' absorption or emission.

The quantity <math> N_{\alpha q}(T_{exc})</math> is the exciton occupation function. Luminescence is technically an out-of-equilibrium process, but we can assume that for very low density of excitations and in steady-state conditions, the exciton population can be approximately described by an equilibrium distribution evaluated at an effective temperature. Here, we use the Boltzmann distribution. Experimentally, <math>T_{exc}</math> tends to coincide with the lattice temperature <math>T</math> more or less above 100 K, while at very low temperature (< 10 K), <math>T_{exc}</math> may vary between 10-50 K. It goes without saying that this needs to carefully be checked in your realistic calculations.

=== Running the jobs ===

In order to study luminescence in a paradigmatic system, we switch to bulk hexagonal boron nitride and we repeat the workflow. As you can easily see, one can think about automatizing the execution of all these calculations via scripting or more advanced tools. However, in the case of very large simulations (memory-limited or disk-space limited) or for systems whose electronic and lattice properties are fragile with respect to tiny calculation details, one must be very careful and run many basic tests.

Fortunately, we are running a fast underconverged example. We use LDA pseudopotentials from the pseudo-dojo library and the following are the calculations steps.

1. Input <code>hbn.scf</code>:

&control
calculation='scf',
prefix='hBN',
restart_mode='from_scratch'
pseudo_dir = '$PSEUDO_DIR',
outdir = './tmp'
verbosity = 'high'
wf_collect=.true.
/
&system
ibrav = 4,
celldm(1) = 4.703675849
celldm(3) = 2.603711434
nat= 4,
ntyp= 2,
force_symmorphic=.true.
ecutwfc = 100,
/
&electrons
diago_david_ndim = 2
diago_full_acc=.true.
diago_thr_init=5.0e-6
mixing_mode = 'plain'
mixing_beta = 0.7
conv_thr = 1.0d-16
/
ATOMIC_SPECIES
B 10.81100 B_LDA_dojo.UPF
N 14.00674 N_LDA_dojo.UPF
ATOMIC_POSITIONS {crystal}
N 0.6666666670 0.3333333330 -0.250000000000
B 0.3333333330 0.6666666670 -0.250000000000
B 0.6666666670 0.3333333330 0.25000000000
N 0.3333333330 0.6666666670 0.25000000000
K_POINTS {automatic}
6 6 2 0 0 0

mpirun -np 4 pw.x -inp hbn.scf > scf.out

2. Input <code>hbn.nscf</code>:

&control
calculation='nscf',
prefix='hBN',
restart_mode='from_scratch'
pseudo_dir = '$PSEUDO_DIR'
outdir = './'
verbosity = 'high'
wf_collect=.true.
/
&system
ibrav = 4,
celldm(1) = 4.703675849
celldm(3) = 2.603711434
nat= 4,
ntyp= 2,
force_symmorphic=.true.
ecutwfc = 100,
nbnd = 120
/
&electrons
diago_david_ndim = 2
diago_full_acc=.true.
diago_thr_init=5.0e-6
mixing_mode = 'plain'
mixing_beta = 0.7
conv_thr = 1.0d-16
/
ATOMIC_SPECIES
B 10.81100 B_LDA_dojo.UPF
N 14.00674 N_LDA_dojo.UPF
ATOMIC_POSITIONS {crystal}
N 0.6666666670 0.3333333330 -0.250000000000
B 0.3333333330 0.6666666670 -0.250000000000
B 0.6666666670 0.3333333330 0.25000000000
N 0.3333333330 0.6666666670 0.25000000000
K_POINTS {automatic}
6 6 2 0 0 0

mpirun -np 4 pw.x -inp hbn.nscf > nscf.out

3. Input <code>hbn.dvscf</code>:

hbn_dvscf
&inputph
tr2_ph=1.0d-12,
verbosity='high'
prefix='hBN',
fildvscf = 'hBN-dvscf',
electron_phonon = 'dvscf',
fildyn='hBN.dyn',
epsil=.false.,
ldisp=.true.,
recover=.true.,
nq1=6,
nq2=6,
nq3=2
/

nohup mpirun -np 8 pw.x -inp hbn.dvscf > dvscf.out &

4. Input <code>bse.in</code> (we include 2 valence and 2 conduction bands):

optics # [R] Linear Response optical properties
bss # [R] BSE solver
bse # [R][BSE] Bethe Salpeter Equation.
dipoles # [R] Oscillator strenghts (or dipoles)
em1s
DIP_CPU= "1 8 1" # [PARALLEL] CPUs for each role
DIP_ROLEs= "k c v" # [PARALLEL] CPUs roles (k,c,v)
DIP_Threads=0 # [OPENMP/X] Number of threads for dipoles
X_and_IO_CPU= "1 1 1 8 1" # [PARALLEL] CPUs for each role
X_and_IO_ROLEs= "q g k c v" # [PARALLEL] CPUs roles (q,g,k,c,v)
X_and_IO_nCPU_LinAlg_INV=-1 # [PARALLEL] CPUs for Linear Algebra (if -1 it is automatically set)
X_Threads=0 # [OPENMP/X] Number of threads for response functions
BS_CPU= "8 1 1" # [PARALLEL] CPUs for each role
BS_ROLEs= "k eh t" # [PARALLEL] CPUs roles (k,eh,t)
BS_nCPU_LinAlg_INV=-1 # [PARALLEL] CPUs for Linear Algebra (if -1 it is automatically set)
BS_nCPU_LinAlg_DIAGO=-1 # [PARALLEL] CPUs for Linear Algebra (if -1 it is automatically set)
X_Threads=0 # [OPENMP/X] Number of threads for response functions
K_Threads=0 # [OPENMP/BSK] Number of threads for response functions
% QpntsRXs
1 | 14 | # [Xs] Transferred momenta
%
% BndsRnXs
1 | 120 | # [Xs] Polarization function bands
%
NGsBlkXs= 10 Ry # [Xs] Response block size
% LongDrXs
1.000000 | 1.000000 | 1.000000 | # [Xs] [cc] Electric Field
%
BSEmod= "resonant" # [BSE] resonant/retarded/coupling
BSKmod= "SEX" # [BSE] IP/Hartree/HF/ALDA/SEX/BSfxc
Lkind= "Lfull" # [BSE] Lbar (default) / full
BSSmod= "d" # [BSS] (h)aydock/(d)iagonalization/(s)lepc/(i)nversion/(t)ddft`
% DipBands
1 | 120 | # [DIP] Bands range for dipoles
%
DipApproach= "G-space v" # [DIP] [G-space v/R-space x/Covariant/Shifted grids]
DipComputed= "R V P" # [DIP] [default R P V; extra P2 Spin Orb]
BSENGexx= 30000 Ry # [BSK] Exchange components
#ALLGexx # [BSS] Force the use use all RL vectors for the exchange part
BSENGBlk= 9000 Ry # [BSK] Screened interaction block size [if -1 uses all the G-vectors of W(q,G,Gp)]
% KfnQP_E
1.25997 | 1.08816 | 1.12683 | # [EXTQP BSK BSS] E parameters (c/v) eV|adim|adim
%
% BSEQptR
 1 | 14 | # [BSK] Transferred momenta range
%
% BSEBands
 7 | 10 | # [BSK] Bands range
%
% BEnRange
0.50000 | 8.00000 | eV # [BSS] Energy range
%
% BDmRange
0.050000 | 0.050000 | eV # [BSS] Damping range
%
BEnSteps= 1000 # [BSS] Energy steps
% BLongDir
1.000000 | 1.000000 | 0.000000 | # [BSS] [cc] Electric Field
%
WRbsWF # [BSS] Write to disk excitonic the WFs

nohup mpirun -np 8 yambo -F bse.in -J bse_Lfull -C bse_Lfull &

Importantly, since we want to describe the phonon-assisted recombination process of an *optical* exciton (i.e., emitting a transverse photon), this time we also run an additional calculation at `Q=0` omitting the nonanalytic long-range Coulomb exchange. Make a second input <code>bse_Lbar.in</code> with the following changes:

Lkind= "Lbar" # [BSE] Lbar (default) / full
% BSEQptR
 1 | 1 | # [BSK] Transferred momenta range
%

4b. So now we make a second BSE run in a different directory specified by <code>-J</code>. Here, we also pass to yambo the directory of the previous run as it includes the important screening databases <code>ndb.em1s*</code> that we do not want to recompute from scratch.

mpirun -np 8 yambo -F bse_Lbar.in -J bse_Lbar,bse_Lfull -C bse_Lbar

5. Now we run <code>lelphc</code> with yambopy to get the el-ph matrix elements:

yambopy l2y -ph path/of/dvscf/hbn.dvscf -b 7 10 -par 4 2

6. And finally we generate the exciton-phonon input <code>excph.in</code> using <code>yambo_ph -excph o</code>. Now, we take a look at all the additional variables that we didn't check before, specifying also the details for luminescence the spectrum calculation.

excph # [R] Exction-phonon
ExcGkkp # [R][EXCPH] Exciton-Phonon Matrix Elelements
ExcPhOptics # [R][EXCPH] Exciton-Phonon Optics
BoseTemp=10.000000 Kn # Bosonic Temperature
EXCTemp= 10.000000 Kn # [EXCPH] Excitonic Temperature (for luminescence spectra)
% ELPhExcStates
1 | 4 | # [EXCPH] Incoming (external) exciton states
%
% ELPhExcSum
1 | 12 | # [EXCPH] Outgoing (virtual) exciton states
%
% ElPhModes
1 | 12 | # [ELPH] Phonon modes included
%
LoutPath= "./bse-L_full" # [EXCPH] Path of the outgoing L
FANdEtresh= 0.100000E-5 eV # [ELPH] Energy treshold for Fan denominator
EXCPHdEtresh= 0.100000E-5 eV # [ELPH] Energy treshold for exc-ph denominator
LDamping= 0.500000E-3 eV # [EXCPH] Damping of exc-ph self-energy
# These are the plot parameters, same as in other parts of yambo
% EnRngeXd
4.00000 | 5.00000 | eV # [Xd] Energy range
%
% DmRngeXd
0.00500000 | 0.00500000 | eV # [Xd] Damping range
%
ETStpsXd= 4000 # [Xd] Total Energy steps

Here <code>BoseTemp</code> and <code>EXCTemp</code> are the lattice and excitonic temperature, respectively.

Now we run the calculation with <code>yambo_ph</code>. Here, we read as <math>Q=0</math> excitons with <code>-J</code> the ones without the long-range Coulomb exchange:

yambo_ph -F excph.in -J excph,bse_Lbar -C excph

and we find our outputs in the <code>excph</code> directory.

NB: Step 6 could have been equivalently run in yambopy, limiting the use of the yambo code to just step 4. This latter option is more flexible, as it allows for a greater degree of control by the user. We are in the last stages of the development and it will be available soon.

=== Results ===

If we check the output directory from the step 6 calculation, we find the <code>o-excph.pl_bse_ph_ass</code> output files containing the luminescence spectra. We can plot them with gnuplot or any other tool:

gnuplot
> set xrange[4.2:5]
> p 'o-excph.pl_bse_ph_ass' u 1:2 w l lc rgb 'red' lw 3

[[File:Luminescence plot.png|500px|center]]

Here, the signal corresponds to a finite-momentum exciton that recombines with the help of several different phonon modes, both optical and acoustic. Each phonon mode whose coupling with the exciton is allowed can generate a peak, and the energy shifts of these peaks with respect to the initial exciton energy correspond to the phonon energies. This result is underconverged, but the main features are all there. In the plot, we show a more converged example using a 12x12x4 grid (all the other parameters being equal). These plots can be compared with Fig. 4(a) of reference <ref name="zanfrognini2023" />.

== References ==

<references>
<ref name="toyozawa2003" >[https://m.booksee.org/book/1121964?force_lang=en Optical processes in solids], Toyozawa, Yutaka, and Chris Oxlade. Cambridge University Press, (2003). </ref>
<ref name='lechifflart2023'>P. Lechifflart, F. Paleari, D. Sangalli, C. Attaccalite, ''First-principles study of luminescence in hexagonal boron nitride single layer: Exciton-phonon coupling and the role of substrate'',
[https://doi.org/10.1103/PhysRevMaterials.7.024006 Phys. Rev. M, '''7''' (2), 024006 (2023)]; [https://arxiv.org/abs/2212.10407 arXiv2212.1047]</ref>
<ref name='cannuccia2019'>E. Cannuccia, B. Monserrat and C. Attaccalite, ''Theory of phonon-assisted luminescence in solids: Application to hexagonal boron nitride'', [https://doi.org/10.1103/PhysRevB.99.081109 Phys. Rev. B '''99''', 081109(R) (2019)]; [https://arxiv.org/abs/1807.11797 arXiv1807.11797]</ref>
<ref name='paleari2019'>F. Paleari et al., ''Exciton-Phonon Coupling in the Ultraviolet Absorption and Emission Spectra of Bulk Hexagonal Boron Nitride'', [https://doi.org/10.1103/PhysRevLett.122.187401 Phys. Rev. Lett. '''122''', 187401 (2019)]; [https://arxiv.org/abs/1810.08976 arXiv1810.089776] </ref>
<ref name='chen2020'>''Exciton-Phonon Interaction and Relaxation Times from First Principles'',
Hsiao-Yi Chen, Davide Sangalli, and Marco Bernardi, [https://doi.org/10.1103/PhysRevLett.125.107401 Phys. Rev. Lett. '''125''', 107401 (2020)]; [https://arxiv.org/abs/2002.08913 arXiv 2002.08913 (2020)]</ref>
<ref name="lechifflart2023_PhD">[https://www.yambo-code.eu/wiki/images/5/54/These_final.pdf Exciton-phonon coupling and phonon-assisted luminescence in hexagonal Boron Nitride nanostructures], PhD Thesis, Pierre Lechifflart (2023)</ref>
<ref name='paleari2019_PhD'>F. Paleari, ''First-principles approaches to the description of indirect absorption and luminescence spectroscopy: exciton-phonon coupling in hexagonal boron nitride'', [https://wwwen.uni.lu/research/fstm/dphyms/people/fulvio_paleari PhD thesis, University of Luxembourg (2019)]</ref>
<ref name='zanfrognini2023'>[https://arxiv.org/abs/2305.17554 Distinguishing different stackings in layered materials via luminescence spectroscopy], M. Zanfrognini et al. Phys. Rev. Lett. '''131''', 206902 (2023) </ref>
<ref name='marini2024'>G. Marini, M. Calandra, P. Cudazzo, ''Optical absorption and photoluminescence of single layer boron nitride from a first principles cumulant approach'', [https://doi.org/10.1021/acs.nanolett.4c00669 Nano Lett., '''24''', 20, 6017 (2024)]; [https://arxiv.org/abs/2402.03826 arXiv 2402.03826 (2024)]</ref>
<ref name='antonius2017'>G. Antonius, S. G. Louie, ''Theory of exciton-phonon coupling'', [https://doi.org/10.1103/PhysRevB.105.085111 Phys. Rev. B, '''105''', 085111 (2022)]; [https://arxiv.org/abs/1705.04245 arXiv1705.04245 (2017)]</ref>
<ref name='paleari2022'>[https://arxiv.org/abs/2205.02783 Exciton-phonon interaction calls for a revision of the “exciton” concept], F. Paleari, A. Marini, Phys. Rev. B, '''106''', 125403 (2022)</ref>
<ref name='cudazzo2020'> P. Cudazzo, ''First-principles description of the exciton-phonon interaction: A cumulant approach'', [https://doi.org/10.1103/PhysRevB.102.045136 Phys. Rev. B, '''102''', 045136 (2020)]; [https://orbilu.uni.lu/bitstream/10993/44769/1/main.pdf Open access pdf from Luxembourg University]</ref>
<ref name='chan2023'>Y-h Chan, J. B. Haber, M. H. Naik, J. B. Neaton, D. Y. Qiu, F. H. da Jornada, S. G. Louie, ''Exciton Lifetime and Optical Line Width Profile via Exciton–Phonon Interactions: Theory and First-Principles Calculations for Monolayer MoS2'', [https://doi.org/10.1021/acs.nanolett.3c00732 Nano Lett., '''23''', 9 (2023)]; [https://arxiv.org/abs/2212.08451 arXiv 2212.08451 (2023)]</ref>
<ref name='murali2025'>M. Nalabothula, S. Reichardt, L. Wirtz, ''Origin of Interlayer Exciton–Phonon Coupling in 2D Heterostructures'', [https://doi.org/10.1021/acs.nanolett.5c00355 Nano Lett., '''25''', 15 (2025)], [https://arxiv.org/abs/2407.16111 arXiv 2407.16111 (2025)]</ref>
</references>

Exciton-phonon coupling and luminescence

2025-10-06T11:48:10Z

Attacc: /* Step 5: run a BSE calculation */

[[File:Tdgw-phonon-usc-01-1024x829.jpg| 400px | right]]

In this advanced tutorial, we will calculate exciton-phonon interactions from first principles by interfacing DFPT (for phonon calculations) and BSE (for exciton calculations).

The DFTP calculations are run with Quantum ESPRESSO, while the many-body GW-BSE calculations are run with Yambo. Finally, the exciton-phonon interaction will be obtained by combining and postprocessing the databases computed in the two previous runs. The great advantage of this workflow is that the calculations can be run in the irreducible Brillouin zones both for the electronic momenta (<math>k</math>) and the transfer momenta (<math>Q</math>, <math>q</math>) of excitons and phonons, thus speeding up considerably the jobs while reducing the IO and memory load.

We will first compute the exciton-phonon coupling matrix elements: these are the building blocks needed to construct experimental observables such as phonon-assisted optical spectra (such as luminescence), Raman spectra and exciton lifetimes. We will do this in the case of monolayer MoS2, a 2D system with large spin-orbit interaction.

As an example of application, we will consider the case of phonon-assisted luminescence. We will do this in the case of bulk hBN, a layered indirect insulator with strong electron-phonon coupling.

'''Note:''' this tutorial will be updated when new exc-ph tools become available in Yambopy (including full-python postprocessing, Raman spectra, interpolated lifetimes, etc).

== Requirements ==

This is an advanced topic: we assume that you already know something about the theory<ref name="toyozawa2003" /><ref name="antonius2017" /><ref name="cudazzo2020" /><ref name="paleari2019_PhD" /><ref name="paleari2022" /><ref name="lechifflart2023_PhD" /> and applications<ref name="paleari2019" /><ref name="cannuccia2019" /><ref name="chen2020" /><ref name="zanfrognini2023" /><ref name="lechifflart2023" /><ref name="chan2023" /><ref name="marini2024" /><ref name="murali2025" /> of exciton-phonon physics.

Also, we assume that you already know how to run both a basic '''Yambo''' GW-BSE calculation and a DFPT phonon calculation with '''Quantum ESPRESSO'''.

Besides the QE executables <code>pw.x</code> and <code>ph.x</code>, we also use the yambo phonon-specific executable <code>yambo_ph</code> and the python utility '''Yambopy'''. The auxiliary code '''LetzElPhC''' (executable <code>lelphc</code>) will be used to obtain the electron-phonon matrix elements by reading the same electronic wavefunctions used by Yambo (and stored in the <code>SAVE</code> directory), while also making full use of crystal symmetries. [https://gitlab.com/lumen-code/LetzElPhC LetzElPhC] will be run by Yambopy, but it must nonetheless be installed. Finally, the exciton-phonon properties can be computed either using <code>yambo_ph</code> or using Yambopy itself.

[[File:Workflow scheme.png|800px|center]]

== Step 0: Pseudopotentials, equilibrium structure and convergence ==

In a real calculation, it is important to ensure that both the pseudopotential and the lattice parameters that we are using are compatible and perform well for the electronic excited states and for the lattice vibrations simultaneously. Furthermore, you have to make sure that the wave function cutoff <code>ecutwfc</code> is converged with respect to the DFPT step and not just to the DFT one. This is in addition to the other customary convergence tests for DFT, DFPT, GW and BSE calculations.

This is often the most time-demanding step when starting on a new system.

For the sake of this tutorial, we assume that we have already done all these tests and we are starting the final workflow to get the exciton-phonon properties.

== Step 1: scf calculation ==

First of all, we run a standard scf calculation with <code>pw.x</code> for Yambo. We stick with non-symmorphic symmetries. At the end, we will have the QE <code>save</code> directory.

This is the input <code>mos2.scf</code>:

&control
wf_collect = .true.,
calculation = "scf",
verbosity = 'high',
pseudo_dir = '$PSEUDO_DIR',
prefix = "mos2",
outdir = '.',
/&end
&system
ecutwfc = 100.0,
occupations = 'fixed',
ibrav = 4,
celldm(1) = 5.9000811881,
celldm(3) = 6.7795677253,
nat = 3,
ntyp = 2,
lspinorb = .true.
noncolin = .true.
assume_isolated = '2D'
force_symmorphic = .true.
/&end
&electrons
electron_maxstep = 200,
mixing_beta = 0.7,
conv_thr = 1.d-08,
/&end
ATOMIC_SPECIES
Mo 95.940 Mo_ONCV_PBE_FR-1.0.upf
S 32.065 S_ONCV_PBE_FR-1.1.upf
ATOMIC_POSITIONS { crystal }
Mo 0.333333333 0.666666667 0.000000000
S 0.666666667 0.333333333 0.073413577
S 0.666666667 0.333333333 -0.073413577
K_POINTS { automatic }
6 6 1 0 0 0

Here we are using full relativistic pseudopotentials from the SG-15 database.

We can run it on our machine (for example using 4 MPI tasks) as:

mpirun -np 4 pw.x -inp mos2.scf > scf.out

== Step 2: nscf calculation for Yambo ==

Copy the QE <code>save</code> directory from the scf calculation and run the nscf calculation for any number of empty states, with the correct <code>k</code>-grid we want to use in Yambo. Here we are using a badly underconverged grid of 6x6x1.

This reciprocal-space grid will also match the momentum transfer <code>q</code> grid on which excitons and phonons will be defined!

The electronic wavefunctions computed at this step and stored in the new nscf <code>save</code> directory will be used both by Yambo and by the electron-phonon code: this is important because using different sets of wavefunctions would lead to a phase mismatch issue in the exciton-phonon matrix elements.

The nscf input <code>mos2.nscf</code> is
&control
wf_collect = .true.,
calculation = "nscf",
verbosity = 'high',
pseudo_dir = '$PSEUDO_DIR',
prefix = "mos2",
outdir = '.',
/&end
&system
ecutwfc = 100.0,
occupations = 'fixed',
ibrav = 4,
celldm(1) = 5.9000811881,
celldm(3) = 6.7795677253,
nat = 3,
ntyp = 2,
lspinorb = .true.
noncolin = .true.
nbnd = 250
assume_isolated = '2D'
force_symmorphic = .true.
/&end
&electrons
electron_maxstep = 200,
mixing_beta = 0.7,
conv_thr = 1.d-08,
/&end
ATOMIC_SPECIES
Mo 95.940 Mo_ONCV_PBE_FR-1.0.upf
S 32.065 S_ONCV_PBE_FR-1.1.upf
ATOMIC_POSITIONS { crystal }
Mo 0.333333333 0.666666667 0.000000000
S 0.666666667 0.333333333 0.073413577
S 0.666666667 0.333333333 -0.073413577
K_POINTS { automatic }
6 6 1 0 0 0

Again, we run the calculation

mpirun -np 4 pw.x -inp mos2.nscf > nscf.out

== Step 3: dvscf phonon calculation ==

Now we run the phonon calculation.

Copy the <code>save</code> directory from the '''scf''' calculation and run <code>ph.x</code> for a dvscf calculation with a standard <code>q</code>-grid matching the <code>k</code>-grid we wanna use in Yambo.

At the end, we will have the <code>_ph0</code> directory containing the variation of the self-consistent potential, <math>\Delta V_{SCF}(q)</math>, and the <code>*.dyn</code> files with the phonon energies and eigenvectors.

NB: one could further refine the phonon energies by enforcing the acoustic sum rule, including non-analytic long-range contributions, interpolating to finer grids... all of this can be done within Quantum ESPRESSO and will not be covered in this version of the tutorial.

The input is <code>mos2.dvscf</code>:

mos2_dvscf
&inputph
tr2_ph=1.0d-12,
verbosity='high'
prefix='mos2',
fildvscf = 'mos2-dvscf',
electron_phonon = 'dvscf',
fildyn='mos2.dyn',
epsil=.false.,
ldisp=.true.,
recover=.true.,
nq1=6,
nq2=6,
nq3=1
/

And now we run as

nohup mpirun -np 8 ph.x -inp mos2.dvscf > dvscf.out &

This time we use nohup and more processes because this calculation may take some time. It is a good idea to set <code>recover=.true.</code> as in a real calculation you will easily breach walltime, and in this way you can safely restart.

== Step 4: create Yambo <code>SAVE</code> directory ==

This is just the standard Yambo initialization: run

p2y

and then

yambo

in the '''nscf''' <code>save</code> folder and then move the newly generated <code>SAVE</code> directory to a convenient place.

== Step 5: run a BSE calculation ==

Now we switch from QE to Yambo. Here, we forgo the GW step for simplicity (we can use a scissor operator to open the band gap).

This calculation has a couple of differences with respect to a standard BSE calculation for optical absorption. We can look at the input file <code>bse.in</code>:

# Runlevels
optics # [R OPT] Optics
rim_cut # [R RIM CUT] Coulomb potential
bss # [R BSS] Bethe Salpeter Equation solver
em1s # [R Xs] Static Inverse Dielectric Matrix
bse # [R BSE] Bethe Salpeter Equation.
bsk # [R BSK] Bethe Salpeter Equation kernel
# RIM and cutoff settings
RandQpts=1000000 # [RIM] Number of random q-points in the BZ
RandGvec= 100 RL # [RIM] Coulomb interaction RS components
CUTGeo= "slab z" # [CUT] Coulomb Cutoff geometry: box/cylinder/sphere X/Y/Z/XY..
# Static screening
X_and_IO_CPU= "1 1 4 2 1" # [PARALLEL] CPUs for each role
X_and_IO_ROLEs= "q g k c v" # [PARALLEL] CPUs roles (q,g,k,c,v)
X_and_IO_nCPU_LinAlg_INV=-1 # [PARALLEL] CPUs for Linear Algebra (if -1 it is automatically set)
Chimod= "hartree" # [X] IP/Hartree/ALDA/LRC/BSfxc
% QpntsRXs
1 | 7 | # [Xs] Transferred momenta
%
% BndsRnXs
1 | 200 | # [Xs] Polarization function bands
%
% LongDrXs
1.000000 | 1.000000 | 1.000000 | # [Xs] [cc] Electric Field
%
NGsBlkXs= 8 Ry # [Xs] Response block size
# BSE
BS_CPU= "4.1.2" # [PARALLEL] CPUs for each role
BS_ROLEs= "k.eh.t" # [PARALLEL] CPUs roles (k,eh,t)
BS_nCPU_diago=4 # [PARALLEL] CPUs for matrix diagonalization
BSEmod= "causal" # [BSE] resonant/causal/coupling
BSKmod= "SEX" # [BSE] IP/Hartree/HF/ALDA/SEX/BSfxc
BSSmod= "d" # [BSS] (h)aydock/(d)iagonalization/(i)nversion/(t)ddft`
BSENGexx= 40000 mRy # [BSK] Exchange components
ALLGexx # [BSS] Force the use use all RL vectors for the exchange part
BSENGBlk= 8000 mRy # [BSK] Screened interaction block size
Lkind="full" #[BSE,X] bar(default)/full/tilde
% KfnQP_E
1.000000 | 1.000000 | 1.000000 | # [EXTQP BSK BSS] E parameters (c/v) eV|adim|adim
%
% BEnRange
0.00000 | 4.00000 | eV # [BSS] Energy range
%
% BDmRange
0.05000 | 0.05000 | eV # [BSS] Damping range
%
BEnSteps= 2000 # [BSS] Energy steps
% BLongDir
1.000000 | 0.000000 | 0.000000 | # [BSS] [cc] Electric Field
%
% BSEQptR
 1 | 7 | # [BSK] Transferred momenta range
%
% BSEBands
25 | 28 | # [BSK] Bands range
%
WRbsWF # [BSS] Write to disk excitonic the FWs

This file is generated using the command: <code> yambo -X s -o b -k sex -y d -r</code> 

First of all, we compute the excitons for all the momenta in the irreducible Brillouin zone for our discrete grid via the <code>BSEQptR</code> variable. This will be a '''finite-momentum''' BSE calculation, analogous to the phonon one.

Second, we change the variable <code>Lkind</code> from <code>bar</code> to <code>full</code>. In Yambo, <code>Lkind="bar"</code>, which is the default for optical absorption, means that we are computing the excitonic response function without the long-range component of the exchange interaction. This cannot be used when computing the exciton momentum dependence, where the long-range exchange interaction can play a role, therefore we have to include it with <code>Lkind="full"</code>. This allows for the calculation of the excitonic longitudinal-transverse splitting (in 3D systems) as well.

We can now run the code:

nohup mpirun -np 8 yambo -F bse.in -J bse_Lfull -C bse_Lfull &

At the end of the calculation, we have obtained the <code>ndb.BS_diago_Q*</code> databases inside the directory <code>bse_Lfull</code>. They contain information on the exciton energies and wavefunctions at each momentum. Do not forget to check the report and logs of your calculation in the same directory to make sure that the code is doing what you want.

== Step 6: obtain the electron-phonon matrix elements ==

We have finished the heavy simulations. Now it's time for the postprocessing. The first order of business is the reconstruction of the electron-phonon coupling matrix elements from the dvscf results and the electronic wavefunctions.

In order to do this, we will run the <code>lelphc</code> executable of the '''LetzElPhC''' code. We will run via command line using yambopy, although it will be instructive to have look at the <code>lelphc</code> input files later.

We run in the same directory where the Yambo <code>SAVE</code> is (remember than you can also virtually move it with a symbolic link).

Type:

yambopy l2y

to see the help for the calculation. For example, if we want to do a serial run of LetzElPhC for bands from <math>n_i</math> to <math>n_f</math>, we should type:

yambopy l2y -ph path/of/ph_input.in -b n_i n_f

Here <math>n_i</math> and <math>n_f</math> are integers representing the initial and final band indices.

These should coincide with those used for the Bethe-Salpeter kernel, i.e. those specified in the <code>BSEBands</code> variable of the BSE input file (this is not strictly necessary, but certainly efficient since these calculations use a lot of disk space).

For our system, we want to do a parallel calculation with 4 qpools and 2 kpools. In addition, we want to explicitly specify the path of the <code>lelphc</code> executable and avoid automatically deleting the LetzElPhC data. So we type:

yambopy l2y -ph path/of/dvscf/mos2.dvscf -b 25 28 -par 4 2 -lelphc path/to/lelphc_exe --debug

At the end, check the <code>SAVE</code>

ls SAVE/ndb.elph_gkkp*

to see that it has created the Yambo-compatible electron-phonon databases.

If you saved the <code>lelphc.in</code> input file, you can inspect it:

# LetzElPhC input for yambo generated by yambopy
nqpool = 2
nkpool = 4
start_bnd = 25
end_bnd = 28
save_dir = ./SAVE
kernel = dfpt
ph_save_dir = dvscf/ph_save
convention = yambo

You can also run it as it is, but the code will generate the database <code>ndb.elph</code>. In order to convert it to the <code>ndb.elph_gkkp*</code> databases of Yambo, you still need a couple of lines of python using the Yambopy class <code>ConvertElectronPhononDB</code> in <code>yambopy/letzelph_interface/lelph2y.py</code>.

Notice the variable <code>convention=yambo</code>: what does it mean? At variance with QE and many other codes, Yambo uses the "backward" momentum transfer convention for electronic scatterings. That is, an electronic transition goes from band <math>n</math> and momentum <math>k-q</math> to band <math>m</math> and momentum <math>k</math>. In the "forward" momentum transfer convention (the more standard one), the transitions go from <math>nk</math> to <math>mk+q</math>. Therefore, this variable ensures that the electron-phonon coupling matrix elements are computed as <math>\langle mk|dV|nk-q\rangle</math>. This will have consequences also in the formulation of the ''exciton''-phonon coupling matrix element.

== Step 7: Obtain the exciton-phonon coupling ==

Now, we can finally access our basic building block for exciton-phonon physics. This could be done entirely in python (using '''Yambopy'''), or by running '''Yambo'''. In this version of the tutorial we present the latter case.

Our objective is obtaining the following quantity:

<math>\mathcal{G}^\mu_{\alpha\lambda}(0,q)=\sum_{vv^\prime c k} A^{\alpha, *}_{cv^\prime} (k, q) g_{vv^\prime}^\mu (k,q) A^{\lambda}_{cv}(k,q) - \sum_{cc^\prime vk} A^{\alpha, *}_{c^\prime v} (k+q, q) g_{c^\prime c}^\mu (k+q,q) A^{\lambda}_{cv}(k,q)</math>

Here, <math>A^{\lambda}_{cv}(k,q)</math> are the exciton coefficients extracted from the eigenvector of the two-particles Hamiltonian during the BSE calculation in step 5, while <math>g_{nm}^\mu (k,q)</math> are the electron-phonon coupling matrix elements obtained in step 6. As you can see, the exciton <math>\lambda</math> undergoes phonon-mediated scattering to state <math>\alpha</math> via phonon mode <math>\mu</math>. The scattering can happen for the hole (valence, <math>v</math>) or for the electron (conduction, <math>c</math>).

NB:

(1) This is written in the "backward" momentum transfer convention used by Yambo. The momentum dependence is different in the "forward" transfer convention.

(2) For simplicity, this is written for zero initial exciton momentum. This means that one of the two states involved in the phonon-mediated scattering process will be in the optical limit (and possibly an optically generated exciton), while the other state can have any momentum: this momentum will be the same as the phonon one. This matrix element can be used to describe phonon-assisted absorption and emission spectra.

We have to write a new yambo input, that we can call <code>excph.in</code>, for this. You can copy (and adapt) the one below, or you can generate one by running from the command line:

yambo_ph -excph o

This generates an input to compute luminescence ("o" is for "optics"). The variables that we are interested in are:

excph # [R] Exction-phonon
ExcGkkp # [R][EXCPH] Exciton-Phonon Matrix Elelements
% ELPhExcStates
1 | 4 | # [EXCPH] Incoming (external) exciton states
%
% ELPhExcSum
1 | 12 | # [EXCPH] Outgoing (virtual) exciton states
%
LoutPath= "./bse_Lfull" # [EXCPH] Path of the outgoing L
% ElPhModes
1 | 9 | # [ELPH] Phonon modes included
%

In this input, we have to select the initial exciton states <math>\lambda</math> with <code>ELPhExcStates</code>, the final exciton states <math>\alpha</math> with <code>ELPhExcSum</code> and the phonon modes <math>\mu</math> with <code>ElPhModes</code>. Here we consider the first four states at <math>Q=0</math> (corresponding to just two excitons because they are both doubly degenerate -- do not break degeneracies when selecting states!) and the first twelve states at each finite-<math>q</math> point. We also include all the nine phonon modes of monolayer MoS2.

What about <code>LoutPath</code>? This variable controls the directory where the databases for the final-state excitons <math>\alpha</math> is located, which can be different from the directory with the initial-state excitons <math>\lambda</math> read as usual with the <code>-J</code> option when running the code. This makes it possible to compute the coupling between different exciton kinds. However, for our tutorial, we stick with the previously computed <code>Lfull</code> in both cases.

When we are satisfied with the input, we run the code using <code>yambo_ph</code>:

yambo_ph -F excph.in -J excph,bse_Lfull -C excph

If you check the output, you should find the <code>ndb.excph*</code> databases in the <code>excph</code> directory.

=== Analysis of the couplings ===

It is a good idea to have a look at what we computed up to now in order to make sure nothing has gone wrong.

It is not easy to know what to expect (apart from symmetry and gauge compliance of the matrix elements), but one can work out the exciton-phonon selection rules in advance, check that the magnitude is reasonable, etc.

It is also not easy to meaningfully plot this quantity. We have to make sure that we are not breaking degenerate states, otherwise the plots will not be invariant.

First of all, we have to know our system: in monolayer MoS2, the first four excitons are all doubly degenerate. The first exciton responsible for a bright peak in the absorption spectrum (the '''A''' peak), is the second state, corresponding to state indices <code>(3,4)</code> in fortran indexing or <code>(2,3)</code> in python indexing.

All these information can be obtained by analyzing the BSE results (this stuff is explained in the BSE tutorials) and by knowledge of the system or class of systems from the literature.

Thus, a good quantity to plot may be the norm of the matrix elements, summed over the degenerate subspace of exciton A, for a certain number of scattered final states mediated by certain phonon modes:

<math>F_A(q)= \sqrt{ \sum_{\alpha \in A,\lambda,\mu} |\mathcal{G}_{\alpha\lambda}^\mu (0,q)|^2 }</math>

In order to do this, we create a python script <code>analyse_excph.py</code> in which we first load the excph dabatases using the <code>YamboExcitonPhononDB</code> from yambopy.
You can find this script in the yambopy directory, in <code>tutorials/exciton-phonon</code>.
First, we select the exciton and phonon states to be included in <code>F_A</code>, together with the path of databases and plot details:

# Exciton in states
exc_in = [2,3] # A: 2,3 -- B: 6,7
exc_out = [0,1,2,3] # first 4 states (dispersion of triplet state and A)
ph_in = 'all'

# Paths of databases
ns_db1 =f'{path}/SAVE/ns.db1'
ndb_exc=f'{path}/excph'

...

Then, we load the data:

# Read lattice and k-space info
ylat = YamboLatticeDB.from_db_file(filename=ns_db1),Expand=True)
print(ylat)

# Read exc-ph databases
X = YamboExcitonPhononDB(ylat,save_excph=ndb_exc)
print(X)

The quantity <math>F_A(q)</math> is defined inside the plotting function as

G_squared = excph.excph_sq
G2plt = np.zeros(len(G_squared))

if exc_in == 'all': exc_in = range(G_squared.shape[2])
if exc_out == 'all': exc_out = range(G_squared.shape[3])
if ph_in == 'all': ph_in = range(G_squared.shape[1])

G_squared = G_squared[:, ph_in, :, :].sum(axis=(1))
G_squared = G_squared[:, exc_in, :].sum(axis=(1))
G_squared = G_squared[:, exc_out].sum(axis=(1))

F_q = np.sqrt( G_squared )*ha2ev # Switch from Ha to eV

And finally, we have to make a plotting function. For this tutorial we will use the default scatterplot provided by <code>YamboExcitonPhononDB</code>

excph.plot_excph(F_q,plt_cbar=plt_cbar,**kwargs)
...

You can get more experience on using Yambopy for these kinds of visualization by following the [https://wiki.yambo-code.eu/wiki/index.php?title=First_steps_in_Yambopy Yambopy tutorials]. In fact, remember that this scripts and all the other yambopy tutorial scripts are just suggestions, not source code written in stone: if you know <code>numpy</code> and <code>matplotlib</code> you can do your own analysis and your own plots, you just need to import the required Yambopy modules to load the data.

In our case, the resulting plot is the following.

[[File:1L MoS2 ExcPh.png|500px|center]]

This can be checked against Fig. 2(d) of reference <ref name="chan2023" />, although you have to keep in mind that our results are badly undersampled in terms of the reciprocal-space grid, as can be easily seen, and the quantity plotted is not exactly the same. However, the main features are already there since they are dictated mostly by crystal symmetries.

Now that we have the exciton-phonon matrix elements, we can use them to build several kinds of observables. Below, we give an example related to phonon-assisted luminescence, but we may update this tutorial in the future to include more cases.

== Step 8: Compute phonon-assisted luminescence ==

[[File:Luminescence scheme.png|250px|right]]

We want to compute the experimental optical signature due to the phonon-assisted recombination of an exciton (as sketched in the figure).

The signal from the phonon replicas can be modeled as a second-order scattering process involving one phonon and one photon:

<math>I^{(1)}_{PL}(\omega;T) \propto \frac{1}{N_q}\sum_{ s \mu \beta q} \left|\sum_\lambda\frac{D_\lambda \mathcal{G}^{\mu q}_{\alpha q,\lambda}}{E_{\alpha q}-E_\lambda -s\Omega_{\mu q}} \right|^2 N_{\alpha q}(T_{exc}) F^s_{\mu q}(T)\delta(\omega - \left[E_{\alpha q}-s\Omega_{\mu q}\right])</math>

In this equation, the oscillator strength of the peak is given by the exciton-phonon coupling matrix elements <math>\mathcal{G}</math> multiplied by the exciton dipoles <math>D</math> (they are called "residuals" in Yambo). Here <math>E_\lambda</math> and <math>E_{\alpha q}</math> are the energies of the optical and finite-momentum excitons, respectively, while <math>\Omega_{\mu q}</math> are the phonon energies.

The occupation function <math>F</math> is <math>F^s_{\mu q}(T)=n_{\mu q}(T)+\frac{1+s}{2}</math>. Here, <math>n(T)</math> is the temperature-dependent phonon Bose-Einstein occupation function. As it can be seen, <math>s=1</math> corresponds to processes of phonon ''emission'' (<math>\propto n(T)+1</math>), while <math>s=-1</math> corresponds to processes of phonon ''absorption'' (<math>\propto n(T)</math>). Therefore, <math>I^{(1)}_{PL}(\omega;T)</math> describes ''light'' emission by recombining excitons mediated by either ''phonon'' absorption or emission.

The quantity <math> N_{\alpha q}(T_{exc})</math> is the exciton occupation function. Luminescence is technically an out-of-equilibrium process, but we can assume that for very low density of excitations and in steady-state conditions, the exciton population can be approximately described by an equilibrium distribution evaluated at an effective temperature. Here, we use the Boltzmann distribution. Experimentally, <math>T_{exc}</math> tends to coincide with the lattice temperature <math>T</math> more or less above 100 K, while at very low temperature (< 10 K), <math>T_{exc}</math> may vary between 10-50 K. It goes without saying that this needs to carefully be checked in your realistic calculations.

=== Running the jobs ===

In order to study luminescence in a paradigmatic system, we switch to bulk hexagonal boron nitride and we repeat the workflow. As you can easily see, one can think about automatizing the execution of all these calculations via scripting or more advanced tools. However, in the case of very large simulations (memory-limited or disk-space limited) or for systems whose electronic and lattice properties are fragile with respect to tiny calculation details, one must be very careful and run many basic tests.

Fortunately, we are running a fast underconverged example. We use LDA pseudopotentials from the pseudo-dojo library and the following are the calculations steps.

1. Input <code>hbn.scf</code>:

&control
calculation='scf',
prefix='hBN',
restart_mode='from_scratch'
pseudo_dir = '$PSEUDO_DIR',
outdir = './tmp'
verbosity = 'high'
wf_collect=.true.
/
&system
ibrav = 4,
celldm(1) = 4.703675849
celldm(3) = 2.603711434
nat= 4,
ntyp= 2,
force_symmorphic=.true.
ecutwfc = 100,
/
&electrons
diago_david_ndim = 2
diago_full_acc=.true.
diago_thr_init=5.0e-6
mixing_mode = 'plain'
mixing_beta = 0.7
conv_thr = 1.0d-16
/
ATOMIC_SPECIES
B 10.81100 B_LDA_dojo.UPF
N 14.00674 N_LDA_dojo.UPF
ATOMIC_POSITIONS {crystal}
N 0.6666666670 0.3333333330 -0.250000000000
B 0.3333333330 0.6666666670 -0.250000000000
B 0.6666666670 0.3333333330 0.25000000000
N 0.3333333330 0.6666666670 0.25000000000
K_POINTS {automatic}
6 6 2 0 0 0

mpirun -np 4 pw.x -inp hbn.scf > scf.out

2. Input <code>hbn.nscf</code>:

&control
calculation='nscf',
prefix='hBN',
restart_mode='from_scratch'
pseudo_dir = '$PSEUDO_DIR'
outdir = './'
verbosity = 'high'
wf_collect=.true.
/
&system
ibrav = 4,
celldm(1) = 4.703675849
celldm(3) = 2.603711434
nat= 4,
ntyp= 2,
force_symmorphic=.true.
ecutwfc = 100,
nbnd = 120
/
&electrons
diago_david_ndim = 2
diago_full_acc=.true.
diago_thr_init=5.0e-6
mixing_mode = 'plain'
mixing_beta = 0.7
conv_thr = 1.0d-16
/
ATOMIC_SPECIES
B 10.81100 B_LDA_dojo.UPF
N 14.00674 N_LDA_dojo.UPF
ATOMIC_POSITIONS {crystal}
N 0.6666666670 0.3333333330 -0.250000000000
B 0.3333333330 0.6666666670 -0.250000000000
B 0.6666666670 0.3333333330 0.25000000000
N 0.3333333330 0.6666666670 0.25000000000
K_POINTS {automatic}
6 6 2 0 0 0

mpirun -np 4 pw.x -inp hbn.nscf > nscf.out

3. Input <code>hbn.dvscf</code>:

hbn_dvscf
&inputph
tr2_ph=1.0d-12,
verbosity='high'
prefix='hBN',
fildvscf = 'hBN-dvscf',
electron_phonon = 'dvscf',
fildyn='hBN.dyn',
epsil=.false.,
ldisp=.true.,
recover=.true.,
nq1=6,
nq2=6,
nq3=2
/

nohup mpirun -np 8 pw.x -inp hbn.dvscf > dvscf.out &

4. Input <code>bse.in</code> (we include 2 valence and 2 conduction bands):

optics # [R] Linear Response optical properties
bss # [R] BSE solver
bse # [R][BSE] Bethe Salpeter Equation.
dipoles # [R] Oscillator strenghts (or dipoles)
em1s
DIP_CPU= "1 8 1" # [PARALLEL] CPUs for each role
DIP_ROLEs= "k c v" # [PARALLEL] CPUs roles (k,c,v)
DIP_Threads=0 # [OPENMP/X] Number of threads for dipoles
X_and_IO_CPU= "1 1 1 8 1" # [PARALLEL] CPUs for each role
X_and_IO_ROLEs= "q g k c v" # [PARALLEL] CPUs roles (q,g,k,c,v)
X_and_IO_nCPU_LinAlg_INV=-1 # [PARALLEL] CPUs for Linear Algebra (if -1 it is automatically set)
X_Threads=0 # [OPENMP/X] Number of threads for response functions
BS_CPU= "8 1 1" # [PARALLEL] CPUs for each role
BS_ROLEs= "k eh t" # [PARALLEL] CPUs roles (k,eh,t)
BS_nCPU_LinAlg_INV=-1 # [PARALLEL] CPUs for Linear Algebra (if -1 it is automatically set)
BS_nCPU_LinAlg_DIAGO=-1 # [PARALLEL] CPUs for Linear Algebra (if -1 it is automatically set)
X_Threads=0 # [OPENMP/X] Number of threads for response functions
K_Threads=0 # [OPENMP/BSK] Number of threads for response functions
% QpntsRXs
1 | 14 | # [Xs] Transferred momenta
%
% BndsRnXs
1 | 120 | # [Xs] Polarization function bands
%
NGsBlkXs= 10 Ry # [Xs] Response block size
% LongDrXs
1.000000 | 1.000000 | 1.000000 | # [Xs] [cc] Electric Field
%
BSEmod= "resonant" # [BSE] resonant/retarded/coupling
BSKmod= "SEX" # [BSE] IP/Hartree/HF/ALDA/SEX/BSfxc
Lkind= "Lfull" # [BSE] Lbar (default) / full
BSSmod= "d" # [BSS] (h)aydock/(d)iagonalization/(s)lepc/(i)nversion/(t)ddft`
% DipBands
1 | 120 | # [DIP] Bands range for dipoles
%
DipApproach= "G-space v" # [DIP] [G-space v/R-space x/Covariant/Shifted grids]
DipComputed= "R V P" # [DIP] [default R P V; extra P2 Spin Orb]
BSENGexx= 30000 Ry # [BSK] Exchange components
#ALLGexx # [BSS] Force the use use all RL vectors for the exchange part
BSENGBlk= 9000 Ry # [BSK] Screened interaction block size [if -1 uses all the G-vectors of W(q,G,Gp)]
% KfnQP_E
1.25997 | 1.08816 | 1.12683 | # [EXTQP BSK BSS] E parameters (c/v) eV|adim|adim
%
% BSEQptR
 1 | 14 | # [BSK] Transferred momenta range
%
% BSEBands
 7 | 10 | # [BSK] Bands range
%
% BEnRange
0.50000 | 8.00000 | eV # [BSS] Energy range
%
% BDmRange
0.050000 | 0.050000 | eV # [BSS] Damping range
%
BEnSteps= 1000 # [BSS] Energy steps
% BLongDir
1.000000 | 1.000000 | 0.000000 | # [BSS] [cc] Electric Field
%
WRbsWF # [BSS] Write to disk excitonic the WFs

nohup mpirun -np 8 yambo -F bse.in -J bse_Lfull -C bse_Lfull &

Importantly, since we want to describe the phonon-assisted recombination process of an *optical* exciton (i.e., emitting a transverse photon), this time we also run an additional calculation at `Q=0` omitting the nonanalytic long-range Coulomb exchange. Make a second input <code>bse_Lbar.in</code> with the following changes:

Lkind= "Lbar" # [BSE] Lbar (default) / full
% BSEQptR
 1 | 1 | # [BSK] Transferred momenta range
%

4b. So now we make a second BSE run in a different directory specified by <code>-J</code>. Here, we also pass to yambo the directory of the previous run as it includes the important screening databases <code>ndb.em1s*</code> that we do not want to recompute from scratch.

mpirun -np 8 yambo -F bse_Lbar.in -J bse_Lbar,bse_Lfull -C bse_Lbar

5. Now we run <code>lelphc</code> with yambopy to get the el-ph matrix elements:

yambopy l2y -ph path/of/dvscf/hbn.dvscf -b 7 10 -par 4 2

6. And finally we generate the exciton-phonon input <code>excph.in</code> using <code>yambo_ph -excph o</code>. Now, we take a look at all the additional variables that we didn't check before, specifying also the details for luminescence the spectrum calculation.

excph # [R] Exction-phonon
ExcGkkp # [R][EXCPH] Exciton-Phonon Matrix Elelements
ExcPhOptics # [R][EXCPH] Exciton-Phonon Optics
BoseTemp=10.000000 Kn # Bosonic Temperature
EXCTemp= 10.000000 Kn # [EXCPH] Excitonic Temperature (for luminescence spectra)
% ELPhExcStates
1 | 4 | # [EXCPH] Incoming (external) exciton states
%
% ELPhExcSum
1 | 12 | # [EXCPH] Outgoing (virtual) exciton states
%
% ElPhModes
1 | 12 | # [ELPH] Phonon modes included
%
LoutPath= "./bse-L_full" # [EXCPH] Path of the outgoing L
FANdEtresh= 0.100000E-5 eV # [ELPH] Energy treshold for Fan denominator
EXCPHdEtresh= 0.100000E-5 eV # [ELPH] Energy treshold for exc-ph denominator
LDamping= 0.500000E-3 eV # [EXCPH] Damping of exc-ph self-energy
# These are the plot parameters, same as in other parts of yambo
% EnRngeXd
4.00000 | 5.00000 | eV # [Xd] Energy range
%
% DmRngeXd
0.00500000 | 0.00500000 | eV # [Xd] Damping range
%
ETStpsXd= 4000 # [Xd] Total Energy steps

Here <code>BoseTemp</code> and <code>EXCTemp</code> are the lattice and excitonic temperature, respectively.

Now we run the calculation with <code>yambo_ph</code>. Here, we read as <math>Q=0</math> excitons with <code>-J</code> the ones without the long-range Coulomb exchange:

yambo_ph -F excph.in -J excph,bse_Lbar -C excph

and we find our outputs in the <code>excph</code> directory.

NB: Step 6 could have been equivalently run in yambopy, limiting the use of the yambo code to just step 4. This latter option is more flexible, as it allows for a greater degree of control by the user. We are in the last stages of the development and it will be available soon.

=== Results ===

If we check the output directory from the step 6 calculation, we find the <code>o-excph.pl_bse_ph_ass</code> output files containing the luminescence spectra. We can plot them with gnuplot or any other tool:

gnuplot
> set xrange[4.2:5]
> p 'o-excph.pl_bse_ph_ass' u 1:2 w l lc rgb 'red' lw 3

[[File:Luminescence plot.png|500px|center]]

Here, the signal corresponds to a finite-momentum exciton that recombines with the help of several different phonon modes, both optical and acoustic. Each phonon mode whose coupling with the exciton is allowed can generate a peak, and the energy shifts of these peaks with respect to the initial exciton energy correspond to the phonon energies. This result is underconverged, but the main features are all there. In the plot, we show a more converged example using a 12x12x4 grid (all the other parameters being equal). These plots can be compared with Fig. 4(a) of reference <ref name="zanfrognini2023" />.

== References ==

<references>
<ref name="toyozawa2003" >[https://m.booksee.org/book/1121964?force_lang=en Optical processes in solids], Toyozawa, Yutaka, and Chris Oxlade. Cambridge University Press, (2003). </ref>
<ref name='lechifflart2023'>P. Lechifflart, F. Paleari, D. Sangalli, C. Attaccalite, ''First-principles study of luminescence in hexagonal boron nitride single layer: Exciton-phonon coupling and the role of substrate'',
[https://doi.org/10.1103/PhysRevMaterials.7.024006 Phys. Rev. M, '''7''' (2), 024006 (2023)]; [https://arxiv.org/abs/2212.10407 arXiv2212.1047]</ref>
<ref name='cannuccia2019'>E. Cannuccia, B. Monserrat and C. Attaccalite, ''Theory of phonon-assisted luminescence in solids: Application to hexagonal boron nitride'', [https://doi.org/10.1103/PhysRevB.99.081109 Phys. Rev. B '''99''', 081109(R) (2019)]; [https://arxiv.org/abs/1807.11797 arXiv1807.11797]</ref>
<ref name='paleari2019'>F. Paleari et al., ''Exciton-Phonon Coupling in the Ultraviolet Absorption and Emission Spectra of Bulk Hexagonal Boron Nitride'', [https://doi.org/10.1103/PhysRevLett.122.187401 Phys. Rev. Lett. '''122''', 187401 (2019)]; [https://arxiv.org/abs/1810.08976 arXiv1810.089776] </ref>
<ref name='chen2020'>''Exciton-Phonon Interaction and Relaxation Times from First Principles'',
Hsiao-Yi Chen, Davide Sangalli, and Marco Bernardi, [https://doi.org/10.1103/PhysRevLett.125.107401 Phys. Rev. Lett. '''125''', 107401 (2020)]; [https://arxiv.org/abs/2002.08913 arXiv 2002.08913 (2020)]</ref>
<ref name="lechifflart2023_PhD">[https://www.yambo-code.eu/wiki/images/5/54/These_final.pdf Exciton-phonon coupling and phonon-assisted luminescence in hexagonal Boron Nitride nanostructures], PhD Thesis, Pierre Lechifflart (2023)</ref>
<ref name='paleari2019_PhD'>F. Paleari, ''First-principles approaches to the description of indirect absorption and luminescence spectroscopy: exciton-phonon coupling in hexagonal boron nitride'', [https://wwwen.uni.lu/research/fstm/dphyms/people/fulvio_paleari PhD thesis, University of Luxembourg (2019)]</ref>
<ref name='zanfrognini2023'>[https://arxiv.org/abs/2305.17554 Distinguishing different stackings in layered materials via luminescence spectroscopy], M. Zanfrognini et al. Phys. Rev. Lett. '''131''', 206902 (2023) </ref>
<ref name='marini2024'>G. Marini, M. Calandra, P. Cudazzo, ''Optical absorption and photoluminescence of single layer boron nitride from a first principles cumulant approach'', [https://doi.org/10.1021/acs.nanolett.4c00669 Nano Lett., '''24''', 20, 6017 (2024)]; [https://arxiv.org/abs/2402.03826 arXiv 2402.03826 (2024)]</ref>
<ref name='antonius2017'>G. Antonius, S. G. Louie, ''Theory of exciton-phonon coupling'', [https://doi.org/10.1103/PhysRevB.105.085111 Phys. Rev. B, '''105''', 085111 (2022)]; [https://arxiv.org/abs/1705.04245 arXiv1705.04245 (2017)]</ref>
<ref name='paleari2022'>[https://arxiv.org/abs/2205.02783 Exciton-phonon interaction calls for a revision of the “exciton” concept], F. Paleari, A. Marini, Phys. Rev. B, '''106''', 125403 (2022)</ref>
<ref name='cudazzo2020'> P. Cudazzo, ''First-principles description of the exciton-phonon interaction: A cumulant approach'', [https://doi.org/10.1103/PhysRevB.102.045136 Phys. Rev. B, '''102''', 045136 (2020)]; [https://orbilu.uni.lu/bitstream/10993/44769/1/main.pdf Open access pdf from Luxembourg University]</ref>
<ref name='chan2023'>Y-h Chan, J. B. Haber, M. H. Naik, J. B. Neaton, D. Y. Qiu, F. H. da Jornada, S. G. Louie, ''Exciton Lifetime and Optical Line Width Profile via Exciton–Phonon Interactions: Theory and First-Principles Calculations for Monolayer MoS2'', [https://doi.org/10.1021/acs.nanolett.3c00732 Nano Lett., '''23''', 9 (2023)]; [https://arxiv.org/abs/2212.08451 arXiv 2212.08451 (2023)]</ref>
<ref name='murali2025'>M. Nalabothula, S. Reichardt, L. Wirtz, ''Origin of Interlayer Exciton–Phonon Coupling in 2D Heterostructures'', [https://doi.org/10.1021/acs.nanolett.5c00355 Nano Lett., '''25''', 15 (2025)], [https://arxiv.org/abs/2407.16111 arXiv 2407.16111 (2025)]</ref>
</references>

Exciton-phonon coupling and luminescence

2025-10-06T11:40:07Z

Attacc: /* Running the jobs */

[[File:Tdgw-phonon-usc-01-1024x829.jpg| 400px | right]]

In this advanced tutorial, we will calculate exciton-phonon interactions from first principles by interfacing DFPT (for phonon calculations) and BSE (for exciton calculations).

The DFTP calculations are run with Quantum ESPRESSO, while the many-body GW-BSE calculations are run with Yambo. Finally, the exciton-phonon interaction will be obtained by combining and postprocessing the databases computed in the two previous runs. The great advantage of this workflow is that the calculations can be run in the irreducible Brillouin zones both for the electronic momenta (<math>k</math>) and the transfer momenta (<math>Q</math>, <math>q</math>) of excitons and phonons, thus speeding up considerably the jobs while reducing the IO and memory load.

We will first compute the exciton-phonon coupling matrix elements: these are the building blocks needed to construct experimental observables such as phonon-assisted optical spectra (such as luminescence), Raman spectra and exciton lifetimes. We will do this in the case of monolayer MoS2, a 2D system with large spin-orbit interaction.

As an example of application, we will consider the case of phonon-assisted luminescence. We will do this in the case of bulk hBN, a layered indirect insulator with strong electron-phonon coupling.

'''Note:''' this tutorial will be updated when new exc-ph tools become available in Yambopy (including full-python postprocessing, Raman spectra, interpolated lifetimes, etc).

== Requirements ==

This is an advanced topic: we assume that you already know something about the theory<ref name="toyozawa2003" /><ref name="antonius2017" /><ref name="cudazzo2020" /><ref name="paleari2019_PhD" /><ref name="paleari2022" /><ref name="lechifflart2023_PhD" /> and applications<ref name="paleari2019" /><ref name="cannuccia2019" /><ref name="chen2020" /><ref name="zanfrognini2023" /><ref name="lechifflart2023" /><ref name="chan2023" /><ref name="marini2024" /><ref name="murali2025" /> of exciton-phonon physics.

Also, we assume that you already know how to run both a basic '''Yambo''' GW-BSE calculation and a DFPT phonon calculation with '''Quantum ESPRESSO'''.

Besides the QE executables <code>pw.x</code> and <code>ph.x</code>, we also use the yambo phonon-specific executable <code>yambo_ph</code> and the python utility '''Yambopy'''. The auxiliary code '''LetzElPhC''' (executable <code>lelphc</code>) will be used to obtain the electron-phonon matrix elements by reading the same electronic wavefunctions used by Yambo (and stored in the <code>SAVE</code> directory), while also making full use of crystal symmetries. [https://gitlab.com/lumen-code/LetzElPhC LetzElPhC] will be run by Yambopy, but it must nonetheless be installed. Finally, the exciton-phonon properties can be computed either using <code>yambo_ph</code> or using Yambopy itself.

[[File:Workflow scheme.png|800px|center]]

== Step 0: Pseudopotentials, equilibrium structure and convergence ==

In a real calculation, it is important to ensure that both the pseudopotential and the lattice parameters that we are using are compatible and perform well for the electronic excited states and for the lattice vibrations simultaneously. Furthermore, you have to make sure that the wave function cutoff <code>ecutwfc</code> is converged with respect to the DFPT step and not just to the DFT one. This is in addition to the other customary convergence tests for DFT, DFPT, GW and BSE calculations.

This is often the most time-demanding step when starting on a new system.

For the sake of this tutorial, we assume that we have already done all these tests and we are starting the final workflow to get the exciton-phonon properties.

== Step 1: scf calculation ==

First of all, we run a standard scf calculation with <code>pw.x</code> for Yambo. We stick with non-symmorphic symmetries. At the end, we will have the QE <code>save</code> directory.

This is the input <code>mos2.scf</code>:

&control
wf_collect = .true.,
calculation = "scf",
verbosity = 'high',
pseudo_dir = '$PSEUDO_DIR',
prefix = "mos2",
outdir = '.',
/&end
&system
ecutwfc = 100.0,
occupations = 'fixed',
ibrav = 4,
celldm(1) = 5.9000811881,
celldm(3) = 6.7795677253,
nat = 3,
ntyp = 2,
lspinorb = .true.
noncolin = .true.
assume_isolated = '2D'
force_symmorphic = .true.
/&end
&electrons
electron_maxstep = 200,
mixing_beta = 0.7,
conv_thr = 1.d-08,
/&end
ATOMIC_SPECIES
Mo 95.940 Mo_ONCV_PBE_FR-1.0.upf
S 32.065 S_ONCV_PBE_FR-1.1.upf
ATOMIC_POSITIONS { crystal }
Mo 0.333333333 0.666666667 0.000000000
S 0.666666667 0.333333333 0.073413577
S 0.666666667 0.333333333 -0.073413577
K_POINTS { automatic }
6 6 1 0 0 0

Here we are using full relativistic pseudopotentials from the SG-15 database.

We can run it on our machine (for example using 4 MPI tasks) as:

mpirun -np 4 pw.x -inp mos2.scf > scf.out

== Step 2: nscf calculation for Yambo ==

Copy the QE <code>save</code> directory from the scf calculation and run the nscf calculation for any number of empty states, with the correct <code>k</code>-grid we want to use in Yambo. Here we are using a badly underconverged grid of 6x6x1.

This reciprocal-space grid will also match the momentum transfer <code>q</code> grid on which excitons and phonons will be defined!

The electronic wavefunctions computed at this step and stored in the new nscf <code>save</code> directory will be used both by Yambo and by the electron-phonon code: this is important because using different sets of wavefunctions would lead to a phase mismatch issue in the exciton-phonon matrix elements.

The nscf input <code>mos2.nscf</code> is
&control
wf_collect = .true.,
calculation = "nscf",
verbosity = 'high',
pseudo_dir = '$PSEUDO_DIR',
prefix = "mos2",
outdir = '.',
/&end
&system
ecutwfc = 100.0,
occupations = 'fixed',
ibrav = 4,
celldm(1) = 5.9000811881,
celldm(3) = 6.7795677253,
nat = 3,
ntyp = 2,
lspinorb = .true.
noncolin = .true.
nbnd = 250
assume_isolated = '2D'
force_symmorphic = .true.
/&end
&electrons
electron_maxstep = 200,
mixing_beta = 0.7,
conv_thr = 1.d-08,
/&end
ATOMIC_SPECIES
Mo 95.940 Mo_ONCV_PBE_FR-1.0.upf
S 32.065 S_ONCV_PBE_FR-1.1.upf
ATOMIC_POSITIONS { crystal }
Mo 0.333333333 0.666666667 0.000000000
S 0.666666667 0.333333333 0.073413577
S 0.666666667 0.333333333 -0.073413577
K_POINTS { automatic }
6 6 1 0 0 0

Again, we run the calculation

mpirun -np 4 pw.x -inp mos2.nscf > nscf.out

== Step 3: dvscf phonon calculation ==

Now we run the phonon calculation.

Copy the <code>save</code> directory from the '''scf''' calculation and run <code>ph.x</code> for a dvscf calculation with a standard <code>q</code>-grid matching the <code>k</code>-grid we wanna use in Yambo.

At the end, we will have the <code>_ph0</code> directory containing the variation of the self-consistent potential, <math>\Delta V_{SCF}(q)</math>, and the <code>*.dyn</code> files with the phonon energies and eigenvectors.

NB: one could further refine the phonon energies by enforcing the acoustic sum rule, including non-analytic long-range contributions, interpolating to finer grids... all of this can be done within Quantum ESPRESSO and will not be covered in this version of the tutorial.

The input is <code>mos2.dvscf</code>:

mos2_dvscf
&inputph
tr2_ph=1.0d-12,
verbosity='high'
prefix='mos2',
fildvscf = 'mos2-dvscf',
electron_phonon = 'dvscf',
fildyn='mos2.dyn',
epsil=.false.,
ldisp=.true.,
recover=.true.,
nq1=6,
nq2=6,
nq3=1
/

And now we run as

nohup mpirun -np 8 ph.x -inp mos2.dvscf > dvscf.out &

This time we use nohup and more processes because this calculation may take some time. It is a good idea to set <code>recover=.true.</code> as in a real calculation you will easily breach walltime, and in this way you can safely restart.

== Step 4: create Yambo <code>SAVE</code> directory ==

This is just the standard Yambo initialization: run

p2y

and then

yambo

in the '''nscf''' <code>save</code> folder and then move the newly generated <code>SAVE</code> directory to a convenient place.

== Step 5: run a BSE calculation ==

Now we switch from QE to Yambo. Here, we forgo the GW step for simplicity (we can use a scissor operator to open the band gap).

This calculation has a couple of differences with respect to a standard BSE calculation for optical absorption. We can look at the input file <code>bse.in</code>:

# Runlevels
optics # [R OPT] Optics
rim_cut # [R RIM CUT] Coulomb potential
bss # [R BSS] Bethe Salpeter Equation solver
em1s # [R Xs] Static Inverse Dielectric Matrix
bse # [R BSE] Bethe Salpeter Equation.
bsk # [R BSK] Bethe Salpeter Equation kernel
# RIM and cutoff settings
RandQpts=1000000 # [RIM] Number of random q-points in the BZ
RandGvec= 100 RL # [RIM] Coulomb interaction RS components
CUTGeo= "slab z" # [CUT] Coulomb Cutoff geometry: box/cylinder/sphere X/Y/Z/XY..
# Static screening
X_and_IO_CPU= "1 1 4 2 1" # [PARALLEL] CPUs for each role
X_and_IO_ROLEs= "q g k c v" # [PARALLEL] CPUs roles (q,g,k,c,v)
X_and_IO_nCPU_LinAlg_INV=-1 # [PARALLEL] CPUs for Linear Algebra (if -1 it is automatically set)
Chimod= "hartree" # [X] IP/Hartree/ALDA/LRC/BSfxc
% QpntsRXs
1 | 7 | # [Xs] Transferred momenta
%
% BndsRnXs
1 | 200 | # [Xs] Polarization function bands
%
% LongDrXs
1.000000 | 1.000000 | 1.000000 | # [Xs] [cc] Electric Field
%
NGsBlkXs= 8 Ry # [Xs] Response block size
# BSE
BS_CPU= "4.1.2" # [PARALLEL] CPUs for each role
BS_ROLEs= "k.eh.t" # [PARALLEL] CPUs roles (k,eh,t)
BS_nCPU_diago=4 # [PARALLEL] CPUs for matrix diagonalization
BSEmod= "causal" # [BSE] resonant/causal/coupling
BSKmod= "SEX" # [BSE] IP/Hartree/HF/ALDA/SEX/BSfxc
BSSmod= "d" # [BSS] (h)aydock/(d)iagonalization/(i)nversion/(t)ddft`
BSENGexx= 40000 mRy # [BSK] Exchange components
ALLGexx # [BSS] Force the use use all RL vectors for the exchange part
BSENGBlk= 8000 mRy # [BSK] Screened interaction block size
Lkind="full" #[BSE,X] bar(default)/full/tilde
% KfnQP_E
1.000000 | 1.000000 | 1.000000 | # [EXTQP BSK BSS] E parameters (c/v) eV|adim|adim
%
% BEnRange
0.00000 | 4.00000 | eV # [BSS] Energy range
%
% BDmRange
0.05000 | 0.05000 | eV # [BSS] Damping range
%
BEnSteps= 2000 # [BSS] Energy steps
% BLongDir
1.000000 | 0.000000 | 0.000000 | # [BSS] [cc] Electric Field
%
% BSEQptR
 1 | 7 | # [BSK] Transferred momenta range
%
% BSEBands
25 | 28 | # [BSK] Bands range
%
WRbsWF # [BSS] Write to disk excitonic the FWs

First of all, we compute the excitons for all the momenta in the irreducible Brillouin zone for our discrete grid via the <code>BSEQptR</code> variable. This will be a '''finite-momentum''' BSE calculation, analogous to the phonon one.

Second, we change the variable <code>Lkind</code> from <code>bar</code> to <code>full</code>. In Yambo, <code>Lkind="bar"</code>, which is the default for optical absorption, means that we are computing the excitonic response function without the long-range component of the exchange interaction. This cannot be used when computing the exciton momentum dependence, where the long-range exchange interaction can play a role, therefore we have to include it with <code>Lkind="full"</code>. This allows for the calculation of the excitonic longitudinal-transverse splitting (in 3D systems) as well.

We can now run the code:

nohup mpirun -np 8 yambo -F bse.in -J bse_Lfull -C bse_Lfull &

At the end of the calculation, we have obtained the <code>ndb.BS_diago_Q*</code> databases inside the directory <code>bse_Lfull</code>. They contain information on the exciton energies and wavefunctions at each momentum. Do not forget to check the report and logs of your calculation in the same directory to make sure that the code is doing what you want.

== Step 6: obtain the electron-phonon matrix elements ==

We have finished the heavy simulations. Now it's time for the postprocessing. The first order of business is the reconstruction of the electron-phonon coupling matrix elements from the dvscf results and the electronic wavefunctions.

In order to do this, we will run the <code>lelphc</code> executable of the '''LetzElPhC''' code. We will run via command line using yambopy, although it will be instructive to have look at the <code>lelphc</code> input files later.

We run in the same directory where the Yambo <code>SAVE</code> is (remember than you can also virtually move it with a symbolic link).

Type:

yambopy l2y

to see the help for the calculation. For example, if we want to do a serial run of LetzElPhC for bands from <math>n_i</math> to <math>n_f</math>, we should type:

yambopy l2y -ph path/of/ph_input.in -b n_i n_f

Here <math>n_i</math> and <math>n_f</math> are integers representing the initial and final band indices.

These should coincide with those used for the Bethe-Salpeter kernel, i.e. those specified in the <code>BSEBands</code> variable of the BSE input file (this is not strictly necessary, but certainly efficient since these calculations use a lot of disk space).

For our system, we want to do a parallel calculation with 4 qpools and 2 kpools. In addition, we want to explicitly specify the path of the <code>lelphc</code> executable and avoid automatically deleting the LetzElPhC data. So we type:

yambopy l2y -ph path/of/dvscf/mos2.dvscf -b 25 28 -par 4 2 -lelphc path/to/lelphc_exe --debug

At the end, check the <code>SAVE</code>

ls SAVE/ndb.elph_gkkp*

to see that it has created the Yambo-compatible electron-phonon databases.

If you saved the <code>lelphc.in</code> input file, you can inspect it:

# LetzElPhC input for yambo generated by yambopy
nqpool = 2
nkpool = 4
start_bnd = 25
end_bnd = 28
save_dir = ./SAVE
kernel = dfpt
ph_save_dir = dvscf/ph_save
convention = yambo

You can also run it as it is, but the code will generate the database <code>ndb.elph</code>. In order to convert it to the <code>ndb.elph_gkkp*</code> databases of Yambo, you still need a couple of lines of python using the Yambopy class <code>ConvertElectronPhononDB</code> in <code>yambopy/letzelph_interface/lelph2y.py</code>.

Notice the variable <code>convention=yambo</code>: what does it mean? At variance with QE and many other codes, Yambo uses the "backward" momentum transfer convention for electronic scatterings. That is, an electronic transition goes from band <math>n</math> and momentum <math>k-q</math> to band <math>m</math> and momentum <math>k</math>. In the "forward" momentum transfer convention (the more standard one), the transitions go from <math>nk</math> to <math>mk+q</math>. Therefore, this variable ensures that the electron-phonon coupling matrix elements are computed as <math>\langle mk|dV|nk-q\rangle</math>. This will have consequences also in the formulation of the ''exciton''-phonon coupling matrix element.

== Step 7: Obtain the exciton-phonon coupling ==

Now, we can finally access our basic building block for exciton-phonon physics. This could be done entirely in python (using '''Yambopy'''), or by running '''Yambo'''. In this version of the tutorial we present the latter case.

Our objective is obtaining the following quantity:

<math>\mathcal{G}^\mu_{\alpha\lambda}(0,q)=\sum_{vv^\prime c k} A^{\alpha, *}_{cv^\prime} (k, q) g_{vv^\prime}^\mu (k,q) A^{\lambda}_{cv}(k,q) - \sum_{cc^\prime vk} A^{\alpha, *}_{c^\prime v} (k+q, q) g_{c^\prime c}^\mu (k+q,q) A^{\lambda}_{cv}(k,q)</math>

Here, <math>A^{\lambda}_{cv}(k,q)</math> are the exciton coefficients extracted from the eigenvector of the two-particles Hamiltonian during the BSE calculation in step 5, while <math>g_{nm}^\mu (k,q)</math> are the electron-phonon coupling matrix elements obtained in step 6. As you can see, the exciton <math>\lambda</math> undergoes phonon-mediated scattering to state <math>\alpha</math> via phonon mode <math>\mu</math>. The scattering can happen for the hole (valence, <math>v</math>) or for the electron (conduction, <math>c</math>).

NB:

(1) This is written in the "backward" momentum transfer convention used by Yambo. The momentum dependence is different in the "forward" transfer convention.

(2) For simplicity, this is written for zero initial exciton momentum. This means that one of the two states involved in the phonon-mediated scattering process will be in the optical limit (and possibly an optically generated exciton), while the other state can have any momentum: this momentum will be the same as the phonon one. This matrix element can be used to describe phonon-assisted absorption and emission spectra.

We have to write a new yambo input, that we can call <code>excph.in</code>, for this. You can copy (and adapt) the one below, or you can generate one by running from the command line:

yambo_ph -excph o

This generates an input to compute luminescence ("o" is for "optics"). The variables that we are interested in are:

excph # [R] Exction-phonon
ExcGkkp # [R][EXCPH] Exciton-Phonon Matrix Elelements
% ELPhExcStates
1 | 4 | # [EXCPH] Incoming (external) exciton states
%
% ELPhExcSum
1 | 12 | # [EXCPH] Outgoing (virtual) exciton states
%
LoutPath= "./bse_Lfull" # [EXCPH] Path of the outgoing L
% ElPhModes
1 | 9 | # [ELPH] Phonon modes included
%

In this input, we have to select the initial exciton states <math>\lambda</math> with <code>ELPhExcStates</code>, the final exciton states <math>\alpha</math> with <code>ELPhExcSum</code> and the phonon modes <math>\mu</math> with <code>ElPhModes</code>. Here we consider the first four states at <math>Q=0</math> (corresponding to just two excitons because they are both doubly degenerate -- do not break degeneracies when selecting states!) and the first twelve states at each finite-<math>q</math> point. We also include all the nine phonon modes of monolayer MoS2.

What about <code>LoutPath</code>? This variable controls the directory where the databases for the final-state excitons <math>\alpha</math> is located, which can be different from the directory with the initial-state excitons <math>\lambda</math> read as usual with the <code>-J</code> option when running the code. This makes it possible to compute the coupling between different exciton kinds. However, for our tutorial, we stick with the previously computed <code>Lfull</code> in both cases.

When we are satisfied with the input, we run the code using <code>yambo_ph</code>:

yambo_ph -F excph.in -J excph,bse_Lfull -C excph

If you check the output, you should find the <code>ndb.excph*</code> databases in the <code>excph</code> directory.

=== Analysis of the couplings ===

It is a good idea to have a look at what we computed up to now in order to make sure nothing has gone wrong.

It is not easy to know what to expect (apart from symmetry and gauge compliance of the matrix elements), but one can work out the exciton-phonon selection rules in advance, check that the magnitude is reasonable, etc.

It is also not easy to meaningfully plot this quantity. We have to make sure that we are not breaking degenerate states, otherwise the plots will not be invariant.

First of all, we have to know our system: in monolayer MoS2, the first four excitons are all doubly degenerate. The first exciton responsible for a bright peak in the absorption spectrum (the '''A''' peak), is the second state, corresponding to state indices <code>(3,4)</code> in fortran indexing or <code>(2,3)</code> in python indexing.

All these information can be obtained by analyzing the BSE results (this stuff is explained in the BSE tutorials) and by knowledge of the system or class of systems from the literature.

Thus, a good quantity to plot may be the norm of the matrix elements, summed over the degenerate subspace of exciton A, for a certain number of scattered final states mediated by certain phonon modes:

<math>F_A(q)= \sqrt{ \sum_{\alpha \in A,\lambda,\mu} |\mathcal{G}_{\alpha\lambda}^\mu (0,q)|^2 }</math>

In order to do this, we create a python script <code>analyse_excph.py</code> in which we first load the excph dabatases using the <code>YamboExcitonPhononDB</code> from yambopy.
You can find this script in the yambopy directory, in <code>tutorials/exciton-phonon</code>.
First, we select the exciton and phonon states to be included in <code>F_A</code>, together with the path of databases and plot details:

# Exciton in states
exc_in = [2,3] # A: 2,3 -- B: 6,7
exc_out = [0,1,2,3] # first 4 states (dispersion of triplet state and A)
ph_in = 'all'

# Paths of databases
ns_db1 =f'{path}/SAVE/ns.db1'
ndb_exc=f'{path}/excph'

...

Then, we load the data:

# Read lattice and k-space info
ylat = YamboLatticeDB.from_db_file(filename=ns_db1),Expand=True)
print(ylat)

# Read exc-ph databases
X = YamboExcitonPhononDB(ylat,save_excph=ndb_exc)
print(X)

The quantity <math>F_A(q)</math> is defined inside the plotting function as

G_squared = excph.excph_sq
G2plt = np.zeros(len(G_squared))

if exc_in == 'all': exc_in = range(G_squared.shape[2])
if exc_out == 'all': exc_out = range(G_squared.shape[3])
if ph_in == 'all': ph_in = range(G_squared.shape[1])

G_squared = G_squared[:, ph_in, :, :].sum(axis=(1))
G_squared = G_squared[:, exc_in, :].sum(axis=(1))
G_squared = G_squared[:, exc_out].sum(axis=(1))

F_q = np.sqrt( G_squared )*ha2ev # Switch from Ha to eV

And finally, we have to make a plotting function. For this tutorial we will use the default scatterplot provided by <code>YamboExcitonPhononDB</code>

excph.plot_excph(F_q,plt_cbar=plt_cbar,**kwargs)
...

You can get more experience on using Yambopy for these kinds of visualization by following the [https://wiki.yambo-code.eu/wiki/index.php?title=First_steps_in_Yambopy Yambopy tutorials]. In fact, remember that this scripts and all the other yambopy tutorial scripts are just suggestions, not source code written in stone: if you know <code>numpy</code> and <code>matplotlib</code> you can do your own analysis and your own plots, you just need to import the required Yambopy modules to load the data.

In our case, the resulting plot is the following.

[[File:1L MoS2 ExcPh.png|500px|center]]

This can be checked against Fig. 2(d) of reference <ref name="chan2023" />, although you have to keep in mind that our results are badly undersampled in terms of the reciprocal-space grid, as can be easily seen, and the quantity plotted is not exactly the same. However, the main features are already there since they are dictated mostly by crystal symmetries.

Now that we have the exciton-phonon matrix elements, we can use them to build several kinds of observables. Below, we give an example related to phonon-assisted luminescence, but we may update this tutorial in the future to include more cases.

== Step 8: Compute phonon-assisted luminescence ==

[[File:Luminescence scheme.png|250px|right]]

We want to compute the experimental optical signature due to the phonon-assisted recombination of an exciton (as sketched in the figure).

The signal from the phonon replicas can be modeled as a second-order scattering process involving one phonon and one photon:

<math>I^{(1)}_{PL}(\omega;T) \propto \frac{1}{N_q}\sum_{ s \mu \beta q} \left|\sum_\lambda\frac{D_\lambda \mathcal{G}^{\mu q}_{\alpha q,\lambda}}{E_{\alpha q}-E_\lambda -s\Omega_{\mu q}} \right|^2 N_{\alpha q}(T_{exc}) F^s_{\mu q}(T)\delta(\omega - \left[E_{\alpha q}-s\Omega_{\mu q}\right])</math>

In this equation, the oscillator strength of the peak is given by the exciton-phonon coupling matrix elements <math>\mathcal{G}</math> multiplied by the exciton dipoles <math>D</math> (they are called "residuals" in Yambo). Here <math>E_\lambda</math> and <math>E_{\alpha q}</math> are the energies of the optical and finite-momentum excitons, respectively, while <math>\Omega_{\mu q}</math> are the phonon energies.

The occupation function <math>F</math> is <math>F^s_{\mu q}(T)=n_{\mu q}(T)+\frac{1+s}{2}</math>. Here, <math>n(T)</math> is the temperature-dependent phonon Bose-Einstein occupation function. As it can be seen, <math>s=1</math> corresponds to processes of phonon ''emission'' (<math>\propto n(T)+1</math>), while <math>s=-1</math> corresponds to processes of phonon ''absorption'' (<math>\propto n(T)</math>). Therefore, <math>I^{(1)}_{PL}(\omega;T)</math> describes ''light'' emission by recombining excitons mediated by either ''phonon'' absorption or emission.

The quantity <math> N_{\alpha q}(T_{exc})</math> is the exciton occupation function. Luminescence is technically an out-of-equilibrium process, but we can assume that for very low density of excitations and in steady-state conditions, the exciton population can be approximately described by an equilibrium distribution evaluated at an effective temperature. Here, we use the Boltzmann distribution. Experimentally, <math>T_{exc}</math> tends to coincide with the lattice temperature <math>T</math> more or less above 100 K, while at very low temperature (< 10 K), <math>T_{exc}</math> may vary between 10-50 K. It goes without saying that this needs to carefully be checked in your realistic calculations.

=== Running the jobs ===

In order to study luminescence in a paradigmatic system, we switch to bulk hexagonal boron nitride and we repeat the workflow. As you can easily see, one can think about automatizing the execution of all these calculations via scripting or more advanced tools. However, in the case of very large simulations (memory-limited or disk-space limited) or for systems whose electronic and lattice properties are fragile with respect to tiny calculation details, one must be very careful and run many basic tests.

Fortunately, we are running a fast underconverged example. We use LDA pseudopotentials from the pseudo-dojo library and the following are the calculations steps.

1. Input <code>hbn.scf</code>:

&control
calculation='scf',
prefix='hBN',
restart_mode='from_scratch'
pseudo_dir = '$PSEUDO_DIR',
outdir = './tmp'
verbosity = 'high'
wf_collect=.true.
/
&system
ibrav = 4,
celldm(1) = 4.703675849
celldm(3) = 2.603711434
nat= 4,
ntyp= 2,
force_symmorphic=.true.
ecutwfc = 100,
/
&electrons
diago_david_ndim = 2
diago_full_acc=.true.
diago_thr_init=5.0e-6
mixing_mode = 'plain'
mixing_beta = 0.7
conv_thr = 1.0d-16
/
ATOMIC_SPECIES
B 10.81100 B_LDA_dojo.UPF
N 14.00674 N_LDA_dojo.UPF
ATOMIC_POSITIONS {crystal}
N 0.6666666670 0.3333333330 -0.250000000000
B 0.3333333330 0.6666666670 -0.250000000000
B 0.6666666670 0.3333333330 0.25000000000
N 0.3333333330 0.6666666670 0.25000000000
K_POINTS {automatic}
6 6 2 0 0 0

mpirun -np 4 pw.x -inp hbn.scf > scf.out

2. Input <code>hbn.nscf</code>:

&control
calculation='nscf',
prefix='hBN',
restart_mode='from_scratch'
pseudo_dir = '$PSEUDO_DIR'
outdir = './'
verbosity = 'high'
wf_collect=.true.
/
&system
ibrav = 4,
celldm(1) = 4.703675849
celldm(3) = 2.603711434
nat= 4,
ntyp= 2,
force_symmorphic=.true.
ecutwfc = 100,
nbnd = 120
/
&electrons
diago_david_ndim = 2
diago_full_acc=.true.
diago_thr_init=5.0e-6
mixing_mode = 'plain'
mixing_beta = 0.7
conv_thr = 1.0d-16
/
ATOMIC_SPECIES
B 10.81100 B_LDA_dojo.UPF
N 14.00674 N_LDA_dojo.UPF
ATOMIC_POSITIONS {crystal}
N 0.6666666670 0.3333333330 -0.250000000000
B 0.3333333330 0.6666666670 -0.250000000000
B 0.6666666670 0.3333333330 0.25000000000
N 0.3333333330 0.6666666670 0.25000000000
K_POINTS {automatic}
6 6 2 0 0 0

mpirun -np 4 pw.x -inp hbn.nscf > nscf.out

3. Input <code>hbn.dvscf</code>:

hbn_dvscf
&inputph
tr2_ph=1.0d-12,
verbosity='high'
prefix='hBN',
fildvscf = 'hBN-dvscf',
electron_phonon = 'dvscf',
fildyn='hBN.dyn',
epsil=.false.,
ldisp=.true.,
recover=.true.,
nq1=6,
nq2=6,
nq3=2
/

nohup mpirun -np 8 pw.x -inp hbn.dvscf > dvscf.out &

4. Input <code>bse.in</code> (we include 2 valence and 2 conduction bands):

optics # [R] Linear Response optical properties
bss # [R] BSE solver
bse # [R][BSE] Bethe Salpeter Equation.
dipoles # [R] Oscillator strenghts (or dipoles)
em1s
DIP_CPU= "1 8 1" # [PARALLEL] CPUs for each role
DIP_ROLEs= "k c v" # [PARALLEL] CPUs roles (k,c,v)
DIP_Threads=0 # [OPENMP/X] Number of threads for dipoles
X_and_IO_CPU= "1 1 1 8 1" # [PARALLEL] CPUs for each role
X_and_IO_ROLEs= "q g k c v" # [PARALLEL] CPUs roles (q,g,k,c,v)
X_and_IO_nCPU_LinAlg_INV=-1 # [PARALLEL] CPUs for Linear Algebra (if -1 it is automatically set)
X_Threads=0 # [OPENMP/X] Number of threads for response functions
BS_CPU= "8 1 1" # [PARALLEL] CPUs for each role
BS_ROLEs= "k eh t" # [PARALLEL] CPUs roles (k,eh,t)
BS_nCPU_LinAlg_INV=-1 # [PARALLEL] CPUs for Linear Algebra (if -1 it is automatically set)
BS_nCPU_LinAlg_DIAGO=-1 # [PARALLEL] CPUs for Linear Algebra (if -1 it is automatically set)
X_Threads=0 # [OPENMP/X] Number of threads for response functions
K_Threads=0 # [OPENMP/BSK] Number of threads for response functions
% QpntsRXs
1 | 14 | # [Xs] Transferred momenta
%
% BndsRnXs
1 | 120 | # [Xs] Polarization function bands
%
NGsBlkXs= 10 Ry # [Xs] Response block size
% LongDrXs
1.000000 | 1.000000 | 1.000000 | # [Xs] [cc] Electric Field
%
BSEmod= "resonant" # [BSE] resonant/retarded/coupling
BSKmod= "SEX" # [BSE] IP/Hartree/HF/ALDA/SEX/BSfxc
Lkind= "Lfull" # [BSE] Lbar (default) / full
BSSmod= "d" # [BSS] (h)aydock/(d)iagonalization/(s)lepc/(i)nversion/(t)ddft`
% DipBands
1 | 120 | # [DIP] Bands range for dipoles
%
DipApproach= "G-space v" # [DIP] [G-space v/R-space x/Covariant/Shifted grids]
DipComputed= "R V P" # [DIP] [default R P V; extra P2 Spin Orb]
BSENGexx= 30000 Ry # [BSK] Exchange components
#ALLGexx # [BSS] Force the use use all RL vectors for the exchange part
BSENGBlk= 9000 Ry # [BSK] Screened interaction block size [if -1 uses all the G-vectors of W(q,G,Gp)]
% KfnQP_E
1.25997 | 1.08816 | 1.12683 | # [EXTQP BSK BSS] E parameters (c/v) eV|adim|adim
%
% BSEQptR
 1 | 14 | # [BSK] Transferred momenta range
%
% BSEBands
 7 | 10 | # [BSK] Bands range
%
% BEnRange
0.50000 | 8.00000 | eV # [BSS] Energy range
%
% BDmRange
0.050000 | 0.050000 | eV # [BSS] Damping range
%
BEnSteps= 1000 # [BSS] Energy steps
% BLongDir
1.000000 | 1.000000 | 0.000000 | # [BSS] [cc] Electric Field
%
WRbsWF # [BSS] Write to disk excitonic the WFs

nohup mpirun -np 8 yambo -F bse.in -J bse_Lfull -C bse_Lfull &

Importantly, since we want to describe the phonon-assisted recombination process of an *optical* exciton (i.e., emitting a transverse photon), this time we also run an additional calculation at `Q=0` omitting the nonanalytic long-range Coulomb exchange. Make a second input <code>bse_Lbar.in</code> with the following changes:

Lkind= "Lbar" # [BSE] Lbar (default) / full
% BSEQptR
 1 | 1 | # [BSK] Transferred momenta range
%

4b. So now we make a second BSE run in a different directory specified by <code>-J</code>. Here, we also pass to yambo the directory of the previous run as it includes the important screening databases <code>ndb.em1s*</code> that we do not want to recompute from scratch.

mpirun -np 8 yambo -F bse_Lbar.in -J bse_Lbar,bse_Lfull -C bse_Lbar

5. Now we run <code>lelphc</code> with yambopy to get the el-ph matrix elements:

yambopy l2y -ph path/of/dvscf/hbn.dvscf -b 7 10 -par 4 2

6. And finally we generate the exciton-phonon input <code>excph.in</code> using <code>yambo_ph -excph o</code>. Now, we take a look at all the additional variables that we didn't check before, specifying also the details for luminescence the spectrum calculation.

excph # [R] Exction-phonon
ExcGkkp # [R][EXCPH] Exciton-Phonon Matrix Elelements
ExcPhOptics # [R][EXCPH] Exciton-Phonon Optics
BoseTemp=10.000000 Kn # Bosonic Temperature
EXCTemp= 10.000000 Kn # [EXCPH] Excitonic Temperature (for luminescence spectra)
% ELPhExcStates
1 | 4 | # [EXCPH] Incoming (external) exciton states
%
% ELPhExcSum
1 | 12 | # [EXCPH] Outgoing (virtual) exciton states
%
% ElPhModes
1 | 12 | # [ELPH] Phonon modes included
%
LoutPath= "./bse-L_full" # [EXCPH] Path of the outgoing L
FANdEtresh= 0.100000E-5 eV # [ELPH] Energy treshold for Fan denominator
EXCPHdEtresh= 0.100000E-5 eV # [ELPH] Energy treshold for exc-ph denominator
LDamping= 0.500000E-3 eV # [EXCPH] Damping of exc-ph self-energy
# These are the plot parameters, same as in other parts of yambo
% EnRngeXd
4.00000 | 5.00000 | eV # [Xd] Energy range
%
% DmRngeXd
0.00500000 | 0.00500000 | eV # [Xd] Damping range
%
ETStpsXd= 4000 # [Xd] Total Energy steps

Here <code>BoseTemp</code> and <code>EXCTemp</code> are the lattice and excitonic temperature, respectively.

Now we run the calculation with <code>yambo_ph</code>. Here, we read as <math>Q=0</math> excitons with <code>-J</code> the ones without the long-range Coulomb exchange:

yambo_ph -F excph.in -J excph,bse_Lbar -C excph

and we find our outputs in the <code>excph</code> directory.

NB: Step 6 could have been equivalently run in yambopy, limiting the use of the yambo code to just step 4. This latter option is more flexible, as it allows for a greater degree of control by the user. We are in the last stages of the development and it will be available soon.

=== Results ===

If we check the output directory from the step 6 calculation, we find the <code>o-excph.pl_bse_ph_ass</code> output files containing the luminescence spectra. We can plot them with gnuplot or any other tool:

gnuplot
> set xrange[4.2:5]
> p 'o-excph.pl_bse_ph_ass' u 1:2 w l lc rgb 'red' lw 3

[[File:Luminescence plot.png|500px|center]]

Here, the signal corresponds to a finite-momentum exciton that recombines with the help of several different phonon modes, both optical and acoustic. Each phonon mode whose coupling with the exciton is allowed can generate a peak, and the energy shifts of these peaks with respect to the initial exciton energy correspond to the phonon energies. This result is underconverged, but the main features are all there. In the plot, we show a more converged example using a 12x12x4 grid (all the other parameters being equal). These plots can be compared with Fig. 4(a) of reference <ref name="zanfrognini2023" />.

== References ==

<references>
<ref name="toyozawa2003" >[https://m.booksee.org/book/1121964?force_lang=en Optical processes in solids], Toyozawa, Yutaka, and Chris Oxlade. Cambridge University Press, (2003). </ref>
<ref name='lechifflart2023'>P. Lechifflart, F. Paleari, D. Sangalli, C. Attaccalite, ''First-principles study of luminescence in hexagonal boron nitride single layer: Exciton-phonon coupling and the role of substrate'',
[https://doi.org/10.1103/PhysRevMaterials.7.024006 Phys. Rev. M, '''7''' (2), 024006 (2023)]; [https://arxiv.org/abs/2212.10407 arXiv2212.1047]</ref>
<ref name='cannuccia2019'>E. Cannuccia, B. Monserrat and C. Attaccalite, ''Theory of phonon-assisted luminescence in solids: Application to hexagonal boron nitride'', [https://doi.org/10.1103/PhysRevB.99.081109 Phys. Rev. B '''99''', 081109(R) (2019)]; [https://arxiv.org/abs/1807.11797 arXiv1807.11797]</ref>
<ref name='paleari2019'>F. Paleari et al., ''Exciton-Phonon Coupling in the Ultraviolet Absorption and Emission Spectra of Bulk Hexagonal Boron Nitride'', [https://doi.org/10.1103/PhysRevLett.122.187401 Phys. Rev. Lett. '''122''', 187401 (2019)]; [https://arxiv.org/abs/1810.08976 arXiv1810.089776] </ref>
<ref name='chen2020'>''Exciton-Phonon Interaction and Relaxation Times from First Principles'',
Hsiao-Yi Chen, Davide Sangalli, and Marco Bernardi, [https://doi.org/10.1103/PhysRevLett.125.107401 Phys. Rev. Lett. '''125''', 107401 (2020)]; [https://arxiv.org/abs/2002.08913 arXiv 2002.08913 (2020)]</ref>
<ref name="lechifflart2023_PhD">[https://www.yambo-code.eu/wiki/images/5/54/These_final.pdf Exciton-phonon coupling and phonon-assisted luminescence in hexagonal Boron Nitride nanostructures], PhD Thesis, Pierre Lechifflart (2023)</ref>
<ref name='paleari2019_PhD'>F. Paleari, ''First-principles approaches to the description of indirect absorption and luminescence spectroscopy: exciton-phonon coupling in hexagonal boron nitride'', [https://wwwen.uni.lu/research/fstm/dphyms/people/fulvio_paleari PhD thesis, University of Luxembourg (2019)]</ref>
<ref name='zanfrognini2023'>[https://arxiv.org/abs/2305.17554 Distinguishing different stackings in layered materials via luminescence spectroscopy], M. Zanfrognini et al. Phys. Rev. Lett. '''131''', 206902 (2023) </ref>
<ref name='marini2024'>G. Marini, M. Calandra, P. Cudazzo, ''Optical absorption and photoluminescence of single layer boron nitride from a first principles cumulant approach'', [https://doi.org/10.1021/acs.nanolett.4c00669 Nano Lett., '''24''', 20, 6017 (2024)]; [https://arxiv.org/abs/2402.03826 arXiv 2402.03826 (2024)]</ref>
<ref name='antonius2017'>G. Antonius, S. G. Louie, ''Theory of exciton-phonon coupling'', [https://doi.org/10.1103/PhysRevB.105.085111 Phys. Rev. B, '''105''', 085111 (2022)]; [https://arxiv.org/abs/1705.04245 arXiv1705.04245 (2017)]</ref>
<ref name='paleari2022'>[https://arxiv.org/abs/2205.02783 Exciton-phonon interaction calls for a revision of the “exciton” concept], F. Paleari, A. Marini, Phys. Rev. B, '''106''', 125403 (2022)</ref>
<ref name='cudazzo2020'> P. Cudazzo, ''First-principles description of the exciton-phonon interaction: A cumulant approach'', [https://doi.org/10.1103/PhysRevB.102.045136 Phys. Rev. B, '''102''', 045136 (2020)]; [https://orbilu.uni.lu/bitstream/10993/44769/1/main.pdf Open access pdf from Luxembourg University]</ref>
<ref name='chan2023'>Y-h Chan, J. B. Haber, M. H. Naik, J. B. Neaton, D. Y. Qiu, F. H. da Jornada, S. G. Louie, ''Exciton Lifetime and Optical Line Width Profile via Exciton–Phonon Interactions: Theory and First-Principles Calculations for Monolayer MoS2'', [https://doi.org/10.1021/acs.nanolett.3c00732 Nano Lett., '''23''', 9 (2023)]; [https://arxiv.org/abs/2212.08451 arXiv 2212.08451 (2023)]</ref>
<ref name='murali2025'>M. Nalabothula, S. Reichardt, L. Wirtz, ''Origin of Interlayer Exciton–Phonon Coupling in 2D Heterostructures'', [https://doi.org/10.1021/acs.nanolett.5c00355 Nano Lett., '''25''', 15 (2025)], [https://arxiv.org/abs/2407.16111 arXiv 2407.16111 (2025)]</ref>
</references>

Exciton-phonon coupling and luminescence

2025-10-06T11:38:46Z

Attacc: /* Step 5: run a BSE calculation */

[[File:Tdgw-phonon-usc-01-1024x829.jpg| 400px | right]]

In this advanced tutorial, we will calculate exciton-phonon interactions from first principles by interfacing DFPT (for phonon calculations) and BSE (for exciton calculations).

The DFTP calculations are run with Quantum ESPRESSO, while the many-body GW-BSE calculations are run with Yambo. Finally, the exciton-phonon interaction will be obtained by combining and postprocessing the databases computed in the two previous runs. The great advantage of this workflow is that the calculations can be run in the irreducible Brillouin zones both for the electronic momenta (<math>k</math>) and the transfer momenta (<math>Q</math>, <math>q</math>) of excitons and phonons, thus speeding up considerably the jobs while reducing the IO and memory load.

We will first compute the exciton-phonon coupling matrix elements: these are the building blocks needed to construct experimental observables such as phonon-assisted optical spectra (such as luminescence), Raman spectra and exciton lifetimes. We will do this in the case of monolayer MoS2, a 2D system with large spin-orbit interaction.

As an example of application, we will consider the case of phonon-assisted luminescence. We will do this in the case of bulk hBN, a layered indirect insulator with strong electron-phonon coupling.

'''Note:''' this tutorial will be updated when new exc-ph tools become available in Yambopy (including full-python postprocessing, Raman spectra, interpolated lifetimes, etc).

== Requirements ==

This is an advanced topic: we assume that you already know something about the theory<ref name="toyozawa2003" /><ref name="antonius2017" /><ref name="cudazzo2020" /><ref name="paleari2019_PhD" /><ref name="paleari2022" /><ref name="lechifflart2023_PhD" /> and applications<ref name="paleari2019" /><ref name="cannuccia2019" /><ref name="chen2020" /><ref name="zanfrognini2023" /><ref name="lechifflart2023" /><ref name="chan2023" /><ref name="marini2024" /><ref name="murali2025" /> of exciton-phonon physics.

Also, we assume that you already know how to run both a basic '''Yambo''' GW-BSE calculation and a DFPT phonon calculation with '''Quantum ESPRESSO'''.

Besides the QE executables <code>pw.x</code> and <code>ph.x</code>, we also use the yambo phonon-specific executable <code>yambo_ph</code> and the python utility '''Yambopy'''. The auxiliary code '''LetzElPhC''' (executable <code>lelphc</code>) will be used to obtain the electron-phonon matrix elements by reading the same electronic wavefunctions used by Yambo (and stored in the <code>SAVE</code> directory), while also making full use of crystal symmetries. [https://gitlab.com/lumen-code/LetzElPhC LetzElPhC] will be run by Yambopy, but it must nonetheless be installed. Finally, the exciton-phonon properties can be computed either using <code>yambo_ph</code> or using Yambopy itself.

[[File:Workflow scheme.png|800px|center]]

== Step 0: Pseudopotentials, equilibrium structure and convergence ==

In a real calculation, it is important to ensure that both the pseudopotential and the lattice parameters that we are using are compatible and perform well for the electronic excited states and for the lattice vibrations simultaneously. Furthermore, you have to make sure that the wave function cutoff <code>ecutwfc</code> is converged with respect to the DFPT step and not just to the DFT one. This is in addition to the other customary convergence tests for DFT, DFPT, GW and BSE calculations.

This is often the most time-demanding step when starting on a new system.

For the sake of this tutorial, we assume that we have already done all these tests and we are starting the final workflow to get the exciton-phonon properties.

== Step 1: scf calculation ==

First of all, we run a standard scf calculation with <code>pw.x</code> for Yambo. We stick with non-symmorphic symmetries. At the end, we will have the QE <code>save</code> directory.

This is the input <code>mos2.scf</code>:

&control
wf_collect = .true.,
calculation = "scf",
verbosity = 'high',
pseudo_dir = '$PSEUDO_DIR',
prefix = "mos2",
outdir = '.',
/&end
&system
ecutwfc = 100.0,
occupations = 'fixed',
ibrav = 4,
celldm(1) = 5.9000811881,
celldm(3) = 6.7795677253,
nat = 3,
ntyp = 2,
lspinorb = .true.
noncolin = .true.
assume_isolated = '2D'
force_symmorphic = .true.
/&end
&electrons
electron_maxstep = 200,
mixing_beta = 0.7,
conv_thr = 1.d-08,
/&end
ATOMIC_SPECIES
Mo 95.940 Mo_ONCV_PBE_FR-1.0.upf
S 32.065 S_ONCV_PBE_FR-1.1.upf
ATOMIC_POSITIONS { crystal }
Mo 0.333333333 0.666666667 0.000000000
S 0.666666667 0.333333333 0.073413577
S 0.666666667 0.333333333 -0.073413577
K_POINTS { automatic }
6 6 1 0 0 0

Here we are using full relativistic pseudopotentials from the SG-15 database.

We can run it on our machine (for example using 4 MPI tasks) as:

mpirun -np 4 pw.x -inp mos2.scf > scf.out

== Step 2: nscf calculation for Yambo ==

Copy the QE <code>save</code> directory from the scf calculation and run the nscf calculation for any number of empty states, with the correct <code>k</code>-grid we want to use in Yambo. Here we are using a badly underconverged grid of 6x6x1.

This reciprocal-space grid will also match the momentum transfer <code>q</code> grid on which excitons and phonons will be defined!

The electronic wavefunctions computed at this step and stored in the new nscf <code>save</code> directory will be used both by Yambo and by the electron-phonon code: this is important because using different sets of wavefunctions would lead to a phase mismatch issue in the exciton-phonon matrix elements.

The nscf input <code>mos2.nscf</code> is
&control
wf_collect = .true.,
calculation = "nscf",
verbosity = 'high',
pseudo_dir = '$PSEUDO_DIR',
prefix = "mos2",
outdir = '.',
/&end
&system
ecutwfc = 100.0,
occupations = 'fixed',
ibrav = 4,
celldm(1) = 5.9000811881,
celldm(3) = 6.7795677253,
nat = 3,
ntyp = 2,
lspinorb = .true.
noncolin = .true.
nbnd = 250
assume_isolated = '2D'
force_symmorphic = .true.
/&end
&electrons
electron_maxstep = 200,
mixing_beta = 0.7,
conv_thr = 1.d-08,
/&end
ATOMIC_SPECIES
Mo 95.940 Mo_ONCV_PBE_FR-1.0.upf
S 32.065 S_ONCV_PBE_FR-1.1.upf
ATOMIC_POSITIONS { crystal }
Mo 0.333333333 0.666666667 0.000000000
S 0.666666667 0.333333333 0.073413577
S 0.666666667 0.333333333 -0.073413577
K_POINTS { automatic }
6 6 1 0 0 0

Again, we run the calculation

mpirun -np 4 pw.x -inp mos2.nscf > nscf.out

== Step 3: dvscf phonon calculation ==

Now we run the phonon calculation.

Copy the <code>save</code> directory from the '''scf''' calculation and run <code>ph.x</code> for a dvscf calculation with a standard <code>q</code>-grid matching the <code>k</code>-grid we wanna use in Yambo.

At the end, we will have the <code>_ph0</code> directory containing the variation of the self-consistent potential, <math>\Delta V_{SCF}(q)</math>, and the <code>*.dyn</code> files with the phonon energies and eigenvectors.

NB: one could further refine the phonon energies by enforcing the acoustic sum rule, including non-analytic long-range contributions, interpolating to finer grids... all of this can be done within Quantum ESPRESSO and will not be covered in this version of the tutorial.

The input is <code>mos2.dvscf</code>:

mos2_dvscf
&inputph
tr2_ph=1.0d-12,
verbosity='high'
prefix='mos2',
fildvscf = 'mos2-dvscf',
electron_phonon = 'dvscf',
fildyn='mos2.dyn',
epsil=.false.,
ldisp=.true.,
recover=.true.,
nq1=6,
nq2=6,
nq3=1
/

And now we run as

nohup mpirun -np 8 ph.x -inp mos2.dvscf > dvscf.out &

This time we use nohup and more processes because this calculation may take some time. It is a good idea to set <code>recover=.true.</code> as in a real calculation you will easily breach walltime, and in this way you can safely restart.

== Step 4: create Yambo <code>SAVE</code> directory ==

This is just the standard Yambo initialization: run

p2y

and then

yambo

in the '''nscf''' <code>save</code> folder and then move the newly generated <code>SAVE</code> directory to a convenient place.

== Step 5: run a BSE calculation ==

Now we switch from QE to Yambo. Here, we forgo the GW step for simplicity (we can use a scissor operator to open the band gap).

This calculation has a couple of differences with respect to a standard BSE calculation for optical absorption. We can look at the input file <code>bse.in</code>:

# Runlevels
optics # [R OPT] Optics
rim_cut # [R RIM CUT] Coulomb potential
bss # [R BSS] Bethe Salpeter Equation solver
em1s # [R Xs] Static Inverse Dielectric Matrix
bse # [R BSE] Bethe Salpeter Equation.
bsk # [R BSK] Bethe Salpeter Equation kernel
# RIM and cutoff settings
RandQpts=1000000 # [RIM] Number of random q-points in the BZ
RandGvec= 100 RL # [RIM] Coulomb interaction RS components
CUTGeo= "slab z" # [CUT] Coulomb Cutoff geometry: box/cylinder/sphere X/Y/Z/XY..
# Static screening
X_and_IO_CPU= "1 1 4 2 1" # [PARALLEL] CPUs for each role
X_and_IO_ROLEs= "q g k c v" # [PARALLEL] CPUs roles (q,g,k,c,v)
X_and_IO_nCPU_LinAlg_INV=-1 # [PARALLEL] CPUs for Linear Algebra (if -1 it is automatically set)
Chimod= "hartree" # [X] IP/Hartree/ALDA/LRC/BSfxc
% QpntsRXs
1 | 7 | # [Xs] Transferred momenta
%
% BndsRnXs
1 | 200 | # [Xs] Polarization function bands
%
% LongDrXs
1.000000 | 1.000000 | 1.000000 | # [Xs] [cc] Electric Field
%
NGsBlkXs= 8 Ry # [Xs] Response block size
# BSE
BS_CPU= "4.1.2" # [PARALLEL] CPUs for each role
BS_ROLEs= "k.eh.t" # [PARALLEL] CPUs roles (k,eh,t)
BS_nCPU_diago=4 # [PARALLEL] CPUs for matrix diagonalization
BSEmod= "causal" # [BSE] resonant/causal/coupling
BSKmod= "SEX" # [BSE] IP/Hartree/HF/ALDA/SEX/BSfxc
BSSmod= "d" # [BSS] (h)aydock/(d)iagonalization/(i)nversion/(t)ddft`
BSENGexx= 40000 mRy # [BSK] Exchange components
ALLGexx # [BSS] Force the use use all RL vectors for the exchange part
BSENGBlk= 8000 mRy # [BSK] Screened interaction block size
Lkind="full" #[BSE,X] bar(default)/full/tilde
% KfnQP_E
1.000000 | 1.000000 | 1.000000 | # [EXTQP BSK BSS] E parameters (c/v) eV|adim|adim
%
% BEnRange
0.00000 | 4.00000 | eV # [BSS] Energy range
%
% BDmRange
0.05000 | 0.05000 | eV # [BSS] Damping range
%
BEnSteps= 2000 # [BSS] Energy steps
% BLongDir
1.000000 | 0.000000 | 0.000000 | # [BSS] [cc] Electric Field
%
% BSEQptR
 1 | 7 | # [BSK] Transferred momenta range
%
% BSEBands
25 | 28 | # [BSK] Bands range
%
WRbsWF # [BSS] Write to disk excitonic the FWs

First of all, we compute the excitons for all the momenta in the irreducible Brillouin zone for our discrete grid via the <code>BSEQptR</code> variable. This will be a '''finite-momentum''' BSE calculation, analogous to the phonon one.

Second, we change the variable <code>Lkind</code> from <code>bar</code> to <code>full</code>. In Yambo, <code>Lkind="bar"</code>, which is the default for optical absorption, means that we are computing the excitonic response function without the long-range component of the exchange interaction. This cannot be used when computing the exciton momentum dependence, where the long-range exchange interaction can play a role, therefore we have to include it with <code>Lkind="full"</code>. This allows for the calculation of the excitonic longitudinal-transverse splitting (in 3D systems) as well.

We can now run the code:

nohup mpirun -np 8 yambo -F bse.in -J bse_Lfull -C bse_Lfull &

At the end of the calculation, we have obtained the <code>ndb.BS_diago_Q*</code> databases inside the directory <code>bse_Lfull</code>. They contain information on the exciton energies and wavefunctions at each momentum. Do not forget to check the report and logs of your calculation in the same directory to make sure that the code is doing what you want.

== Step 6: obtain the electron-phonon matrix elements ==

We have finished the heavy simulations. Now it's time for the postprocessing. The first order of business is the reconstruction of the electron-phonon coupling matrix elements from the dvscf results and the electronic wavefunctions.

In order to do this, we will run the <code>lelphc</code> executable of the '''LetzElPhC''' code. We will run via command line using yambopy, although it will be instructive to have look at the <code>lelphc</code> input files later.

We run in the same directory where the Yambo <code>SAVE</code> is (remember than you can also virtually move it with a symbolic link).

Type:

yambopy l2y

to see the help for the calculation. For example, if we want to do a serial run of LetzElPhC for bands from <math>n_i</math> to <math>n_f</math>, we should type:

yambopy l2y -ph path/of/ph_input.in -b n_i n_f

Here <math>n_i</math> and <math>n_f</math> are integers representing the initial and final band indices.

These should coincide with those used for the Bethe-Salpeter kernel, i.e. those specified in the <code>BSEBands</code> variable of the BSE input file (this is not strictly necessary, but certainly efficient since these calculations use a lot of disk space).

For our system, we want to do a parallel calculation with 4 qpools and 2 kpools. In addition, we want to explicitly specify the path of the <code>lelphc</code> executable and avoid automatically deleting the LetzElPhC data. So we type:

yambopy l2y -ph path/of/dvscf/mos2.dvscf -b 25 28 -par 4 2 -lelphc path/to/lelphc_exe --debug

At the end, check the <code>SAVE</code>

ls SAVE/ndb.elph_gkkp*

to see that it has created the Yambo-compatible electron-phonon databases.

If you saved the <code>lelphc.in</code> input file, you can inspect it:

# LetzElPhC input for yambo generated by yambopy
nqpool = 2
nkpool = 4
start_bnd = 25
end_bnd = 28
save_dir = ./SAVE
kernel = dfpt
ph_save_dir = dvscf/ph_save
convention = yambo

You can also run it as it is, but the code will generate the database <code>ndb.elph</code>. In order to convert it to the <code>ndb.elph_gkkp*</code> databases of Yambo, you still need a couple of lines of python using the Yambopy class <code>ConvertElectronPhononDB</code> in <code>yambopy/letzelph_interface/lelph2y.py</code>.

Notice the variable <code>convention=yambo</code>: what does it mean? At variance with QE and many other codes, Yambo uses the "backward" momentum transfer convention for electronic scatterings. That is, an electronic transition goes from band <math>n</math> and momentum <math>k-q</math> to band <math>m</math> and momentum <math>k</math>. In the "forward" momentum transfer convention (the more standard one), the transitions go from <math>nk</math> to <math>mk+q</math>. Therefore, this variable ensures that the electron-phonon coupling matrix elements are computed as <math>\langle mk|dV|nk-q\rangle</math>. This will have consequences also in the formulation of the ''exciton''-phonon coupling matrix element.

== Step 7: Obtain the exciton-phonon coupling ==

Now, we can finally access our basic building block for exciton-phonon physics. This could be done entirely in python (using '''Yambopy'''), or by running '''Yambo'''. In this version of the tutorial we present the latter case.

Our objective is obtaining the following quantity:

<math>\mathcal{G}^\mu_{\alpha\lambda}(0,q)=\sum_{vv^\prime c k} A^{\alpha, *}_{cv^\prime} (k, q) g_{vv^\prime}^\mu (k,q) A^{\lambda}_{cv}(k,q) - \sum_{cc^\prime vk} A^{\alpha, *}_{c^\prime v} (k+q, q) g_{c^\prime c}^\mu (k+q,q) A^{\lambda}_{cv}(k,q)</math>

Here, <math>A^{\lambda}_{cv}(k,q)</math> are the exciton coefficients extracted from the eigenvector of the two-particles Hamiltonian during the BSE calculation in step 5, while <math>g_{nm}^\mu (k,q)</math> are the electron-phonon coupling matrix elements obtained in step 6. As you can see, the exciton <math>\lambda</math> undergoes phonon-mediated scattering to state <math>\alpha</math> via phonon mode <math>\mu</math>. The scattering can happen for the hole (valence, <math>v</math>) or for the electron (conduction, <math>c</math>).

NB:

(1) This is written in the "backward" momentum transfer convention used by Yambo. The momentum dependence is different in the "forward" transfer convention.

(2) For simplicity, this is written for zero initial exciton momentum. This means that one of the two states involved in the phonon-mediated scattering process will be in the optical limit (and possibly an optically generated exciton), while the other state can have any momentum: this momentum will be the same as the phonon one. This matrix element can be used to describe phonon-assisted absorption and emission spectra.

We have to write a new yambo input, that we can call <code>excph.in</code>, for this. You can copy (and adapt) the one below, or you can generate one by running from the command line:

yambo_ph -excph o

This generates an input to compute luminescence ("o" is for "optics"). The variables that we are interested in are:

excph # [R] Exction-phonon
ExcGkkp # [R][EXCPH] Exciton-Phonon Matrix Elelements
% ELPhExcStates
1 | 4 | # [EXCPH] Incoming (external) exciton states
%
% ELPhExcSum
1 | 12 | # [EXCPH] Outgoing (virtual) exciton states
%
LoutPath= "./bse_Lfull" # [EXCPH] Path of the outgoing L
% ElPhModes
1 | 9 | # [ELPH] Phonon modes included
%

In this input, we have to select the initial exciton states <math>\lambda</math> with <code>ELPhExcStates</code>, the final exciton states <math>\alpha</math> with <code>ELPhExcSum</code> and the phonon modes <math>\mu</math> with <code>ElPhModes</code>. Here we consider the first four states at <math>Q=0</math> (corresponding to just two excitons because they are both doubly degenerate -- do not break degeneracies when selecting states!) and the first twelve states at each finite-<math>q</math> point. We also include all the nine phonon modes of monolayer MoS2.

What about <code>LoutPath</code>? This variable controls the directory where the databases for the final-state excitons <math>\alpha</math> is located, which can be different from the directory with the initial-state excitons <math>\lambda</math> read as usual with the <code>-J</code> option when running the code. This makes it possible to compute the coupling between different exciton kinds. However, for our tutorial, we stick with the previously computed <code>Lfull</code> in both cases.

When we are satisfied with the input, we run the code using <code>yambo_ph</code>:

yambo_ph -F excph.in -J excph,bse_Lfull -C excph

If you check the output, you should find the <code>ndb.excph*</code> databases in the <code>excph</code> directory.

=== Analysis of the couplings ===

It is a good idea to have a look at what we computed up to now in order to make sure nothing has gone wrong.

It is not easy to know what to expect (apart from symmetry and gauge compliance of the matrix elements), but one can work out the exciton-phonon selection rules in advance, check that the magnitude is reasonable, etc.

It is also not easy to meaningfully plot this quantity. We have to make sure that we are not breaking degenerate states, otherwise the plots will not be invariant.

First of all, we have to know our system: in monolayer MoS2, the first four excitons are all doubly degenerate. The first exciton responsible for a bright peak in the absorption spectrum (the '''A''' peak), is the second state, corresponding to state indices <code>(3,4)</code> in fortran indexing or <code>(2,3)</code> in python indexing.

All these information can be obtained by analyzing the BSE results (this stuff is explained in the BSE tutorials) and by knowledge of the system or class of systems from the literature.

Thus, a good quantity to plot may be the norm of the matrix elements, summed over the degenerate subspace of exciton A, for a certain number of scattered final states mediated by certain phonon modes:

<math>F_A(q)= \sqrt{ \sum_{\alpha \in A,\lambda,\mu} |\mathcal{G}_{\alpha\lambda}^\mu (0,q)|^2 }</math>

In order to do this, we create a python script <code>analyse_excph.py</code> in which we first load the excph dabatases using the <code>YamboExcitonPhononDB</code> from yambopy.
You can find this script in the yambopy directory, in <code>tutorials/exciton-phonon</code>.
First, we select the exciton and phonon states to be included in <code>F_A</code>, together with the path of databases and plot details:

# Exciton in states
exc_in = [2,3] # A: 2,3 -- B: 6,7
exc_out = [0,1,2,3] # first 4 states (dispersion of triplet state and A)
ph_in = 'all'

# Paths of databases
ns_db1 =f'{path}/SAVE/ns.db1'
ndb_exc=f'{path}/excph'

...

Then, we load the data:

# Read lattice and k-space info
ylat = YamboLatticeDB.from_db_file(filename=ns_db1),Expand=True)
print(ylat)

# Read exc-ph databases
X = YamboExcitonPhononDB(ylat,save_excph=ndb_exc)
print(X)

The quantity <math>F_A(q)</math> is defined inside the plotting function as

G_squared = excph.excph_sq
G2plt = np.zeros(len(G_squared))

if exc_in == 'all': exc_in = range(G_squared.shape[2])
if exc_out == 'all': exc_out = range(G_squared.shape[3])
if ph_in == 'all': ph_in = range(G_squared.shape[1])

G_squared = G_squared[:, ph_in, :, :].sum(axis=(1))
G_squared = G_squared[:, exc_in, :].sum(axis=(1))
G_squared = G_squared[:, exc_out].sum(axis=(1))

F_q = np.sqrt( G_squared )*ha2ev # Switch from Ha to eV

And finally, we have to make a plotting function. For this tutorial we will use the default scatterplot provided by <code>YamboExcitonPhononDB</code>

excph.plot_excph(F_q,plt_cbar=plt_cbar,**kwargs)
...

You can get more experience on using Yambopy for these kinds of visualization by following the [https://wiki.yambo-code.eu/wiki/index.php?title=First_steps_in_Yambopy Yambopy tutorials]. In fact, remember that this scripts and all the other yambopy tutorial scripts are just suggestions, not source code written in stone: if you know <code>numpy</code> and <code>matplotlib</code> you can do your own analysis and your own plots, you just need to import the required Yambopy modules to load the data.

In our case, the resulting plot is the following.

[[File:1L MoS2 ExcPh.png|500px|center]]

This can be checked against Fig. 2(d) of reference <ref name="chan2023" />, although you have to keep in mind that our results are badly undersampled in terms of the reciprocal-space grid, as can be easily seen, and the quantity plotted is not exactly the same. However, the main features are already there since they are dictated mostly by crystal symmetries.

Now that we have the exciton-phonon matrix elements, we can use them to build several kinds of observables. Below, we give an example related to phonon-assisted luminescence, but we may update this tutorial in the future to include more cases.

== Step 8: Compute phonon-assisted luminescence ==

[[File:Luminescence scheme.png|250px|right]]

We want to compute the experimental optical signature due to the phonon-assisted recombination of an exciton (as sketched in the figure).

The signal from the phonon replicas can be modeled as a second-order scattering process involving one phonon and one photon:

<math>I^{(1)}_{PL}(\omega;T) \propto \frac{1}{N_q}\sum_{ s \mu \beta q} \left|\sum_\lambda\frac{D_\lambda \mathcal{G}^{\mu q}_{\alpha q,\lambda}}{E_{\alpha q}-E_\lambda -s\Omega_{\mu q}} \right|^2 N_{\alpha q}(T_{exc}) F^s_{\mu q}(T)\delta(\omega - \left[E_{\alpha q}-s\Omega_{\mu q}\right])</math>

In this equation, the oscillator strength of the peak is given by the exciton-phonon coupling matrix elements <math>\mathcal{G}</math> multiplied by the exciton dipoles <math>D</math> (they are called "residuals" in Yambo). Here <math>E_\lambda</math> and <math>E_{\alpha q}</math> are the energies of the optical and finite-momentum excitons, respectively, while <math>\Omega_{\mu q}</math> are the phonon energies.

The occupation function <math>F</math> is <math>F^s_{\mu q}(T)=n_{\mu q}(T)+\frac{1+s}{2}</math>. Here, <math>n(T)</math> is the temperature-dependent phonon Bose-Einstein occupation function. As it can be seen, <math>s=1</math> corresponds to processes of phonon ''emission'' (<math>\propto n(T)+1</math>), while <math>s=-1</math> corresponds to processes of phonon ''absorption'' (<math>\propto n(T)</math>). Therefore, <math>I^{(1)}_{PL}(\omega;T)</math> describes ''light'' emission by recombining excitons mediated by either ''phonon'' absorption or emission.

The quantity <math> N_{\alpha q}(T_{exc})</math> is the exciton occupation function. Luminescence is technically an out-of-equilibrium process, but we can assume that for very low density of excitations and in steady-state conditions, the exciton population can be approximately described by an equilibrium distribution evaluated at an effective temperature. Here, we use the Boltzmann distribution. Experimentally, <math>T_{exc}</math> tends to coincide with the lattice temperature <math>T</math> more or less above 100 K, while at very low temperature (< 10 K), <math>T_{exc}</math> may vary between 10-50 K. It goes without saying that this needs to carefully be checked in your realistic calculations.

=== Running the jobs ===

In order to study luminescence in a paradigmatic system, we switch to bulk hexagonal boron nitride and we repeat the workflow. As you can easily see, one can think about automatizing the execution of all these calculations via scripting or more advanced tools. However, in the case of very large simulations (memory-limited or disk-space limited) or for systems whose electronic and lattice properties are fragile with respect to tiny calculation details, one must be very careful and run many basic tests.

Fortunately, we are running a fast underconverged example. We use LDA pseudopotentials from the pseudo-dojo library and the following are the calculations steps.

1. Input <code>hbn.scf</code>:

&control
calculation='scf',
prefix='hBN',
restart_mode='from_scratch'
pseudo_dir = '$PSEUDO_DIR',
outdir = './tmp'
verbosity = 'high'
wf_collect=.true.
/
&system
ibrav = 4,
celldm(1) = 4.703675849
celldm(3) = 2.603711434
nat= 4,
ntyp= 2,
force_symmorphic=.true.
ecutwfc = 100,
/
&electrons
diago_david_ndim = 2
diago_full_acc=.true.
diago_thr_init=5.0e-6
mixing_mode = 'plain'
mixing_beta = 0.7
conv_thr = 1.0d-16
/
ATOMIC_SPECIES
B 10.81100 B_LDA_dojo.UPF
N 14.00674 N_LDA_dojo.UPF
ATOMIC_POSITIONS {crystal}
N 0.6666666670 0.3333333330 -0.250000000000
B 0.3333333330 0.6666666670 -0.250000000000
B 0.6666666670 0.3333333330 0.25000000000
N 0.3333333330 0.6666666670 0.25000000000
K_POINTS {automatic}
6 6 2 0 0 0

mpirun -np 4 pw.x -inp hbn.scf > scf.out

2. Input <code>hbn.nscf</code>:

&control
calculation='nscf',
prefix='hBN',
restart_mode='from_scratch'
pseudo_dir = '$PSEUDO_DIR'
outdir = './'
verbosity = 'high'
wf_collect=.true.
/
&system
ibrav = 4,
celldm(1) = 4.703675849
celldm(3) = 2.603711434
nat= 4,
ntyp= 2,
force_symmorphic=.true.
ecutwfc = 100,
nbnd = 120
/
&electrons
diago_david_ndim = 2
diago_full_acc=.true.
diago_thr_init=5.0e-6
mixing_mode = 'plain'
mixing_beta = 0.7
conv_thr = 1.0d-16
/
ATOMIC_SPECIES
B 10.81100 B_LDA_dojo.UPF
N 14.00674 N_LDA_dojo.UPF
ATOMIC_POSITIONS {crystal}
N 0.6666666670 0.3333333330 -0.250000000000
B 0.3333333330 0.6666666670 -0.250000000000
B 0.6666666670 0.3333333330 0.25000000000
N 0.3333333330 0.6666666670 0.25000000000
K_POINTS {automatic}
6 6 2 0 0 0

mpirun -np 4 pw.x -inp hbn.nscf > nscf.out

3. Input <code>hbn.dvscf</code>:

hbn_dvscf
&inputph
tr2_ph=1.0d-12,
verbosity='high'
prefix='hBN',
fildvscf = 'hBN-dvscf',
electron_phonon = 'dvscf',
fildyn='hBN.dyn',
epsil=.false.,
ldisp=.true.,
recover=.true.,
nq1=6,
nq2=6,
nq3=2
/

nohup mpirun -np 8 pw.x -inp hbn.dvscf > dvscf.out &

4. Input <code>bse.in</code> (we include 2 valence and 2 conduction bands):

optics # [R] Linear Response optical properties
bss # [R] BSE solver
bse # [R][BSE] Bethe Salpeter Equation.
dipoles # [R] Oscillator strenghts (or dipoles)
em1s
DIP_CPU= "1 8 1" # [PARALLEL] CPUs for each role
DIP_ROLEs= "k c v" # [PARALLEL] CPUs roles (k,c,v)
DIP_Threads=0 # [OPENMP/X] Number of threads for dipoles
X_and_IO_CPU= "1 1 1 8 1" # [PARALLEL] CPUs for each role
X_and_IO_ROLEs= "q g k c v" # [PARALLEL] CPUs roles (q,g,k,c,v)
X_and_IO_nCPU_LinAlg_INV=-1 # [PARALLEL] CPUs for Linear Algebra (if -1 it is automatically set)
X_Threads=0 # [OPENMP/X] Number of threads for response functions
BS_CPU= "8 1 1" # [PARALLEL] CPUs for each role
BS_ROLEs= "k eh t" # [PARALLEL] CPUs roles (k,eh,t)
BS_nCPU_LinAlg_INV=-1 # [PARALLEL] CPUs for Linear Algebra (if -1 it is automatically set)
BS_nCPU_LinAlg_DIAGO=-1 # [PARALLEL] CPUs for Linear Algebra (if -1 it is automatically set)
X_Threads=0 # [OPENMP/X] Number of threads for response functions
K_Threads=0 # [OPENMP/BSK] Number of threads for response functions
% QpntsRXs
1 | 14 | # [Xs] Transferred momenta
%
% BndsRnXs
1 | 120 | # [Xs] Polarization function bands
%
NGsBlkXs= 10 Ry # [Xs] Response block size
% LongDrXs
1.000000 | 1.000000 | 1.000000 | # [Xs] [cc] Electric Field
%
BSEmod= "resonant" # [BSE] resonant/retarded/coupling
BSKmod= "SEX" # [BSE] IP/Hartree/HF/ALDA/SEX/BSfxc
Lkind= "Lfull" # [BSE] Lbar (default) / full
BSSmod= "d" # [BSS] (h)aydock/(d)iagonalization/(s)lepc/(i)nversion/(t)ddft`
% DipBands
1 | 120 | # [DIP] Bands range for dipoles
%
DipApproach= "G-space v" # [DIP] [G-space v/R-space x/Covariant/Shifted grids]
DipComputed= "R V P" # [DIP] [default R P V; extra P2 Spin Orb]
BSENGexx= 30 Ry # [BSK] Exchange components
#ALLGexx # [BSS] Force the use use all RL vectors for the exchange part
BSENGBlk= 9 Ry # [BSK] Screened interaction block size [if -1 uses all the G-vectors of W(q,G,Gp)]
% KfnQP_E
1.25997 | 1.08816 | 1.12683 | # [EXTQP BSK BSS] E parameters (c/v) eV|adim|adim
%
% BSEQptR
 1 | 14 | # [BSK] Transferred momenta range
%
% BSEBands
 7 | 10 | # [BSK] Bands range
%
% BEnRange
0.50000 | 8.00000 | eV # [BSS] Energy range
%
% BDmRange
0.050000 | 0.050000 | eV # [BSS] Damping range
%
BEnSteps= 1000 # [BSS] Energy steps
% BLongDir
1.000000 | 1.000000 | 0.000000 | # [BSS] [cc] Electric Field
%
WRbsWF # [BSS] Write to disk excitonic the WFs

nohup mpirun -np 8 yambo -F bse.in -J bse_Lfull -C bse_Lfull &

Importantly, since we want to describe the phonon-assisted recombination process of an *optical* exciton (i.e., emitting a transverse photon), this time we also run an additional calculation at `Q=0` omitting the nonanalytic long-range Coulomb exchange. Make a second input <code>bse_Lbar.in</code> with the following changes:

Lkind= "Lbar" # [BSE] Lbar (default) / full
% BSEQptR
 1 | 1 | # [BSK] Transferred momenta range
%

4b. So now we make a second BSE run in a different directory specified by <code>-J</code>. Here, we also pass to yambo the directory of the previous run as it includes the important screening databases <code>ndb.em1s*</code> that we do not want to recompute from scratch.

mpirun -np 8 yambo -F bse_Lbar.in -J bse_Lbar,bse_Lfull -C bse_Lbar

5. Now we run <code>lelphc</code> with yambopy to get the el-ph matrix elements:

yambopy l2y -ph path/of/dvscf/hbn.dvscf -b 7 10 -par 4 2

6. And finally we generate the exciton-phonon input <code>excph.in</code> using <code>yambo_ph -excph o</code>. Now, we take a look at all the additional variables that we didn't check before, specifying also the details for luminescence the spectrum calculation.

excph # [R] Exction-phonon
ExcGkkp # [R][EXCPH] Exciton-Phonon Matrix Elelements
ExcPhOptics # [R][EXCPH] Exciton-Phonon Optics
BoseTemp=10.000000 Kn # Bosonic Temperature
EXCTemp= 10.000000 Kn # [EXCPH] Excitonic Temperature (for luminescence spectra)
% ELPhExcStates
1 | 4 | # [EXCPH] Incoming (external) exciton states
%
% ELPhExcSum
1 | 12 | # [EXCPH] Outgoing (virtual) exciton states
%
% ElPhModes
1 | 12 | # [ELPH] Phonon modes included
%
LoutPath= "./bse-L_full" # [EXCPH] Path of the outgoing L
FANdEtresh= 0.100000E-5 eV # [ELPH] Energy treshold for Fan denominator
EXCPHdEtresh= 0.100000E-5 eV # [ELPH] Energy treshold for exc-ph denominator
LDamping= 0.500000E-3 eV # [EXCPH] Damping of exc-ph self-energy
# These are the plot parameters, same as in other parts of yambo
% EnRngeXd
4.00000 | 5.00000 | eV # [Xd] Energy range
%
% DmRngeXd
0.00500000 | 0.00500000 | eV # [Xd] Damping range
%
ETStpsXd= 4000 # [Xd] Total Energy steps

Here <code>BoseTemp</code> and <code>EXCTemp</code> are the lattice and excitonic temperature, respectively.

Now we run the calculation with <code>yambo_ph</code>. Here, we read as <math>Q=0</math> excitons with <code>-J</code> the ones without the long-range Coulomb exchange:

yambo_ph -F excph.in -J excph,bse_Lbar -C excph

and we find our outputs in the <code>excph</code> directory.

NB: Step 6 could have been equivalently run in yambopy, limiting the use of the yambo code to just step 4. This latter option is more flexible, as it allows for a greater degree of control by the user. We are in the last stages of the development and it will be available soon.

=== Results ===

If we check the output directory from the step 6 calculation, we find the <code>o-excph.pl_bse_ph_ass</code> output files containing the luminescence spectra. We can plot them with gnuplot or any other tool:

gnuplot
> set xrange[4.2:5]
> p 'o-excph.pl_bse_ph_ass' u 1:2 w l lc rgb 'red' lw 3

[[File:Luminescence plot.png|500px|center]]

Here, the signal corresponds to a finite-momentum exciton that recombines with the help of several different phonon modes, both optical and acoustic. Each phonon mode whose coupling with the exciton is allowed can generate a peak, and the energy shifts of these peaks with respect to the initial exciton energy correspond to the phonon energies. This result is underconverged, but the main features are all there. In the plot, we show a more converged example using a 12x12x4 grid (all the other parameters being equal). These plots can be compared with Fig. 4(a) of reference <ref name="zanfrognini2023" />.

== References ==

<references>
<ref name="toyozawa2003" >[https://m.booksee.org/book/1121964?force_lang=en Optical processes in solids], Toyozawa, Yutaka, and Chris Oxlade. Cambridge University Press, (2003). </ref>
<ref name='lechifflart2023'>P. Lechifflart, F. Paleari, D. Sangalli, C. Attaccalite, ''First-principles study of luminescence in hexagonal boron nitride single layer: Exciton-phonon coupling and the role of substrate'',
[https://doi.org/10.1103/PhysRevMaterials.7.024006 Phys. Rev. M, '''7''' (2), 024006 (2023)]; [https://arxiv.org/abs/2212.10407 arXiv2212.1047]</ref>
<ref name='cannuccia2019'>E. Cannuccia, B. Monserrat and C. Attaccalite, ''Theory of phonon-assisted luminescence in solids: Application to hexagonal boron nitride'', [https://doi.org/10.1103/PhysRevB.99.081109 Phys. Rev. B '''99''', 081109(R) (2019)]; [https://arxiv.org/abs/1807.11797 arXiv1807.11797]</ref>
<ref name='paleari2019'>F. Paleari et al., ''Exciton-Phonon Coupling in the Ultraviolet Absorption and Emission Spectra of Bulk Hexagonal Boron Nitride'', [https://doi.org/10.1103/PhysRevLett.122.187401 Phys. Rev. Lett. '''122''', 187401 (2019)]; [https://arxiv.org/abs/1810.08976 arXiv1810.089776] </ref>
<ref name='chen2020'>''Exciton-Phonon Interaction and Relaxation Times from First Principles'',
Hsiao-Yi Chen, Davide Sangalli, and Marco Bernardi, [https://doi.org/10.1103/PhysRevLett.125.107401 Phys. Rev. Lett. '''125''', 107401 (2020)]; [https://arxiv.org/abs/2002.08913 arXiv 2002.08913 (2020)]</ref>
<ref name="lechifflart2023_PhD">[https://www.yambo-code.eu/wiki/images/5/54/These_final.pdf Exciton-phonon coupling and phonon-assisted luminescence in hexagonal Boron Nitride nanostructures], PhD Thesis, Pierre Lechifflart (2023)</ref>
<ref name='paleari2019_PhD'>F. Paleari, ''First-principles approaches to the description of indirect absorption and luminescence spectroscopy: exciton-phonon coupling in hexagonal boron nitride'', [https://wwwen.uni.lu/research/fstm/dphyms/people/fulvio_paleari PhD thesis, University of Luxembourg (2019)]</ref>
<ref name='zanfrognini2023'>[https://arxiv.org/abs/2305.17554 Distinguishing different stackings in layered materials via luminescence spectroscopy], M. Zanfrognini et al. Phys. Rev. Lett. '''131''', 206902 (2023) </ref>
<ref name='marini2024'>G. Marini, M. Calandra, P. Cudazzo, ''Optical absorption and photoluminescence of single layer boron nitride from a first principles cumulant approach'', [https://doi.org/10.1021/acs.nanolett.4c00669 Nano Lett., '''24''', 20, 6017 (2024)]; [https://arxiv.org/abs/2402.03826 arXiv 2402.03826 (2024)]</ref>
<ref name='antonius2017'>G. Antonius, S. G. Louie, ''Theory of exciton-phonon coupling'', [https://doi.org/10.1103/PhysRevB.105.085111 Phys. Rev. B, '''105''', 085111 (2022)]; [https://arxiv.org/abs/1705.04245 arXiv1705.04245 (2017)]</ref>
<ref name='paleari2022'>[https://arxiv.org/abs/2205.02783 Exciton-phonon interaction calls for a revision of the “exciton” concept], F. Paleari, A. Marini, Phys. Rev. B, '''106''', 125403 (2022)</ref>
<ref name='cudazzo2020'> P. Cudazzo, ''First-principles description of the exciton-phonon interaction: A cumulant approach'', [https://doi.org/10.1103/PhysRevB.102.045136 Phys. Rev. B, '''102''', 045136 (2020)]; [https://orbilu.uni.lu/bitstream/10993/44769/1/main.pdf Open access pdf from Luxembourg University]</ref>
<ref name='chan2023'>Y-h Chan, J. B. Haber, M. H. Naik, J. B. Neaton, D. Y. Qiu, F. H. da Jornada, S. G. Louie, ''Exciton Lifetime and Optical Line Width Profile via Exciton–Phonon Interactions: Theory and First-Principles Calculations for Monolayer MoS2'', [https://doi.org/10.1021/acs.nanolett.3c00732 Nano Lett., '''23''', 9 (2023)]; [https://arxiv.org/abs/2212.08451 arXiv 2212.08451 (2023)]</ref>
<ref name='murali2025'>M. Nalabothula, S. Reichardt, L. Wirtz, ''Origin of Interlayer Exciton–Phonon Coupling in 2D Heterostructures'', [https://doi.org/10.1021/acs.nanolett.5c00355 Nano Lett., '''25''', 15 (2025)], [https://arxiv.org/abs/2407.16111 arXiv 2407.16111 (2025)]</ref>
</references>

Real time approach to non-linear response (SHG)

2025-09-28T08:04:04Z

Attacc: /* How to choose the external field direction for the different X2 */

== Second Harmonic Generation in AlAs ==
In this tutorial, we will calculate the second harmonic generation of bulk AlAs, the Yambo databases can be downloaded here: [https://media.yambo-code.eu/educational/tutorials/files/AlAs_DBs.tar.gz AlAs_DBs.tar.gz] (10 MB). The first steps of this tutorials are the same as the one on [http://www.yambo-code.eu/wiki/index.php?title=Prerequisites_for_Real_Time_propagation_with_Yambo Prerequisites for Real-Time propagation with Yambo] with the only difference that we will work on AlAs and we will consider an external field in the direction <code> 1.000000 | 1.000000 | 0.000000 |</code>. The DFT input are available here: [https://media.yambo-code.eu/educational/tutorials/files/AlAs_abinit.tar.gz ABINIT] or [https://media.yambo-code.eu/educational/tutorials/files/AlAs_pwscf.tar.gz QuantumEspresso].
You can run the DFT calculation with ABINIT with the command:

abinit < AlAs.in > output_AlAs

or using QuantumEspresso:

pw.x -inp AlAs.scf.in > output_scf
pw.x -inp AlAs.nscf.in > output_scf

and then import the ABINIT wave-function with the command:

a2y -F AlAso_DS2_WFK.nc

and the QuantumEspresso one, in the folder AlAs.save with the command:

p2y
Now we consider an external field in the <code>[1,1,0]</code> direction and remove symmetries not compatible with this field, as explained in the tutorial [http://www.yambo-code.eu/wiki/index.php?title=Prerequisites_for_Real_Time_propagation_with_Yambo Prerequisites for Real-Time propagation with Yambo].

==Real-time simulation for the SHG==

You can generate the input file with the command <code>yambo_nl -u n</code>:

nloptics # [R NL] Non-linear optics
% NLBands
 3 | 6 | # [NL] Bands
%
NLstep= 0.0100 fs # [NL] Real Time step length
NLverbosity= "high" # [NL] Verbosity level (low | high)
NLtime=-1.000000 fs # [NL] Simulation Time
NLintegrator= "INVINT" # [NL] Integrator ("EULEREXP/RK4/RK2EXP/HEUN/INVINT/CRANKNIC")
NLCorrelation= "IPA" # [NL] Correlation ("IPA/HARTREE/TDDFT/LRC/JGM/SEX/HF")
NLLrcAlpha= 0.000000 # [NL] Long Range Correction
% NLEnRange
 1.000000 | 5.000000 | eV # [NL] Energy range
%
NLEnSteps= 5 # [NL] Energy steps
NLDamping= 0.150000 eV # [NL] Damping
% Field1_Dir
 1.000000 | 1.000000 | 0.000000 | # [RT Field1] Versor
Field1_kind= "SOFTSIN" # [NL ExtF] Kind(SIN|SOFTSIN|RES|ANTIRES|GAUSS|DELTA|QSSIN)

The line <code>|1.000000 | 1.000000 | 0.000000 | # [RT Field1] Versor</code> referees to the direction of the external field (x,y,0). At present only an external field is present but the code can be easily generalized to deal with more fields.
The default parameters of Yambo/Lumen are already tuned for second-harmonic generation, so the only thing you have to change is the band range, between 3 and 6 and the energy range between 1.0-5.0 eV and the number of energy steps in this interval that we set to 10. Notice that you cannot set to zero the lowest value of the energy range because this will requires a simulation that lasts infinite time, see below. Finally, consider that Yambo performs a separate calculation for each frequency, so if you set many energy steps the computational time grows linearly with this number.
Notice that we set <code>NLverbosity= "high"</code> in this way the code will produce a file for each laser frequency containing the time dependent polarization.
Run <code>yambo_nl</code>. Calculations will take about fifteen minutes on a single processor PC, you have time to study the next section that explains how non-linear response is extracted from the real-time simulations.
In order to speed up calculations, you can run them in parallel.

==Non-linear response with Yambo==

In order to calculate the non-linear response, the system is excited with different laser fields with a sinusoidal shape at frequencies <math>\omega_1, \omega_2, .... , \omega_n </math> determined by the parameters [[Variables#NLEnRangev|NLEnRange]] and [[Variables#NLEnSteps|NLEnSteps]]. A dephasing term is added to the Hamiltonian <math>\gamma = </math>[[Variables#NLDamping|NLDamping]] to simulate a finite broadening and to remove the eigenmodes that are excited by the sudden turning on of the external field. After the dephasing time the outgoing signal is analyzed to extract the non-linear coefficients as shown in the figure below:

[[File:Pt analysis.png|600px|center|Non-linear response analysis]]

In the report file <code>r_nlinear</code> you will find the length of the dephasing part and of the sampling one:

Dephasing Time [fs]: 52.65695
Sampling Time [fs]: 4.18566
Total simulation time [fs]: 56.84262
The length of the dephasing interval is inversely proportional to the damping term <math>T_{depth} \simeq 1/\gamma</math> while the length of the sampling is dictated by the smallest frequency we are interested in: <math>T_{samp} \simeq 1/\omega_1 </math>. For this reason if <math> \omega_1=0 </math> or <math> \gamma = 0 </math> simulation time goes to infinity. The response at zero frequency can be calculated as limit of small frequency perturbation.
You can have a look to the file <code>src/nloptics/NL_initialize.F</code> to see how simulation lengths are defined.
Calculations can take some time, run them in parallel, the best number of processors = number of frequencies or reduce the number of frequencies step in the SHG.

==Analysis of the results==

In the sampling region we suppose that the polarization can be written as: <math>\bf{P}(t) = \sum_{n=-\infty}^{+\infty} \bf{p}_n e^{-i\omega_n t} </math> where the coefficient <math>\bf{p}_1,...,\bf{p}_n </math> are related to <math>\chi^{(1)},...,\chi^{(n)} </math>. We sample the polarization signal at different times and invert the previous equation by truncating the sum at a finite order <ref>[https://arxiv.org/abs/1309.4012 Nonlinear optics from an ab initio approach by means of the dynamical Berry phase: Application to second- and third-harmonic generation in semiconductors], C. Attaccalite and M. Grüning, Phys. Rev. B 88, 235113(2013)</ref>.
This is done with the command <code>ypp_nl -u</code> that automatically produce an input with the correct values:

nonlinear # [R] NonLinear Optics Post-Processing
Xorder= 4 # Max order of the response functions
% TimeRange
52.65695 | -1.00000 | fs # Time-window where processing is done
%
ETStpsRt= 200 # Total Energy steps
% EnRngeRt
0.00000 | 10.00000 | eV # Energy range
%
DampMode= "NONE" # Damping type ( NONE | LORENTZIAN | GAUSSIAN )
DampFactor= 0.10000 eV # Damping parameter

where <code>Xorder</code> is the order where the previous sum is truncated, and the TimeRange specifies the sampling region. Notice that differently from the first tutorial, in this case, we do not need Damping in <code>ypp_nl</code> because we already included it in the real-time dynamics. Run <code>ypp_nl</code> and it will produce a file called <code>o.YPP-X_probe_order_2</code>. This file contains the different components of <math>\chi^2_{xy*} </math> and in particular the columns 6 and 7 correspond to the imaginary and real part of <math>\chi^2_{xyz} </math>. You can plot the result with gnuplot and the command:

p 'o.YPP-X_probe_order_2' u 1:(sqrt($6**2+$7**2)) w lp ps 1.5 pt 7 lw 1.5

the result should look like

[[File:AlAs results.png|700px|center|SHG in AlAs]]

and compare it with the <math> \chi^2_{zxy} </math> calculated with more frequencies and with the converged result on a <math> 18x18x18</math> k-point grid and bands between 2 and 10. In the figure you can find also the comparison with the results of Ref. <ref>Luppi et al. [https://arxiv.org/abs/1006.2649 PRB B, '''82''', 235201(2010)]</ref>.
Notice that the QuantumEspresso results are slightly different from the Abinit ones. This is due to the different pseudo-potential employed in the calculations if pseudopotentials were the same calculation would have been identical. You can download the script to generate this plot and the converged results [http://www.attaccalite.com/lumen/tutorials/AlAs/AlAs_results.tgz here].

'''Notice that''' : the following parameters are not used in the non-linear response analysis: <code> EnRngeRt</code>, <code>ETStpsRt</code>, <code>DampMode</code>, <code>DampFactor</code>. The damping factor is set directly in the real-time simulation.

'''System of units in Non-linear Optics''': notice that in Yambo the non-linear response functions are in the gaussian system of units, for example the <math> \chi^2 (\omega) </math> is in cm/statvolt. In order to convert the non-linear coefficients between different system of units, you can have a look at the [https://www.attaccalite.com/tutorials_yambo/Appendix_C_Boyd.pdf Appendix C] of the book [https://www.elsevier.com/books/nonlinear-optics/boyd/978-0-12-369470-6 "Non-linear optics" by Robert W. Boyd].

More tutorials on non-linear response (Third harmonic generation, parallelization, spin-orbit etc..) with Yambo can be found here: [http://www.attaccalite.com/lumen/tutorials.html More Tutorials]. 

==Analysis of the results using YamboPy==
The analysis of the result performed in the previous section using <code>ypp_nl</code> can be performed using python script [https://github.com/yambo-code/yambopy YamboPy]. 
In YamboPy we implemented all necessary functions to reads the Yambo databases and post-process the results. Here we show how to get the SHG signal from the previous
simulations. We suppose you correctly installed <code>YamboPy</code> on your PC. Go in the folder where you ran non-linear calculation and type in the python:
 
from yambopy import *
NLDB=YamboNLDB()
pol =NLDB.Polarization[0]
time=NLDB.IO_TIME_points

in this way you read all the Non-linear databases. If your runs are in a different folder then the 'SAVE' one you can specify it using the command:
NLDB=YamboNLDB(calc='MYJOB')

now in the array <code>pol</code> you have all the polarization for all laser frequencies in the three Cartesian directions, while the variable <code>time</code> contains all the time series of your simulation.
Now you can get the non-linear response with the command:

Harmonic_Analysis(NLDB,X_order=4)

this command will perform a Fourier analysis of the results in the same way of <code>ypp_nl</code> and generate new files with all the requested harmonics ''o.YamboPy-X_probe_order_1'', ''o.YamboPy-X_probe_order_2'' etc...
equivalent to the one generated by <code>ypp_nl</code>. Results can be plot with gnuplot using the command:

p 'o.YamboPy-X_probe_order_2' u 1:(sqrt($6**2+$7**2)) w lp ps 1.5 pt 7 lw 1.5

The script that performs non-linear analysis can be found in <code>yambopy/nl/harmonic_analysis.py</code>. We strongly advice you to have a look to this script and modify it according
to your needs and in order to extract other non-linear response functions.

==How to choose the external field direction for the different X2==

In the X2abc response you have three field directions. The two components ''b'' and ''c'' are determined by the external field and the third ''a''
is the direction where you measure the response. 

The external field in Yambo is set using the variable
% Field1_Dir
1.000000 | 0.000000 | 0.000000 | # [NL ExtF] Versor .
%

For example if you set in Yambo field direction as:

1.0 | 0.0 | 0.0 | ---> you calculate all components X2*xx
0.0 | 1.0 | 0.0 | ---> you calculate all components X2*yy
0.0 | 0.0 | 1.0 | ---> you calculate all components X2*zz

the * correspond to the different direction in the response file <code>o.YPP-X_probe_order_2</code>.
In the <code>o.YPP-X_probe_order_2</code> you have seven columns:

The first column is the energy [[omega]],
the 2nd and 3rd columns are the imaginary and real part of X2x**
the 4th and 5th columns are the imaginary and real part of X2y**
the 6th and 7th columns are the imaginary and real part of X2z**

where the ** are the direction of the incoming field, see above.

For example if you want to calculate the <math>\chi^{(2)}_{zxx}</math> you put the external field in the direction <code> 1.0 | 0.0 | 0.0 |</code>
and then plot the column 6 and 7 of the <code>o.YPP-X_probe_order_2</code> file. 

In order to get the other components of the X2 the calculation are more involved. For example if you put field in the

1.0 | 1.0 | 0.0 |

this corresponds to <math>E(t)=\frac{1}{\sqrt{2}} [ E_x(t) + E_y(t) ]</math> and so at the second order you will have <math>E^2(t)=\frac{1}{2} \left [ E^2_x(t) + E^2_y(t) + E_x(t) E_y(t) + E_y(t) E_x(t) \right]</math> 
this means that the X2 in the <code>o.YPP-X_probe_order_2</code> will correspond to a linear combination of the following different response functions. 
For example in the the 2nd and 3rd columns are the imaginary and real part of: 

<math>\chi^{(2)}_{x**}=\frac{1}{2} \left [\chi^2_{xxx}+\chi^{(2)}_{xyy} + \chi^{(2)}_{xxy} + \chi^{(2)}_{xyx} \right ]</math>

the same for the other column replacing the first <code>x</code> for <code>y,z</code>.
If you know that some components are zero this allow you to extract the corresponding off-diagonal part of <math>\chi^{(2)}_{abc}</math> otherwise you have to perform different calculations to get the component you are interested in. 
Now we present '''a simple example of monolayer hBN (m-hBN)'''. In m-hBN there is only a non-zero component of the <math>\chi^{(2)}</math>and all the others are related by symmetry: 
<math>\chi^{(2)}_{yyy}=-\chi^{(2)}_{yxx}=-\chi^{(2)}_{xxy}=-\chi^{(2)}_{xyx}</math> 
so if you put the field in the <code>|1|1|0|</code> direction you will get: 
<math>\chi^{(2)}_{x**} = \frac{1}{2} \left[\chi^{(2)}_{xxy} + \chi^{(2)}_{xyx} \right] = - \chi^{(2)}_{yyy} </math> 
<math>\chi^{(2)}_{y**} =\frac{1}{2} \left[ \chi^{(2)}_{yyy} + \chi^{(2)}_{yxx} \right] = 0.0 </math>
 
In the figure below you can see the different <math>\chi^{(2)}</math> of monolayer hBN.

[[File:Xhi2 xy.png|center| 800px|xhi2_xy]]

as you can see in the second panel, when the field is in the <code>xy</code> you get a linear combination of <math>\chi^{(2)}</math> corresponding to the equation above, in this case the <code>y</code> is zero while the <code>x</code> component is equal to <math>-\chi^{(2)}_{yyy}</math>.

'''Nota bene:''' if you change the direction of the external field you must to remove the corresponding symmetries as explained in the tutorial [[Prerequisites for Real Time_propagation with Yambo#Reduce symmetries real-time linear response tutorial]]. If you have to calculate <math>\chi^{(2)}</math> along many directions it can be convenient to remove all symmetries at once.

==Non-linear response of low-dimensional structures: 2D or 1D ==

The Yambo code is a 3D periodic code, so when you want to study a low-dimensional system 2D or 1D, you have to use a supercell approach.
For example to simulate the non-linear response in a 2D-crystal one, can put the crystal in the xy plane and choose a larger distance in the z-direction
in order to reduce the interaction between the periodic replica. Clearly in this case k-point sampling will be only in the x,y directions.
For calculations on this type of systems, these two warnings must be taken into account:

* if you calculate GW corrections or include electron-hole interaction in the linear/non-linear response it is a good idea to use a '''Coulomb cutoff''', similar to the 2D BSE case [http://www.yambo-code.org/wiki/index.php?title=How_to_treat_low_dimensional_systems How to treat low dimensional systems]. You can add the cutoff just adding the "-r" in the input generation.

* the calculation of SHG and THG are always performed respect to the supercell, therefore you have to '''re-scale''' the result to the effective thickness of the layer, usually the inter-layer distance of the corresponding bulk material for 2D systems: <math>\chi_{rescaled}(\omega) = L_z/d_{eff} \cdot \chi(\omega) </math> where <math>L_z</math> is the z-dimension of the supercell, and <math>d_{eff}</math> is the effective thickness of the 2D system.

'''Nota bene''': Non-linear response along non-periodic directions is not implemented in Yambo, the code will print zero in these directions for all response functions. We plan to implement it in a future version of the code.

==References==
<references />

==Links for schools==
* Back to [[Rome 2023#Tutorials]]
* Back to [[ICTP2020]]

 
{| style="width:100%" border="1"
|style="width:25%; text-align:left"|Prev: [[Linear response from real time simulations|Linear response from real time simulations]]
|style="width:45%; text-align:center"|Now: [[ICTP2020|ICTP Tutorials]] --> [[Real time approach to non-linear response|Non Linear Response]]
|style="width:50%; text-align:left"|Next: [[Correlation effects in the non-linear response|Correlation effects in the non-linear response ]]
|-
|}

Real time approach to non-linear response (SHG)

2025-09-28T08:03:05Z

Attacc: /* How to choose the external field direction for the different X2 */

== Second Harmonic Generation in AlAs ==
In this tutorial, we will calculate the second harmonic generation of bulk AlAs, the Yambo databases can be downloaded here: [https://media.yambo-code.eu/educational/tutorials/files/AlAs_DBs.tar.gz AlAs_DBs.tar.gz] (10 MB). The first steps of this tutorials are the same as the one on [http://www.yambo-code.eu/wiki/index.php?title=Prerequisites_for_Real_Time_propagation_with_Yambo Prerequisites for Real-Time propagation with Yambo] with the only difference that we will work on AlAs and we will consider an external field in the direction <code> 1.000000 | 1.000000 | 0.000000 |</code>. The DFT input are available here: [https://media.yambo-code.eu/educational/tutorials/files/AlAs_abinit.tar.gz ABINIT] or [https://media.yambo-code.eu/educational/tutorials/files/AlAs_pwscf.tar.gz QuantumEspresso].
You can run the DFT calculation with ABINIT with the command:

abinit < AlAs.in > output_AlAs

or using QuantumEspresso:

pw.x -inp AlAs.scf.in > output_scf
pw.x -inp AlAs.nscf.in > output_scf

and then import the ABINIT wave-function with the command:

a2y -F AlAso_DS2_WFK.nc

and the QuantumEspresso one, in the folder AlAs.save with the command:

p2y
Now we consider an external field in the <code>[1,1,0]</code> direction and remove symmetries not compatible with this field, as explained in the tutorial [http://www.yambo-code.eu/wiki/index.php?title=Prerequisites_for_Real_Time_propagation_with_Yambo Prerequisites for Real-Time propagation with Yambo].

==Real-time simulation for the SHG==

You can generate the input file with the command <code>yambo_nl -u n</code>:

nloptics # [R NL] Non-linear optics
% NLBands
 3 | 6 | # [NL] Bands
%
NLstep= 0.0100 fs # [NL] Real Time step length
NLverbosity= "high" # [NL] Verbosity level (low | high)
NLtime=-1.000000 fs # [NL] Simulation Time
NLintegrator= "INVINT" # [NL] Integrator ("EULEREXP/RK4/RK2EXP/HEUN/INVINT/CRANKNIC")
NLCorrelation= "IPA" # [NL] Correlation ("IPA/HARTREE/TDDFT/LRC/JGM/SEX/HF")
NLLrcAlpha= 0.000000 # [NL] Long Range Correction
% NLEnRange
 1.000000 | 5.000000 | eV # [NL] Energy range
%
NLEnSteps= 5 # [NL] Energy steps
NLDamping= 0.150000 eV # [NL] Damping
% Field1_Dir
 1.000000 | 1.000000 | 0.000000 | # [RT Field1] Versor
Field1_kind= "SOFTSIN" # [NL ExtF] Kind(SIN|SOFTSIN|RES|ANTIRES|GAUSS|DELTA|QSSIN)

The line <code>|1.000000 | 1.000000 | 0.000000 | # [RT Field1] Versor</code> referees to the direction of the external field (x,y,0). At present only an external field is present but the code can be easily generalized to deal with more fields.
The default parameters of Yambo/Lumen are already tuned for second-harmonic generation, so the only thing you have to change is the band range, between 3 and 6 and the energy range between 1.0-5.0 eV and the number of energy steps in this interval that we set to 10. Notice that you cannot set to zero the lowest value of the energy range because this will requires a simulation that lasts infinite time, see below. Finally, consider that Yambo performs a separate calculation for each frequency, so if you set many energy steps the computational time grows linearly with this number.
Notice that we set <code>NLverbosity= "high"</code> in this way the code will produce a file for each laser frequency containing the time dependent polarization.
Run <code>yambo_nl</code>. Calculations will take about fifteen minutes on a single processor PC, you have time to study the next section that explains how non-linear response is extracted from the real-time simulations.
In order to speed up calculations, you can run them in parallel.

==Non-linear response with Yambo==

In order to calculate the non-linear response, the system is excited with different laser fields with a sinusoidal shape at frequencies <math>\omega_1, \omega_2, .... , \omega_n </math> determined by the parameters [[Variables#NLEnRangev|NLEnRange]] and [[Variables#NLEnSteps|NLEnSteps]]. A dephasing term is added to the Hamiltonian <math>\gamma = </math>[[Variables#NLDamping|NLDamping]] to simulate a finite broadening and to remove the eigenmodes that are excited by the sudden turning on of the external field. After the dephasing time the outgoing signal is analyzed to extract the non-linear coefficients as shown in the figure below:

[[File:Pt analysis.png|600px|center|Non-linear response analysis]]

In the report file <code>r_nlinear</code> you will find the length of the dephasing part and of the sampling one:

Dephasing Time [fs]: 52.65695
Sampling Time [fs]: 4.18566
Total simulation time [fs]: 56.84262
The length of the dephasing interval is inversely proportional to the damping term <math>T_{depth} \simeq 1/\gamma</math> while the length of the sampling is dictated by the smallest frequency we are interested in: <math>T_{samp} \simeq 1/\omega_1 </math>. For this reason if <math> \omega_1=0 </math> or <math> \gamma = 0 </math> simulation time goes to infinity. The response at zero frequency can be calculated as limit of small frequency perturbation.
You can have a look to the file <code>src/nloptics/NL_initialize.F</code> to see how simulation lengths are defined.
Calculations can take some time, run them in parallel, the best number of processors = number of frequencies or reduce the number of frequencies step in the SHG.

==Analysis of the results==

In the sampling region we suppose that the polarization can be written as: <math>\bf{P}(t) = \sum_{n=-\infty}^{+\infty} \bf{p}_n e^{-i\omega_n t} </math> where the coefficient <math>\bf{p}_1,...,\bf{p}_n </math> are related to <math>\chi^{(1)},...,\chi^{(n)} </math>. We sample the polarization signal at different times and invert the previous equation by truncating the sum at a finite order <ref>[https://arxiv.org/abs/1309.4012 Nonlinear optics from an ab initio approach by means of the dynamical Berry phase: Application to second- and third-harmonic generation in semiconductors], C. Attaccalite and M. Grüning, Phys. Rev. B 88, 235113(2013)</ref>.
This is done with the command <code>ypp_nl -u</code> that automatically produce an input with the correct values:

nonlinear # [R] NonLinear Optics Post-Processing
Xorder= 4 # Max order of the response functions
% TimeRange
52.65695 | -1.00000 | fs # Time-window where processing is done
%
ETStpsRt= 200 # Total Energy steps
% EnRngeRt
0.00000 | 10.00000 | eV # Energy range
%
DampMode= "NONE" # Damping type ( NONE | LORENTZIAN | GAUSSIAN )
DampFactor= 0.10000 eV # Damping parameter

where <code>Xorder</code> is the order where the previous sum is truncated, and the TimeRange specifies the sampling region. Notice that differently from the first tutorial, in this case, we do not need Damping in <code>ypp_nl</code> because we already included it in the real-time dynamics. Run <code>ypp_nl</code> and it will produce a file called <code>o.YPP-X_probe_order_2</code>. This file contains the different components of <math>\chi^2_{xy*} </math> and in particular the columns 6 and 7 correspond to the imaginary and real part of <math>\chi^2_{xyz} </math>. You can plot the result with gnuplot and the command:

p 'o.YPP-X_probe_order_2' u 1:(sqrt($6**2+$7**2)) w lp ps 1.5 pt 7 lw 1.5

the result should look like

[[File:AlAs results.png|700px|center|SHG in AlAs]]

and compare it with the <math> \chi^2_{zxy} </math> calculated with more frequencies and with the converged result on a <math> 18x18x18</math> k-point grid and bands between 2 and 10. In the figure you can find also the comparison with the results of Ref. <ref>Luppi et al. [https://arxiv.org/abs/1006.2649 PRB B, '''82''', 235201(2010)]</ref>.
Notice that the QuantumEspresso results are slightly different from the Abinit ones. This is due to the different pseudo-potential employed in the calculations if pseudopotentials were the same calculation would have been identical. You can download the script to generate this plot and the converged results [http://www.attaccalite.com/lumen/tutorials/AlAs/AlAs_results.tgz here].

'''Notice that''' : the following parameters are not used in the non-linear response analysis: <code> EnRngeRt</code>, <code>ETStpsRt</code>, <code>DampMode</code>, <code>DampFactor</code>. The damping factor is set directly in the real-time simulation.

'''System of units in Non-linear Optics''': notice that in Yambo the non-linear response functions are in the gaussian system of units, for example the <math> \chi^2 (\omega) </math> is in cm/statvolt. In order to convert the non-linear coefficients between different system of units, you can have a look at the [https://www.attaccalite.com/tutorials_yambo/Appendix_C_Boyd.pdf Appendix C] of the book [https://www.elsevier.com/books/nonlinear-optics/boyd/978-0-12-369470-6 "Non-linear optics" by Robert W. Boyd].

More tutorials on non-linear response (Third harmonic generation, parallelization, spin-orbit etc..) with Yambo can be found here: [http://www.attaccalite.com/lumen/tutorials.html More Tutorials]. 

==Analysis of the results using YamboPy==
The analysis of the result performed in the previous section using <code>ypp_nl</code> can be performed using python script [https://github.com/yambo-code/yambopy YamboPy]. 
In YamboPy we implemented all necessary functions to reads the Yambo databases and post-process the results. Here we show how to get the SHG signal from the previous
simulations. We suppose you correctly installed <code>YamboPy</code> on your PC. Go in the folder where you ran non-linear calculation and type in the python:
 
from yambopy import *
NLDB=YamboNLDB()
pol =NLDB.Polarization[0]
time=NLDB.IO_TIME_points

in this way you read all the Non-linear databases. If your runs are in a different folder then the 'SAVE' one you can specify it using the command:
NLDB=YamboNLDB(calc='MYJOB')

now in the array <code>pol</code> you have all the polarization for all laser frequencies in the three Cartesian directions, while the variable <code>time</code> contains all the time series of your simulation.
Now you can get the non-linear response with the command:

Harmonic_Analysis(NLDB,X_order=4)

this command will perform a Fourier analysis of the results in the same way of <code>ypp_nl</code> and generate new files with all the requested harmonics ''o.YamboPy-X_probe_order_1'', ''o.YamboPy-X_probe_order_2'' etc...
equivalent to the one generated by <code>ypp_nl</code>. Results can be plot with gnuplot using the command:

p 'o.YamboPy-X_probe_order_2' u 1:(sqrt($6**2+$7**2)) w lp ps 1.5 pt 7 lw 1.5

The script that performs non-linear analysis can be found in <code>yambopy/nl/harmonic_analysis.py</code>. We strongly advice you to have a look to this script and modify it according
to your needs and in order to extract other non-linear response functions.

==How to choose the external field direction for the different X2==

In the X2abc response you have three field directions. The two components ''b'' and ''c'' are determined by the external field and the third ''a''
is the direction where you measure the response. 

The external field in Yambo is set using the variable
% Field1_Dir
1.000000 | 0.000000 | 0.000000 | # [NL ExtF] Versor .
%

For example if you set in Yambo field direction as:

1.0 | 0.0 | 0.0 | ---> you calculate all components X2*xx
0.0 | 1.0 | 0.0 | ---> you calculate all components X2*yy
0.0 | 0.0 | 1.0 | ---> you calculate all components X2*zz

the * correspond to the different direction in the response file <code>o.YPP-X_probe_order_2</code>.
In the <code>o.YPP-X_probe_order_2</code> you have seven columns:

The first column is the energy [[omega]],
the 2nd and 3rd columns are the imaginary and real part of X2x**
the 4th and 5th columns are the imaginary and real part of X2y**
the 6th and 7th columns are the imaginary and real part of X2z**

where the ** are the direction of the incoming field, see above.

For example if you want to calculate the <math>\chi^{(2)}_{zxx}</math> you put the external field in the direction <code> 1.0 | 0.0 | 0.0 |</code>
and then plot the column 6 and 7 of the <code>o.YPP-X_probe_order_2</code> file. 

In order to get the other components of the X2 the calculation are more involved. For example if you put field in the

1.0 | 1.0 | 0.0 |

this corresponds to <math>E(t)=\frac{1}{\sqrt{2}} [ E_x(t) + E_y(t) ]</math> and so at the second order you will have <math>E^2(t)=\frac{1}{2} \left [ E^2_x(t) + E^2_y(t) + E_x(t) E_y(t) + E_y(t) E_x(t) \right]</math> 
this means that the X2 in the <code>o.YPP-X_probe_order_2</code> will correspond to a linear combination of the following different response functions. 
For example in the the 2nd and 3rd columns are the imaginary and real part of: 

<math>\chi^{(2)}_{x**}=\frac{1}{2} \left [\chi^2_{xxx}+\chi^{(2)}_{xyy} + \chi^{(2)}_{xxy} + \chi^{(2)}_{xyx} \right ]</math>

the same for the other column replacing the first <code>x</code> for <code>y,z</code>.
If you know that some components are zero this allow you to extract the corresponding off-diagonal part of <math>\chi^{(2)}_{abc}</math> otherwise you have to perform different calculations to get the component you are interested in. 
Now we present '''a simple example of monolayer hBN (m-hBN)'''. In m-hBN there is only a non-zero component of the $\chi^2$ and all the others are related by symmetry: 
<math>\chi^{(2)}_{yyy}=-\chi^{(2)}_{yxx}=-\chi^{(2)}_{xxy}=-\chi^{(2)}_{xyx}</math> 
so if you put the field in the <code>|1|1|0|</code> direction you will get: 
<math>\chi^{(2)}_{x**} = \frac{1}{2} \left[\chi^{(2)}_{xxy} + \chi^{(2)}_{xyx} \right] = - \chi^{(2)}_{yyy} </math> 
<math>\chi^{(2)}_{y**} =\frac{1}{2} \left[ \chi^{(2)}_{yyy} + \chi^{(2)}_{yxx} \right] = 0.0 </math>
 
In the figure below you can see the different <math>\chi^{(2)}</math> of monolayer hBN.

[[File:Xhi2 xy.png|center| 800px|xhi2_xy]]

as you can see in the second panel, when the field is in the <code>xy</code> you get a linear combination of <code>\chi^{(2)}</code> corresponding to the equation above, in this case the <code>y</code> is zero while the <code>x</code> component is equal to <math>-\chi^{(2)}_{yyy}</math>.

'''Nota bene:''' if you change the direction of the external field you must to remove the corresponding symmetries as explained in the tutorial [[Prerequisites for Real Time_propagation with Yambo#Reduce symmetries real-time linear response tutorial]]. If you have to calculate <math>\chi^{(2)}</math> along many directions it can be convenient to remove all symmetries at once.

==Non-linear response of low-dimensional structures: 2D or 1D ==

The Yambo code is a 3D periodic code, so when you want to study a low-dimensional system 2D or 1D, you have to use a supercell approach.
For example to simulate the non-linear response in a 2D-crystal one, can put the crystal in the xy plane and choose a larger distance in the z-direction
in order to reduce the interaction between the periodic replica. Clearly in this case k-point sampling will be only in the x,y directions.
For calculations on this type of systems, these two warnings must be taken into account:

* if you calculate GW corrections or include electron-hole interaction in the linear/non-linear response it is a good idea to use a '''Coulomb cutoff''', similar to the 2D BSE case [http://www.yambo-code.org/wiki/index.php?title=How_to_treat_low_dimensional_systems How to treat low dimensional systems]. You can add the cutoff just adding the "-r" in the input generation.

* the calculation of SHG and THG are always performed respect to the supercell, therefore you have to '''re-scale''' the result to the effective thickness of the layer, usually the inter-layer distance of the corresponding bulk material for 2D systems: <math>\chi_{rescaled}(\omega) = L_z/d_{eff} \cdot \chi(\omega) </math> where <math>L_z</math> is the z-dimension of the supercell, and <math>d_{eff}</math> is the effective thickness of the 2D system.

'''Nota bene''': Non-linear response along non-periodic directions is not implemented in Yambo, the code will print zero in these directions for all response functions. We plan to implement it in a future version of the code.

==References==
<references />

==Links for schools==
* Back to [[Rome 2023#Tutorials]]
* Back to [[ICTP2020]]

 
{| style="width:100%" border="1"
|style="width:25%; text-align:left"|Prev: [[Linear response from real time simulations|Linear response from real time simulations]]
|style="width:45%; text-align:center"|Now: [[ICTP2020|ICTP Tutorials]] --> [[Real time approach to non-linear response|Non Linear Response]]
|style="width:50%; text-align:left"|Next: [[Correlation effects in the non-linear response|Correlation effects in the non-linear response ]]
|-
|}

Real time approach to non-linear response (SHG)

2025-09-28T07:55:40Z

Attacc: /* How to choose the external field direction for the different X2 */

== Second Harmonic Generation in AlAs ==
In this tutorial, we will calculate the second harmonic generation of bulk AlAs, the Yambo databases can be downloaded here: [https://media.yambo-code.eu/educational/tutorials/files/AlAs_DBs.tar.gz AlAs_DBs.tar.gz] (10 MB). The first steps of this tutorials are the same as the one on [http://www.yambo-code.eu/wiki/index.php?title=Prerequisites_for_Real_Time_propagation_with_Yambo Prerequisites for Real-Time propagation with Yambo] with the only difference that we will work on AlAs and we will consider an external field in the direction <code> 1.000000 | 1.000000 | 0.000000 |</code>. The DFT input are available here: [https://media.yambo-code.eu/educational/tutorials/files/AlAs_abinit.tar.gz ABINIT] or [https://media.yambo-code.eu/educational/tutorials/files/AlAs_pwscf.tar.gz QuantumEspresso].
You can run the DFT calculation with ABINIT with the command:

abinit < AlAs.in > output_AlAs

or using QuantumEspresso:

pw.x -inp AlAs.scf.in > output_scf
pw.x -inp AlAs.nscf.in > output_scf

and then import the ABINIT wave-function with the command:

a2y -F AlAso_DS2_WFK.nc

and the QuantumEspresso one, in the folder AlAs.save with the command:

p2y
Now we consider an external field in the <code>[1,1,0]</code> direction and remove symmetries not compatible with this field, as explained in the tutorial [http://www.yambo-code.eu/wiki/index.php?title=Prerequisites_for_Real_Time_propagation_with_Yambo Prerequisites for Real-Time propagation with Yambo].

==Real-time simulation for the SHG==

You can generate the input file with the command <code>yambo_nl -u n</code>:

nloptics # [R NL] Non-linear optics
% NLBands
 3 | 6 | # [NL] Bands
%
NLstep= 0.0100 fs # [NL] Real Time step length
NLverbosity= "high" # [NL] Verbosity level (low | high)
NLtime=-1.000000 fs # [NL] Simulation Time
NLintegrator= "INVINT" # [NL] Integrator ("EULEREXP/RK4/RK2EXP/HEUN/INVINT/CRANKNIC")
NLCorrelation= "IPA" # [NL] Correlation ("IPA/HARTREE/TDDFT/LRC/JGM/SEX/HF")
NLLrcAlpha= 0.000000 # [NL] Long Range Correction
% NLEnRange
 1.000000 | 5.000000 | eV # [NL] Energy range
%
NLEnSteps= 5 # [NL] Energy steps
NLDamping= 0.150000 eV # [NL] Damping
% Field1_Dir
 1.000000 | 1.000000 | 0.000000 | # [RT Field1] Versor
Field1_kind= "SOFTSIN" # [NL ExtF] Kind(SIN|SOFTSIN|RES|ANTIRES|GAUSS|DELTA|QSSIN)

The line <code>|1.000000 | 1.000000 | 0.000000 | # [RT Field1] Versor</code> referees to the direction of the external field (x,y,0). At present only an external field is present but the code can be easily generalized to deal with more fields.
The default parameters of Yambo/Lumen are already tuned for second-harmonic generation, so the only thing you have to change is the band range, between 3 and 6 and the energy range between 1.0-5.0 eV and the number of energy steps in this interval that we set to 10. Notice that you cannot set to zero the lowest value of the energy range because this will requires a simulation that lasts infinite time, see below. Finally, consider that Yambo performs a separate calculation for each frequency, so if you set many energy steps the computational time grows linearly with this number.
Notice that we set <code>NLverbosity= "high"</code> in this way the code will produce a file for each laser frequency containing the time dependent polarization.
Run <code>yambo_nl</code>. Calculations will take about fifteen minutes on a single processor PC, you have time to study the next section that explains how non-linear response is extracted from the real-time simulations.
In order to speed up calculations, you can run them in parallel.

==Non-linear response with Yambo==

In order to calculate the non-linear response, the system is excited with different laser fields with a sinusoidal shape at frequencies <math>\omega_1, \omega_2, .... , \omega_n </math> determined by the parameters [[Variables#NLEnRangev|NLEnRange]] and [[Variables#NLEnSteps|NLEnSteps]]. A dephasing term is added to the Hamiltonian <math>\gamma = </math>[[Variables#NLDamping|NLDamping]] to simulate a finite broadening and to remove the eigenmodes that are excited by the sudden turning on of the external field. After the dephasing time the outgoing signal is analyzed to extract the non-linear coefficients as shown in the figure below:

[[File:Pt analysis.png|600px|center|Non-linear response analysis]]

In the report file <code>r_nlinear</code> you will find the length of the dephasing part and of the sampling one:

Dephasing Time [fs]: 52.65695
Sampling Time [fs]: 4.18566
Total simulation time [fs]: 56.84262
The length of the dephasing interval is inversely proportional to the damping term <math>T_{depth} \simeq 1/\gamma</math> while the length of the sampling is dictated by the smallest frequency we are interested in: <math>T_{samp} \simeq 1/\omega_1 </math>. For this reason if <math> \omega_1=0 </math> or <math> \gamma = 0 </math> simulation time goes to infinity. The response at zero frequency can be calculated as limit of small frequency perturbation.
You can have a look to the file <code>src/nloptics/NL_initialize.F</code> to see how simulation lengths are defined.
Calculations can take some time, run them in parallel, the best number of processors = number of frequencies or reduce the number of frequencies step in the SHG.

==Analysis of the results==

In the sampling region we suppose that the polarization can be written as: <math>\bf{P}(t) = \sum_{n=-\infty}^{+\infty} \bf{p}_n e^{-i\omega_n t} </math> where the coefficient <math>\bf{p}_1,...,\bf{p}_n </math> are related to <math>\chi^{(1)},...,\chi^{(n)} </math>. We sample the polarization signal at different times and invert the previous equation by truncating the sum at a finite order <ref>[https://arxiv.org/abs/1309.4012 Nonlinear optics from an ab initio approach by means of the dynamical Berry phase: Application to second- and third-harmonic generation in semiconductors], C. Attaccalite and M. Grüning, Phys. Rev. B 88, 235113(2013)</ref>.
This is done with the command <code>ypp_nl -u</code> that automatically produce an input with the correct values:

nonlinear # [R] NonLinear Optics Post-Processing
Xorder= 4 # Max order of the response functions
% TimeRange
52.65695 | -1.00000 | fs # Time-window where processing is done
%
ETStpsRt= 200 # Total Energy steps
% EnRngeRt
0.00000 | 10.00000 | eV # Energy range
%
DampMode= "NONE" # Damping type ( NONE | LORENTZIAN | GAUSSIAN )
DampFactor= 0.10000 eV # Damping parameter

where <code>Xorder</code> is the order where the previous sum is truncated, and the TimeRange specifies the sampling region. Notice that differently from the first tutorial, in this case, we do not need Damping in <code>ypp_nl</code> because we already included it in the real-time dynamics. Run <code>ypp_nl</code> and it will produce a file called <code>o.YPP-X_probe_order_2</code>. This file contains the different components of <math>\chi^2_{xy*} </math> and in particular the columns 6 and 7 correspond to the imaginary and real part of <math>\chi^2_{xyz} </math>. You can plot the result with gnuplot and the command:

p 'o.YPP-X_probe_order_2' u 1:(sqrt($6**2+$7**2)) w lp ps 1.5 pt 7 lw 1.5

the result should look like

[[File:AlAs results.png|700px|center|SHG in AlAs]]

and compare it with the <math> \chi^2_{zxy} </math> calculated with more frequencies and with the converged result on a <math> 18x18x18</math> k-point grid and bands between 2 and 10. In the figure you can find also the comparison with the results of Ref. <ref>Luppi et al. [https://arxiv.org/abs/1006.2649 PRB B, '''82''', 235201(2010)]</ref>.
Notice that the QuantumEspresso results are slightly different from the Abinit ones. This is due to the different pseudo-potential employed in the calculations if pseudopotentials were the same calculation would have been identical. You can download the script to generate this plot and the converged results [http://www.attaccalite.com/lumen/tutorials/AlAs/AlAs_results.tgz here].

'''Notice that''' : the following parameters are not used in the non-linear response analysis: <code> EnRngeRt</code>, <code>ETStpsRt</code>, <code>DampMode</code>, <code>DampFactor</code>. The damping factor is set directly in the real-time simulation.

'''System of units in Non-linear Optics''': notice that in Yambo the non-linear response functions are in the gaussian system of units, for example the <math> \chi^2 (\omega) </math> is in cm/statvolt. In order to convert the non-linear coefficients between different system of units, you can have a look at the [https://www.attaccalite.com/tutorials_yambo/Appendix_C_Boyd.pdf Appendix C] of the book [https://www.elsevier.com/books/nonlinear-optics/boyd/978-0-12-369470-6 "Non-linear optics" by Robert W. Boyd].

More tutorials on non-linear response (Third harmonic generation, parallelization, spin-orbit etc..) with Yambo can be found here: [http://www.attaccalite.com/lumen/tutorials.html More Tutorials]. 

==Analysis of the results using YamboPy==
The analysis of the result performed in the previous section using <code>ypp_nl</code> can be performed using python script [https://github.com/yambo-code/yambopy YamboPy]. 
In YamboPy we implemented all necessary functions to reads the Yambo databases and post-process the results. Here we show how to get the SHG signal from the previous
simulations. We suppose you correctly installed <code>YamboPy</code> on your PC. Go in the folder where you ran non-linear calculation and type in the python:
 
from yambopy import *
NLDB=YamboNLDB()
pol =NLDB.Polarization[0]
time=NLDB.IO_TIME_points

in this way you read all the Non-linear databases. If your runs are in a different folder then the 'SAVE' one you can specify it using the command:
NLDB=YamboNLDB(calc='MYJOB')

now in the array <code>pol</code> you have all the polarization for all laser frequencies in the three Cartesian directions, while the variable <code>time</code> contains all the time series of your simulation.
Now you can get the non-linear response with the command:

Harmonic_Analysis(NLDB,X_order=4)

this command will perform a Fourier analysis of the results in the same way of <code>ypp_nl</code> and generate new files with all the requested harmonics ''o.YamboPy-X_probe_order_1'', ''o.YamboPy-X_probe_order_2'' etc...
equivalent to the one generated by <code>ypp_nl</code>. Results can be plot with gnuplot using the command:

p 'o.YamboPy-X_probe_order_2' u 1:(sqrt($6**2+$7**2)) w lp ps 1.5 pt 7 lw 1.5

The script that performs non-linear analysis can be found in <code>yambopy/nl/harmonic_analysis.py</code>. We strongly advice you to have a look to this script and modify it according
to your needs and in order to extract other non-linear response functions.

==How to choose the external field direction for the different X2==

In the X2abc response you have three field directions. The two components ''b'' and ''c'' are determined by the external field and the third ''a''
is the direction where you measure the response. 

The external field in Yambo is set using the variable
% Field1_Dir
1.000000 | 0.000000 | 0.000000 | # [NL ExtF] Versor .
%

For example if you set in Yambo field direction as:

1.0 | 0.0 | 0.0 | ---> you calculate all components X2*xx
0.0 | 1.0 | 0.0 | ---> you calculate all components X2*yy
0.0 | 0.0 | 1.0 | ---> you calculate all components X2*zz

the * correspond to the different direction in the response file <code>o.YPP-X_probe_order_2</code>.
In the <code>o.YPP-X_probe_order_2</code> you have seven columns:

The first column is the energy [[omega]],
the 2nd and 3rd columns are the imaginary and real part of X2x**
the 4th and 5th columns are the imaginary and real part of X2y**
the 6th and 7th columns are the imaginary and real part of X2z**

where the ** are the direction of the incoming field, see above.

For example if you want to calculate the <math>\chi^{(2)}_{zxx}</math> you put the external field in the direction <code> 1.0 | 0.0 | 0.0 |</code>
and then plot the column 6 and 7 of the <code>o.YPP-X_probe_order_2</code> file. 

In order to get the other components of the X2 the calculation are more involved. For example if you put field in the

1.0 | 1.0 | 0.0 |

this corresponds to <math>E(t)=\frac{1}{\sqrt{2}} [ E_x(t) + E_y(t) ]</math> and so at the second order you will have <math>E^2(t)=\frac{1}{2} \left [ E^2_x(t) + E^2_y(t) + E_x(t) E_y(t) + E_y(t) E_x(t) \right]</math> 
this means that the X2 in the <code>o.YPP-X_probe_order_2</code> will correspond to a linear combination of the following different response functions. 
For example in the the 2nd and 3rd columns are the imaginary and real part of: 

<math>\chi^{(2)}_{x**}=\frac{1}{2} \left [\chi^2_{xxx}+\chi^{(2)}_{xyy} + \chi^{(2)}_{xxy} + \chi^{(2)}_{xyx} \right ]</math>

the same for the other column replacing the first <code>x</code> for <code>y,z</code>.
If you know that some components are zero this allow you to extract the corresponding off-diagonal part of <math>\chi^{(2)}_{abc}</math> otherwise you have to perform different calculations to get the component you are interested in. 
Now we present '''a simple example of monolayer hBN (m-hBN)'''. In m-hBN there is only a non-zero component of the $\chi^2$ and all the others are related by symmetry: 
<math>\chi^{(2)}_{yyy}=-\chi^{(2)}_{yxx}=-\chi^{(2)}_{xxy}=-\chi^{(2)}_{xyx}</math> 
so if you put the field in the <code>|1|1|0|</code> direction you will get: 
<math>\chi^{(2)}_{x**} = \frac{1}{2} \left[\chi^{(2)}_{xxy} + \chi^{(2)}_{xyx} \right] = - \chi^{(2)}_{yyy} </math> 
<math>\chi^{(2)}_{y**} =\frac{1}{2} \left[ \chi^{(2)}_{yyy} + \chi^{(2)}_{yxx} \right] = 0.0 </math>
 
In the figure below you can see the different <math>\chi^{(2)}</math> of monolayer hBN.

[[File:Xhi2 xy.png|center| 800px|xhi2_xy]]

as you can see in the second panel, when the field is in the <code>xy</code> you get a linear combination of <code>\chi^{(2)}</code> corresponding to the equation above, in this case the <code>y</code> is zero while the <code>x</code> component is equal to <math>\chi^{(2)}_{yyy}</math>.

'''Nota bene:''' if you change the direction of the external field you must to remove the corresponding symmetries as explained in the tutorial [[Prerequisites for Real Time_propagation with Yambo#Reduce symmetries real-time linear response tutorial]]. If you have to calculate <math>\chi^{(2)}</math> along many directions it can be convenient to remove all symmetries at once.

==Non-linear response of low-dimensional structures: 2D or 1D ==

The Yambo code is a 3D periodic code, so when you want to study a low-dimensional system 2D or 1D, you have to use a supercell approach.
For example to simulate the non-linear response in a 2D-crystal one, can put the crystal in the xy plane and choose a larger distance in the z-direction
in order to reduce the interaction between the periodic replica. Clearly in this case k-point sampling will be only in the x,y directions.
For calculations on this type of systems, these two warnings must be taken into account:

* if you calculate GW corrections or include electron-hole interaction in the linear/non-linear response it is a good idea to use a '''Coulomb cutoff''', similar to the 2D BSE case [http://www.yambo-code.org/wiki/index.php?title=How_to_treat_low_dimensional_systems How to treat low dimensional systems]. You can add the cutoff just adding the "-r" in the input generation.

* the calculation of SHG and THG are always performed respect to the supercell, therefore you have to '''re-scale''' the result to the effective thickness of the layer, usually the inter-layer distance of the corresponding bulk material for 2D systems: <math>\chi_{rescaled}(\omega) = L_z/d_{eff} \cdot \chi(\omega) </math> where <math>L_z</math> is the z-dimension of the supercell, and <math>d_{eff}</math> is the effective thickness of the 2D system.

'''Nota bene''': Non-linear response along non-periodic directions is not implemented in Yambo, the code will print zero in these directions for all response functions. We plan to implement it in a future version of the code.

==References==
<references />

==Links for schools==
* Back to [[Rome 2023#Tutorials]]
* Back to [[ICTP2020]]

 
{| style="width:100%" border="1"
|style="width:25%; text-align:left"|Prev: [[Linear response from real time simulations|Linear response from real time simulations]]
|style="width:45%; text-align:center"|Now: [[ICTP2020|ICTP Tutorials]] --> [[Real time approach to non-linear response|Non Linear Response]]
|style="width:50%; text-align:left"|Next: [[Correlation effects in the non-linear response|Correlation effects in the non-linear response ]]
|-
|}

Real time approach to non-linear response (SHG)

2025-09-28T07:53:59Z

Attacc: /* How to choose the external field direction for the different X2 */

== Second Harmonic Generation in AlAs ==
In this tutorial, we will calculate the second harmonic generation of bulk AlAs, the Yambo databases can be downloaded here: [https://media.yambo-code.eu/educational/tutorials/files/AlAs_DBs.tar.gz AlAs_DBs.tar.gz] (10 MB). The first steps of this tutorials are the same as the one on [http://www.yambo-code.eu/wiki/index.php?title=Prerequisites_for_Real_Time_propagation_with_Yambo Prerequisites for Real-Time propagation with Yambo] with the only difference that we will work on AlAs and we will consider an external field in the direction <code> 1.000000 | 1.000000 | 0.000000 |</code>. The DFT input are available here: [https://media.yambo-code.eu/educational/tutorials/files/AlAs_abinit.tar.gz ABINIT] or [https://media.yambo-code.eu/educational/tutorials/files/AlAs_pwscf.tar.gz QuantumEspresso].
You can run the DFT calculation with ABINIT with the command:

abinit < AlAs.in > output_AlAs

or using QuantumEspresso:

pw.x -inp AlAs.scf.in > output_scf
pw.x -inp AlAs.nscf.in > output_scf

and then import the ABINIT wave-function with the command:

a2y -F AlAso_DS2_WFK.nc

and the QuantumEspresso one, in the folder AlAs.save with the command:

p2y
Now we consider an external field in the <code>[1,1,0]</code> direction and remove symmetries not compatible with this field, as explained in the tutorial [http://www.yambo-code.eu/wiki/index.php?title=Prerequisites_for_Real_Time_propagation_with_Yambo Prerequisites for Real-Time propagation with Yambo].

==Real-time simulation for the SHG==

You can generate the input file with the command <code>yambo_nl -u n</code>:

nloptics # [R NL] Non-linear optics
% NLBands
 3 | 6 | # [NL] Bands
%
NLstep= 0.0100 fs # [NL] Real Time step length
NLverbosity= "high" # [NL] Verbosity level (low | high)
NLtime=-1.000000 fs # [NL] Simulation Time
NLintegrator= "INVINT" # [NL] Integrator ("EULEREXP/RK4/RK2EXP/HEUN/INVINT/CRANKNIC")
NLCorrelation= "IPA" # [NL] Correlation ("IPA/HARTREE/TDDFT/LRC/JGM/SEX/HF")
NLLrcAlpha= 0.000000 # [NL] Long Range Correction
% NLEnRange
 1.000000 | 5.000000 | eV # [NL] Energy range
%
NLEnSteps= 5 # [NL] Energy steps
NLDamping= 0.150000 eV # [NL] Damping
% Field1_Dir
 1.000000 | 1.000000 | 0.000000 | # [RT Field1] Versor
Field1_kind= "SOFTSIN" # [NL ExtF] Kind(SIN|SOFTSIN|RES|ANTIRES|GAUSS|DELTA|QSSIN)

The line <code>|1.000000 | 1.000000 | 0.000000 | # [RT Field1] Versor</code> referees to the direction of the external field (x,y,0). At present only an external field is present but the code can be easily generalized to deal with more fields.
The default parameters of Yambo/Lumen are already tuned for second-harmonic generation, so the only thing you have to change is the band range, between 3 and 6 and the energy range between 1.0-5.0 eV and the number of energy steps in this interval that we set to 10. Notice that you cannot set to zero the lowest value of the energy range because this will requires a simulation that lasts infinite time, see below. Finally, consider that Yambo performs a separate calculation for each frequency, so if you set many energy steps the computational time grows linearly with this number.
Notice that we set <code>NLverbosity= "high"</code> in this way the code will produce a file for each laser frequency containing the time dependent polarization.
Run <code>yambo_nl</code>. Calculations will take about fifteen minutes on a single processor PC, you have time to study the next section that explains how non-linear response is extracted from the real-time simulations.
In order to speed up calculations, you can run them in parallel.

==Non-linear response with Yambo==

In order to calculate the non-linear response, the system is excited with different laser fields with a sinusoidal shape at frequencies <math>\omega_1, \omega_2, .... , \omega_n </math> determined by the parameters [[Variables#NLEnRangev|NLEnRange]] and [[Variables#NLEnSteps|NLEnSteps]]. A dephasing term is added to the Hamiltonian <math>\gamma = </math>[[Variables#NLDamping|NLDamping]] to simulate a finite broadening and to remove the eigenmodes that are excited by the sudden turning on of the external field. After the dephasing time the outgoing signal is analyzed to extract the non-linear coefficients as shown in the figure below:

[[File:Pt analysis.png|600px|center|Non-linear response analysis]]

In the report file <code>r_nlinear</code> you will find the length of the dephasing part and of the sampling one:

Dephasing Time [fs]: 52.65695
Sampling Time [fs]: 4.18566
Total simulation time [fs]: 56.84262
The length of the dephasing interval is inversely proportional to the damping term <math>T_{depth} \simeq 1/\gamma</math> while the length of the sampling is dictated by the smallest frequency we are interested in: <math>T_{samp} \simeq 1/\omega_1 </math>. For this reason if <math> \omega_1=0 </math> or <math> \gamma = 0 </math> simulation time goes to infinity. The response at zero frequency can be calculated as limit of small frequency perturbation.
You can have a look to the file <code>src/nloptics/NL_initialize.F</code> to see how simulation lengths are defined.
Calculations can take some time, run them in parallel, the best number of processors = number of frequencies or reduce the number of frequencies step in the SHG.

==Analysis of the results==

In the sampling region we suppose that the polarization can be written as: <math>\bf{P}(t) = \sum_{n=-\infty}^{+\infty} \bf{p}_n e^{-i\omega_n t} </math> where the coefficient <math>\bf{p}_1,...,\bf{p}_n </math> are related to <math>\chi^{(1)},...,\chi^{(n)} </math>. We sample the polarization signal at different times and invert the previous equation by truncating the sum at a finite order <ref>[https://arxiv.org/abs/1309.4012 Nonlinear optics from an ab initio approach by means of the dynamical Berry phase: Application to second- and third-harmonic generation in semiconductors], C. Attaccalite and M. Grüning, Phys. Rev. B 88, 235113(2013)</ref>.
This is done with the command <code>ypp_nl -u</code> that automatically produce an input with the correct values:

nonlinear # [R] NonLinear Optics Post-Processing
Xorder= 4 # Max order of the response functions
% TimeRange
52.65695 | -1.00000 | fs # Time-window where processing is done
%
ETStpsRt= 200 # Total Energy steps
% EnRngeRt
0.00000 | 10.00000 | eV # Energy range
%
DampMode= "NONE" # Damping type ( NONE | LORENTZIAN | GAUSSIAN )
DampFactor= 0.10000 eV # Damping parameter

where <code>Xorder</code> is the order where the previous sum is truncated, and the TimeRange specifies the sampling region. Notice that differently from the first tutorial, in this case, we do not need Damping in <code>ypp_nl</code> because we already included it in the real-time dynamics. Run <code>ypp_nl</code> and it will produce a file called <code>o.YPP-X_probe_order_2</code>. This file contains the different components of <math>\chi^2_{xy*} </math> and in particular the columns 6 and 7 correspond to the imaginary and real part of <math>\chi^2_{xyz} </math>. You can plot the result with gnuplot and the command:

p 'o.YPP-X_probe_order_2' u 1:(sqrt($6**2+$7**2)) w lp ps 1.5 pt 7 lw 1.5

the result should look like

[[File:AlAs results.png|700px|center|SHG in AlAs]]

and compare it with the <math> \chi^2_{zxy} </math> calculated with more frequencies and with the converged result on a <math> 18x18x18</math> k-point grid and bands between 2 and 10. In the figure you can find also the comparison with the results of Ref. <ref>Luppi et al. [https://arxiv.org/abs/1006.2649 PRB B, '''82''', 235201(2010)]</ref>.
Notice that the QuantumEspresso results are slightly different from the Abinit ones. This is due to the different pseudo-potential employed in the calculations if pseudopotentials were the same calculation would have been identical. You can download the script to generate this plot and the converged results [http://www.attaccalite.com/lumen/tutorials/AlAs/AlAs_results.tgz here].

'''Notice that''' : the following parameters are not used in the non-linear response analysis: <code> EnRngeRt</code>, <code>ETStpsRt</code>, <code>DampMode</code>, <code>DampFactor</code>. The damping factor is set directly in the real-time simulation.

'''System of units in Non-linear Optics''': notice that in Yambo the non-linear response functions are in the gaussian system of units, for example the <math> \chi^2 (\omega) </math> is in cm/statvolt. In order to convert the non-linear coefficients between different system of units, you can have a look at the [https://www.attaccalite.com/tutorials_yambo/Appendix_C_Boyd.pdf Appendix C] of the book [https://www.elsevier.com/books/nonlinear-optics/boyd/978-0-12-369470-6 "Non-linear optics" by Robert W. Boyd].

More tutorials on non-linear response (Third harmonic generation, parallelization, spin-orbit etc..) with Yambo can be found here: [http://www.attaccalite.com/lumen/tutorials.html More Tutorials]. 

==Analysis of the results using YamboPy==
The analysis of the result performed in the previous section using <code>ypp_nl</code> can be performed using python script [https://github.com/yambo-code/yambopy YamboPy]. 
In YamboPy we implemented all necessary functions to reads the Yambo databases and post-process the results. Here we show how to get the SHG signal from the previous
simulations. We suppose you correctly installed <code>YamboPy</code> on your PC. Go in the folder where you ran non-linear calculation and type in the python:
 
from yambopy import *
NLDB=YamboNLDB()
pol =NLDB.Polarization[0]
time=NLDB.IO_TIME_points

in this way you read all the Non-linear databases. If your runs are in a different folder then the 'SAVE' one you can specify it using the command:
NLDB=YamboNLDB(calc='MYJOB')

now in the array <code>pol</code> you have all the polarization for all laser frequencies in the three Cartesian directions, while the variable <code>time</code> contains all the time series of your simulation.
Now you can get the non-linear response with the command:

Harmonic_Analysis(NLDB,X_order=4)

this command will perform a Fourier analysis of the results in the same way of <code>ypp_nl</code> and generate new files with all the requested harmonics ''o.YamboPy-X_probe_order_1'', ''o.YamboPy-X_probe_order_2'' etc...
equivalent to the one generated by <code>ypp_nl</code>. Results can be plot with gnuplot using the command:

p 'o.YamboPy-X_probe_order_2' u 1:(sqrt($6**2+$7**2)) w lp ps 1.5 pt 7 lw 1.5

The script that performs non-linear analysis can be found in <code>yambopy/nl/harmonic_analysis.py</code>. We strongly advice you to have a look to this script and modify it according
to your needs and in order to extract other non-linear response functions.

==How to choose the external field direction for the different X2==

In the X2abc response you have three field directions. The two components ''b'' and ''c'' are determined by the external field and the third ''a''
is the direction where you measure the response. 

The external field in Yambo is set using the variable
% Field1_Dir
1.000000 | 0.000000 | 0.000000 | # [NL ExtF] Versor .
%

For example if you set in Yambo field direction as:

1.0 | 0.0 | 0.0 | ---> you calculate all components X2*xx
0.0 | 1.0 | 0.0 | ---> you calculate all components X2*yy
0.0 | 0.0 | 1.0 | ---> you calculate all components X2*zz

the * correspond to the different direction in the response file <code>o.YPP-X_probe_order_2</code>.
In the <code>o.YPP-X_probe_order_2</code> you have seven columns:

The first column is the energy [[omega]],
the 2nd and 3rd columns are the imaginary and real part of X2x**
the 4th and 5th columns are the imaginary and real part of X2y**
the 6th and 7th columns are the imaginary and real part of X2z**

where the ** are the direction of the incoming field, see above.

For example if you want to calculate the <math>\chi^{(2)}_{zxx}</math> you put the external field in the direction <code> 1.0 | 0.0 | 0.0 |</code>
and then plot the column 6 and 7 of the <code>o.YPP-X_probe_order_2</code> file. 

In order to get the other components of the X2 the calculation are more involved. For example if you put field in the

1.0 | 1.0 | 0.0 |

this corresponds to <math>E(t)=\frac{1}{\sqrt{2}} [ E_x(t) + E_y(t) ]</math> and so at the second order you will have <math>E^2(t)=\frac{1}{2} \left [ E^2_x(t) + E^2_y(t) + E_x(t) E_y(t) + E_y(t) E_x(t) \right]</math> 
this means that the X2 in the <code>o.YPP-X_probe_order_2</code> will correspond to a linear combination of the following different response functions. 
For example in the the 2nd and 3rd columns are the imaginary and real part of: 

<math>\chi^{(2)}_{x**}=\frac{1}{2} \left [\chi^2_{xxx}+\chi^{(2)}_{xyy} + \chi^{(2)}_{xxy} + \chi^{(2)}_{xyx} \right ]</math>

the same for the other column replacing the first <code>x</code> for <code>y,z</code>.
If you know that some components are zero this allow you to extract the corresponding off-diagonal part of <math>\chi^{(2)}_{abc}</math> otherwise you have to perform different calculations to get the component you are interested in. 
Now we present '''a simple example of monolayer hBN (m-hBN)'''. In m-hBN there is only a non-zero component of the $\chi^2$ and all the others are related by symmetry: 
<math>\chi^{(2)}_{yyy}=-\chi^{(2)}_{yxx}=-\chi^{(2)}_{xxy}=-\chi^{(2)}_{xyx}</math> 
so if you put the field in the <code>|1|1|0|</code> direction you will get: 
<math>\chi^{(2)}_{x**} = \frac{1}{2} \left[\chi^{(2)}_{xxy} + \chi^{(2)}_{xyx} \right] = - \chi^{(2)}_{yyy} </math> 
<math>\chi^{(2)}_{y**} =\frac{1}{2} \left[ \chi^{(2)}_{yyy} + \chi^{(2)}_{yxx} \right] = 0.0 </math>
 
In the figure below you can see the different <math>\chi^{(2)}</math> of monolayer hBN.

[[File:Xhi2 xy.png|center| 800px|xhi2_xy]]

as you can see in the second panel, when the field is in the <code>xy</code> you get a linear combination of <code>\chi^{(2)}</code> corresponding to the equation above, in this case the <code>y</code> is zero while the <code>x</code> component is equal to <math>\chi^{(2)}_{yyy}</math>.

'''Nota bene:''' if you change the direction of the external field you have to remove the corresponding symmetries as explained in the tutorial [[Prerequisites for Real Time_propagation with Yambo#Reduce symmetries real-time linear response tutorial]].

==Non-linear response of low-dimensional structures: 2D or 1D ==

The Yambo code is a 3D periodic code, so when you want to study a low-dimensional system 2D or 1D, you have to use a supercell approach.
For example to simulate the non-linear response in a 2D-crystal one, can put the crystal in the xy plane and choose a larger distance in the z-direction
in order to reduce the interaction between the periodic replica. Clearly in this case k-point sampling will be only in the x,y directions.
For calculations on this type of systems, these two warnings must be taken into account:

* if you calculate GW corrections or include electron-hole interaction in the linear/non-linear response it is a good idea to use a '''Coulomb cutoff''', similar to the 2D BSE case [http://www.yambo-code.org/wiki/index.php?title=How_to_treat_low_dimensional_systems How to treat low dimensional systems]. You can add the cutoff just adding the "-r" in the input generation.

* the calculation of SHG and THG are always performed respect to the supercell, therefore you have to '''re-scale''' the result to the effective thickness of the layer, usually the inter-layer distance of the corresponding bulk material for 2D systems: <math>\chi_{rescaled}(\omega) = L_z/d_{eff} \cdot \chi(\omega) </math> where <math>L_z</math> is the z-dimension of the supercell, and <math>d_{eff}</math> is the effective thickness of the 2D system.

'''Nota bene''': Non-linear response along non-periodic directions is not implemented in Yambo, the code will print zero in these directions for all response functions. We plan to implement it in a future version of the code.

==References==
<references />

==Links for schools==
* Back to [[Rome 2023#Tutorials]]
* Back to [[ICTP2020]]

 
{| style="width:100%" border="1"
|style="width:25%; text-align:left"|Prev: [[Linear response from real time simulations|Linear response from real time simulations]]
|style="width:45%; text-align:center"|Now: [[ICTP2020|ICTP Tutorials]] --> [[Real time approach to non-linear response|Non Linear Response]]
|style="width:50%; text-align:left"|Next: [[Correlation effects in the non-linear response|Correlation effects in the non-linear response ]]
|-
|}

Real time approach to non-linear response (SHG)

2025-09-28T07:52:36Z

Attacc: /* How to choose the external field direction for the different X2 */

== Second Harmonic Generation in AlAs ==
In this tutorial, we will calculate the second harmonic generation of bulk AlAs, the Yambo databases can be downloaded here: [https://media.yambo-code.eu/educational/tutorials/files/AlAs_DBs.tar.gz AlAs_DBs.tar.gz] (10 MB). The first steps of this tutorials are the same as the one on [http://www.yambo-code.eu/wiki/index.php?title=Prerequisites_for_Real_Time_propagation_with_Yambo Prerequisites for Real-Time propagation with Yambo] with the only difference that we will work on AlAs and we will consider an external field in the direction <code> 1.000000 | 1.000000 | 0.000000 |</code>. The DFT input are available here: [https://media.yambo-code.eu/educational/tutorials/files/AlAs_abinit.tar.gz ABINIT] or [https://media.yambo-code.eu/educational/tutorials/files/AlAs_pwscf.tar.gz QuantumEspresso].
You can run the DFT calculation with ABINIT with the command:

abinit < AlAs.in > output_AlAs

or using QuantumEspresso:

pw.x -inp AlAs.scf.in > output_scf
pw.x -inp AlAs.nscf.in > output_scf

and then import the ABINIT wave-function with the command:

a2y -F AlAso_DS2_WFK.nc

and the QuantumEspresso one, in the folder AlAs.save with the command:

p2y
Now we consider an external field in the <code>[1,1,0]</code> direction and remove symmetries not compatible with this field, as explained in the tutorial [http://www.yambo-code.eu/wiki/index.php?title=Prerequisites_for_Real_Time_propagation_with_Yambo Prerequisites for Real-Time propagation with Yambo].

==Real-time simulation for the SHG==

You can generate the input file with the command <code>yambo_nl -u n</code>:

nloptics # [R NL] Non-linear optics
% NLBands
 3 | 6 | # [NL] Bands
%
NLstep= 0.0100 fs # [NL] Real Time step length
NLverbosity= "high" # [NL] Verbosity level (low | high)
NLtime=-1.000000 fs # [NL] Simulation Time
NLintegrator= "INVINT" # [NL] Integrator ("EULEREXP/RK4/RK2EXP/HEUN/INVINT/CRANKNIC")
NLCorrelation= "IPA" # [NL] Correlation ("IPA/HARTREE/TDDFT/LRC/JGM/SEX/HF")
NLLrcAlpha= 0.000000 # [NL] Long Range Correction
% NLEnRange
 1.000000 | 5.000000 | eV # [NL] Energy range
%
NLEnSteps= 5 # [NL] Energy steps
NLDamping= 0.150000 eV # [NL] Damping
% Field1_Dir
 1.000000 | 1.000000 | 0.000000 | # [RT Field1] Versor
Field1_kind= "SOFTSIN" # [NL ExtF] Kind(SIN|SOFTSIN|RES|ANTIRES|GAUSS|DELTA|QSSIN)

The line <code>|1.000000 | 1.000000 | 0.000000 | # [RT Field1] Versor</code> referees to the direction of the external field (x,y,0). At present only an external field is present but the code can be easily generalized to deal with more fields.
The default parameters of Yambo/Lumen are already tuned for second-harmonic generation, so the only thing you have to change is the band range, between 3 and 6 and the energy range between 1.0-5.0 eV and the number of energy steps in this interval that we set to 10. Notice that you cannot set to zero the lowest value of the energy range because this will requires a simulation that lasts infinite time, see below. Finally, consider that Yambo performs a separate calculation for each frequency, so if you set many energy steps the computational time grows linearly with this number.
Notice that we set <code>NLverbosity= "high"</code> in this way the code will produce a file for each laser frequency containing the time dependent polarization.
Run <code>yambo_nl</code>. Calculations will take about fifteen minutes on a single processor PC, you have time to study the next section that explains how non-linear response is extracted from the real-time simulations.
In order to speed up calculations, you can run them in parallel.

==Non-linear response with Yambo==

In order to calculate the non-linear response, the system is excited with different laser fields with a sinusoidal shape at frequencies <math>\omega_1, \omega_2, .... , \omega_n </math> determined by the parameters [[Variables#NLEnRangev|NLEnRange]] and [[Variables#NLEnSteps|NLEnSteps]]. A dephasing term is added to the Hamiltonian <math>\gamma = </math>[[Variables#NLDamping|NLDamping]] to simulate a finite broadening and to remove the eigenmodes that are excited by the sudden turning on of the external field. After the dephasing time the outgoing signal is analyzed to extract the non-linear coefficients as shown in the figure below:

[[File:Pt analysis.png|600px|center|Non-linear response analysis]]

In the report file <code>r_nlinear</code> you will find the length of the dephasing part and of the sampling one:

Dephasing Time [fs]: 52.65695
Sampling Time [fs]: 4.18566
Total simulation time [fs]: 56.84262
The length of the dephasing interval is inversely proportional to the damping term <math>T_{depth} \simeq 1/\gamma</math> while the length of the sampling is dictated by the smallest frequency we are interested in: <math>T_{samp} \simeq 1/\omega_1 </math>. For this reason if <math> \omega_1=0 </math> or <math> \gamma = 0 </math> simulation time goes to infinity. The response at zero frequency can be calculated as limit of small frequency perturbation.
You can have a look to the file <code>src/nloptics/NL_initialize.F</code> to see how simulation lengths are defined.
Calculations can take some time, run them in parallel, the best number of processors = number of frequencies or reduce the number of frequencies step in the SHG.

==Analysis of the results==

In the sampling region we suppose that the polarization can be written as: <math>\bf{P}(t) = \sum_{n=-\infty}^{+\infty} \bf{p}_n e^{-i\omega_n t} </math> where the coefficient <math>\bf{p}_1,...,\bf{p}_n </math> are related to <math>\chi^{(1)},...,\chi^{(n)} </math>. We sample the polarization signal at different times and invert the previous equation by truncating the sum at a finite order <ref>[https://arxiv.org/abs/1309.4012 Nonlinear optics from an ab initio approach by means of the dynamical Berry phase: Application to second- and third-harmonic generation in semiconductors], C. Attaccalite and M. Grüning, Phys. Rev. B 88, 235113(2013)</ref>.
This is done with the command <code>ypp_nl -u</code> that automatically produce an input with the correct values:

nonlinear # [R] NonLinear Optics Post-Processing
Xorder= 4 # Max order of the response functions
% TimeRange
52.65695 | -1.00000 | fs # Time-window where processing is done
%
ETStpsRt= 200 # Total Energy steps
% EnRngeRt
0.00000 | 10.00000 | eV # Energy range
%
DampMode= "NONE" # Damping type ( NONE | LORENTZIAN | GAUSSIAN )
DampFactor= 0.10000 eV # Damping parameter

where <code>Xorder</code> is the order where the previous sum is truncated, and the TimeRange specifies the sampling region. Notice that differently from the first tutorial, in this case, we do not need Damping in <code>ypp_nl</code> because we already included it in the real-time dynamics. Run <code>ypp_nl</code> and it will produce a file called <code>o.YPP-X_probe_order_2</code>. This file contains the different components of <math>\chi^2_{xy*} </math> and in particular the columns 6 and 7 correspond to the imaginary and real part of <math>\chi^2_{xyz} </math>. You can plot the result with gnuplot and the command:

p 'o.YPP-X_probe_order_2' u 1:(sqrt($6**2+$7**2)) w lp ps 1.5 pt 7 lw 1.5

the result should look like

[[File:AlAs results.png|700px|center|SHG in AlAs]]

and compare it with the <math> \chi^2_{zxy} </math> calculated with more frequencies and with the converged result on a <math> 18x18x18</math> k-point grid and bands between 2 and 10. In the figure you can find also the comparison with the results of Ref. <ref>Luppi et al. [https://arxiv.org/abs/1006.2649 PRB B, '''82''', 235201(2010)]</ref>.
Notice that the QuantumEspresso results are slightly different from the Abinit ones. This is due to the different pseudo-potential employed in the calculations if pseudopotentials were the same calculation would have been identical. You can download the script to generate this plot and the converged results [http://www.attaccalite.com/lumen/tutorials/AlAs/AlAs_results.tgz here].

'''Notice that''' : the following parameters are not used in the non-linear response analysis: <code> EnRngeRt</code>, <code>ETStpsRt</code>, <code>DampMode</code>, <code>DampFactor</code>. The damping factor is set directly in the real-time simulation.

'''System of units in Non-linear Optics''': notice that in Yambo the non-linear response functions are in the gaussian system of units, for example the <math> \chi^2 (\omega) </math> is in cm/statvolt. In order to convert the non-linear coefficients between different system of units, you can have a look at the [https://www.attaccalite.com/tutorials_yambo/Appendix_C_Boyd.pdf Appendix C] of the book [https://www.elsevier.com/books/nonlinear-optics/boyd/978-0-12-369470-6 "Non-linear optics" by Robert W. Boyd].

More tutorials on non-linear response (Third harmonic generation, parallelization, spin-orbit etc..) with Yambo can be found here: [http://www.attaccalite.com/lumen/tutorials.html More Tutorials]. 

==Analysis of the results using YamboPy==
The analysis of the result performed in the previous section using <code>ypp_nl</code> can be performed using python script [https://github.com/yambo-code/yambopy YamboPy]. 
In YamboPy we implemented all necessary functions to reads the Yambo databases and post-process the results. Here we show how to get the SHG signal from the previous
simulations. We suppose you correctly installed <code>YamboPy</code> on your PC. Go in the folder where you ran non-linear calculation and type in the python:
 
from yambopy import *
NLDB=YamboNLDB()
pol =NLDB.Polarization[0]
time=NLDB.IO_TIME_points

in this way you read all the Non-linear databases. If your runs are in a different folder then the 'SAVE' one you can specify it using the command:
NLDB=YamboNLDB(calc='MYJOB')

now in the array <code>pol</code> you have all the polarization for all laser frequencies in the three Cartesian directions, while the variable <code>time</code> contains all the time series of your simulation.
Now you can get the non-linear response with the command:

Harmonic_Analysis(NLDB,X_order=4)

this command will perform a Fourier analysis of the results in the same way of <code>ypp_nl</code> and generate new files with all the requested harmonics ''o.YamboPy-X_probe_order_1'', ''o.YamboPy-X_probe_order_2'' etc...
equivalent to the one generated by <code>ypp_nl</code>. Results can be plot with gnuplot using the command:

p 'o.YamboPy-X_probe_order_2' u 1:(sqrt($6**2+$7**2)) w lp ps 1.5 pt 7 lw 1.5

The script that performs non-linear analysis can be found in <code>yambopy/nl/harmonic_analysis.py</code>. We strongly advice you to have a look to this script and modify it according
to your needs and in order to extract other non-linear response functions.

==How to choose the external field direction for the different X2==

In the X2abc response you have three field directions. The two components ''b'' and ''c'' are determined by the external field and the third ''a''
is the direction where you measure the response. 

The external field in Yambo is set using the variable
% Field1_Dir
1.000000 | 0.000000 | 0.000000 | # [NL ExtF] Versor .
%

For example if you set in Yambo field direction as:

1.0 | 0.0 | 0.0 | ---> you calculate all components X2*xx
0.0 | 1.0 | 0.0 | ---> you calculate all components X2*yy
0.0 | 0.0 | 1.0 | ---> you calculate all components X2*zz

the * correspond to the different direction in the response file <code>o.YPP-X_probe_order_2</code>.
In the <code>o.YPP-X_probe_order_2</code> you have seven columns:

The first column is the energy [[omega]],
the 2nd and 3rd columns are the imaginary and real part of X2x**
the 4th and 5th columns are the imaginary and real part of X2y**
the 6th and 7th columns are the imaginary and real part of X2z**

where the ** are the direction of the incoming field, see above.

For example if you want to calculate the <math>\chi^{(2)}_{zxx}</math> you put the external field in the direction <code> 1.0 | 0.0 | 0.0 |</code>
and then plot the column 6 and 7 of the <code>o.YPP-X_probe_order_2</code> file. 

In order to get the other components of the X2 the calculation are more involved. For example if you put field in the

1.0 | 1.0 | 0.0 |

this corresponds to <math>E(t)=\frac{1}{\sqrt{2}} [ E_x(t) + E_y(t) ]</math> and so at the second order you will have <math>E^2(t)=\frac{1}{2} \left [ E^2_x(t) + E^2_y(t) + E_x(t) E_y(t) + E_y(t) E_x(t) \right]</math> 
this means that the X2 in the <code>o.YPP-X_probe_order_2</code> will correspond to a linear combination of the following different response functions. 
For example in the the 2nd and 3rd columns are the imaginary and real part of: 

<math>\chi^{(2)}_{x**}=\frac{1}{2} \left [\chi^2_{xxx}+\chi^{(2)}_{xyy} + \chi^{(2)}_{xxy} + \chi^{(2)}_{xyx} \right ]</math>

the same for the other column replacing the first <code>x</code> for <code>y,z</code>.
If you know that some components are zero this allow you to extract the corresponding off-diagonal part of <math>\chi^{(2)}_{abc}</math> otherwise you have to perform different calculations to get the component you are interested in. 
Now we present '''a simple example of monolayer hBN (m-hBN)'''. In m-hBN there is only a non-zero component of the $\chi^2$ and all the others are related by symmetry: 
<math>\chi^{(2)}_{yyy}=-\chi^{(2)}_{yxx}=-\chi^{(2)}_{xxy}=-\chi^{(2)}_{xyx}</math> 
so if you put the field in the <code>|1|1|0|</code> direction you will get: 
<math>\chi^{(2)}_{x**} = \frac{1}{2} \left[\chi^{(2)}_{xxy} + \chi^{(2)}_{xyx} \right] = - \chi^{(2)}_{yyy} </math> 
<math>\chi^{(2)}_{y**} =\frac{1}{2} \left[ \chi^{(2)}_{yyy} + \chi^{(2)}_{yxx} \right] = 0.0 </math>
 
In the figure below you can see the different <math>\chi^{(2)}</math> of monolayer hBN.

[[File:Xhi2 xy.png|center| 800px|xhi2_xy]]

as you can see in the second panel, when the field is in the <code>xy</code> you get a linear combination of <code>\chi^{(2)}</code> corresponding to the equation above, in this case the <code>y</code> is zero while the <code>x</code> component is equal to <math>\chi^{(2)}_{yyy}</code>.

'''Nota bene:''' if you change the direction of the external field you have to remove the corresponding symmetries as explained in the tutorial [[Prerequisites for Real Time_propagation with Yambo#Reduce symmetries real-time linear response tutorial]].

==Non-linear response of low-dimensional structures: 2D or 1D ==

The Yambo code is a 3D periodic code, so when you want to study a low-dimensional system 2D or 1D, you have to use a supercell approach.
For example to simulate the non-linear response in a 2D-crystal one, can put the crystal in the xy plane and choose a larger distance in the z-direction
in order to reduce the interaction between the periodic replica. Clearly in this case k-point sampling will be only in the x,y directions.
For calculations on this type of systems, these two warnings must be taken into account:

* if you calculate GW corrections or include electron-hole interaction in the linear/non-linear response it is a good idea to use a '''Coulomb cutoff''', similar to the 2D BSE case [http://www.yambo-code.org/wiki/index.php?title=How_to_treat_low_dimensional_systems How to treat low dimensional systems]. You can add the cutoff just adding the "-r" in the input generation.

* the calculation of SHG and THG are always performed respect to the supercell, therefore you have to '''re-scale''' the result to the effective thickness of the layer, usually the inter-layer distance of the corresponding bulk material for 2D systems: <math>\chi_{rescaled}(\omega) = L_z/d_{eff} \cdot \chi(\omega) </math> where <math>L_z</math> is the z-dimension of the supercell, and <math>d_{eff}</math> is the effective thickness of the 2D system.

'''Nota bene''': Non-linear response along non-periodic directions is not implemented in Yambo, the code will print zero in these directions for all response functions. We plan to implement it in a future version of the code.

==References==
<references />

==Links for schools==
* Back to [[Rome 2023#Tutorials]]
* Back to [[ICTP2020]]

 
{| style="width:100%" border="1"
|style="width:25%; text-align:left"|Prev: [[Linear response from real time simulations|Linear response from real time simulations]]
|style="width:45%; text-align:center"|Now: [[ICTP2020|ICTP Tutorials]] --> [[Real time approach to non-linear response|Non Linear Response]]
|style="width:50%; text-align:left"|Next: [[Correlation effects in the non-linear response|Correlation effects in the non-linear response ]]
|-
|}

Real time approach to non-linear response (SHG)

2025-09-28T07:50:38Z

Attacc: /* How to choose the external field direction for the different X2 */

== Second Harmonic Generation in AlAs ==
In this tutorial, we will calculate the second harmonic generation of bulk AlAs, the Yambo databases can be downloaded here: [https://media.yambo-code.eu/educational/tutorials/files/AlAs_DBs.tar.gz AlAs_DBs.tar.gz] (10 MB). The first steps of this tutorials are the same as the one on [http://www.yambo-code.eu/wiki/index.php?title=Prerequisites_for_Real_Time_propagation_with_Yambo Prerequisites for Real-Time propagation with Yambo] with the only difference that we will work on AlAs and we will consider an external field in the direction <code> 1.000000 | 1.000000 | 0.000000 |</code>. The DFT input are available here: [https://media.yambo-code.eu/educational/tutorials/files/AlAs_abinit.tar.gz ABINIT] or [https://media.yambo-code.eu/educational/tutorials/files/AlAs_pwscf.tar.gz QuantumEspresso].
You can run the DFT calculation with ABINIT with the command:

abinit < AlAs.in > output_AlAs

or using QuantumEspresso:

pw.x -inp AlAs.scf.in > output_scf
pw.x -inp AlAs.nscf.in > output_scf

and then import the ABINIT wave-function with the command:

a2y -F AlAso_DS2_WFK.nc

and the QuantumEspresso one, in the folder AlAs.save with the command:

p2y
Now we consider an external field in the <code>[1,1,0]</code> direction and remove symmetries not compatible with this field, as explained in the tutorial [http://www.yambo-code.eu/wiki/index.php?title=Prerequisites_for_Real_Time_propagation_with_Yambo Prerequisites for Real-Time propagation with Yambo].

==Real-time simulation for the SHG==

You can generate the input file with the command <code>yambo_nl -u n</code>:

nloptics # [R NL] Non-linear optics
% NLBands
 3 | 6 | # [NL] Bands
%
NLstep= 0.0100 fs # [NL] Real Time step length
NLverbosity= "high" # [NL] Verbosity level (low | high)
NLtime=-1.000000 fs # [NL] Simulation Time
NLintegrator= "INVINT" # [NL] Integrator ("EULEREXP/RK4/RK2EXP/HEUN/INVINT/CRANKNIC")
NLCorrelation= "IPA" # [NL] Correlation ("IPA/HARTREE/TDDFT/LRC/JGM/SEX/HF")
NLLrcAlpha= 0.000000 # [NL] Long Range Correction
% NLEnRange
 1.000000 | 5.000000 | eV # [NL] Energy range
%
NLEnSteps= 5 # [NL] Energy steps
NLDamping= 0.150000 eV # [NL] Damping
% Field1_Dir
 1.000000 | 1.000000 | 0.000000 | # [RT Field1] Versor
Field1_kind= "SOFTSIN" # [NL ExtF] Kind(SIN|SOFTSIN|RES|ANTIRES|GAUSS|DELTA|QSSIN)

The line <code>|1.000000 | 1.000000 | 0.000000 | # [RT Field1] Versor</code> referees to the direction of the external field (x,y,0). At present only an external field is present but the code can be easily generalized to deal with more fields.
The default parameters of Yambo/Lumen are already tuned for second-harmonic generation, so the only thing you have to change is the band range, between 3 and 6 and the energy range between 1.0-5.0 eV and the number of energy steps in this interval that we set to 10. Notice that you cannot set to zero the lowest value of the energy range because this will requires a simulation that lasts infinite time, see below. Finally, consider that Yambo performs a separate calculation for each frequency, so if you set many energy steps the computational time grows linearly with this number.
Notice that we set <code>NLverbosity= "high"</code> in this way the code will produce a file for each laser frequency containing the time dependent polarization.
Run <code>yambo_nl</code>. Calculations will take about fifteen minutes on a single processor PC, you have time to study the next section that explains how non-linear response is extracted from the real-time simulations.
In order to speed up calculations, you can run them in parallel.

==Non-linear response with Yambo==

In order to calculate the non-linear response, the system is excited with different laser fields with a sinusoidal shape at frequencies <math>\omega_1, \omega_2, .... , \omega_n </math> determined by the parameters [[Variables#NLEnRangev|NLEnRange]] and [[Variables#NLEnSteps|NLEnSteps]]. A dephasing term is added to the Hamiltonian <math>\gamma = </math>[[Variables#NLDamping|NLDamping]] to simulate a finite broadening and to remove the eigenmodes that are excited by the sudden turning on of the external field. After the dephasing time the outgoing signal is analyzed to extract the non-linear coefficients as shown in the figure below:

[[File:Pt analysis.png|600px|center|Non-linear response analysis]]

In the report file <code>r_nlinear</code> you will find the length of the dephasing part and of the sampling one:

Dephasing Time [fs]: 52.65695
Sampling Time [fs]: 4.18566
Total simulation time [fs]: 56.84262
The length of the dephasing interval is inversely proportional to the damping term <math>T_{depth} \simeq 1/\gamma</math> while the length of the sampling is dictated by the smallest frequency we are interested in: <math>T_{samp} \simeq 1/\omega_1 </math>. For this reason if <math> \omega_1=0 </math> or <math> \gamma = 0 </math> simulation time goes to infinity. The response at zero frequency can be calculated as limit of small frequency perturbation.
You can have a look to the file <code>src/nloptics/NL_initialize.F</code> to see how simulation lengths are defined.
Calculations can take some time, run them in parallel, the best number of processors = number of frequencies or reduce the number of frequencies step in the SHG.

==Analysis of the results==

In the sampling region we suppose that the polarization can be written as: <math>\bf{P}(t) = \sum_{n=-\infty}^{+\infty} \bf{p}_n e^{-i\omega_n t} </math> where the coefficient <math>\bf{p}_1,...,\bf{p}_n </math> are related to <math>\chi^{(1)},...,\chi^{(n)} </math>. We sample the polarization signal at different times and invert the previous equation by truncating the sum at a finite order <ref>[https://arxiv.org/abs/1309.4012 Nonlinear optics from an ab initio approach by means of the dynamical Berry phase: Application to second- and third-harmonic generation in semiconductors], C. Attaccalite and M. Grüning, Phys. Rev. B 88, 235113(2013)</ref>.
This is done with the command <code>ypp_nl -u</code> that automatically produce an input with the correct values:

nonlinear # [R] NonLinear Optics Post-Processing
Xorder= 4 # Max order of the response functions
% TimeRange
52.65695 | -1.00000 | fs # Time-window where processing is done
%
ETStpsRt= 200 # Total Energy steps
% EnRngeRt
0.00000 | 10.00000 | eV # Energy range
%
DampMode= "NONE" # Damping type ( NONE | LORENTZIAN | GAUSSIAN )
DampFactor= 0.10000 eV # Damping parameter

where <code>Xorder</code> is the order where the previous sum is truncated, and the TimeRange specifies the sampling region. Notice that differently from the first tutorial, in this case, we do not need Damping in <code>ypp_nl</code> because we already included it in the real-time dynamics. Run <code>ypp_nl</code> and it will produce a file called <code>o.YPP-X_probe_order_2</code>. This file contains the different components of <math>\chi^2_{xy*} </math> and in particular the columns 6 and 7 correspond to the imaginary and real part of <math>\chi^2_{xyz} </math>. You can plot the result with gnuplot and the command:

p 'o.YPP-X_probe_order_2' u 1:(sqrt($6**2+$7**2)) w lp ps 1.5 pt 7 lw 1.5

the result should look like

[[File:AlAs results.png|700px|center|SHG in AlAs]]

and compare it with the <math> \chi^2_{zxy} </math> calculated with more frequencies and with the converged result on a <math> 18x18x18</math> k-point grid and bands between 2 and 10. In the figure you can find also the comparison with the results of Ref. <ref>Luppi et al. [https://arxiv.org/abs/1006.2649 PRB B, '''82''', 235201(2010)]</ref>.
Notice that the QuantumEspresso results are slightly different from the Abinit ones. This is due to the different pseudo-potential employed in the calculations if pseudopotentials were the same calculation would have been identical. You can download the script to generate this plot and the converged results [http://www.attaccalite.com/lumen/tutorials/AlAs/AlAs_results.tgz here].

'''Notice that''' : the following parameters are not used in the non-linear response analysis: <code> EnRngeRt</code>, <code>ETStpsRt</code>, <code>DampMode</code>, <code>DampFactor</code>. The damping factor is set directly in the real-time simulation.

'''System of units in Non-linear Optics''': notice that in Yambo the non-linear response functions are in the gaussian system of units, for example the <math> \chi^2 (\omega) </math> is in cm/statvolt. In order to convert the non-linear coefficients between different system of units, you can have a look at the [https://www.attaccalite.com/tutorials_yambo/Appendix_C_Boyd.pdf Appendix C] of the book [https://www.elsevier.com/books/nonlinear-optics/boyd/978-0-12-369470-6 "Non-linear optics" by Robert W. Boyd].

More tutorials on non-linear response (Third harmonic generation, parallelization, spin-orbit etc..) with Yambo can be found here: [http://www.attaccalite.com/lumen/tutorials.html More Tutorials]. 

==Analysis of the results using YamboPy==
The analysis of the result performed in the previous section using <code>ypp_nl</code> can be performed using python script [https://github.com/yambo-code/yambopy YamboPy]. 
In YamboPy we implemented all necessary functions to reads the Yambo databases and post-process the results. Here we show how to get the SHG signal from the previous
simulations. We suppose you correctly installed <code>YamboPy</code> on your PC. Go in the folder where you ran non-linear calculation and type in the python:
 
from yambopy import *
NLDB=YamboNLDB()
pol =NLDB.Polarization[0]
time=NLDB.IO_TIME_points

in this way you read all the Non-linear databases. If your runs are in a different folder then the 'SAVE' one you can specify it using the command:
NLDB=YamboNLDB(calc='MYJOB')

now in the array <code>pol</code> you have all the polarization for all laser frequencies in the three Cartesian directions, while the variable <code>time</code> contains all the time series of your simulation.
Now you can get the non-linear response with the command:

Harmonic_Analysis(NLDB,X_order=4)

this command will perform a Fourier analysis of the results in the same way of <code>ypp_nl</code> and generate new files with all the requested harmonics ''o.YamboPy-X_probe_order_1'', ''o.YamboPy-X_probe_order_2'' etc...
equivalent to the one generated by <code>ypp_nl</code>. Results can be plot with gnuplot using the command:

p 'o.YamboPy-X_probe_order_2' u 1:(sqrt($6**2+$7**2)) w lp ps 1.5 pt 7 lw 1.5

The script that performs non-linear analysis can be found in <code>yambopy/nl/harmonic_analysis.py</code>. We strongly advice you to have a look to this script and modify it according
to your needs and in order to extract other non-linear response functions.

==How to choose the external field direction for the different X2==

In the X2abc response you have three field directions. The two components ''b'' and ''c'' are determined by the external field and the third ''a''
is the direction where you measure the response. 

The external field in Yambo is set using the variable
% Field1_Dir
1.000000 | 0.000000 | 0.000000 | # [NL ExtF] Versor .
%

For example if you set in Yambo field direction as:

1.0 | 0.0 | 0.0 | ---> you calculate all components X2*xx
0.0 | 1.0 | 0.0 | ---> you calculate all components X2*yy
0.0 | 0.0 | 1.0 | ---> you calculate all components X2*zz

the * correspond to the different direction in the response file <code>o.YPP-X_probe_order_2</code>.
In the <code>o.YPP-X_probe_order_2</code> you have seven columns:

The first column is the energy [[omega]],
the 2nd and 3rd columns are the imaginary and real part of X2x**
the 4th and 5th columns are the imaginary and real part of X2y**
the 6th and 7th columns are the imaginary and real part of X2z**

where the ** are the direction of the incoming field, see above.

For example if you want to calculate the <math>\chi^{(2)}_{zxx}</math> you put the external field in the direction <code> 1.0 | 0.0 | 0.0 |</code>
and then plot the column 6 and 7 of the <code>o.YPP-X_probe_order_2</code> file. 

In order to get the other components of the X2 the calculation are more involved. For example if you put field in the

1.0 | 1.0 | 0.0 |

this corresponds to <math>E(t)=\frac{1}{\sqrt{2}} [ E_x(t) + E_y(t) ]</math> and so at the second order you will have <math>E^2(t)=\frac{1}{2} \left [ E^2_x(t) + E^2_y(t) + E_x(t) E_y(t) + E_y(t) E_x(t) \right]</math> 
this means that the X2 in the <code>o.YPP-X_probe_order_2</code> will correspond to a linear combination of the following different response functions. 
For example in the the 2nd and 3rd columns are the imaginary and real part of: 

<math>\chi^{(2)}_{x**}=\frac{1}{2} \left [\chi^2_{xxx}+\chi^{(2)}_{xyy} + \chi^{(2)}_{xxy} + \chi^{(2)}_{xyx} \right ]</math>

the same for the other column replacing the first <code>x</code> for <code>y,z</code>.
If you know that some components are zero this allow you to extract the corresponding off-diagonal part of <math>\chi^{(2)}_{abc}</math> otherwise you have to perform different calculations to get the component you are interested in. 
Now we present '''a simple example of monolayer hBN (m-hBN)'''. In m-hBN there is only a non-zero component of the $\chi^2$ and all the others are related by symmetry: 
<math>\chi^{(2)}_{yyy}=-\chi^{(2)}_{yxx}=-\chi^{(2)}_{xxy}=-\chi^{(2)}_{xyx}</math> 
so if you put the field in the <code>|1|1|0|</code> direction you will get: 
<math>\chi^{(2)}_{x**} = \frac{1}{2} \left[\chi^{(2)}_{xxy} + \chi^{(2)}_{xyx} \right] = - \chi^{(2)}_{yyy} </math> 
<math>\chi^{(2)}_{y**} =\frac{1}{2} \left[ \chi^{(2)}_{yyy} + \chi^{(2)}_{yxx} \right] = 0.0 </math>
 
In the figure below you can see the different $\chi^{(2)}$ of monolayer hBN.

[[File:Xhi2 xy.png|center| 800px|xhi2_xy]]

'''Nota bene:''' if you change the direction of the external field you have to remove the corresponding symmetries as explained in the tutorial [[Prerequisites for Real Time_propagation with Yambo#Reduce symmetries real-time linear response tutorial]].

==Non-linear response of low-dimensional structures: 2D or 1D ==

The Yambo code is a 3D periodic code, so when you want to study a low-dimensional system 2D or 1D, you have to use a supercell approach.
For example to simulate the non-linear response in a 2D-crystal one, can put the crystal in the xy plane and choose a larger distance in the z-direction
in order to reduce the interaction between the periodic replica. Clearly in this case k-point sampling will be only in the x,y directions.
For calculations on this type of systems, these two warnings must be taken into account:

* if you calculate GW corrections or include electron-hole interaction in the linear/non-linear response it is a good idea to use a '''Coulomb cutoff''', similar to the 2D BSE case [http://www.yambo-code.org/wiki/index.php?title=How_to_treat_low_dimensional_systems How to treat low dimensional systems]. You can add the cutoff just adding the "-r" in the input generation.

* the calculation of SHG and THG are always performed respect to the supercell, therefore you have to '''re-scale''' the result to the effective thickness of the layer, usually the inter-layer distance of the corresponding bulk material for 2D systems: <math>\chi_{rescaled}(\omega) = L_z/d_{eff} \cdot \chi(\omega) </math> where <math>L_z</math> is the z-dimension of the supercell, and <math>d_{eff}</math> is the effective thickness of the 2D system.

'''Nota bene''': Non-linear response along non-periodic directions is not implemented in Yambo, the code will print zero in these directions for all response functions. We plan to implement it in a future version of the code.

==References==
<references />

==Links for schools==
* Back to [[Rome 2023#Tutorials]]
* Back to [[ICTP2020]]

 
{| style="width:100%" border="1"
|style="width:25%; text-align:left"|Prev: [[Linear response from real time simulations|Linear response from real time simulations]]
|style="width:45%; text-align:center"|Now: [[ICTP2020|ICTP Tutorials]] --> [[Real time approach to non-linear response|Non Linear Response]]
|style="width:50%; text-align:left"|Next: [[Correlation effects in the non-linear response|Correlation effects in the non-linear response ]]
|-
|}

Real time approach to non-linear response (SHG)

2025-09-28T07:50:22Z

Attacc: /* How to choose the external field direction for the different X2 */

== Second Harmonic Generation in AlAs ==
In this tutorial, we will calculate the second harmonic generation of bulk AlAs, the Yambo databases can be downloaded here: [https://media.yambo-code.eu/educational/tutorials/files/AlAs_DBs.tar.gz AlAs_DBs.tar.gz] (10 MB). The first steps of this tutorials are the same as the one on [http://www.yambo-code.eu/wiki/index.php?title=Prerequisites_for_Real_Time_propagation_with_Yambo Prerequisites for Real-Time propagation with Yambo] with the only difference that we will work on AlAs and we will consider an external field in the direction <code> 1.000000 | 1.000000 | 0.000000 |</code>. The DFT input are available here: [https://media.yambo-code.eu/educational/tutorials/files/AlAs_abinit.tar.gz ABINIT] or [https://media.yambo-code.eu/educational/tutorials/files/AlAs_pwscf.tar.gz QuantumEspresso].
You can run the DFT calculation with ABINIT with the command:

abinit < AlAs.in > output_AlAs

or using QuantumEspresso:

pw.x -inp AlAs.scf.in > output_scf
pw.x -inp AlAs.nscf.in > output_scf

and then import the ABINIT wave-function with the command:

a2y -F AlAso_DS2_WFK.nc

and the QuantumEspresso one, in the folder AlAs.save with the command:

p2y
Now we consider an external field in the <code>[1,1,0]</code> direction and remove symmetries not compatible with this field, as explained in the tutorial [http://www.yambo-code.eu/wiki/index.php?title=Prerequisites_for_Real_Time_propagation_with_Yambo Prerequisites for Real-Time propagation with Yambo].

==Real-time simulation for the SHG==

You can generate the input file with the command <code>yambo_nl -u n</code>:

nloptics # [R NL] Non-linear optics
% NLBands
 3 | 6 | # [NL] Bands
%
NLstep= 0.0100 fs # [NL] Real Time step length
NLverbosity= "high" # [NL] Verbosity level (low | high)
NLtime=-1.000000 fs # [NL] Simulation Time
NLintegrator= "INVINT" # [NL] Integrator ("EULEREXP/RK4/RK2EXP/HEUN/INVINT/CRANKNIC")
NLCorrelation= "IPA" # [NL] Correlation ("IPA/HARTREE/TDDFT/LRC/JGM/SEX/HF")
NLLrcAlpha= 0.000000 # [NL] Long Range Correction
% NLEnRange
 1.000000 | 5.000000 | eV # [NL] Energy range
%
NLEnSteps= 5 # [NL] Energy steps
NLDamping= 0.150000 eV # [NL] Damping
% Field1_Dir
 1.000000 | 1.000000 | 0.000000 | # [RT Field1] Versor
Field1_kind= "SOFTSIN" # [NL ExtF] Kind(SIN|SOFTSIN|RES|ANTIRES|GAUSS|DELTA|QSSIN)

The line <code>|1.000000 | 1.000000 | 0.000000 | # [RT Field1] Versor</code> referees to the direction of the external field (x,y,0). At present only an external field is present but the code can be easily generalized to deal with more fields.
The default parameters of Yambo/Lumen are already tuned for second-harmonic generation, so the only thing you have to change is the band range, between 3 and 6 and the energy range between 1.0-5.0 eV and the number of energy steps in this interval that we set to 10. Notice that you cannot set to zero the lowest value of the energy range because this will requires a simulation that lasts infinite time, see below. Finally, consider that Yambo performs a separate calculation for each frequency, so if you set many energy steps the computational time grows linearly with this number.
Notice that we set <code>NLverbosity= "high"</code> in this way the code will produce a file for each laser frequency containing the time dependent polarization.
Run <code>yambo_nl</code>. Calculations will take about fifteen minutes on a single processor PC, you have time to study the next section that explains how non-linear response is extracted from the real-time simulations.
In order to speed up calculations, you can run them in parallel.

==Non-linear response with Yambo==

In order to calculate the non-linear response, the system is excited with different laser fields with a sinusoidal shape at frequencies <math>\omega_1, \omega_2, .... , \omega_n </math> determined by the parameters [[Variables#NLEnRangev|NLEnRange]] and [[Variables#NLEnSteps|NLEnSteps]]. A dephasing term is added to the Hamiltonian <math>\gamma = </math>[[Variables#NLDamping|NLDamping]] to simulate a finite broadening and to remove the eigenmodes that are excited by the sudden turning on of the external field. After the dephasing time the outgoing signal is analyzed to extract the non-linear coefficients as shown in the figure below:

[[File:Pt analysis.png|600px|center|Non-linear response analysis]]

In the report file <code>r_nlinear</code> you will find the length of the dephasing part and of the sampling one:

Dephasing Time [fs]: 52.65695
Sampling Time [fs]: 4.18566
Total simulation time [fs]: 56.84262
The length of the dephasing interval is inversely proportional to the damping term <math>T_{depth} \simeq 1/\gamma</math> while the length of the sampling is dictated by the smallest frequency we are interested in: <math>T_{samp} \simeq 1/\omega_1 </math>. For this reason if <math> \omega_1=0 </math> or <math> \gamma = 0 </math> simulation time goes to infinity. The response at zero frequency can be calculated as limit of small frequency perturbation.
You can have a look to the file <code>src/nloptics/NL_initialize.F</code> to see how simulation lengths are defined.
Calculations can take some time, run them in parallel, the best number of processors = number of frequencies or reduce the number of frequencies step in the SHG.

==Analysis of the results==

In the sampling region we suppose that the polarization can be written as: <math>\bf{P}(t) = \sum_{n=-\infty}^{+\infty} \bf{p}_n e^{-i\omega_n t} </math> where the coefficient <math>\bf{p}_1,...,\bf{p}_n </math> are related to <math>\chi^{(1)},...,\chi^{(n)} </math>. We sample the polarization signal at different times and invert the previous equation by truncating the sum at a finite order <ref>[https://arxiv.org/abs/1309.4012 Nonlinear optics from an ab initio approach by means of the dynamical Berry phase: Application to second- and third-harmonic generation in semiconductors], C. Attaccalite and M. Grüning, Phys. Rev. B 88, 235113(2013)</ref>.
This is done with the command <code>ypp_nl -u</code> that automatically produce an input with the correct values:

nonlinear # [R] NonLinear Optics Post-Processing
Xorder= 4 # Max order of the response functions
% TimeRange
52.65695 | -1.00000 | fs # Time-window where processing is done
%
ETStpsRt= 200 # Total Energy steps
% EnRngeRt
0.00000 | 10.00000 | eV # Energy range
%
DampMode= "NONE" # Damping type ( NONE | LORENTZIAN | GAUSSIAN )
DampFactor= 0.10000 eV # Damping parameter

where <code>Xorder</code> is the order where the previous sum is truncated, and the TimeRange specifies the sampling region. Notice that differently from the first tutorial, in this case, we do not need Damping in <code>ypp_nl</code> because we already included it in the real-time dynamics. Run <code>ypp_nl</code> and it will produce a file called <code>o.YPP-X_probe_order_2</code>. This file contains the different components of <math>\chi^2_{xy*} </math> and in particular the columns 6 and 7 correspond to the imaginary and real part of <math>\chi^2_{xyz} </math>. You can plot the result with gnuplot and the command:

p 'o.YPP-X_probe_order_2' u 1:(sqrt($6**2+$7**2)) w lp ps 1.5 pt 7 lw 1.5

the result should look like

[[File:AlAs results.png|700px|center|SHG in AlAs]]

and compare it with the <math> \chi^2_{zxy} </math> calculated with more frequencies and with the converged result on a <math> 18x18x18</math> k-point grid and bands between 2 and 10. In the figure you can find also the comparison with the results of Ref. <ref>Luppi et al. [https://arxiv.org/abs/1006.2649 PRB B, '''82''', 235201(2010)]</ref>.
Notice that the QuantumEspresso results are slightly different from the Abinit ones. This is due to the different pseudo-potential employed in the calculations if pseudopotentials were the same calculation would have been identical. You can download the script to generate this plot and the converged results [http://www.attaccalite.com/lumen/tutorials/AlAs/AlAs_results.tgz here].

'''Notice that''' : the following parameters are not used in the non-linear response analysis: <code> EnRngeRt</code>, <code>ETStpsRt</code>, <code>DampMode</code>, <code>DampFactor</code>. The damping factor is set directly in the real-time simulation.

'''System of units in Non-linear Optics''': notice that in Yambo the non-linear response functions are in the gaussian system of units, for example the <math> \chi^2 (\omega) </math> is in cm/statvolt. In order to convert the non-linear coefficients between different system of units, you can have a look at the [https://www.attaccalite.com/tutorials_yambo/Appendix_C_Boyd.pdf Appendix C] of the book [https://www.elsevier.com/books/nonlinear-optics/boyd/978-0-12-369470-6 "Non-linear optics" by Robert W. Boyd].

More tutorials on non-linear response (Third harmonic generation, parallelization, spin-orbit etc..) with Yambo can be found here: [http://www.attaccalite.com/lumen/tutorials.html More Tutorials]. 

==Analysis of the results using YamboPy==
The analysis of the result performed in the previous section using <code>ypp_nl</code> can be performed using python script [https://github.com/yambo-code/yambopy YamboPy]. 
In YamboPy we implemented all necessary functions to reads the Yambo databases and post-process the results. Here we show how to get the SHG signal from the previous
simulations. We suppose you correctly installed <code>YamboPy</code> on your PC. Go in the folder where you ran non-linear calculation and type in the python:
 
from yambopy import *
NLDB=YamboNLDB()
pol =NLDB.Polarization[0]
time=NLDB.IO_TIME_points

in this way you read all the Non-linear databases. If your runs are in a different folder then the 'SAVE' one you can specify it using the command:
NLDB=YamboNLDB(calc='MYJOB')

now in the array <code>pol</code> you have all the polarization for all laser frequencies in the three Cartesian directions, while the variable <code>time</code> contains all the time series of your simulation.
Now you can get the non-linear response with the command:

Harmonic_Analysis(NLDB,X_order=4)

this command will perform a Fourier analysis of the results in the same way of <code>ypp_nl</code> and generate new files with all the requested harmonics ''o.YamboPy-X_probe_order_1'', ''o.YamboPy-X_probe_order_2'' etc...
equivalent to the one generated by <code>ypp_nl</code>. Results can be plot with gnuplot using the command:

p 'o.YamboPy-X_probe_order_2' u 1:(sqrt($6**2+$7**2)) w lp ps 1.5 pt 7 lw 1.5

The script that performs non-linear analysis can be found in <code>yambopy/nl/harmonic_analysis.py</code>. We strongly advice you to have a look to this script and modify it according
to your needs and in order to extract other non-linear response functions.

==How to choose the external field direction for the different X2==

In the X2abc response you have three field directions. The two components ''b'' and ''c'' are determined by the external field and the third ''a''
is the direction where you measure the response. 

The external field in Yambo is set using the variable
% Field1_Dir
1.000000 | 0.000000 | 0.000000 | # [NL ExtF] Versor .
%

For example if you set in Yambo field direction as:

1.0 | 0.0 | 0.0 | ---> you calculate all components X2*xx
0.0 | 1.0 | 0.0 | ---> you calculate all components X2*yy
0.0 | 0.0 | 1.0 | ---> you calculate all components X2*zz

the * correspond to the different direction in the response file <code>o.YPP-X_probe_order_2</code>.
In the <code>o.YPP-X_probe_order_2</code> you have seven columns:

The first column is the energy [[omega]],
the 2nd and 3rd columns are the imaginary and real part of X2x**
the 4th and 5th columns are the imaginary and real part of X2y**
the 6th and 7th columns are the imaginary and real part of X2z**

where the ** are the direction of the incoming field, see above.

For example if you want to calculate the <math>\chi^{(2)}_{zxx}</math> you put the external field in the direction <code> 1.0 | 0.0 | 0.0 |</code>
and then plot the column 6 and 7 of the <code>o.YPP-X_probe_order_2</code> file. 

In order to get the other components of the X2 the calculation are more involved. For example if you put field in the

1.0 | 1.0 | 0.0 |

this corresponds to <math>E(t)=\frac{1}{\sqrt{2}} [ E_x(t) + E_y(t) ]</math> and so at the second order you will have <math>E^2(t)=\frac{1}{2} \left [ E^2_x(t) + E^2_y(t) + E_x(t) E_y(t) + E_y(t) E_x(t) \right]</math> 
this means that the X2 in the <code>o.YPP-X_probe_order_2</code> will correspond to a linear combination of the following different response functions. 
For example in the the 2nd and 3rd columns are the imaginary and real part of: 

<math>\chi^{(2)}_{x**}=\frac{1}{2} \left [\chi^2_{xxx}+\chi^{(2)}_{xyy} + \chi^{(2)}_{xxy} + \chi^{(2)}_{xyx} \right ]</math>

the same for the other column replacing the first <code>x</code> for <code>y,z</code>.
If you know that some components are zero this allow you to extract the corresponding off-diagonal part of <math>\chi^{(2)}_{abc}</math> otherwise you have to perform different calculations to get the component you are interested in. 
Now we present '''a simple example of monolayer hBN (m-hBN)'''. In m-hBN there is only a non-zero component of the $\chi^2$ and all the others are related by symmetry: 
<math>\chi^{(2)}_{yyy}=-\chi^{(2)}_{yxx}=-\chi^{(2)}_{xxy}=-\chi^{(2)}_{xyx}</math> 
so if you put the field in the <code>|1|1|0|</code> direction you will get: 
<math>\chi^{(2)}_{x**} = \frac{1}{2} \left[\chi^{(2)}_{xxy} + \chi^{(2)}_{xyx} \right] = - \chi^{(2)}_{yyy} </math> 
<math>\chi^{(2)}_{y**} =\frac{1}{2} \left[ \chi^{(2)}_{yyy} + \chi^{(2)}_{yxx} \right] = 0.0 </math>
 
In the figure below you can see the different $\chi^{(2)}$ of monolayer hBN.

[[File:Xhi2 xy.png|center| 300px|xhi2_xy]]

'''Nota bene:''' if you change the direction of the external field you have to remove the corresponding symmetries as explained in the tutorial [[Prerequisites for Real Time_propagation with Yambo#Reduce symmetries real-time linear response tutorial]].

==Non-linear response of low-dimensional structures: 2D or 1D ==

The Yambo code is a 3D periodic code, so when you want to study a low-dimensional system 2D or 1D, you have to use a supercell approach.
For example to simulate the non-linear response in a 2D-crystal one, can put the crystal in the xy plane and choose a larger distance in the z-direction
in order to reduce the interaction between the periodic replica. Clearly in this case k-point sampling will be only in the x,y directions.
For calculations on this type of systems, these two warnings must be taken into account:

* if you calculate GW corrections or include electron-hole interaction in the linear/non-linear response it is a good idea to use a '''Coulomb cutoff''', similar to the 2D BSE case [http://www.yambo-code.org/wiki/index.php?title=How_to_treat_low_dimensional_systems How to treat low dimensional systems]. You can add the cutoff just adding the "-r" in the input generation.

* the calculation of SHG and THG are always performed respect to the supercell, therefore you have to '''re-scale''' the result to the effective thickness of the layer, usually the inter-layer distance of the corresponding bulk material for 2D systems: <math>\chi_{rescaled}(\omega) = L_z/d_{eff} \cdot \chi(\omega) </math> where <math>L_z</math> is the z-dimension of the supercell, and <math>d_{eff}</math> is the effective thickness of the 2D system.

'''Nota bene''': Non-linear response along non-periodic directions is not implemented in Yambo, the code will print zero in these directions for all response functions. We plan to implement it in a future version of the code.

==References==
<references />

==Links for schools==
* Back to [[Rome 2023#Tutorials]]
* Back to [[ICTP2020]]

 
{| style="width:100%" border="1"
|style="width:25%; text-align:left"|Prev: [[Linear response from real time simulations|Linear response from real time simulations]]
|style="width:45%; text-align:center"|Now: [[ICTP2020|ICTP Tutorials]] --> [[Real time approach to non-linear response|Non Linear Response]]
|style="width:50%; text-align:left"|Next: [[Correlation effects in the non-linear response|Correlation effects in the non-linear response ]]
|-
|}

File:Xhi2 xy.png

2025-09-28T07:49:20Z

Attacc: Uploaded own work with UploadWizard

=={{int:filedesc}}==
{{Information
|description={{en|1=xhi2_xy}}
|date=2025-09-28
|source={{own}}
|author=[[User:Attacc|Attacc]]
|permission=
|other versions=
}}

=={{int:license-header}}==
{{self|cc-by-sa-4.0}}

This file was uploaded with the UploadWizard extension.

[[Category:Uploaded with UploadWizard]]

Real time approach to non-linear response (SHG)

2025-09-27T10:23:35Z

Attacc: /* How to choose the external field direction for the different X2 */

== Second Harmonic Generation in AlAs ==
In this tutorial, we will calculate the second harmonic generation of bulk AlAs, the Yambo databases can be downloaded here: [https://media.yambo-code.eu/educational/tutorials/files/AlAs_DBs.tar.gz AlAs_DBs.tar.gz] (10 MB). The first steps of this tutorials are the same as the one on [http://www.yambo-code.eu/wiki/index.php?title=Prerequisites_for_Real_Time_propagation_with_Yambo Prerequisites for Real-Time propagation with Yambo] with the only difference that we will work on AlAs and we will consider an external field in the direction <code> 1.000000 | 1.000000 | 0.000000 |</code>. The DFT input are available here: [https://media.yambo-code.eu/educational/tutorials/files/AlAs_abinit.tar.gz ABINIT] or [https://media.yambo-code.eu/educational/tutorials/files/AlAs_pwscf.tar.gz QuantumEspresso].
You can run the DFT calculation with ABINIT with the command:

abinit < AlAs.in > output_AlAs

or using QuantumEspresso:

pw.x -inp AlAs.scf.in > output_scf
pw.x -inp AlAs.nscf.in > output_scf

and then import the ABINIT wave-function with the command:

a2y -F AlAso_DS2_WFK.nc

and the QuantumEspresso one, in the folder AlAs.save with the command:

p2y
Now we consider an external field in the <code>[1,1,0]</code> direction and remove symmetries not compatible with this field, as explained in the tutorial [http://www.yambo-code.eu/wiki/index.php?title=Prerequisites_for_Real_Time_propagation_with_Yambo Prerequisites for Real-Time propagation with Yambo].

==Real-time simulation for the SHG==

You can generate the input file with the command <code>yambo_nl -u n</code>:

nloptics # [R NL] Non-linear optics
% NLBands
 3 | 6 | # [NL] Bands
%
NLstep= 0.0100 fs # [NL] Real Time step length
NLverbosity= "high" # [NL] Verbosity level (low | high)
NLtime=-1.000000 fs # [NL] Simulation Time
NLintegrator= "INVINT" # [NL] Integrator ("EULEREXP/RK4/RK2EXP/HEUN/INVINT/CRANKNIC")
NLCorrelation= "IPA" # [NL] Correlation ("IPA/HARTREE/TDDFT/LRC/JGM/SEX/HF")
NLLrcAlpha= 0.000000 # [NL] Long Range Correction
% NLEnRange
 1.000000 | 5.000000 | eV # [NL] Energy range
%
NLEnSteps= 5 # [NL] Energy steps
NLDamping= 0.150000 eV # [NL] Damping
% Field1_Dir
 1.000000 | 1.000000 | 0.000000 | # [RT Field1] Versor
Field1_kind= "SOFTSIN" # [NL ExtF] Kind(SIN|SOFTSIN|RES|ANTIRES|GAUSS|DELTA|QSSIN)

The line <code>|1.000000 | 1.000000 | 0.000000 | # [RT Field1] Versor</code> referees to the direction of the external field (x,y,0). At present only an external field is present but the code can be easily generalized to deal with more fields.
The default parameters of Yambo/Lumen are already tuned for second-harmonic generation, so the only thing you have to change is the band range, between 3 and 6 and the energy range between 1.0-5.0 eV and the number of energy steps in this interval that we set to 10. Notice that you cannot set to zero the lowest value of the energy range because this will requires a simulation that lasts infinite time, see below. Finally, consider that Yambo performs a separate calculation for each frequency, so if you set many energy steps the computational time grows linearly with this number.
Notice that we set <code>NLverbosity= "high"</code> in this way the code will produce a file for each laser frequency containing the time dependent polarization.
Run <code>yambo_nl</code>. Calculations will take about fifteen minutes on a single processor PC, you have time to study the next section that explains how non-linear response is extracted from the real-time simulations.
In order to speed up calculations, you can run them in parallel.

==Non-linear response with Yambo==

In order to calculate the non-linear response, the system is excited with different laser fields with a sinusoidal shape at frequencies <math>\omega_1, \omega_2, .... , \omega_n </math> determined by the parameters [[Variables#NLEnRangev|NLEnRange]] and [[Variables#NLEnSteps|NLEnSteps]]. A dephasing term is added to the Hamiltonian <math>\gamma = </math>[[Variables#NLDamping|NLDamping]] to simulate a finite broadening and to remove the eigenmodes that are excited by the sudden turning on of the external field. After the dephasing time the outgoing signal is analyzed to extract the non-linear coefficients as shown in the figure below:

[[File:Pt analysis.png|600px|center|Non-linear response analysis]]

In the report file <code>r_nlinear</code> you will find the length of the dephasing part and of the sampling one:

Dephasing Time [fs]: 52.65695
Sampling Time [fs]: 4.18566
Total simulation time [fs]: 56.84262
The length of the dephasing interval is inversely proportional to the damping term <math>T_{depth} \simeq 1/\gamma</math> while the length of the sampling is dictated by the smallest frequency we are interested in: <math>T_{samp} \simeq 1/\omega_1 </math>. For this reason if <math> \omega_1=0 </math> or <math> \gamma = 0 </math> simulation time goes to infinity. The response at zero frequency can be calculated as limit of small frequency perturbation.
You can have a look to the file <code>src/nloptics/NL_initialize.F</code> to see how simulation lengths are defined.
Calculations can take some time, run them in parallel, the best number of processors = number of frequencies or reduce the number of frequencies step in the SHG.

==Analysis of the results==

In the sampling region we suppose that the polarization can be written as: <math>\bf{P}(t) = \sum_{n=-\infty}^{+\infty} \bf{p}_n e^{-i\omega_n t} </math> where the coefficient <math>\bf{p}_1,...,\bf{p}_n </math> are related to <math>\chi^{(1)},...,\chi^{(n)} </math>. We sample the polarization signal at different times and invert the previous equation by truncating the sum at a finite order <ref>[https://arxiv.org/abs/1309.4012 Nonlinear optics from an ab initio approach by means of the dynamical Berry phase: Application to second- and third-harmonic generation in semiconductors], C. Attaccalite and M. Grüning, Phys. Rev. B 88, 235113(2013)</ref>.
This is done with the command <code>ypp_nl -u</code> that automatically produce an input with the correct values:

nonlinear # [R] NonLinear Optics Post-Processing
Xorder= 4 # Max order of the response functions
% TimeRange
52.65695 | -1.00000 | fs # Time-window where processing is done
%
ETStpsRt= 200 # Total Energy steps
% EnRngeRt
0.00000 | 10.00000 | eV # Energy range
%
DampMode= "NONE" # Damping type ( NONE | LORENTZIAN | GAUSSIAN )
DampFactor= 0.10000 eV # Damping parameter

where <code>Xorder</code> is the order where the previous sum is truncated, and the TimeRange specifies the sampling region. Notice that differently from the first tutorial, in this case, we do not need Damping in <code>ypp_nl</code> because we already included it in the real-time dynamics. Run <code>ypp_nl</code> and it will produce a file called <code>o.YPP-X_probe_order_2</code>. This file contains the different components of <math>\chi^2_{xy*} </math> and in particular the columns 6 and 7 correspond to the imaginary and real part of <math>\chi^2_{xyz} </math>. You can plot the result with gnuplot and the command:

p 'o.YPP-X_probe_order_2' u 1:(sqrt($6**2+$7**2)) w lp ps 1.5 pt 7 lw 1.5

the result should look like

[[File:AlAs results.png|700px|center|SHG in AlAs]]

and compare it with the <math> \chi^2_{zxy} </math> calculated with more frequencies and with the converged result on a <math> 18x18x18</math> k-point grid and bands between 2 and 10. In the figure you can find also the comparison with the results of Ref. <ref>Luppi et al. [https://arxiv.org/abs/1006.2649 PRB B, '''82''', 235201(2010)]</ref>.
Notice that the QuantumEspresso results are slightly different from the Abinit ones. This is due to the different pseudo-potential employed in the calculations if pseudopotentials were the same calculation would have been identical. You can download the script to generate this plot and the converged results [http://www.attaccalite.com/lumen/tutorials/AlAs/AlAs_results.tgz here].

'''Notice that''' : the following parameters are not used in the non-linear response analysis: <code> EnRngeRt</code>, <code>ETStpsRt</code>, <code>DampMode</code>, <code>DampFactor</code>. The damping factor is set directly in the real-time simulation.

'''System of units in Non-linear Optics''': notice that in Yambo the non-linear response functions are in the gaussian system of units, for example the <math> \chi^2 (\omega) </math> is in cm/statvolt. In order to convert the non-linear coefficients between different system of units, you can have a look at the [https://www.attaccalite.com/tutorials_yambo/Appendix_C_Boyd.pdf Appendix C] of the book [https://www.elsevier.com/books/nonlinear-optics/boyd/978-0-12-369470-6 "Non-linear optics" by Robert W. Boyd].

More tutorials on non-linear response (Third harmonic generation, parallelization, spin-orbit etc..) with Yambo can be found here: [http://www.attaccalite.com/lumen/tutorials.html More Tutorials]. 

==Analysis of the results using YamboPy==
The analysis of the result performed in the previous section using <code>ypp_nl</code> can be performed using python script [https://github.com/yambo-code/yambopy YamboPy]. 
In YamboPy we implemented all necessary functions to reads the Yambo databases and post-process the results. Here we show how to get the SHG signal from the previous
simulations. We suppose you correctly installed <code>YamboPy</code> on your PC. Go in the folder where you ran non-linear calculation and type in the python:
 
from yambopy import *
NLDB=YamboNLDB()
pol =NLDB.Polarization[0]
time=NLDB.IO_TIME_points

in this way you read all the Non-linear databases. If your runs are in a different folder then the 'SAVE' one you can specify it using the command:
NLDB=YamboNLDB(calc='MYJOB')

now in the array <code>pol</code> you have all the polarization for all laser frequencies in the three Cartesian directions, while the variable <code>time</code> contains all the time series of your simulation.
Now you can get the non-linear response with the command:

Harmonic_Analysis(NLDB,X_order=4)

this command will perform a Fourier analysis of the results in the same way of <code>ypp_nl</code> and generate new files with all the requested harmonics ''o.YamboPy-X_probe_order_1'', ''o.YamboPy-X_probe_order_2'' etc...
equivalent to the one generated by <code>ypp_nl</code>. Results can be plot with gnuplot using the command:

p 'o.YamboPy-X_probe_order_2' u 1:(sqrt($6**2+$7**2)) w lp ps 1.5 pt 7 lw 1.5

The script that performs non-linear analysis can be found in <code>yambopy/nl/harmonic_analysis.py</code>. We strongly advice you to have a look to this script and modify it according
to your needs and in order to extract other non-linear response functions.

==How to choose the external field direction for the different X2==

In the X2abc response you have three field directions. The two components ''b'' and ''c'' are determined by the external field and the third ''a''
is the direction where you measure the response. 

The external field in Yambo is set using the variable
% Field1_Dir
1.000000 | 0.000000 | 0.000000 | # [NL ExtF] Versor .
%

For example if you set in Yambo field direction as:

1.0 | 0.0 | 0.0 | ---> you calculate all components X2*xx
0.0 | 1.0 | 0.0 | ---> you calculate all components X2*yy
0.0 | 0.0 | 1.0 | ---> you calculate all components X2*zz

the * correspond to the different direction in the response file <code>o.YPP-X_probe_order_2</code>.
In the <code>o.YPP-X_probe_order_2</code> you have seven columns:

The first column is the energy [[omega]],
the 2nd and 3rd columns are the imaginary and real part of X2x**
the 4th and 5th columns are the imaginary and real part of X2y**
the 6th and 7th columns are the imaginary and real part of X2z**

where the ** are the direction of the incoming field, see above.

For example if you want to calculate the <math>\chi^{(2)}_{zxx}</math> you put the external field in the direction <code> 1.0 | 0.0 | 0.0 |</code>
and then plot the column 6 and 7 of the <code>o.YPP-X_probe_order_2</code> file. 

In order to get the other components of the X2 the calculation are more involved. For example if you put field in the

1.0 | 1.0 | 0.0 |

this corresponds to <math>E(t)=\frac{1}{\sqrt{2}} [ E_x(t) + E_y(t) ]</math> and so at the second order you will have <math>E^2(t)=\frac{1}{2} \left [ E^2_x(t) + E^2_y(t) + E_x(t) E_y(t) + E_y(t) E_x(t) \right]</math> 
this means that the X2 in the <code>o.YPP-X_probe_order_2</code> will correspond to a linear combination of the following different response functions. 
For example in the the 2nd and 3rd columns are the imaginary and real part of: 

<math>\chi^{(2)}_{x**}=\frac{1}{2} \left [\chi^2_{xxx}+\chi^{(2)}_{xyy} + \chi^{(2)}_{xxy} + \chi^{(2)}_{xyx} \right ]</math>

the same for the other column replacing the first <code>x</code> for <code>y,z</code>.
If you know that some components are zero this allow you to extract the corresponding off-diagonal part of <math>\chi^{(2)}_{abc}</math> otherwise you have to perform different calculations to get the component you are interested in. 
Now we present '''a simple example of monolayer hBN (m-hBN)'''. In m-hBN there is only a non-zero component of the $\chi^2$ and all the others are related by symmetry: 
<math>\chi^{(2)}_{yyy}=-\chi^{(2)}_{yxx}=-\chi^{(2)}_{xxy}=-\chi^{(2)}_{xyx}</math> 
so if you put the field in the <code>|1|1|0|</code> direction you will get: 
<math>\chi^{(2)}_{x**} = \frac{1}{2} \left[\chi^{(2)}_{xxy} + \chi^{(2)}_{xyx} \right] = - \chi^{(2)}_{yyy} </math> 
<math>\chi^{(2)}_{y**} =\frac{1}{2} \left[ \chi^{(2)}_{yyy} + \chi^{(2)}_{yxx} \right] = 0.0 </math>
 
'''Nota bene:''' if you change the direction of the external field you have to remove the corresponding symmetries as explained in the tutorial [[Prerequisites for Real Time_propagation with Yambo#Reduce symmetries real-time linear response tutorial]].

==Non-linear response of low-dimensional structures: 2D or 1D ==

The Yambo code is a 3D periodic code, so when you want to study a low-dimensional system 2D or 1D, you have to use a supercell approach.
For example to simulate the non-linear response in a 2D-crystal one, can put the crystal in the xy plane and choose a larger distance in the z-direction
in order to reduce the interaction between the periodic replica. Clearly in this case k-point sampling will be only in the x,y directions.
For calculations on this type of systems, these two warnings must be taken into account:

* if you calculate GW corrections or include electron-hole interaction in the linear/non-linear response it is a good idea to use a '''Coulomb cutoff''', similar to the 2D BSE case [http://www.yambo-code.org/wiki/index.php?title=How_to_treat_low_dimensional_systems How to treat low dimensional systems]. You can add the cutoff just adding the "-r" in the input generation.

* the calculation of SHG and THG are always performed respect to the supercell, therefore you have to '''re-scale''' the result to the effective thickness of the layer, usually the inter-layer distance of the corresponding bulk material for 2D systems: <math>\chi_{rescaled}(\omega) = L_z/d_{eff} \cdot \chi(\omega) </math> where <math>L_z</math> is the z-dimension of the supercell, and <math>d_{eff}</math> is the effective thickness of the 2D system.

'''Nota bene''': Non-linear response along non-periodic directions is not implemented in Yambo, the code will print zero in these directions for all response functions. We plan to implement it in a future version of the code.

==References==
<references />

==Links for schools==
* Back to [[Rome 2023#Tutorials]]
* Back to [[ICTP2020]]

 
{| style="width:100%" border="1"
|style="width:25%; text-align:left"|Prev: [[Linear response from real time simulations|Linear response from real time simulations]]
|style="width:45%; text-align:center"|Now: [[ICTP2020|ICTP Tutorials]] --> [[Real time approach to non-linear response|Non Linear Response]]
|style="width:50%; text-align:left"|Next: [[Correlation effects in the non-linear response|Correlation effects in the non-linear response ]]
|-
|}

Real time approach to non-linear response (SHG)

2025-09-27T10:23:18Z

Attacc: /* How to choose the external field direction for the different X2 */

== Second Harmonic Generation in AlAs ==
In this tutorial, we will calculate the second harmonic generation of bulk AlAs, the Yambo databases can be downloaded here: [https://media.yambo-code.eu/educational/tutorials/files/AlAs_DBs.tar.gz AlAs_DBs.tar.gz] (10 MB). The first steps of this tutorials are the same as the one on [http://www.yambo-code.eu/wiki/index.php?title=Prerequisites_for_Real_Time_propagation_with_Yambo Prerequisites for Real-Time propagation with Yambo] with the only difference that we will work on AlAs and we will consider an external field in the direction <code> 1.000000 | 1.000000 | 0.000000 |</code>. The DFT input are available here: [https://media.yambo-code.eu/educational/tutorials/files/AlAs_abinit.tar.gz ABINIT] or [https://media.yambo-code.eu/educational/tutorials/files/AlAs_pwscf.tar.gz QuantumEspresso].
You can run the DFT calculation with ABINIT with the command:

abinit < AlAs.in > output_AlAs

or using QuantumEspresso:

pw.x -inp AlAs.scf.in > output_scf
pw.x -inp AlAs.nscf.in > output_scf

and then import the ABINIT wave-function with the command:

a2y -F AlAso_DS2_WFK.nc

and the QuantumEspresso one, in the folder AlAs.save with the command:

p2y
Now we consider an external field in the <code>[1,1,0]</code> direction and remove symmetries not compatible with this field, as explained in the tutorial [http://www.yambo-code.eu/wiki/index.php?title=Prerequisites_for_Real_Time_propagation_with_Yambo Prerequisites for Real-Time propagation with Yambo].

==Real-time simulation for the SHG==

You can generate the input file with the command <code>yambo_nl -u n</code>:

nloptics # [R NL] Non-linear optics
% NLBands
 3 | 6 | # [NL] Bands
%
NLstep= 0.0100 fs # [NL] Real Time step length
NLverbosity= "high" # [NL] Verbosity level (low | high)
NLtime=-1.000000 fs # [NL] Simulation Time
NLintegrator= "INVINT" # [NL] Integrator ("EULEREXP/RK4/RK2EXP/HEUN/INVINT/CRANKNIC")
NLCorrelation= "IPA" # [NL] Correlation ("IPA/HARTREE/TDDFT/LRC/JGM/SEX/HF")
NLLrcAlpha= 0.000000 # [NL] Long Range Correction
% NLEnRange
 1.000000 | 5.000000 | eV # [NL] Energy range
%
NLEnSteps= 5 # [NL] Energy steps
NLDamping= 0.150000 eV # [NL] Damping
% Field1_Dir
 1.000000 | 1.000000 | 0.000000 | # [RT Field1] Versor
Field1_kind= "SOFTSIN" # [NL ExtF] Kind(SIN|SOFTSIN|RES|ANTIRES|GAUSS|DELTA|QSSIN)

The line <code>|1.000000 | 1.000000 | 0.000000 | # [RT Field1] Versor</code> referees to the direction of the external field (x,y,0). At present only an external field is present but the code can be easily generalized to deal with more fields.
The default parameters of Yambo/Lumen are already tuned for second-harmonic generation, so the only thing you have to change is the band range, between 3 and 6 and the energy range between 1.0-5.0 eV and the number of energy steps in this interval that we set to 10. Notice that you cannot set to zero the lowest value of the energy range because this will requires a simulation that lasts infinite time, see below. Finally, consider that Yambo performs a separate calculation for each frequency, so if you set many energy steps the computational time grows linearly with this number.
Notice that we set <code>NLverbosity= "high"</code> in this way the code will produce a file for each laser frequency containing the time dependent polarization.
Run <code>yambo_nl</code>. Calculations will take about fifteen minutes on a single processor PC, you have time to study the next section that explains how non-linear response is extracted from the real-time simulations.
In order to speed up calculations, you can run them in parallel.

==Non-linear response with Yambo==

In order to calculate the non-linear response, the system is excited with different laser fields with a sinusoidal shape at frequencies <math>\omega_1, \omega_2, .... , \omega_n </math> determined by the parameters [[Variables#NLEnRangev|NLEnRange]] and [[Variables#NLEnSteps|NLEnSteps]]. A dephasing term is added to the Hamiltonian <math>\gamma = </math>[[Variables#NLDamping|NLDamping]] to simulate a finite broadening and to remove the eigenmodes that are excited by the sudden turning on of the external field. After the dephasing time the outgoing signal is analyzed to extract the non-linear coefficients as shown in the figure below:

[[File:Pt analysis.png|600px|center|Non-linear response analysis]]

In the report file <code>r_nlinear</code> you will find the length of the dephasing part and of the sampling one:

Dephasing Time [fs]: 52.65695
Sampling Time [fs]: 4.18566
Total simulation time [fs]: 56.84262
The length of the dephasing interval is inversely proportional to the damping term <math>T_{depth} \simeq 1/\gamma</math> while the length of the sampling is dictated by the smallest frequency we are interested in: <math>T_{samp} \simeq 1/\omega_1 </math>. For this reason if <math> \omega_1=0 </math> or <math> \gamma = 0 </math> simulation time goes to infinity. The response at zero frequency can be calculated as limit of small frequency perturbation.
You can have a look to the file <code>src/nloptics/NL_initialize.F</code> to see how simulation lengths are defined.
Calculations can take some time, run them in parallel, the best number of processors = number of frequencies or reduce the number of frequencies step in the SHG.

==Analysis of the results==

In the sampling region we suppose that the polarization can be written as: <math>\bf{P}(t) = \sum_{n=-\infty}^{+\infty} \bf{p}_n e^{-i\omega_n t} </math> where the coefficient <math>\bf{p}_1,...,\bf{p}_n </math> are related to <math>\chi^{(1)},...,\chi^{(n)} </math>. We sample the polarization signal at different times and invert the previous equation by truncating the sum at a finite order <ref>[https://arxiv.org/abs/1309.4012 Nonlinear optics from an ab initio approach by means of the dynamical Berry phase: Application to second- and third-harmonic generation in semiconductors], C. Attaccalite and M. Grüning, Phys. Rev. B 88, 235113(2013)</ref>.
This is done with the command <code>ypp_nl -u</code> that automatically produce an input with the correct values:

nonlinear # [R] NonLinear Optics Post-Processing
Xorder= 4 # Max order of the response functions
% TimeRange
52.65695 | -1.00000 | fs # Time-window where processing is done
%
ETStpsRt= 200 # Total Energy steps
% EnRngeRt
0.00000 | 10.00000 | eV # Energy range
%
DampMode= "NONE" # Damping type ( NONE | LORENTZIAN | GAUSSIAN )
DampFactor= 0.10000 eV # Damping parameter

where <code>Xorder</code> is the order where the previous sum is truncated, and the TimeRange specifies the sampling region. Notice that differently from the first tutorial, in this case, we do not need Damping in <code>ypp_nl</code> because we already included it in the real-time dynamics. Run <code>ypp_nl</code> and it will produce a file called <code>o.YPP-X_probe_order_2</code>. This file contains the different components of <math>\chi^2_{xy*} </math> and in particular the columns 6 and 7 correspond to the imaginary and real part of <math>\chi^2_{xyz} </math>. You can plot the result with gnuplot and the command:

p 'o.YPP-X_probe_order_2' u 1:(sqrt($6**2+$7**2)) w lp ps 1.5 pt 7 lw 1.5

the result should look like

[[File:AlAs results.png|700px|center|SHG in AlAs]]

and compare it with the <math> \chi^2_{zxy} </math> calculated with more frequencies and with the converged result on a <math> 18x18x18</math> k-point grid and bands between 2 and 10. In the figure you can find also the comparison with the results of Ref. <ref>Luppi et al. [https://arxiv.org/abs/1006.2649 PRB B, '''82''', 235201(2010)]</ref>.
Notice that the QuantumEspresso results are slightly different from the Abinit ones. This is due to the different pseudo-potential employed in the calculations if pseudopotentials were the same calculation would have been identical. You can download the script to generate this plot and the converged results [http://www.attaccalite.com/lumen/tutorials/AlAs/AlAs_results.tgz here].

'''Notice that''' : the following parameters are not used in the non-linear response analysis: <code> EnRngeRt</code>, <code>ETStpsRt</code>, <code>DampMode</code>, <code>DampFactor</code>. The damping factor is set directly in the real-time simulation.

'''System of units in Non-linear Optics''': notice that in Yambo the non-linear response functions are in the gaussian system of units, for example the <math> \chi^2 (\omega) </math> is in cm/statvolt. In order to convert the non-linear coefficients between different system of units, you can have a look at the [https://www.attaccalite.com/tutorials_yambo/Appendix_C_Boyd.pdf Appendix C] of the book [https://www.elsevier.com/books/nonlinear-optics/boyd/978-0-12-369470-6 "Non-linear optics" by Robert W. Boyd].

More tutorials on non-linear response (Third harmonic generation, parallelization, spin-orbit etc..) with Yambo can be found here: [http://www.attaccalite.com/lumen/tutorials.html More Tutorials]. 

==Analysis of the results using YamboPy==
The analysis of the result performed in the previous section using <code>ypp_nl</code> can be performed using python script [https://github.com/yambo-code/yambopy YamboPy]. 
In YamboPy we implemented all necessary functions to reads the Yambo databases and post-process the results. Here we show how to get the SHG signal from the previous
simulations. We suppose you correctly installed <code>YamboPy</code> on your PC. Go in the folder where you ran non-linear calculation and type in the python:
 
from yambopy import *
NLDB=YamboNLDB()
pol =NLDB.Polarization[0]
time=NLDB.IO_TIME_points

in this way you read all the Non-linear databases. If your runs are in a different folder then the 'SAVE' one you can specify it using the command:
NLDB=YamboNLDB(calc='MYJOB')

now in the array <code>pol</code> you have all the polarization for all laser frequencies in the three Cartesian directions, while the variable <code>time</code> contains all the time series of your simulation.
Now you can get the non-linear response with the command:

Harmonic_Analysis(NLDB,X_order=4)

this command will perform a Fourier analysis of the results in the same way of <code>ypp_nl</code> and generate new files with all the requested harmonics ''o.YamboPy-X_probe_order_1'', ''o.YamboPy-X_probe_order_2'' etc...
equivalent to the one generated by <code>ypp_nl</code>. Results can be plot with gnuplot using the command:

p 'o.YamboPy-X_probe_order_2' u 1:(sqrt($6**2+$7**2)) w lp ps 1.5 pt 7 lw 1.5

The script that performs non-linear analysis can be found in <code>yambopy/nl/harmonic_analysis.py</code>. We strongly advice you to have a look to this script and modify it according
to your needs and in order to extract other non-linear response functions.

==How to choose the external field direction for the different X2==

In the X2abc response you have three field directions. The two components ''b'' and ''c'' are determined by the external field and the third ''a''
is the direction where you measure the response. 

The external field in Yambo is set using the variable
% Field1_Dir
1.000000 | 0.000000 | 0.000000 | # [NL ExtF] Versor .
%

For example if you set in Yambo field direction as:

1.0 | 0.0 | 0.0 | ---> you calculate all components X2*xx
0.0 | 1.0 | 0.0 | ---> you calculate all components X2*yy
0.0 | 0.0 | 1.0 | ---> you calculate all components X2*zz

the * correspond to the different direction in the response file <code>o.YPP-X_probe_order_2</code>.
In the <code>o.YPP-X_probe_order_2</code> you have seven columns:

The first column is the energy [[omega]],
the 2nd and 3rd columns are the imaginary and real part of X2x**
the 4th and 5th columns are the imaginary and real part of X2y**
the 6th and 7th columns are the imaginary and real part of X2z**

where the ** are the direction of the incoming field, see above.

For example if you want to calculate the <math>\chi^{(2)}_{zxx}</math> you put the external field in the direction <code> 1.0 | 0.0 | 0.0 |</code>
and then plot the column 6 and 7 of the <code>o.YPP-X_probe_order_2</code> file. 

In order to get the other components of the X2 the calculation are more involved. For example if you put field in the

1.0 | 1.0 | 0.0 |

this corresponds to <math>E(t)=\frac{1}{\sqrt{2}} [ E_x(t) + E_y(t) ]</math> and so at the second order you will have <math>E^2(t)=\frac{1}{2} \left [ E^2_x(t) + E^2_y(t) + E_x(t) E_y(t) + E_y(t) E_x(t) \right]</math> 
this means that the X2 in the <code>o.YPP-X_probe_order_2</code> will correspond to a linear combination of the following different response functions. 
For example in the the 2nd and 3rd columns are the imaginary and real part of: 

<math>\chi^{(2)}_{x**}=\frac{1}{2} \left [\chi^2_{xxx}+\chi^{(2)}_{xyy} + \chi^{(2)}_{xxy} + \chi^{(2)}_{xyx} \right ]</math>

the same for the other column replacing the first <code>x</code> for <code>y,z</code>.
If you know that some components are zero this allow you to extract the corresponding off-diagonal part of <math>\chi^{(2)}_{abc}</math> otherwise you have to perform different calculations to get the component you are interested in. 
Now we present '''a simple example of monolayer hBN (m-hBN)'''. In m-hBN there is only a non-zero component of the $\chi^2$ and all the others are related by symmetry: 
<math>\chi^{(2)}_{yyy}=-\chi^{(2)}_{yxx}=-\chi^{(2)}_{xxy}=-\chi^{(2)}_{xyx}</math> 
so if you put the field in the <code>|1|1|0|</code> direction you will get: 
<math>\chi^{(2)}_{x**} = \frac{1}{2} \left[\chi^{(2)}_{xxy} + \chi^{(2)}_{xyx} \right] = - \chi^{(2)}_{yyy} </math> 
<math>\chi^{(2)}_{y**} =\frac{1}{2} \left[ \chi^{(2)}_{yyy} + \chi^{(2)}_{yxx} \right] = 0.0 </math>
 
'''Nota bene:''' if you change the direction of the external field you have to remove the corresponding symmetries as explained in the tutorial
[[Prerequisites for Real Time_propagation with Yambo#Reduce symmetries real-time linear response tutorial]].

==Non-linear response of low-dimensional structures: 2D or 1D ==

The Yambo code is a 3D periodic code, so when you want to study a low-dimensional system 2D or 1D, you have to use a supercell approach.
For example to simulate the non-linear response in a 2D-crystal one, can put the crystal in the xy plane and choose a larger distance in the z-direction
in order to reduce the interaction between the periodic replica. Clearly in this case k-point sampling will be only in the x,y directions.
For calculations on this type of systems, these two warnings must be taken into account:

* if you calculate GW corrections or include electron-hole interaction in the linear/non-linear response it is a good idea to use a '''Coulomb cutoff''', similar to the 2D BSE case [http://www.yambo-code.org/wiki/index.php?title=How_to_treat_low_dimensional_systems How to treat low dimensional systems]. You can add the cutoff just adding the "-r" in the input generation.

* the calculation of SHG and THG are always performed respect to the supercell, therefore you have to '''re-scale''' the result to the effective thickness of the layer, usually the inter-layer distance of the corresponding bulk material for 2D systems: <math>\chi_{rescaled}(\omega) = L_z/d_{eff} \cdot \chi(\omega) </math> where <math>L_z</math> is the z-dimension of the supercell, and <math>d_{eff}</math> is the effective thickness of the 2D system.

'''Nota bene''': Non-linear response along non-periodic directions is not implemented in Yambo, the code will print zero in these directions for all response functions. We plan to implement it in a future version of the code.

==References==
<references />

==Links for schools==
* Back to [[Rome 2023#Tutorials]]
* Back to [[ICTP2020]]

 
{| style="width:100%" border="1"
|style="width:25%; text-align:left"|Prev: [[Linear response from real time simulations|Linear response from real time simulations]]
|style="width:45%; text-align:center"|Now: [[ICTP2020|ICTP Tutorials]] --> [[Real time approach to non-linear response|Non Linear Response]]
|style="width:50%; text-align:left"|Next: [[Correlation effects in the non-linear response|Correlation effects in the non-linear response ]]
|-
|}

Real time approach to non-linear response (SHG)

2025-09-27T10:22:45Z

Attacc: /* How to choose the external field direction for the different X2 */

== Second Harmonic Generation in AlAs ==
In this tutorial, we will calculate the second harmonic generation of bulk AlAs, the Yambo databases can be downloaded here: [https://media.yambo-code.eu/educational/tutorials/files/AlAs_DBs.tar.gz AlAs_DBs.tar.gz] (10 MB). The first steps of this tutorials are the same as the one on [http://www.yambo-code.eu/wiki/index.php?title=Prerequisites_for_Real_Time_propagation_with_Yambo Prerequisites for Real-Time propagation with Yambo] with the only difference that we will work on AlAs and we will consider an external field in the direction <code> 1.000000 | 1.000000 | 0.000000 |</code>. The DFT input are available here: [https://media.yambo-code.eu/educational/tutorials/files/AlAs_abinit.tar.gz ABINIT] or [https://media.yambo-code.eu/educational/tutorials/files/AlAs_pwscf.tar.gz QuantumEspresso].
You can run the DFT calculation with ABINIT with the command:

abinit < AlAs.in > output_AlAs

or using QuantumEspresso:

pw.x -inp AlAs.scf.in > output_scf
pw.x -inp AlAs.nscf.in > output_scf

and then import the ABINIT wave-function with the command:

a2y -F AlAso_DS2_WFK.nc

and the QuantumEspresso one, in the folder AlAs.save with the command:

p2y
Now we consider an external field in the <code>[1,1,0]</code> direction and remove symmetries not compatible with this field, as explained in the tutorial [http://www.yambo-code.eu/wiki/index.php?title=Prerequisites_for_Real_Time_propagation_with_Yambo Prerequisites for Real-Time propagation with Yambo].

==Real-time simulation for the SHG==

You can generate the input file with the command <code>yambo_nl -u n</code>:

nloptics # [R NL] Non-linear optics
% NLBands
 3 | 6 | # [NL] Bands
%
NLstep= 0.0100 fs # [NL] Real Time step length
NLverbosity= "high" # [NL] Verbosity level (low | high)
NLtime=-1.000000 fs # [NL] Simulation Time
NLintegrator= "INVINT" # [NL] Integrator ("EULEREXP/RK4/RK2EXP/HEUN/INVINT/CRANKNIC")
NLCorrelation= "IPA" # [NL] Correlation ("IPA/HARTREE/TDDFT/LRC/JGM/SEX/HF")
NLLrcAlpha= 0.000000 # [NL] Long Range Correction
% NLEnRange
 1.000000 | 5.000000 | eV # [NL] Energy range
%
NLEnSteps= 5 # [NL] Energy steps
NLDamping= 0.150000 eV # [NL] Damping
% Field1_Dir
 1.000000 | 1.000000 | 0.000000 | # [RT Field1] Versor
Field1_kind= "SOFTSIN" # [NL ExtF] Kind(SIN|SOFTSIN|RES|ANTIRES|GAUSS|DELTA|QSSIN)

The line <code>|1.000000 | 1.000000 | 0.000000 | # [RT Field1] Versor</code> referees to the direction of the external field (x,y,0). At present only an external field is present but the code can be easily generalized to deal with more fields.
The default parameters of Yambo/Lumen are already tuned for second-harmonic generation, so the only thing you have to change is the band range, between 3 and 6 and the energy range between 1.0-5.0 eV and the number of energy steps in this interval that we set to 10. Notice that you cannot set to zero the lowest value of the energy range because this will requires a simulation that lasts infinite time, see below. Finally, consider that Yambo performs a separate calculation for each frequency, so if you set many energy steps the computational time grows linearly with this number.
Notice that we set <code>NLverbosity= "high"</code> in this way the code will produce a file for each laser frequency containing the time dependent polarization.
Run <code>yambo_nl</code>. Calculations will take about fifteen minutes on a single processor PC, you have time to study the next section that explains how non-linear response is extracted from the real-time simulations.
In order to speed up calculations, you can run them in parallel.

==Non-linear response with Yambo==

In order to calculate the non-linear response, the system is excited with different laser fields with a sinusoidal shape at frequencies <math>\omega_1, \omega_2, .... , \omega_n </math> determined by the parameters [[Variables#NLEnRangev|NLEnRange]] and [[Variables#NLEnSteps|NLEnSteps]]. A dephasing term is added to the Hamiltonian <math>\gamma = </math>[[Variables#NLDamping|NLDamping]] to simulate a finite broadening and to remove the eigenmodes that are excited by the sudden turning on of the external field. After the dephasing time the outgoing signal is analyzed to extract the non-linear coefficients as shown in the figure below:

[[File:Pt analysis.png|600px|center|Non-linear response analysis]]

In the report file <code>r_nlinear</code> you will find the length of the dephasing part and of the sampling one:

Dephasing Time [fs]: 52.65695
Sampling Time [fs]: 4.18566
Total simulation time [fs]: 56.84262
The length of the dephasing interval is inversely proportional to the damping term <math>T_{depth} \simeq 1/\gamma</math> while the length of the sampling is dictated by the smallest frequency we are interested in: <math>T_{samp} \simeq 1/\omega_1 </math>. For this reason if <math> \omega_1=0 </math> or <math> \gamma = 0 </math> simulation time goes to infinity. The response at zero frequency can be calculated as limit of small frequency perturbation.
You can have a look to the file <code>src/nloptics/NL_initialize.F</code> to see how simulation lengths are defined.
Calculations can take some time, run them in parallel, the best number of processors = number of frequencies or reduce the number of frequencies step in the SHG.

==Analysis of the results==

In the sampling region we suppose that the polarization can be written as: <math>\bf{P}(t) = \sum_{n=-\infty}^{+\infty} \bf{p}_n e^{-i\omega_n t} </math> where the coefficient <math>\bf{p}_1,...,\bf{p}_n </math> are related to <math>\chi^{(1)},...,\chi^{(n)} </math>. We sample the polarization signal at different times and invert the previous equation by truncating the sum at a finite order <ref>[https://arxiv.org/abs/1309.4012 Nonlinear optics from an ab initio approach by means of the dynamical Berry phase: Application to second- and third-harmonic generation in semiconductors], C. Attaccalite and M. Grüning, Phys. Rev. B 88, 235113(2013)</ref>.
This is done with the command <code>ypp_nl -u</code> that automatically produce an input with the correct values:

nonlinear # [R] NonLinear Optics Post-Processing
Xorder= 4 # Max order of the response functions
% TimeRange
52.65695 | -1.00000 | fs # Time-window where processing is done
%
ETStpsRt= 200 # Total Energy steps
% EnRngeRt
0.00000 | 10.00000 | eV # Energy range
%
DampMode= "NONE" # Damping type ( NONE | LORENTZIAN | GAUSSIAN )
DampFactor= 0.10000 eV # Damping parameter

where <code>Xorder</code> is the order where the previous sum is truncated, and the TimeRange specifies the sampling region. Notice that differently from the first tutorial, in this case, we do not need Damping in <code>ypp_nl</code> because we already included it in the real-time dynamics. Run <code>ypp_nl</code> and it will produce a file called <code>o.YPP-X_probe_order_2</code>. This file contains the different components of <math>\chi^2_{xy*} </math> and in particular the columns 6 and 7 correspond to the imaginary and real part of <math>\chi^2_{xyz} </math>. You can plot the result with gnuplot and the command:

p 'o.YPP-X_probe_order_2' u 1:(sqrt($6**2+$7**2)) w lp ps 1.5 pt 7 lw 1.5

the result should look like

[[File:AlAs results.png|700px|center|SHG in AlAs]]

and compare it with the <math> \chi^2_{zxy} </math> calculated with more frequencies and with the converged result on a <math> 18x18x18</math> k-point grid and bands between 2 and 10. In the figure you can find also the comparison with the results of Ref. <ref>Luppi et al. [https://arxiv.org/abs/1006.2649 PRB B, '''82''', 235201(2010)]</ref>.
Notice that the QuantumEspresso results are slightly different from the Abinit ones. This is due to the different pseudo-potential employed in the calculations if pseudopotentials were the same calculation would have been identical. You can download the script to generate this plot and the converged results [http://www.attaccalite.com/lumen/tutorials/AlAs/AlAs_results.tgz here].

'''Notice that''' : the following parameters are not used in the non-linear response analysis: <code> EnRngeRt</code>, <code>ETStpsRt</code>, <code>DampMode</code>, <code>DampFactor</code>. The damping factor is set directly in the real-time simulation.

'''System of units in Non-linear Optics''': notice that in Yambo the non-linear response functions are in the gaussian system of units, for example the <math> \chi^2 (\omega) </math> is in cm/statvolt. In order to convert the non-linear coefficients between different system of units, you can have a look at the [https://www.attaccalite.com/tutorials_yambo/Appendix_C_Boyd.pdf Appendix C] of the book [https://www.elsevier.com/books/nonlinear-optics/boyd/978-0-12-369470-6 "Non-linear optics" by Robert W. Boyd].

More tutorials on non-linear response (Third harmonic generation, parallelization, spin-orbit etc..) with Yambo can be found here: [http://www.attaccalite.com/lumen/tutorials.html More Tutorials]. 

==Analysis of the results using YamboPy==
The analysis of the result performed in the previous section using <code>ypp_nl</code> can be performed using python script [https://github.com/yambo-code/yambopy YamboPy]. 
In YamboPy we implemented all necessary functions to reads the Yambo databases and post-process the results. Here we show how to get the SHG signal from the previous
simulations. We suppose you correctly installed <code>YamboPy</code> on your PC. Go in the folder where you ran non-linear calculation and type in the python:
 
from yambopy import *
NLDB=YamboNLDB()
pol =NLDB.Polarization[0]
time=NLDB.IO_TIME_points

in this way you read all the Non-linear databases. If your runs are in a different folder then the 'SAVE' one you can specify it using the command:
NLDB=YamboNLDB(calc='MYJOB')

now in the array <code>pol</code> you have all the polarization for all laser frequencies in the three Cartesian directions, while the variable <code>time</code> contains all the time series of your simulation.
Now you can get the non-linear response with the command:

Harmonic_Analysis(NLDB,X_order=4)

this command will perform a Fourier analysis of the results in the same way of <code>ypp_nl</code> and generate new files with all the requested harmonics ''o.YamboPy-X_probe_order_1'', ''o.YamboPy-X_probe_order_2'' etc...
equivalent to the one generated by <code>ypp_nl</code>. Results can be plot with gnuplot using the command:

p 'o.YamboPy-X_probe_order_2' u 1:(sqrt($6**2+$7**2)) w lp ps 1.5 pt 7 lw 1.5

The script that performs non-linear analysis can be found in <code>yambopy/nl/harmonic_analysis.py</code>. We strongly advice you to have a look to this script and modify it according
to your needs and in order to extract other non-linear response functions.

==How to choose the external field direction for the different X2==

In the X2abc response you have three field directions. The two components ''b'' and ''c'' are determined by the external field and the third ''a''
is the direction where you measure the response. 

The external field in Yambo is set using the variable
% Field1_Dir
1.000000 | 0.000000 | 0.000000 | # [NL ExtF] Versor .
%

For example if you set in Yambo field direction as:

1.0 | 0.0 | 0.0 | ---> you calculate all components X2*xx
0.0 | 1.0 | 0.0 | ---> you calculate all components X2*yy
0.0 | 0.0 | 1.0 | ---> you calculate all components X2*zz

the * correspond to the different direction in the response file <code>o.YPP-X_probe_order_2</code>.
In the <code>o.YPP-X_probe_order_2</code> you have seven columns:

The first column is the energy [[omega]],
the 2nd and 3rd columns are the imaginary and real part of X2x**
the 4th and 5th columns are the imaginary and real part of X2y**
the 6th and 7th columns are the imaginary and real part of X2z**

where the ** are the direction of the incoming field, see above.

For example if you want to calculate the <math>\chi^{(2)}_{zxx}</math> you put the external field in the direction <code> 1.0 | 0.0 | 0.0 |</code>
and then plot the column 6 and 7 of the <code>o.YPP-X_probe_order_2</code> file. 

on [[Prerequisites for Real Time_propagation with Yambo#Reduce symmetries real-time linear response tutorial]].

In order to get the other components of the X2 the calculation are more involved. For example if you put field in the

1.0 | 1.0 | 0.0 |

this corresponds to <math>E(t)=\frac{1}{\sqrt{2}} [ E_x(t) + E_y(t) ]</math> and so at the second order you will have <math>E^2(t)=\frac{1}{2} \left [ E^2_x(t) + E^2_y(t) + E_x(t) E_y(t) + E_y(t) E_x(t) \right]</math> 
this means that the X2 in the <code>o.YPP-X_probe_order_2</code> will correspond to a linear combination of the following different response functions. 
For example in the the 2nd and 3rd columns are the imaginary and real part of: 

<math>\chi^{(2)}_{x**}=\frac{1}{2} \left [\chi^2_{xxx}+\chi^{(2)}_{xyy} + \chi^{(2)}_{xxy} + \chi^{(2)}_{xyx} \right ]</math>

the same for the other column replacing the first <code>x</code> for <code>y,z</code>.
If you know that some components are zero this allow you to extract the corresponding off-diagonal part of <math>\chi^{(2)}_{abc}</math> otherwise you have to perform different calculations to get the component you are interested in. 
Now we present '''a simple example of monolayer hBN (m-hBN)'''. In m-hBN there is only a non-zero component of the $\chi^2$ and all the others are related by symmetry: 
<math>\chi^{(2)}_{yyy}=-\chi^{(2)}_{yxx}=-\chi^{(2)}_{xxy}=-\chi^{(2)}_{xyx}</math> 
so if you put the field in the <code>|1|1|0|</code> direction you will get: 
<math>\chi^{(2)}_{x**} = \frac{1}{2} \left[\chi^{(2)}_{xxy} + \chi^{(2)}_{xyx} \right] = - \chi^{(2)}_{yyy} </math> 
<math>\chi^{(2)}_{y**} =\frac{1}{2} \left[ \chi^{(2)}_{yyy} + \chi^{(2)}_{yxx} \right] = 0.0 </math>
 
'''Nota bene:''' if you change the direction of the external field you have to remove the corresponding symmetries as explained in the tutorial

==Non-linear response of low-dimensional structures: 2D or 1D ==

The Yambo code is a 3D periodic code, so when you want to study a low-dimensional system 2D or 1D, you have to use a supercell approach.
For example to simulate the non-linear response in a 2D-crystal one, can put the crystal in the xy plane and choose a larger distance in the z-direction
in order to reduce the interaction between the periodic replica. Clearly in this case k-point sampling will be only in the x,y directions.
For calculations on this type of systems, these two warnings must be taken into account:

* if you calculate GW corrections or include electron-hole interaction in the linear/non-linear response it is a good idea to use a '''Coulomb cutoff''', similar to the 2D BSE case [http://www.yambo-code.org/wiki/index.php?title=How_to_treat_low_dimensional_systems How to treat low dimensional systems]. You can add the cutoff just adding the "-r" in the input generation.

* the calculation of SHG and THG are always performed respect to the supercell, therefore you have to '''re-scale''' the result to the effective thickness of the layer, usually the inter-layer distance of the corresponding bulk material for 2D systems: <math>\chi_{rescaled}(\omega) = L_z/d_{eff} \cdot \chi(\omega) </math> where <math>L_z</math> is the z-dimension of the supercell, and <math>d_{eff}</math> is the effective thickness of the 2D system.

'''Nota bene''': Non-linear response along non-periodic directions is not implemented in Yambo, the code will print zero in these directions for all response functions. We plan to implement it in a future version of the code.

==References==
<references />

==Links for schools==
* Back to [[Rome 2023#Tutorials]]
* Back to [[ICTP2020]]

 
{| style="width:100%" border="1"
|style="width:25%; text-align:left"|Prev: [[Linear response from real time simulations|Linear response from real time simulations]]
|style="width:45%; text-align:center"|Now: [[ICTP2020|ICTP Tutorials]] --> [[Real time approach to non-linear response|Non Linear Response]]
|style="width:50%; text-align:left"|Next: [[Correlation effects in the non-linear response|Correlation effects in the non-linear response ]]
|-
|}

Real time approach to non-linear response (SHG)

2025-09-27T10:21:26Z

Attacc: /* How to choose the external field direction for the different X2 */

== Second Harmonic Generation in AlAs ==
In this tutorial, we will calculate the second harmonic generation of bulk AlAs, the Yambo databases can be downloaded here: [https://media.yambo-code.eu/educational/tutorials/files/AlAs_DBs.tar.gz AlAs_DBs.tar.gz] (10 MB). The first steps of this tutorials are the same as the one on [http://www.yambo-code.eu/wiki/index.php?title=Prerequisites_for_Real_Time_propagation_with_Yambo Prerequisites for Real-Time propagation with Yambo] with the only difference that we will work on AlAs and we will consider an external field in the direction <code> 1.000000 | 1.000000 | 0.000000 |</code>. The DFT input are available here: [https://media.yambo-code.eu/educational/tutorials/files/AlAs_abinit.tar.gz ABINIT] or [https://media.yambo-code.eu/educational/tutorials/files/AlAs_pwscf.tar.gz QuantumEspresso].
You can run the DFT calculation with ABINIT with the command:

abinit < AlAs.in > output_AlAs

or using QuantumEspresso:

pw.x -inp AlAs.scf.in > output_scf
pw.x -inp AlAs.nscf.in > output_scf

and then import the ABINIT wave-function with the command:

a2y -F AlAso_DS2_WFK.nc

and the QuantumEspresso one, in the folder AlAs.save with the command:

p2y
Now we consider an external field in the <code>[1,1,0]</code> direction and remove symmetries not compatible with this field, as explained in the tutorial [http://www.yambo-code.eu/wiki/index.php?title=Prerequisites_for_Real_Time_propagation_with_Yambo Prerequisites for Real-Time propagation with Yambo].

==Real-time simulation for the SHG==

You can generate the input file with the command <code>yambo_nl -u n</code>:

nloptics # [R NL] Non-linear optics
% NLBands
 3 | 6 | # [NL] Bands
%
NLstep= 0.0100 fs # [NL] Real Time step length
NLverbosity= "high" # [NL] Verbosity level (low | high)
NLtime=-1.000000 fs # [NL] Simulation Time
NLintegrator= "INVINT" # [NL] Integrator ("EULEREXP/RK4/RK2EXP/HEUN/INVINT/CRANKNIC")
NLCorrelation= "IPA" # [NL] Correlation ("IPA/HARTREE/TDDFT/LRC/JGM/SEX/HF")
NLLrcAlpha= 0.000000 # [NL] Long Range Correction
% NLEnRange
 1.000000 | 5.000000 | eV # [NL] Energy range
%
NLEnSteps= 5 # [NL] Energy steps
NLDamping= 0.150000 eV # [NL] Damping
% Field1_Dir
 1.000000 | 1.000000 | 0.000000 | # [RT Field1] Versor
Field1_kind= "SOFTSIN" # [NL ExtF] Kind(SIN|SOFTSIN|RES|ANTIRES|GAUSS|DELTA|QSSIN)

The line <code>|1.000000 | 1.000000 | 0.000000 | # [RT Field1] Versor</code> referees to the direction of the external field (x,y,0). At present only an external field is present but the code can be easily generalized to deal with more fields.
The default parameters of Yambo/Lumen are already tuned for second-harmonic generation, so the only thing you have to change is the band range, between 3 and 6 and the energy range between 1.0-5.0 eV and the number of energy steps in this interval that we set to 10. Notice that you cannot set to zero the lowest value of the energy range because this will requires a simulation that lasts infinite time, see below. Finally, consider that Yambo performs a separate calculation for each frequency, so if you set many energy steps the computational time grows linearly with this number.
Notice that we set <code>NLverbosity= "high"</code> in this way the code will produce a file for each laser frequency containing the time dependent polarization.
Run <code>yambo_nl</code>. Calculations will take about fifteen minutes on a single processor PC, you have time to study the next section that explains how non-linear response is extracted from the real-time simulations.
In order to speed up calculations, you can run them in parallel.

==Non-linear response with Yambo==

In order to calculate the non-linear response, the system is excited with different laser fields with a sinusoidal shape at frequencies <math>\omega_1, \omega_2, .... , \omega_n </math> determined by the parameters [[Variables#NLEnRangev|NLEnRange]] and [[Variables#NLEnSteps|NLEnSteps]]. A dephasing term is added to the Hamiltonian <math>\gamma = </math>[[Variables#NLDamping|NLDamping]] to simulate a finite broadening and to remove the eigenmodes that are excited by the sudden turning on of the external field. After the dephasing time the outgoing signal is analyzed to extract the non-linear coefficients as shown in the figure below:

[[File:Pt analysis.png|600px|center|Non-linear response analysis]]

In the report file <code>r_nlinear</code> you will find the length of the dephasing part and of the sampling one:

Dephasing Time [fs]: 52.65695
Sampling Time [fs]: 4.18566
Total simulation time [fs]: 56.84262
The length of the dephasing interval is inversely proportional to the damping term <math>T_{depth} \simeq 1/\gamma</math> while the length of the sampling is dictated by the smallest frequency we are interested in: <math>T_{samp} \simeq 1/\omega_1 </math>. For this reason if <math> \omega_1=0 </math> or <math> \gamma = 0 </math> simulation time goes to infinity. The response at zero frequency can be calculated as limit of small frequency perturbation.
You can have a look to the file <code>src/nloptics/NL_initialize.F</code> to see how simulation lengths are defined.
Calculations can take some time, run them in parallel, the best number of processors = number of frequencies or reduce the number of frequencies step in the SHG.

==Analysis of the results==

In the sampling region we suppose that the polarization can be written as: <math>\bf{P}(t) = \sum_{n=-\infty}^{+\infty} \bf{p}_n e^{-i\omega_n t} </math> where the coefficient <math>\bf{p}_1,...,\bf{p}_n </math> are related to <math>\chi^{(1)},...,\chi^{(n)} </math>. We sample the polarization signal at different times and invert the previous equation by truncating the sum at a finite order <ref>[https://arxiv.org/abs/1309.4012 Nonlinear optics from an ab initio approach by means of the dynamical Berry phase: Application to second- and third-harmonic generation in semiconductors], C. Attaccalite and M. Grüning, Phys. Rev. B 88, 235113(2013)</ref>.
This is done with the command <code>ypp_nl -u</code> that automatically produce an input with the correct values:

nonlinear # [R] NonLinear Optics Post-Processing
Xorder= 4 # Max order of the response functions
% TimeRange
52.65695 | -1.00000 | fs # Time-window where processing is done
%
ETStpsRt= 200 # Total Energy steps
% EnRngeRt
0.00000 | 10.00000 | eV # Energy range
%
DampMode= "NONE" # Damping type ( NONE | LORENTZIAN | GAUSSIAN )
DampFactor= 0.10000 eV # Damping parameter

where <code>Xorder</code> is the order where the previous sum is truncated, and the TimeRange specifies the sampling region. Notice that differently from the first tutorial, in this case, we do not need Damping in <code>ypp_nl</code> because we already included it in the real-time dynamics. Run <code>ypp_nl</code> and it will produce a file called <code>o.YPP-X_probe_order_2</code>. This file contains the different components of <math>\chi^2_{xy*} </math> and in particular the columns 6 and 7 correspond to the imaginary and real part of <math>\chi^2_{xyz} </math>. You can plot the result with gnuplot and the command:

p 'o.YPP-X_probe_order_2' u 1:(sqrt($6**2+$7**2)) w lp ps 1.5 pt 7 lw 1.5

the result should look like

[[File:AlAs results.png|700px|center|SHG in AlAs]]

and compare it with the <math> \chi^2_{zxy} </math> calculated with more frequencies and with the converged result on a <math> 18x18x18</math> k-point grid and bands between 2 and 10. In the figure you can find also the comparison with the results of Ref. <ref>Luppi et al. [https://arxiv.org/abs/1006.2649 PRB B, '''82''', 235201(2010)]</ref>.
Notice that the QuantumEspresso results are slightly different from the Abinit ones. This is due to the different pseudo-potential employed in the calculations if pseudopotentials were the same calculation would have been identical. You can download the script to generate this plot and the converged results [http://www.attaccalite.com/lumen/tutorials/AlAs/AlAs_results.tgz here].

'''Notice that''' : the following parameters are not used in the non-linear response analysis: <code> EnRngeRt</code>, <code>ETStpsRt</code>, <code>DampMode</code>, <code>DampFactor</code>. The damping factor is set directly in the real-time simulation.

'''System of units in Non-linear Optics''': notice that in Yambo the non-linear response functions are in the gaussian system of units, for example the <math> \chi^2 (\omega) </math> is in cm/statvolt. In order to convert the non-linear coefficients between different system of units, you can have a look at the [https://www.attaccalite.com/tutorials_yambo/Appendix_C_Boyd.pdf Appendix C] of the book [https://www.elsevier.com/books/nonlinear-optics/boyd/978-0-12-369470-6 "Non-linear optics" by Robert W. Boyd].

More tutorials on non-linear response (Third harmonic generation, parallelization, spin-orbit etc..) with Yambo can be found here: [http://www.attaccalite.com/lumen/tutorials.html More Tutorials]. 

==Analysis of the results using YamboPy==
The analysis of the result performed in the previous section using <code>ypp_nl</code> can be performed using python script [https://github.com/yambo-code/yambopy YamboPy]. 
In YamboPy we implemented all necessary functions to reads the Yambo databases and post-process the results. Here we show how to get the SHG signal from the previous
simulations. We suppose you correctly installed <code>YamboPy</code> on your PC. Go in the folder where you ran non-linear calculation and type in the python:
 
from yambopy import *
NLDB=YamboNLDB()
pol =NLDB.Polarization[0]
time=NLDB.IO_TIME_points

in this way you read all the Non-linear databases. If your runs are in a different folder then the 'SAVE' one you can specify it using the command:
NLDB=YamboNLDB(calc='MYJOB')

now in the array <code>pol</code> you have all the polarization for all laser frequencies in the three Cartesian directions, while the variable <code>time</code> contains all the time series of your simulation.
Now you can get the non-linear response with the command:

Harmonic_Analysis(NLDB,X_order=4)

this command will perform a Fourier analysis of the results in the same way of <code>ypp_nl</code> and generate new files with all the requested harmonics ''o.YamboPy-X_probe_order_1'', ''o.YamboPy-X_probe_order_2'' etc...
equivalent to the one generated by <code>ypp_nl</code>. Results can be plot with gnuplot using the command:

p 'o.YamboPy-X_probe_order_2' u 1:(sqrt($6**2+$7**2)) w lp ps 1.5 pt 7 lw 1.5

The script that performs non-linear analysis can be found in <code>yambopy/nl/harmonic_analysis.py</code>. We strongly advice you to have a look to this script and modify it according
to your needs and in order to extract other non-linear response functions.

==How to choose the external field direction for the different X2==

In the X2abc response you have three field directions. The two components ''b'' and ''c'' are determined by the external field and the third ''a''
is the direction where you measure the response. 

The external field in Yambo is set using the variable
% Field1_Dir
1.000000 | 0.000000 | 0.000000 | # [NL ExtF] Versor .
%

For example if you set in Yambo field direction as:

1.0 | 0.0 | 0.0 | ---> you calculate all components X2*xx
0.0 | 1.0 | 0.0 | ---> you calculate all components X2*yy
0.0 | 0.0 | 1.0 | ---> you calculate all components X2*zz

the * correspond to the different direction in the response file <code>o.YPP-X_probe_order_2</code>.
In the <code>o.YPP-X_probe_order_2</code> you have seven columns:

The first column is the energy [[omega]],
the 2nd and 3rd columns are the imaginary and real part of X2x**
the 4th and 5th columns are the imaginary and real part of X2y**
the 6th and 7th columns are the imaginary and real part of X2z**

where the ** are the direction of the incoming field, see above.

For example if you want to calculate the <math>\chi^{(2)}_{zxx}</math> you put the external field in the direction <code> 1.0 | 0.0 | 0.0 |</code>
and then plot the column 6 and 7 of the <code>o.YPP-X_probe_order_2</code> file. 

'''Nota bene:''' if you change the direction of the external field you have to remove the corresponding symmetries as explained in the tutorial
on [[Prerequisites for Real Time_propagation with Yambo#Reduce symmetries real-time linear response tutorial]].

In order to get the other components of the X2 the calculation are more involved. For example if you put field in the

1.0 | 1.0 | 0.0 |

this corresponds to <math>E(t)=\frac{1}{\sqrt{2}} [ E_x(t) + E_y(t) ]</math> and so at the second order you will have <math>E^2(t)=\frac{1}{2} \left [ E^2_x(t) + E^2_y(t) + E_x(t) E_y(t) + E_y(t) E_x(t) \right]</math> 
this means that the X2 in the <code>o.YPP-X_probe_order_2</code> will correspond to a linear combination of the following different response functions. 
For example in the the 2nd and 3rd columns are the imaginary and real part of: 

<math>\chi^{(2)}_{x**}=\frac{1}{2} \left [\chi^2_{xxx}+\chi^{(2)}_{xyy} + \chi^{(2)}_{xxy} + \chi^{(2)}_{xyx} \right ]</math>

the same for the other column replacing the first <code>x</code> for <code>y,z</code>.
If you know that some components are zero this allow you to extract the corresponding off-diagonal part of <math>\chi^{(2)}_{abc}</math> otherwise you have to perform different calculations to get the component you are interested in. 
Now we present '''a simple example of monolayer hBN (m-hBN)'''. In m-hBN there is only a non-zero component of the $\chi^2$ and all the others are related by symmetry: 
<math>\chi^{(2)}_{yyy}=-\chi^{(2)}_{yxx}=-\chi^{(2)}_{xxy}=-\chi^{(2)}_{xyx}</math> 
so if you put the field in the <code>|1|1|0|</code> direction you will get: 
<math>\chi^{(2)}_{x**} = \frac{1}{2} \left[\chi^{(2)}_{xxy} + \chi^{(2)}_{xyx} \right] = - \chi^{(2)}_{yyy} </math> 
<math>\chi^{(2)}_{y**} =\frac{1}{2} \left[ \chi^{(2)}_{yyy} + \chi^{(2)}_{yxx} \right] = 0.0 </math>

==Non-linear response of low-dimensional structures: 2D or 1D ==

The Yambo code is a 3D periodic code, so when you want to study a low-dimensional system 2D or 1D, you have to use a supercell approach.
For example to simulate the non-linear response in a 2D-crystal one, can put the crystal in the xy plane and choose a larger distance in the z-direction
in order to reduce the interaction between the periodic replica. Clearly in this case k-point sampling will be only in the x,y directions.
For calculations on this type of systems, these two warnings must be taken into account:

* if you calculate GW corrections or include electron-hole interaction in the linear/non-linear response it is a good idea to use a '''Coulomb cutoff''', similar to the 2D BSE case [http://www.yambo-code.org/wiki/index.php?title=How_to_treat_low_dimensional_systems How to treat low dimensional systems]. You can add the cutoff just adding the "-r" in the input generation.

* the calculation of SHG and THG are always performed respect to the supercell, therefore you have to '''re-scale''' the result to the effective thickness of the layer, usually the inter-layer distance of the corresponding bulk material for 2D systems: <math>\chi_{rescaled}(\omega) = L_z/d_{eff} \cdot \chi(\omega) </math> where <math>L_z</math> is the z-dimension of the supercell, and <math>d_{eff}</math> is the effective thickness of the 2D system.

'''Nota bene''': Non-linear response along non-periodic directions is not implemented in Yambo, the code will print zero in these directions for all response functions. We plan to implement it in a future version of the code.

==References==
<references />

==Links for schools==
* Back to [[Rome 2023#Tutorials]]
* Back to [[ICTP2020]]

 
{| style="width:100%" border="1"
|style="width:25%; text-align:left"|Prev: [[Linear response from real time simulations|Linear response from real time simulations]]
|style="width:45%; text-align:center"|Now: [[ICTP2020|ICTP Tutorials]] --> [[Real time approach to non-linear response|Non Linear Response]]
|style="width:50%; text-align:left"|Next: [[Correlation effects in the non-linear response|Correlation effects in the non-linear response ]]
|-
|}

Real time approach to non-linear response (SHG)

2025-09-27T08:42:32Z

Attacc: /* How to choose the external field direction for the different X2 */

== Second Harmonic Generation in AlAs ==
In this tutorial, we will calculate the second harmonic generation of bulk AlAs, the Yambo databases can be downloaded here: [https://media.yambo-code.eu/educational/tutorials/files/AlAs_DBs.tar.gz AlAs_DBs.tar.gz] (10 MB). The first steps of this tutorials are the same as the one on [http://www.yambo-code.eu/wiki/index.php?title=Prerequisites_for_Real_Time_propagation_with_Yambo Prerequisites for Real-Time propagation with Yambo] with the only difference that we will work on AlAs and we will consider an external field in the direction <code> 1.000000 | 1.000000 | 0.000000 |</code>. The DFT input are available here: [https://media.yambo-code.eu/educational/tutorials/files/AlAs_abinit.tar.gz ABINIT] or [https://media.yambo-code.eu/educational/tutorials/files/AlAs_pwscf.tar.gz QuantumEspresso].
You can run the DFT calculation with ABINIT with the command:

abinit < AlAs.in > output_AlAs

or using QuantumEspresso:

pw.x -inp AlAs.scf.in > output_scf
pw.x -inp AlAs.nscf.in > output_scf

and then import the ABINIT wave-function with the command:

a2y -F AlAso_DS2_WFK.nc

and the QuantumEspresso one, in the folder AlAs.save with the command:

p2y
Now we consider an external field in the <code>[1,1,0]</code> direction and remove symmetries not compatible with this field, as explained in the tutorial [http://www.yambo-code.eu/wiki/index.php?title=Prerequisites_for_Real_Time_propagation_with_Yambo Prerequisites for Real-Time propagation with Yambo].

==Real-time simulation for the SHG==

You can generate the input file with the command <code>yambo_nl -u n</code>:

nloptics # [R NL] Non-linear optics
% NLBands
 3 | 6 | # [NL] Bands
%
NLstep= 0.0100 fs # [NL] Real Time step length
NLverbosity= "high" # [NL] Verbosity level (low | high)
NLtime=-1.000000 fs # [NL] Simulation Time
NLintegrator= "INVINT" # [NL] Integrator ("EULEREXP/RK4/RK2EXP/HEUN/INVINT/CRANKNIC")
NLCorrelation= "IPA" # [NL] Correlation ("IPA/HARTREE/TDDFT/LRC/JGM/SEX/HF")
NLLrcAlpha= 0.000000 # [NL] Long Range Correction
% NLEnRange
 1.000000 | 5.000000 | eV # [NL] Energy range
%
NLEnSteps= 5 # [NL] Energy steps
NLDamping= 0.150000 eV # [NL] Damping
% Field1_Dir
 1.000000 | 1.000000 | 0.000000 | # [RT Field1] Versor
Field1_kind= "SOFTSIN" # [NL ExtF] Kind(SIN|SOFTSIN|RES|ANTIRES|GAUSS|DELTA|QSSIN)

The line <code>|1.000000 | 1.000000 | 0.000000 | # [RT Field1] Versor</code> referees to the direction of the external field (x,y,0). At present only an external field is present but the code can be easily generalized to deal with more fields.
The default parameters of Yambo/Lumen are already tuned for second-harmonic generation, so the only thing you have to change is the band range, between 3 and 6 and the energy range between 1.0-5.0 eV and the number of energy steps in this interval that we set to 10. Notice that you cannot set to zero the lowest value of the energy range because this will requires a simulation that lasts infinite time, see below. Finally, consider that Yambo performs a separate calculation for each frequency, so if you set many energy steps the computational time grows linearly with this number.
Notice that we set <code>NLverbosity= "high"</code> in this way the code will produce a file for each laser frequency containing the time dependent polarization.
Run <code>yambo_nl</code>. Calculations will take about fifteen minutes on a single processor PC, you have time to study the next section that explains how non-linear response is extracted from the real-time simulations.
In order to speed up calculations, you can run them in parallel.

==Non-linear response with Yambo==

In order to calculate the non-linear response, the system is excited with different laser fields with a sinusoidal shape at frequencies <math>\omega_1, \omega_2, .... , \omega_n </math> determined by the parameters [[Variables#NLEnRangev|NLEnRange]] and [[Variables#NLEnSteps|NLEnSteps]]. A dephasing term is added to the Hamiltonian <math>\gamma = </math>[[Variables#NLDamping|NLDamping]] to simulate a finite broadening and to remove the eigenmodes that are excited by the sudden turning on of the external field. After the dephasing time the outgoing signal is analyzed to extract the non-linear coefficients as shown in the figure below:

[[File:Pt analysis.png|600px|center|Non-linear response analysis]]

In the report file <code>r_nlinear</code> you will find the length of the dephasing part and of the sampling one:

Dephasing Time [fs]: 52.65695
Sampling Time [fs]: 4.18566
Total simulation time [fs]: 56.84262
The length of the dephasing interval is inversely proportional to the damping term <math>T_{depth} \simeq 1/\gamma</math> while the length of the sampling is dictated by the smallest frequency we are interested in: <math>T_{samp} \simeq 1/\omega_1 </math>. For this reason if <math> \omega_1=0 </math> or <math> \gamma = 0 </math> simulation time goes to infinity. The response at zero frequency can be calculated as limit of small frequency perturbation.
You can have a look to the file <code>src/nloptics/NL_initialize.F</code> to see how simulation lengths are defined.
Calculations can take some time, run them in parallel, the best number of processors = number of frequencies or reduce the number of frequencies step in the SHG.

==Analysis of the results==

In the sampling region we suppose that the polarization can be written as: <math>\bf{P}(t) = \sum_{n=-\infty}^{+\infty} \bf{p}_n e^{-i\omega_n t} </math> where the coefficient <math>\bf{p}_1,...,\bf{p}_n </math> are related to <math>\chi^{(1)},...,\chi^{(n)} </math>. We sample the polarization signal at different times and invert the previous equation by truncating the sum at a finite order <ref>[https://arxiv.org/abs/1309.4012 Nonlinear optics from an ab initio approach by means of the dynamical Berry phase: Application to second- and third-harmonic generation in semiconductors], C. Attaccalite and M. Grüning, Phys. Rev. B 88, 235113(2013)</ref>.
This is done with the command <code>ypp_nl -u</code> that automatically produce an input with the correct values:

nonlinear # [R] NonLinear Optics Post-Processing
Xorder= 4 # Max order of the response functions
% TimeRange
52.65695 | -1.00000 | fs # Time-window where processing is done
%
ETStpsRt= 200 # Total Energy steps
% EnRngeRt
0.00000 | 10.00000 | eV # Energy range
%
DampMode= "NONE" # Damping type ( NONE | LORENTZIAN | GAUSSIAN )
DampFactor= 0.10000 eV # Damping parameter

where <code>Xorder</code> is the order where the previous sum is truncated, and the TimeRange specifies the sampling region. Notice that differently from the first tutorial, in this case, we do not need Damping in <code>ypp_nl</code> because we already included it in the real-time dynamics. Run <code>ypp_nl</code> and it will produce a file called <code>o.YPP-X_probe_order_2</code>. This file contains the different components of <math>\chi^2_{xy*} </math> and in particular the columns 6 and 7 correspond to the imaginary and real part of <math>\chi^2_{xyz} </math>. You can plot the result with gnuplot and the command:

p 'o.YPP-X_probe_order_2' u 1:(sqrt($6**2+$7**2)) w lp ps 1.5 pt 7 lw 1.5

the result should look like

[[File:AlAs results.png|700px|center|SHG in AlAs]]

and compare it with the <math> \chi^2_{zxy} </math> calculated with more frequencies and with the converged result on a <math> 18x18x18</math> k-point grid and bands between 2 and 10. In the figure you can find also the comparison with the results of Ref. <ref>Luppi et al. [https://arxiv.org/abs/1006.2649 PRB B, '''82''', 235201(2010)]</ref>.
Notice that the QuantumEspresso results are slightly different from the Abinit ones. This is due to the different pseudo-potential employed in the calculations if pseudopotentials were the same calculation would have been identical. You can download the script to generate this plot and the converged results [http://www.attaccalite.com/lumen/tutorials/AlAs/AlAs_results.tgz here].

'''Notice that''' : the following parameters are not used in the non-linear response analysis: <code> EnRngeRt</code>, <code>ETStpsRt</code>, <code>DampMode</code>, <code>DampFactor</code>. The damping factor is set directly in the real-time simulation.

'''System of units in Non-linear Optics''': notice that in Yambo the non-linear response functions are in the gaussian system of units, for example the <math> \chi^2 (\omega) </math> is in cm/statvolt. In order to convert the non-linear coefficients between different system of units, you can have a look at the [https://www.attaccalite.com/tutorials_yambo/Appendix_C_Boyd.pdf Appendix C] of the book [https://www.elsevier.com/books/nonlinear-optics/boyd/978-0-12-369470-6 "Non-linear optics" by Robert W. Boyd].

More tutorials on non-linear response (Third harmonic generation, parallelization, spin-orbit etc..) with Yambo can be found here: [http://www.attaccalite.com/lumen/tutorials.html More Tutorials]. 

==Analysis of the results using YamboPy==
The analysis of the result performed in the previous section using <code>ypp_nl</code> can be performed using python script [https://github.com/yambo-code/yambopy YamboPy]. 
In YamboPy we implemented all necessary functions to reads the Yambo databases and post-process the results. Here we show how to get the SHG signal from the previous
simulations. We suppose you correctly installed <code>YamboPy</code> on your PC. Go in the folder where you ran non-linear calculation and type in the python:
 
from yambopy import *
NLDB=YamboNLDB()
pol =NLDB.Polarization[0]
time=NLDB.IO_TIME_points

in this way you read all the Non-linear databases. If your runs are in a different folder then the 'SAVE' one you can specify it using the command:
NLDB=YamboNLDB(calc='MYJOB')

now in the array <code>pol</code> you have all the polarization for all laser frequencies in the three Cartesian directions, while the variable <code>time</code> contains all the time series of your simulation.
Now you can get the non-linear response with the command:

Harmonic_Analysis(NLDB,X_order=4)

this command will perform a Fourier analysis of the results in the same way of <code>ypp_nl</code> and generate new files with all the requested harmonics ''o.YamboPy-X_probe_order_1'', ''o.YamboPy-X_probe_order_2'' etc...
equivalent to the one generated by <code>ypp_nl</code>. Results can be plot with gnuplot using the command:

p 'o.YamboPy-X_probe_order_2' u 1:(sqrt($6**2+$7**2)) w lp ps 1.5 pt 7 lw 1.5

The script that performs non-linear analysis can be found in <code>yambopy/nl/harmonic_analysis.py</code>. We strongly advice you to have a look to this script and modify it according
to your needs and in order to extract other non-linear response functions.

==How to choose the external field direction for the different X2==

In the X2abc response you have three field directions. The two components ''b'' and ''c'' are determined by the external field and the third ''a''
is the direction where you measure the response. 

The external field in Yambo is set using the variable
% Field1_Dir
1.000000 | 0.000000 | 0.000000 | # [NL ExtF] Versor .
%

For example if you set in Yambo field direction as:

1.0 | 0.0 | 0.0 | ---> you calculate all components X2*xx
0.0 | 1.0 | 0.0 | ---> you calculate all components X2*yy
0.0 | 0.0 | 1.0 | ---> you calculate all components X2*zz

the * correspond to the different direction in the response file <code>o.YPP-X_probe_order_2</code>.
In the <code>o.YPP-X_probe_order_2</code> you have seven columns:

The first column is the energy [[omega]],
the 2nd and 3rd columns are the imaginary and real part of X2x**
the 4th and 5th columns are the imaginary and real part of X2y**
the 6th and 7th columns are the imaginary and real part of X2z**

where the ** are the direction of the incoming field, see above.

For example if you want to calculate the <math>\chi^{(2)}_{zxx}</math> you put the external field in the direction <code> 1.0 | 0.0 | 0.0 |</code>
and then plot the column 6 and 7 of the <code>o.YPP-X_probe_order_2</code> file. 

'''Nota bene:''' if you change the direction of the external field you have to remove the corresponding symmetries as explained in the tutorial
on [[Prerequisites for Real Time_propagation with Yambo#Reduce symmetries real-time linear response tutorial]].

In order to get the other components of the X2 the calculation are more involved. For example if you put field in the

1.0 | 1.0 | 0.0 |

this corresponds to <math>E(t)=\frac{1}{\sqrt{2}} [ E_x(t) + E_y(t) ]</math> and so at the second order you will have <math>E^2(t)=\frac{1}{2} [ E^2_x(t) + E^2_y(t) + E_x(t) E_y(t) + E_y(t) E_x(t) ]</math> 
this means that the X2 in the <code>o.YPP-X_probe_order_2</code> will correspond to a linear combination of the following different response functions. 
For example in the the 2nd and 3rd columns are the imaginary and real part of: 

<math>\chi^{(2)}_{x**}=\frac{1}{2} \left [\chi^2_{xxx}+\chi^{(2)}_{xyy} + \chi^{(2)}_{xxy} + \chi^{(2)}_{xyx} \right ]</math>

the same for the other column replacing the first <code>x</code> for <code>y,z</code>.
If you know that some components are zero this allow you to extract the corresponding off-diagonal part of <math>\chi^{(2)}_{abc}</math> otherwise you have to perform different calculations to get the component you are interested in. 
Now we present '''a simple example of monolayer hBN (m-hBN)'''. In m-hBN there is only a non-zero component of the $\chi^2$ and all the others are related by symmetry: 
<math>\chi^{(2)}_{yyy}=-\chi^{(2)}_{yxx}=-\chi^{(2)}_{xxy}=-\chi^{(2)}_{xyx}</math> 
so if you put the field in the <code>|1|1|0|</code> direction you will get: 
<math>\chi^{(2)}_{x**} = \frac{1}{2} \left[\chi^{(2)}_{xxy} + \chi^{(2)}_{xyx} \right] = - \chi^{(2)}_{yyy} </math> 
<math>\chi^{(2)}_{y**} =\frac{1}{2} \left[ \chi^{(2)}_{yyy} + \chi^{(2)}_{yxx} \right] = 0.0 </math>

==Non-linear response of low-dimensional structures: 2D or 1D ==

The Yambo code is a 3D periodic code, so when you want to study a low-dimensional system 2D or 1D, you have to use a supercell approach.
For example to simulate the non-linear response in a 2D-crystal one, can put the crystal in the xy plane and choose a larger distance in the z-direction
in order to reduce the interaction between the periodic replica. Clearly in this case k-point sampling will be only in the x,y directions.
For calculations on this type of systems, these two warnings must be taken into account:

* if you calculate GW corrections or include electron-hole interaction in the linear/non-linear response it is a good idea to use a '''Coulomb cutoff''', similar to the 2D BSE case [http://www.yambo-code.org/wiki/index.php?title=How_to_treat_low_dimensional_systems How to treat low dimensional systems]. You can add the cutoff just adding the "-r" in the input generation.

* the calculation of SHG and THG are always performed respect to the supercell, therefore you have to '''re-scale''' the result to the effective thickness of the layer, usually the inter-layer distance of the corresponding bulk material for 2D systems: <math>\chi_{rescaled}(\omega) = L_z/d_{eff} \cdot \chi(\omega) </math> where <math>L_z</math> is the z-dimension of the supercell, and <math>d_{eff}</math> is the effective thickness of the 2D system.

'''Nota bene''': Non-linear response along non-periodic directions is not implemented in Yambo, the code will print zero in these directions for all response functions. We plan to implement it in a future version of the code.

==References==
<references />

==Links for schools==
* Back to [[Rome 2023#Tutorials]]
* Back to [[ICTP2020]]

 
{| style="width:100%" border="1"
|style="width:25%; text-align:left"|Prev: [[Linear response from real time simulations|Linear response from real time simulations]]
|style="width:45%; text-align:center"|Now: [[ICTP2020|ICTP Tutorials]] --> [[Real time approach to non-linear response|Non Linear Response]]
|style="width:50%; text-align:left"|Next: [[Correlation effects in the non-linear response|Correlation effects in the non-linear response ]]
|-
|}

Real time approach to non-linear response (SHG)

2025-09-27T08:42:01Z

Attacc: /* How to choose the external field direction for the different X2 */

== Second Harmonic Generation in AlAs ==
In this tutorial, we will calculate the second harmonic generation of bulk AlAs, the Yambo databases can be downloaded here: [https://media.yambo-code.eu/educational/tutorials/files/AlAs_DBs.tar.gz AlAs_DBs.tar.gz] (10 MB). The first steps of this tutorials are the same as the one on [http://www.yambo-code.eu/wiki/index.php?title=Prerequisites_for_Real_Time_propagation_with_Yambo Prerequisites for Real-Time propagation with Yambo] with the only difference that we will work on AlAs and we will consider an external field in the direction <code> 1.000000 | 1.000000 | 0.000000 |</code>. The DFT input are available here: [https://media.yambo-code.eu/educational/tutorials/files/AlAs_abinit.tar.gz ABINIT] or [https://media.yambo-code.eu/educational/tutorials/files/AlAs_pwscf.tar.gz QuantumEspresso].
You can run the DFT calculation with ABINIT with the command:

abinit < AlAs.in > output_AlAs

or using QuantumEspresso:

pw.x -inp AlAs.scf.in > output_scf
pw.x -inp AlAs.nscf.in > output_scf

and then import the ABINIT wave-function with the command:

a2y -F AlAso_DS2_WFK.nc

and the QuantumEspresso one, in the folder AlAs.save with the command:

p2y
Now we consider an external field in the <code>[1,1,0]</code> direction and remove symmetries not compatible with this field, as explained in the tutorial [http://www.yambo-code.eu/wiki/index.php?title=Prerequisites_for_Real_Time_propagation_with_Yambo Prerequisites for Real-Time propagation with Yambo].

==Real-time simulation for the SHG==

You can generate the input file with the command <code>yambo_nl -u n</code>:

nloptics # [R NL] Non-linear optics
% NLBands
 3 | 6 | # [NL] Bands
%
NLstep= 0.0100 fs # [NL] Real Time step length
NLverbosity= "high" # [NL] Verbosity level (low | high)
NLtime=-1.000000 fs # [NL] Simulation Time
NLintegrator= "INVINT" # [NL] Integrator ("EULEREXP/RK4/RK2EXP/HEUN/INVINT/CRANKNIC")
NLCorrelation= "IPA" # [NL] Correlation ("IPA/HARTREE/TDDFT/LRC/JGM/SEX/HF")
NLLrcAlpha= 0.000000 # [NL] Long Range Correction
% NLEnRange
 1.000000 | 5.000000 | eV # [NL] Energy range
%
NLEnSteps= 5 # [NL] Energy steps
NLDamping= 0.150000 eV # [NL] Damping
% Field1_Dir
 1.000000 | 1.000000 | 0.000000 | # [RT Field1] Versor
Field1_kind= "SOFTSIN" # [NL ExtF] Kind(SIN|SOFTSIN|RES|ANTIRES|GAUSS|DELTA|QSSIN)

The line <code>|1.000000 | 1.000000 | 0.000000 | # [RT Field1] Versor</code> referees to the direction of the external field (x,y,0). At present only an external field is present but the code can be easily generalized to deal with more fields.
The default parameters of Yambo/Lumen are already tuned for second-harmonic generation, so the only thing you have to change is the band range, between 3 and 6 and the energy range between 1.0-5.0 eV and the number of energy steps in this interval that we set to 10. Notice that you cannot set to zero the lowest value of the energy range because this will requires a simulation that lasts infinite time, see below. Finally, consider that Yambo performs a separate calculation for each frequency, so if you set many energy steps the computational time grows linearly with this number.
Notice that we set <code>NLverbosity= "high"</code> in this way the code will produce a file for each laser frequency containing the time dependent polarization.
Run <code>yambo_nl</code>. Calculations will take about fifteen minutes on a single processor PC, you have time to study the next section that explains how non-linear response is extracted from the real-time simulations.
In order to speed up calculations, you can run them in parallel.

==Non-linear response with Yambo==

In order to calculate the non-linear response, the system is excited with different laser fields with a sinusoidal shape at frequencies <math>\omega_1, \omega_2, .... , \omega_n </math> determined by the parameters [[Variables#NLEnRangev|NLEnRange]] and [[Variables#NLEnSteps|NLEnSteps]]. A dephasing term is added to the Hamiltonian <math>\gamma = </math>[[Variables#NLDamping|NLDamping]] to simulate a finite broadening and to remove the eigenmodes that are excited by the sudden turning on of the external field. After the dephasing time the outgoing signal is analyzed to extract the non-linear coefficients as shown in the figure below:

[[File:Pt analysis.png|600px|center|Non-linear response analysis]]

In the report file <code>r_nlinear</code> you will find the length of the dephasing part and of the sampling one:

Dephasing Time [fs]: 52.65695
Sampling Time [fs]: 4.18566
Total simulation time [fs]: 56.84262
The length of the dephasing interval is inversely proportional to the damping term <math>T_{depth} \simeq 1/\gamma</math> while the length of the sampling is dictated by the smallest frequency we are interested in: <math>T_{samp} \simeq 1/\omega_1 </math>. For this reason if <math> \omega_1=0 </math> or <math> \gamma = 0 </math> simulation time goes to infinity. The response at zero frequency can be calculated as limit of small frequency perturbation.
You can have a look to the file <code>src/nloptics/NL_initialize.F</code> to see how simulation lengths are defined.
Calculations can take some time, run them in parallel, the best number of processors = number of frequencies or reduce the number of frequencies step in the SHG.

==Analysis of the results==

In the sampling region we suppose that the polarization can be written as: <math>\bf{P}(t) = \sum_{n=-\infty}^{+\infty} \bf{p}_n e^{-i\omega_n t} </math> where the coefficient <math>\bf{p}_1,...,\bf{p}_n </math> are related to <math>\chi^{(1)},...,\chi^{(n)} </math>. We sample the polarization signal at different times and invert the previous equation by truncating the sum at a finite order <ref>[https://arxiv.org/abs/1309.4012 Nonlinear optics from an ab initio approach by means of the dynamical Berry phase: Application to second- and third-harmonic generation in semiconductors], C. Attaccalite and M. Grüning, Phys. Rev. B 88, 235113(2013)</ref>.
This is done with the command <code>ypp_nl -u</code> that automatically produce an input with the correct values:

nonlinear # [R] NonLinear Optics Post-Processing
Xorder= 4 # Max order of the response functions
% TimeRange
52.65695 | -1.00000 | fs # Time-window where processing is done
%
ETStpsRt= 200 # Total Energy steps
% EnRngeRt
0.00000 | 10.00000 | eV # Energy range
%
DampMode= "NONE" # Damping type ( NONE | LORENTZIAN | GAUSSIAN )
DampFactor= 0.10000 eV # Damping parameter

where <code>Xorder</code> is the order where the previous sum is truncated, and the TimeRange specifies the sampling region. Notice that differently from the first tutorial, in this case, we do not need Damping in <code>ypp_nl</code> because we already included it in the real-time dynamics. Run <code>ypp_nl</code> and it will produce a file called <code>o.YPP-X_probe_order_2</code>. This file contains the different components of <math>\chi^2_{xy*} </math> and in particular the columns 6 and 7 correspond to the imaginary and real part of <math>\chi^2_{xyz} </math>. You can plot the result with gnuplot and the command:

p 'o.YPP-X_probe_order_2' u 1:(sqrt($6**2+$7**2)) w lp ps 1.5 pt 7 lw 1.5

the result should look like

[[File:AlAs results.png|700px|center|SHG in AlAs]]

and compare it with the <math> \chi^2_{zxy} </math> calculated with more frequencies and with the converged result on a <math> 18x18x18</math> k-point grid and bands between 2 and 10. In the figure you can find also the comparison with the results of Ref. <ref>Luppi et al. [https://arxiv.org/abs/1006.2649 PRB B, '''82''', 235201(2010)]</ref>.
Notice that the QuantumEspresso results are slightly different from the Abinit ones. This is due to the different pseudo-potential employed in the calculations if pseudopotentials were the same calculation would have been identical. You can download the script to generate this plot and the converged results [http://www.attaccalite.com/lumen/tutorials/AlAs/AlAs_results.tgz here].

'''Notice that''' : the following parameters are not used in the non-linear response analysis: <code> EnRngeRt</code>, <code>ETStpsRt</code>, <code>DampMode</code>, <code>DampFactor</code>. The damping factor is set directly in the real-time simulation.

'''System of units in Non-linear Optics''': notice that in Yambo the non-linear response functions are in the gaussian system of units, for example the <math> \chi^2 (\omega) </math> is in cm/statvolt. In order to convert the non-linear coefficients between different system of units, you can have a look at the [https://www.attaccalite.com/tutorials_yambo/Appendix_C_Boyd.pdf Appendix C] of the book [https://www.elsevier.com/books/nonlinear-optics/boyd/978-0-12-369470-6 "Non-linear optics" by Robert W. Boyd].

More tutorials on non-linear response (Third harmonic generation, parallelization, spin-orbit etc..) with Yambo can be found here: [http://www.attaccalite.com/lumen/tutorials.html More Tutorials]. 

==Analysis of the results using YamboPy==
The analysis of the result performed in the previous section using <code>ypp_nl</code> can be performed using python script [https://github.com/yambo-code/yambopy YamboPy]. 
In YamboPy we implemented all necessary functions to reads the Yambo databases and post-process the results. Here we show how to get the SHG signal from the previous
simulations. We suppose you correctly installed <code>YamboPy</code> on your PC. Go in the folder where you ran non-linear calculation and type in the python:
 
from yambopy import *
NLDB=YamboNLDB()
pol =NLDB.Polarization[0]
time=NLDB.IO_TIME_points

in this way you read all the Non-linear databases. If your runs are in a different folder then the 'SAVE' one you can specify it using the command:
NLDB=YamboNLDB(calc='MYJOB')

now in the array <code>pol</code> you have all the polarization for all laser frequencies in the three Cartesian directions, while the variable <code>time</code> contains all the time series of your simulation.
Now you can get the non-linear response with the command:

Harmonic_Analysis(NLDB,X_order=4)

this command will perform a Fourier analysis of the results in the same way of <code>ypp_nl</code> and generate new files with all the requested harmonics ''o.YamboPy-X_probe_order_1'', ''o.YamboPy-X_probe_order_2'' etc...
equivalent to the one generated by <code>ypp_nl</code>. Results can be plot with gnuplot using the command:

p 'o.YamboPy-X_probe_order_2' u 1:(sqrt($6**2+$7**2)) w lp ps 1.5 pt 7 lw 1.5

The script that performs non-linear analysis can be found in <code>yambopy/nl/harmonic_analysis.py</code>. We strongly advice you to have a look to this script and modify it according
to your needs and in order to extract other non-linear response functions.

==How to choose the external field direction for the different X2==

In the X2abc response you have three field directions. The two components ''b'' and ''c'' are determined by the external field and the third ''a''
is the direction where you measure the response. 

The external field in Yambo is set using the variable
% Field1_Dir
1.000000 | 0.000000 | 0.000000 | # [NL ExtF] Versor .
%

For example if you set in Yambo field direction as:

1.0 | 0.0 | 0.0 | ---> you calculate all components X2*xx
0.0 | 1.0 | 0.0 | ---> you calculate all components X2*yy
0.0 | 0.0 | 1.0 | ---> you calculate all components X2*zz

the * correspond to the different direction in the response file <code>o.YPP-X_probe_order_2</code>.
In the <code>o.YPP-X_probe_order_2</code> you have seven columns:

The first column is the energy [[omega]],
the 2nd and 3rd columns are the imaginary and real part of X2x**
the 4th and 5th columns are the imaginary and real part of X2y**
the 6th and 7th columns are the imaginary and real part of X2z**

where the ** are the direction of the incoming field, see above.

For example if you want to calculate the <math>\chi^{(2)}_{zxx}</math> you put the external field in the direction <code> 1.0 | 0.0 | 0.0 |</code>
and then plot the column 6 and 7 of the <code>o.YPP-X_probe_order_2</code> file. 

'''Nota bene:''' if you change the direction of the external field you have to remove the corresponding symmetries as explained in the tutorial
on [[Prerequisites for Real Time_propagation with Yambo#Reduce symmetries real-time linear response tutorial]].

In order to get the other components of the X2 the calculation are more involved. For example if you put field in the

1.0 | 1.0 | 0.0 |

this corresponds to <math>E(t)=\frac{1}{\sqrt{2}} [ E_x(t) + E_y(t) ]</math> and so at the second order you will have <math>E^2(t)=\frac{1}{2} [ E^2_x(t) + E^2_y(t) + E_x(t) E_y(t) + E_y(t) E_x(t) ]</math> 
this means that the X2 in the <code>o.YPP-X_probe_order_2</code> will correspond to a linear combination of the following different response functions. 
For example in the the 2nd and 3rd columns are the imaginary and real part of: 

<math>\chi^{(2)}_{x**}=\frac{1}{2} \left [\chi^2_{xxx}+\chi^{(2)}_{xyy} + \chi^{(2)}_{xxy} + \chi^{(2)}_{xyx} \right ]</math>

the same for the other column replacing the first <code>x</code> for <code>y,z</code>.
If you know that some components are zero this allow you to extract the corresponding off-diagonal part of <math>\chi^{(2)}_{abc}</math> otherwise you have to perform different calculations to get the component you are interested in. 
Now we present '''a simple example of monolayer hBN (m-hBN)'''. In m-hBN there is only a non-zero component of the $\chi^2$ and all the others are related by symmetry: 
<math>\chi^{(2)}_{yyy}=-\chi^{(2)}_{yxx}=-\chi^{(2)}_{xxy}=-\chi^{(2)}_{xyx}</math> 
so if you put the field in the <code>|1|1|0|</code> direction you will get: 
<math>\chi^{(2)}_{x**} = \frac{1}{2} \left[\chi^{(2)}_{xxy} + \chi^{(2)}_{xyx} \right] = - \chi^{(2)}_{yyy} </math>
<math>\chi^{(2)}_{y**} =\frac{1}{2} \left[ \chi^{(2)}_{yyy} + \chi^{(2)}_{yxx} \right] = 0.0 </math>

==Non-linear response of low-dimensional structures: 2D or 1D ==

The Yambo code is a 3D periodic code, so when you want to study a low-dimensional system 2D or 1D, you have to use a supercell approach.
For example to simulate the non-linear response in a 2D-crystal one, can put the crystal in the xy plane and choose a larger distance in the z-direction
in order to reduce the interaction between the periodic replica. Clearly in this case k-point sampling will be only in the x,y directions.
For calculations on this type of systems, these two warnings must be taken into account:

* if you calculate GW corrections or include electron-hole interaction in the linear/non-linear response it is a good idea to use a '''Coulomb cutoff''', similar to the 2D BSE case [http://www.yambo-code.org/wiki/index.php?title=How_to_treat_low_dimensional_systems How to treat low dimensional systems]. You can add the cutoff just adding the "-r" in the input generation.

* the calculation of SHG and THG are always performed respect to the supercell, therefore you have to '''re-scale''' the result to the effective thickness of the layer, usually the inter-layer distance of the corresponding bulk material for 2D systems: <math>\chi_{rescaled}(\omega) = L_z/d_{eff} \cdot \chi(\omega) </math> where <math>L_z</math> is the z-dimension of the supercell, and <math>d_{eff}</math> is the effective thickness of the 2D system.

'''Nota bene''': Non-linear response along non-periodic directions is not implemented in Yambo, the code will print zero in these directions for all response functions. We plan to implement it in a future version of the code.

==References==
<references />

==Links for schools==
* Back to [[Rome 2023#Tutorials]]
* Back to [[ICTP2020]]

 
{| style="width:100%" border="1"
|style="width:25%; text-align:left"|Prev: [[Linear response from real time simulations|Linear response from real time simulations]]
|style="width:45%; text-align:center"|Now: [[ICTP2020|ICTP Tutorials]] --> [[Real time approach to non-linear response|Non Linear Response]]
|style="width:50%; text-align:left"|Next: [[Correlation effects in the non-linear response|Correlation effects in the non-linear response ]]
|-
|}

Real time approach to non-linear response (SHG)

2025-09-27T08:40:27Z

Attacc: /* How to choose the external field direction for the different X2 */

== Second Harmonic Generation in AlAs ==
In this tutorial, we will calculate the second harmonic generation of bulk AlAs, the Yambo databases can be downloaded here: [https://media.yambo-code.eu/educational/tutorials/files/AlAs_DBs.tar.gz AlAs_DBs.tar.gz] (10 MB). The first steps of this tutorials are the same as the one on [http://www.yambo-code.eu/wiki/index.php?title=Prerequisites_for_Real_Time_propagation_with_Yambo Prerequisites for Real-Time propagation with Yambo] with the only difference that we will work on AlAs and we will consider an external field in the direction <code> 1.000000 | 1.000000 | 0.000000 |</code>. The DFT input are available here: [https://media.yambo-code.eu/educational/tutorials/files/AlAs_abinit.tar.gz ABINIT] or [https://media.yambo-code.eu/educational/tutorials/files/AlAs_pwscf.tar.gz QuantumEspresso].
You can run the DFT calculation with ABINIT with the command:

abinit < AlAs.in > output_AlAs

or using QuantumEspresso:

pw.x -inp AlAs.scf.in > output_scf
pw.x -inp AlAs.nscf.in > output_scf

and then import the ABINIT wave-function with the command:

a2y -F AlAso_DS2_WFK.nc

and the QuantumEspresso one, in the folder AlAs.save with the command:

p2y
Now we consider an external field in the <code>[1,1,0]</code> direction and remove symmetries not compatible with this field, as explained in the tutorial [http://www.yambo-code.eu/wiki/index.php?title=Prerequisites_for_Real_Time_propagation_with_Yambo Prerequisites for Real-Time propagation with Yambo].

==Real-time simulation for the SHG==

You can generate the input file with the command <code>yambo_nl -u n</code>:

nloptics # [R NL] Non-linear optics
% NLBands
 3 | 6 | # [NL] Bands
%
NLstep= 0.0100 fs # [NL] Real Time step length
NLverbosity= "high" # [NL] Verbosity level (low | high)
NLtime=-1.000000 fs # [NL] Simulation Time
NLintegrator= "INVINT" # [NL] Integrator ("EULEREXP/RK4/RK2EXP/HEUN/INVINT/CRANKNIC")
NLCorrelation= "IPA" # [NL] Correlation ("IPA/HARTREE/TDDFT/LRC/JGM/SEX/HF")
NLLrcAlpha= 0.000000 # [NL] Long Range Correction
% NLEnRange
 1.000000 | 5.000000 | eV # [NL] Energy range
%
NLEnSteps= 5 # [NL] Energy steps
NLDamping= 0.150000 eV # [NL] Damping
% Field1_Dir
 1.000000 | 1.000000 | 0.000000 | # [RT Field1] Versor
Field1_kind= "SOFTSIN" # [NL ExtF] Kind(SIN|SOFTSIN|RES|ANTIRES|GAUSS|DELTA|QSSIN)

The line <code>|1.000000 | 1.000000 | 0.000000 | # [RT Field1] Versor</code> referees to the direction of the external field (x,y,0). At present only an external field is present but the code can be easily generalized to deal with more fields.
The default parameters of Yambo/Lumen are already tuned for second-harmonic generation, so the only thing you have to change is the band range, between 3 and 6 and the energy range between 1.0-5.0 eV and the number of energy steps in this interval that we set to 10. Notice that you cannot set to zero the lowest value of the energy range because this will requires a simulation that lasts infinite time, see below. Finally, consider that Yambo performs a separate calculation for each frequency, so if you set many energy steps the computational time grows linearly with this number.
Notice that we set <code>NLverbosity= "high"</code> in this way the code will produce a file for each laser frequency containing the time dependent polarization.
Run <code>yambo_nl</code>. Calculations will take about fifteen minutes on a single processor PC, you have time to study the next section that explains how non-linear response is extracted from the real-time simulations.
In order to speed up calculations, you can run them in parallel.

==Non-linear response with Yambo==

In order to calculate the non-linear response, the system is excited with different laser fields with a sinusoidal shape at frequencies <math>\omega_1, \omega_2, .... , \omega_n </math> determined by the parameters [[Variables#NLEnRangev|NLEnRange]] and [[Variables#NLEnSteps|NLEnSteps]]. A dephasing term is added to the Hamiltonian <math>\gamma = </math>[[Variables#NLDamping|NLDamping]] to simulate a finite broadening and to remove the eigenmodes that are excited by the sudden turning on of the external field. After the dephasing time the outgoing signal is analyzed to extract the non-linear coefficients as shown in the figure below:

[[File:Pt analysis.png|600px|center|Non-linear response analysis]]

In the report file <code>r_nlinear</code> you will find the length of the dephasing part and of the sampling one:

Dephasing Time [fs]: 52.65695
Sampling Time [fs]: 4.18566
Total simulation time [fs]: 56.84262
The length of the dephasing interval is inversely proportional to the damping term <math>T_{depth} \simeq 1/\gamma</math> while the length of the sampling is dictated by the smallest frequency we are interested in: <math>T_{samp} \simeq 1/\omega_1 </math>. For this reason if <math> \omega_1=0 </math> or <math> \gamma = 0 </math> simulation time goes to infinity. The response at zero frequency can be calculated as limit of small frequency perturbation.
You can have a look to the file <code>src/nloptics/NL_initialize.F</code> to see how simulation lengths are defined.
Calculations can take some time, run them in parallel, the best number of processors = number of frequencies or reduce the number of frequencies step in the SHG.

==Analysis of the results==

In the sampling region we suppose that the polarization can be written as: <math>\bf{P}(t) = \sum_{n=-\infty}^{+\infty} \bf{p}_n e^{-i\omega_n t} </math> where the coefficient <math>\bf{p}_1,...,\bf{p}_n </math> are related to <math>\chi^{(1)},...,\chi^{(n)} </math>. We sample the polarization signal at different times and invert the previous equation by truncating the sum at a finite order <ref>[https://arxiv.org/abs/1309.4012 Nonlinear optics from an ab initio approach by means of the dynamical Berry phase: Application to second- and third-harmonic generation in semiconductors], C. Attaccalite and M. Grüning, Phys. Rev. B 88, 235113(2013)</ref>.
This is done with the command <code>ypp_nl -u</code> that automatically produce an input with the correct values:

nonlinear # [R] NonLinear Optics Post-Processing
Xorder= 4 # Max order of the response functions
% TimeRange
52.65695 | -1.00000 | fs # Time-window where processing is done
%
ETStpsRt= 200 # Total Energy steps
% EnRngeRt
0.00000 | 10.00000 | eV # Energy range
%
DampMode= "NONE" # Damping type ( NONE | LORENTZIAN | GAUSSIAN )
DampFactor= 0.10000 eV # Damping parameter

where <code>Xorder</code> is the order where the previous sum is truncated, and the TimeRange specifies the sampling region. Notice that differently from the first tutorial, in this case, we do not need Damping in <code>ypp_nl</code> because we already included it in the real-time dynamics. Run <code>ypp_nl</code> and it will produce a file called <code>o.YPP-X_probe_order_2</code>. This file contains the different components of <math>\chi^2_{xy*} </math> and in particular the columns 6 and 7 correspond to the imaginary and real part of <math>\chi^2_{xyz} </math>. You can plot the result with gnuplot and the command:

p 'o.YPP-X_probe_order_2' u 1:(sqrt($6**2+$7**2)) w lp ps 1.5 pt 7 lw 1.5

the result should look like

[[File:AlAs results.png|700px|center|SHG in AlAs]]

and compare it with the <math> \chi^2_{zxy} </math> calculated with more frequencies and with the converged result on a <math> 18x18x18</math> k-point grid and bands between 2 and 10. In the figure you can find also the comparison with the results of Ref. <ref>Luppi et al. [https://arxiv.org/abs/1006.2649 PRB B, '''82''', 235201(2010)]</ref>.
Notice that the QuantumEspresso results are slightly different from the Abinit ones. This is due to the different pseudo-potential employed in the calculations if pseudopotentials were the same calculation would have been identical. You can download the script to generate this plot and the converged results [http://www.attaccalite.com/lumen/tutorials/AlAs/AlAs_results.tgz here].

'''Notice that''' : the following parameters are not used in the non-linear response analysis: <code> EnRngeRt</code>, <code>ETStpsRt</code>, <code>DampMode</code>, <code>DampFactor</code>. The damping factor is set directly in the real-time simulation.

'''System of units in Non-linear Optics''': notice that in Yambo the non-linear response functions are in the gaussian system of units, for example the <math> \chi^2 (\omega) </math> is in cm/statvolt. In order to convert the non-linear coefficients between different system of units, you can have a look at the [https://www.attaccalite.com/tutorials_yambo/Appendix_C_Boyd.pdf Appendix C] of the book [https://www.elsevier.com/books/nonlinear-optics/boyd/978-0-12-369470-6 "Non-linear optics" by Robert W. Boyd].

More tutorials on non-linear response (Third harmonic generation, parallelization, spin-orbit etc..) with Yambo can be found here: [http://www.attaccalite.com/lumen/tutorials.html More Tutorials]. 

==Analysis of the results using YamboPy==
The analysis of the result performed in the previous section using <code>ypp_nl</code> can be performed using python script [https://github.com/yambo-code/yambopy YamboPy]. 
In YamboPy we implemented all necessary functions to reads the Yambo databases and post-process the results. Here we show how to get the SHG signal from the previous
simulations. We suppose you correctly installed <code>YamboPy</code> on your PC. Go in the folder where you ran non-linear calculation and type in the python:
 
from yambopy import *
NLDB=YamboNLDB()
pol =NLDB.Polarization[0]
time=NLDB.IO_TIME_points

in this way you read all the Non-linear databases. If your runs are in a different folder then the 'SAVE' one you can specify it using the command:
NLDB=YamboNLDB(calc='MYJOB')

now in the array <code>pol</code> you have all the polarization for all laser frequencies in the three Cartesian directions, while the variable <code>time</code> contains all the time series of your simulation.
Now you can get the non-linear response with the command:

Harmonic_Analysis(NLDB,X_order=4)

this command will perform a Fourier analysis of the results in the same way of <code>ypp_nl</code> and generate new files with all the requested harmonics ''o.YamboPy-X_probe_order_1'', ''o.YamboPy-X_probe_order_2'' etc...
equivalent to the one generated by <code>ypp_nl</code>. Results can be plot with gnuplot using the command:

p 'o.YamboPy-X_probe_order_2' u 1:(sqrt($6**2+$7**2)) w lp ps 1.5 pt 7 lw 1.5

The script that performs non-linear analysis can be found in <code>yambopy/nl/harmonic_analysis.py</code>. We strongly advice you to have a look to this script and modify it according
to your needs and in order to extract other non-linear response functions.

==How to choose the external field direction for the different X2==

In the X2abc response you have three field directions. The two components ''b'' and ''c'' are determined by the external field and the third ''a''
is the direction where you measure the response. 

The external field in Yambo is set using the variable
% Field1_Dir
1.000000 | 0.000000 | 0.000000 | # [NL ExtF] Versor .
%

For example if you set in Yambo field direction as:

1.0 | 0.0 | 0.0 | ---> you calculate all components X2*xx
0.0 | 1.0 | 0.0 | ---> you calculate all components X2*yy
0.0 | 0.0 | 1.0 | ---> you calculate all components X2*zz

the * correspond to the different direction in the response file <code>o.YPP-X_probe_order_2</code>.
In the <code>o.YPP-X_probe_order_2</code> you have seven columns:

The first column is the energy [[omega]],
the 2nd and 3rd columns are the imaginary and real part of X2x**
the 4th and 5th columns are the imaginary and real part of X2y**
the 6th and 7th columns are the imaginary and real part of X2z**

where the ** are the direction of the incoming field, see above.

For example if you want to calculate the <math>\chi^{(2)}_{zxx}</math> you put the external field in the direction <code> 1.0 | 0.0 | 0.0 |</code>
and then plot the column 6 and 7 of the <code>o.YPP-X_probe_order_2</code> file. 

'''Nota bene:''' if you change the direction of the external field you have to remove the corresponding symmetries as explained in the tutorial
on [[Prerequisites for Real Time_propagation with Yambo#Reduce symmetries real-time linear response tutorial]].

In order to get the other components of the X2 the calculation are more involved. For example if you put field in the

1.0 | 1.0 | 0.0 |

this corresponds to <math>E(t)=\frac{1}{\sqrt{2}} [ E_x(t) + E_y(t) ]</math> and so at the second order you will have <math>E^2(t)=\frac{1}{2} [ E^2_x(t) + E^2_y(t) + E_x(t) E_y(t) + E_y(t) E_x(t) ]</math> 
this means that the X2 in the <code>o.YPP-X_probe_order_2</code> will correspond to a linear combination of the following different response functions. 
For example in the the 2nd and 3rd columns are the imaginary and real part of: 

<math>\chi^{(2)}_{x**}=\frac{1}{2} \left [\chi^2_{xxx}+\chi^{(2)}_{xyy} + \chi^{(2)}_{xxy} + \chi^{(2)}_{xyx} \right ]</math>

the same for the other column replacing the first <code>x</code> for <code>y,z</code>.
If you know that some components are zero this allow you to extract the corresponding off-diagonal part of <math>\chi^{(2)}_{abc}</math> otherwise you have to perform different calculations to get the component you are interested in. 
Now we present '''a simple example of monolayer hBN (m-hBN)'''. In m-hBN there is only a non-zero component of the $\chi^2$ and all the others are related by symmetry: 
<math>\chi^{(2)}_{yyy}=-\chi^{(2)}_{yxx}=-\chi^{(2)}_{xxy}=-\chi^{(2)}_{xyx}</math> 
so if you put the field in the <code>|1|1|0|</code> direction you will get:
<math>\chi^{(2)}_{x**} = \frac{1}{2} \left[\chi^{(2)}_{xxy} + \chi^{(2)}_{xyx} \right] = - \chi^{(2)}_{yyy} </math>
<math>\chi^{(2)}_{y**} =-\chi^{(2)}_{yxx}=-\chi^{(2)}_{xxy}=-\chi^{(2)}_{xyx}</math>

==Non-linear response of low-dimensional structures: 2D or 1D ==

The Yambo code is a 3D periodic code, so when you want to study a low-dimensional system 2D or 1D, you have to use a supercell approach.
For example to simulate the non-linear response in a 2D-crystal one, can put the crystal in the xy plane and choose a larger distance in the z-direction
in order to reduce the interaction between the periodic replica. Clearly in this case k-point sampling will be only in the x,y directions.
For calculations on this type of systems, these two warnings must be taken into account:

* if you calculate GW corrections or include electron-hole interaction in the linear/non-linear response it is a good idea to use a '''Coulomb cutoff''', similar to the 2D BSE case [http://www.yambo-code.org/wiki/index.php?title=How_to_treat_low_dimensional_systems How to treat low dimensional systems]. You can add the cutoff just adding the "-r" in the input generation.

* the calculation of SHG and THG are always performed respect to the supercell, therefore you have to '''re-scale''' the result to the effective thickness of the layer, usually the inter-layer distance of the corresponding bulk material for 2D systems: <math>\chi_{rescaled}(\omega) = L_z/d_{eff} \cdot \chi(\omega) </math> where <math>L_z</math> is the z-dimension of the supercell, and <math>d_{eff}</math> is the effective thickness of the 2D system.

'''Nota bene''': Non-linear response along non-periodic directions is not implemented in Yambo, the code will print zero in these directions for all response functions. We plan to implement it in a future version of the code.

==References==
<references />

==Links for schools==
* Back to [[Rome 2023#Tutorials]]
* Back to [[ICTP2020]]

 
{| style="width:100%" border="1"
|style="width:25%; text-align:left"|Prev: [[Linear response from real time simulations|Linear response from real time simulations]]
|style="width:45%; text-align:center"|Now: [[ICTP2020|ICTP Tutorials]] --> [[Real time approach to non-linear response|Non Linear Response]]
|style="width:50%; text-align:left"|Next: [[Correlation effects in the non-linear response|Correlation effects in the non-linear response ]]
|-
|}

Real time approach to non-linear response (SHG)

2025-09-27T08:39:40Z

Attacc: /* How to choose the external field direction for the different X2 */

== Second Harmonic Generation in AlAs ==
In this tutorial, we will calculate the second harmonic generation of bulk AlAs, the Yambo databases can be downloaded here: [https://media.yambo-code.eu/educational/tutorials/files/AlAs_DBs.tar.gz AlAs_DBs.tar.gz] (10 MB). The first steps of this tutorials are the same as the one on [http://www.yambo-code.eu/wiki/index.php?title=Prerequisites_for_Real_Time_propagation_with_Yambo Prerequisites for Real-Time propagation with Yambo] with the only difference that we will work on AlAs and we will consider an external field in the direction <code> 1.000000 | 1.000000 | 0.000000 |</code>. The DFT input are available here: [https://media.yambo-code.eu/educational/tutorials/files/AlAs_abinit.tar.gz ABINIT] or [https://media.yambo-code.eu/educational/tutorials/files/AlAs_pwscf.tar.gz QuantumEspresso].
You can run the DFT calculation with ABINIT with the command:

abinit < AlAs.in > output_AlAs

or using QuantumEspresso:

pw.x -inp AlAs.scf.in > output_scf
pw.x -inp AlAs.nscf.in > output_scf

and then import the ABINIT wave-function with the command:

a2y -F AlAso_DS2_WFK.nc

and the QuantumEspresso one, in the folder AlAs.save with the command:

p2y
Now we consider an external field in the <code>[1,1,0]</code> direction and remove symmetries not compatible with this field, as explained in the tutorial [http://www.yambo-code.eu/wiki/index.php?title=Prerequisites_for_Real_Time_propagation_with_Yambo Prerequisites for Real-Time propagation with Yambo].

==Real-time simulation for the SHG==

You can generate the input file with the command <code>yambo_nl -u n</code>:

nloptics # [R NL] Non-linear optics
% NLBands
 3 | 6 | # [NL] Bands
%
NLstep= 0.0100 fs # [NL] Real Time step length
NLverbosity= "high" # [NL] Verbosity level (low | high)
NLtime=-1.000000 fs # [NL] Simulation Time
NLintegrator= "INVINT" # [NL] Integrator ("EULEREXP/RK4/RK2EXP/HEUN/INVINT/CRANKNIC")
NLCorrelation= "IPA" # [NL] Correlation ("IPA/HARTREE/TDDFT/LRC/JGM/SEX/HF")
NLLrcAlpha= 0.000000 # [NL] Long Range Correction
% NLEnRange
 1.000000 | 5.000000 | eV # [NL] Energy range
%
NLEnSteps= 5 # [NL] Energy steps
NLDamping= 0.150000 eV # [NL] Damping
% Field1_Dir
 1.000000 | 1.000000 | 0.000000 | # [RT Field1] Versor
Field1_kind= "SOFTSIN" # [NL ExtF] Kind(SIN|SOFTSIN|RES|ANTIRES|GAUSS|DELTA|QSSIN)

The line <code>|1.000000 | 1.000000 | 0.000000 | # [RT Field1] Versor</code> referees to the direction of the external field (x,y,0). At present only an external field is present but the code can be easily generalized to deal with more fields.
The default parameters of Yambo/Lumen are already tuned for second-harmonic generation, so the only thing you have to change is the band range, between 3 and 6 and the energy range between 1.0-5.0 eV and the number of energy steps in this interval that we set to 10. Notice that you cannot set to zero the lowest value of the energy range because this will requires a simulation that lasts infinite time, see below. Finally, consider that Yambo performs a separate calculation for each frequency, so if you set many energy steps the computational time grows linearly with this number.
Notice that we set <code>NLverbosity= "high"</code> in this way the code will produce a file for each laser frequency containing the time dependent polarization.
Run <code>yambo_nl</code>. Calculations will take about fifteen minutes on a single processor PC, you have time to study the next section that explains how non-linear response is extracted from the real-time simulations.
In order to speed up calculations, you can run them in parallel.

==Non-linear response with Yambo==

In order to calculate the non-linear response, the system is excited with different laser fields with a sinusoidal shape at frequencies <math>\omega_1, \omega_2, .... , \omega_n </math> determined by the parameters [[Variables#NLEnRangev|NLEnRange]] and [[Variables#NLEnSteps|NLEnSteps]]. A dephasing term is added to the Hamiltonian <math>\gamma = </math>[[Variables#NLDamping|NLDamping]] to simulate a finite broadening and to remove the eigenmodes that are excited by the sudden turning on of the external field. After the dephasing time the outgoing signal is analyzed to extract the non-linear coefficients as shown in the figure below:

[[File:Pt analysis.png|600px|center|Non-linear response analysis]]

In the report file <code>r_nlinear</code> you will find the length of the dephasing part and of the sampling one:

Dephasing Time [fs]: 52.65695
Sampling Time [fs]: 4.18566
Total simulation time [fs]: 56.84262
The length of the dephasing interval is inversely proportional to the damping term <math>T_{depth} \simeq 1/\gamma</math> while the length of the sampling is dictated by the smallest frequency we are interested in: <math>T_{samp} \simeq 1/\omega_1 </math>. For this reason if <math> \omega_1=0 </math> or <math> \gamma = 0 </math> simulation time goes to infinity. The response at zero frequency can be calculated as limit of small frequency perturbation.
You can have a look to the file <code>src/nloptics/NL_initialize.F</code> to see how simulation lengths are defined.
Calculations can take some time, run them in parallel, the best number of processors = number of frequencies or reduce the number of frequencies step in the SHG.

==Analysis of the results==

In the sampling region we suppose that the polarization can be written as: <math>\bf{P}(t) = \sum_{n=-\infty}^{+\infty} \bf{p}_n e^{-i\omega_n t} </math> where the coefficient <math>\bf{p}_1,...,\bf{p}_n </math> are related to <math>\chi^{(1)},...,\chi^{(n)} </math>. We sample the polarization signal at different times and invert the previous equation by truncating the sum at a finite order <ref>[https://arxiv.org/abs/1309.4012 Nonlinear optics from an ab initio approach by means of the dynamical Berry phase: Application to second- and third-harmonic generation in semiconductors], C. Attaccalite and M. Grüning, Phys. Rev. B 88, 235113(2013)</ref>.
This is done with the command <code>ypp_nl -u</code> that automatically produce an input with the correct values:

nonlinear # [R] NonLinear Optics Post-Processing
Xorder= 4 # Max order of the response functions
% TimeRange
52.65695 | -1.00000 | fs # Time-window where processing is done
%
ETStpsRt= 200 # Total Energy steps
% EnRngeRt
0.00000 | 10.00000 | eV # Energy range
%
DampMode= "NONE" # Damping type ( NONE | LORENTZIAN | GAUSSIAN )
DampFactor= 0.10000 eV # Damping parameter

where <code>Xorder</code> is the order where the previous sum is truncated, and the TimeRange specifies the sampling region. Notice that differently from the first tutorial, in this case, we do not need Damping in <code>ypp_nl</code> because we already included it in the real-time dynamics. Run <code>ypp_nl</code> and it will produce a file called <code>o.YPP-X_probe_order_2</code>. This file contains the different components of <math>\chi^2_{xy*} </math> and in particular the columns 6 and 7 correspond to the imaginary and real part of <math>\chi^2_{xyz} </math>. You can plot the result with gnuplot and the command:

p 'o.YPP-X_probe_order_2' u 1:(sqrt($6**2+$7**2)) w lp ps 1.5 pt 7 lw 1.5

the result should look like

[[File:AlAs results.png|700px|center|SHG in AlAs]]

and compare it with the <math> \chi^2_{zxy} </math> calculated with more frequencies and with the converged result on a <math> 18x18x18</math> k-point grid and bands between 2 and 10. In the figure you can find also the comparison with the results of Ref. <ref>Luppi et al. [https://arxiv.org/abs/1006.2649 PRB B, '''82''', 235201(2010)]</ref>.
Notice that the QuantumEspresso results are slightly different from the Abinit ones. This is due to the different pseudo-potential employed in the calculations if pseudopotentials were the same calculation would have been identical. You can download the script to generate this plot and the converged results [http://www.attaccalite.com/lumen/tutorials/AlAs/AlAs_results.tgz here].

'''Notice that''' : the following parameters are not used in the non-linear response analysis: <code> EnRngeRt</code>, <code>ETStpsRt</code>, <code>DampMode</code>, <code>DampFactor</code>. The damping factor is set directly in the real-time simulation.

'''System of units in Non-linear Optics''': notice that in Yambo the non-linear response functions are in the gaussian system of units, for example the <math> \chi^2 (\omega) </math> is in cm/statvolt. In order to convert the non-linear coefficients between different system of units, you can have a look at the [https://www.attaccalite.com/tutorials_yambo/Appendix_C_Boyd.pdf Appendix C] of the book [https://www.elsevier.com/books/nonlinear-optics/boyd/978-0-12-369470-6 "Non-linear optics" by Robert W. Boyd].

More tutorials on non-linear response (Third harmonic generation, parallelization, spin-orbit etc..) with Yambo can be found here: [http://www.attaccalite.com/lumen/tutorials.html More Tutorials]. 

==Analysis of the results using YamboPy==
The analysis of the result performed in the previous section using <code>ypp_nl</code> can be performed using python script [https://github.com/yambo-code/yambopy YamboPy]. 
In YamboPy we implemented all necessary functions to reads the Yambo databases and post-process the results. Here we show how to get the SHG signal from the previous
simulations. We suppose you correctly installed <code>YamboPy</code> on your PC. Go in the folder where you ran non-linear calculation and type in the python:
 
from yambopy import *
NLDB=YamboNLDB()
pol =NLDB.Polarization[0]
time=NLDB.IO_TIME_points

in this way you read all the Non-linear databases. If your runs are in a different folder then the 'SAVE' one you can specify it using the command:
NLDB=YamboNLDB(calc='MYJOB')

now in the array <code>pol</code> you have all the polarization for all laser frequencies in the three Cartesian directions, while the variable <code>time</code> contains all the time series of your simulation.
Now you can get the non-linear response with the command:

Harmonic_Analysis(NLDB,X_order=4)

this command will perform a Fourier analysis of the results in the same way of <code>ypp_nl</code> and generate new files with all the requested harmonics ''o.YamboPy-X_probe_order_1'', ''o.YamboPy-X_probe_order_2'' etc...
equivalent to the one generated by <code>ypp_nl</code>. Results can be plot with gnuplot using the command:

p 'o.YamboPy-X_probe_order_2' u 1:(sqrt($6**2+$7**2)) w lp ps 1.5 pt 7 lw 1.5

The script that performs non-linear analysis can be found in <code>yambopy/nl/harmonic_analysis.py</code>. We strongly advice you to have a look to this script and modify it according
to your needs and in order to extract other non-linear response functions.

==How to choose the external field direction for the different X2==

In the X2abc response you have three field directions. The two components ''b'' and ''c'' are determined by the external field and the third ''a''
is the direction where you measure the response. 

The external field in Yambo is set using the variable
% Field1_Dir
1.000000 | 0.000000 | 0.000000 | # [NL ExtF] Versor .
%

For example if you set in Yambo field direction as:

1.0 | 0.0 | 0.0 | ---> you calculate all components X2*xx
0.0 | 1.0 | 0.0 | ---> you calculate all components X2*yy
0.0 | 0.0 | 1.0 | ---> you calculate all components X2*zz

the * correspond to the different direction in the response file <code>o.YPP-X_probe_order_2</code>.
In the <code>o.YPP-X_probe_order_2</code> you have seven columns:

The first column is the energy [[omega]],
the 2nd and 3rd columns are the imaginary and real part of X2x**
the 4th and 5th columns are the imaginary and real part of X2y**
the 6th and 7th columns are the imaginary and real part of X2z**

where the ** are the direction of the incoming field, see above.

For example if you want to calculate the <math>\chi^{(2)}_{zxx}</math> you put the external field in the direction <code> 1.0 | 0.0 | 0.0 |</code>
and then plot the column 6 and 7 of the <code>o.YPP-X_probe_order_2</code> file. 

'''Nota bene:''' if you change the direction of the external field you have to remove the corresponding symmetries as explained in the tutorial
on [[Prerequisites for Real Time_propagation with Yambo#Reduce symmetries real-time linear response tutorial]].

In order to get the other components of the X2 the calculation are more involved. For example if you put field in the

1.0 | 1.0 | 0.0 |

this corresponds to <math>E(t)=\frac{1}{\sqrt{2}} [ E_x(t) + E_y(t) ]</math> and so at the second order you will have <math>E^2(t)=\frac{1}{2} [ E^2_x(t) + E^2_y(t) + E_x(t) E_y(t) + E_y(t) E_x(t) ]</math> 
this means that the X2 in the <code>o.YPP-X_probe_order_2</code> will correspond to a linear combination of the following different response functions. 
For example in the the 2nd and 3rd columns are the imaginary and real part of: 

<math>\chi^{(2)}_{x**}=\frac{1}{2} \left [\chi^2_{xxx}+\chi^{(2)}_{xyy} + \chi^{(2)}_{xxy} + \chi^{(2)}_{xyx} \right ]</math>

the same for the other column replacing the first <code>x</code> for <code>y,z</code>.
If you know that some components are zero this allow you to extract the corresponding off-diagonal part of <math>\chi^{(2)}_{abc}</math> otherwise you have to perform different calculations to get the component you are interested in. Hereafter we present a simple example of monolayer hBN (m-hBN). In m-hBN there is only a non-zero component of the $\chi^2$ and all the others are related by symmetry: 
<math>\chi^{(2)}_{yyy}=-\chi^{(2)}_{yxx}=-\chi^{(2)}_{xxy}=-\chi^{(2)}_{xyx}</math> 
so if you put the field in the <code>|1|1|0|</code> direction you will get:
<math>\chi^{(2)}_{x**} = \frac{1}{2} \left[\chi^{(2)}_{xxy} + \chi^{(2)}_{xyx} \right] = - \chi^{(2)}_{yyy} </math>
<math>\chi^{(2)}_{y**} =-\chi^{(2)}_{yxx}=-\chi^{(2)}_{xxy}=-\chi^{(2)}_{xyx}</math>

==Non-linear response of low-dimensional structures: 2D or 1D ==

The Yambo code is a 3D periodic code, so when you want to study a low-dimensional system 2D or 1D, you have to use a supercell approach.
For example to simulate the non-linear response in a 2D-crystal one, can put the crystal in the xy plane and choose a larger distance in the z-direction
in order to reduce the interaction between the periodic replica. Clearly in this case k-point sampling will be only in the x,y directions.
For calculations on this type of systems, these two warnings must be taken into account:

* if you calculate GW corrections or include electron-hole interaction in the linear/non-linear response it is a good idea to use a '''Coulomb cutoff''', similar to the 2D BSE case [http://www.yambo-code.org/wiki/index.php?title=How_to_treat_low_dimensional_systems How to treat low dimensional systems]. You can add the cutoff just adding the "-r" in the input generation.

* the calculation of SHG and THG are always performed respect to the supercell, therefore you have to '''re-scale''' the result to the effective thickness of the layer, usually the inter-layer distance of the corresponding bulk material for 2D systems: <math>\chi_{rescaled}(\omega) = L_z/d_{eff} \cdot \chi(\omega) </math> where <math>L_z</math> is the z-dimension of the supercell, and <math>d_{eff}</math> is the effective thickness of the 2D system.

'''Nota bene''': Non-linear response along non-periodic directions is not implemented in Yambo, the code will print zero in these directions for all response functions. We plan to implement it in a future version of the code.

==References==
<references />

==Links for schools==
* Back to [[Rome 2023#Tutorials]]
* Back to [[ICTP2020]]

 
{| style="width:100%" border="1"
|style="width:25%; text-align:left"|Prev: [[Linear response from real time simulations|Linear response from real time simulations]]
|style="width:45%; text-align:center"|Now: [[ICTP2020|ICTP Tutorials]] --> [[Real time approach to non-linear response|Non Linear Response]]
|style="width:50%; text-align:left"|Next: [[Correlation effects in the non-linear response|Correlation effects in the non-linear response ]]
|-
|}

Real time approach to non-linear response (SHG)

2025-09-27T08:38:47Z

Attacc: /* How to choose the external field direction for the different X2 */

== Second Harmonic Generation in AlAs ==
In this tutorial, we will calculate the second harmonic generation of bulk AlAs, the Yambo databases can be downloaded here: [https://media.yambo-code.eu/educational/tutorials/files/AlAs_DBs.tar.gz AlAs_DBs.tar.gz] (10 MB). The first steps of this tutorials are the same as the one on [http://www.yambo-code.eu/wiki/index.php?title=Prerequisites_for_Real_Time_propagation_with_Yambo Prerequisites for Real-Time propagation with Yambo] with the only difference that we will work on AlAs and we will consider an external field in the direction <code> 1.000000 | 1.000000 | 0.000000 |</code>. The DFT input are available here: [https://media.yambo-code.eu/educational/tutorials/files/AlAs_abinit.tar.gz ABINIT] or [https://media.yambo-code.eu/educational/tutorials/files/AlAs_pwscf.tar.gz QuantumEspresso].
You can run the DFT calculation with ABINIT with the command:

abinit < AlAs.in > output_AlAs

or using QuantumEspresso:

pw.x -inp AlAs.scf.in > output_scf
pw.x -inp AlAs.nscf.in > output_scf

and then import the ABINIT wave-function with the command:

a2y -F AlAso_DS2_WFK.nc

and the QuantumEspresso one, in the folder AlAs.save with the command:

p2y
Now we consider an external field in the <code>[1,1,0]</code> direction and remove symmetries not compatible with this field, as explained in the tutorial [http://www.yambo-code.eu/wiki/index.php?title=Prerequisites_for_Real_Time_propagation_with_Yambo Prerequisites for Real-Time propagation with Yambo].

==Real-time simulation for the SHG==

You can generate the input file with the command <code>yambo_nl -u n</code>:

nloptics # [R NL] Non-linear optics
% NLBands
 3 | 6 | # [NL] Bands
%
NLstep= 0.0100 fs # [NL] Real Time step length
NLverbosity= "high" # [NL] Verbosity level (low | high)
NLtime=-1.000000 fs # [NL] Simulation Time
NLintegrator= "INVINT" # [NL] Integrator ("EULEREXP/RK4/RK2EXP/HEUN/INVINT/CRANKNIC")
NLCorrelation= "IPA" # [NL] Correlation ("IPA/HARTREE/TDDFT/LRC/JGM/SEX/HF")
NLLrcAlpha= 0.000000 # [NL] Long Range Correction
% NLEnRange
 1.000000 | 5.000000 | eV # [NL] Energy range
%
NLEnSteps= 5 # [NL] Energy steps
NLDamping= 0.150000 eV # [NL] Damping
% Field1_Dir
 1.000000 | 1.000000 | 0.000000 | # [RT Field1] Versor
Field1_kind= "SOFTSIN" # [NL ExtF] Kind(SIN|SOFTSIN|RES|ANTIRES|GAUSS|DELTA|QSSIN)

The line <code>|1.000000 | 1.000000 | 0.000000 | # [RT Field1] Versor</code> referees to the direction of the external field (x,y,0). At present only an external field is present but the code can be easily generalized to deal with more fields.
The default parameters of Yambo/Lumen are already tuned for second-harmonic generation, so the only thing you have to change is the band range, between 3 and 6 and the energy range between 1.0-5.0 eV and the number of energy steps in this interval that we set to 10. Notice that you cannot set to zero the lowest value of the energy range because this will requires a simulation that lasts infinite time, see below. Finally, consider that Yambo performs a separate calculation for each frequency, so if you set many energy steps the computational time grows linearly with this number.
Notice that we set <code>NLverbosity= "high"</code> in this way the code will produce a file for each laser frequency containing the time dependent polarization.
Run <code>yambo_nl</code>. Calculations will take about fifteen minutes on a single processor PC, you have time to study the next section that explains how non-linear response is extracted from the real-time simulations.
In order to speed up calculations, you can run them in parallel.

==Non-linear response with Yambo==

In order to calculate the non-linear response, the system is excited with different laser fields with a sinusoidal shape at frequencies <math>\omega_1, \omega_2, .... , \omega_n </math> determined by the parameters [[Variables#NLEnRangev|NLEnRange]] and [[Variables#NLEnSteps|NLEnSteps]]. A dephasing term is added to the Hamiltonian <math>\gamma = </math>[[Variables#NLDamping|NLDamping]] to simulate a finite broadening and to remove the eigenmodes that are excited by the sudden turning on of the external field. After the dephasing time the outgoing signal is analyzed to extract the non-linear coefficients as shown in the figure below:

[[File:Pt analysis.png|600px|center|Non-linear response analysis]]

In the report file <code>r_nlinear</code> you will find the length of the dephasing part and of the sampling one:

Dephasing Time [fs]: 52.65695
Sampling Time [fs]: 4.18566
Total simulation time [fs]: 56.84262
The length of the dephasing interval is inversely proportional to the damping term <math>T_{depth} \simeq 1/\gamma</math> while the length of the sampling is dictated by the smallest frequency we are interested in: <math>T_{samp} \simeq 1/\omega_1 </math>. For this reason if <math> \omega_1=0 </math> or <math> \gamma = 0 </math> simulation time goes to infinity. The response at zero frequency can be calculated as limit of small frequency perturbation.
You can have a look to the file <code>src/nloptics/NL_initialize.F</code> to see how simulation lengths are defined.
Calculations can take some time, run them in parallel, the best number of processors = number of frequencies or reduce the number of frequencies step in the SHG.

==Analysis of the results==

In the sampling region we suppose that the polarization can be written as: <math>\bf{P}(t) = \sum_{n=-\infty}^{+\infty} \bf{p}_n e^{-i\omega_n t} </math> where the coefficient <math>\bf{p}_1,...,\bf{p}_n </math> are related to <math>\chi^{(1)},...,\chi^{(n)} </math>. We sample the polarization signal at different times and invert the previous equation by truncating the sum at a finite order <ref>[https://arxiv.org/abs/1309.4012 Nonlinear optics from an ab initio approach by means of the dynamical Berry phase: Application to second- and third-harmonic generation in semiconductors], C. Attaccalite and M. Grüning, Phys. Rev. B 88, 235113(2013)</ref>.
This is done with the command <code>ypp_nl -u</code> that automatically produce an input with the correct values:

nonlinear # [R] NonLinear Optics Post-Processing
Xorder= 4 # Max order of the response functions
% TimeRange
52.65695 | -1.00000 | fs # Time-window where processing is done
%
ETStpsRt= 200 # Total Energy steps
% EnRngeRt
0.00000 | 10.00000 | eV # Energy range
%
DampMode= "NONE" # Damping type ( NONE | LORENTZIAN | GAUSSIAN )
DampFactor= 0.10000 eV # Damping parameter

where <code>Xorder</code> is the order where the previous sum is truncated, and the TimeRange specifies the sampling region. Notice that differently from the first tutorial, in this case, we do not need Damping in <code>ypp_nl</code> because we already included it in the real-time dynamics. Run <code>ypp_nl</code> and it will produce a file called <code>o.YPP-X_probe_order_2</code>. This file contains the different components of <math>\chi^2_{xy*} </math> and in particular the columns 6 and 7 correspond to the imaginary and real part of <math>\chi^2_{xyz} </math>. You can plot the result with gnuplot and the command:

p 'o.YPP-X_probe_order_2' u 1:(sqrt($6**2+$7**2)) w lp ps 1.5 pt 7 lw 1.5

the result should look like

[[File:AlAs results.png|700px|center|SHG in AlAs]]

and compare it with the <math> \chi^2_{zxy} </math> calculated with more frequencies and with the converged result on a <math> 18x18x18</math> k-point grid and bands between 2 and 10. In the figure you can find also the comparison with the results of Ref. <ref>Luppi et al. [https://arxiv.org/abs/1006.2649 PRB B, '''82''', 235201(2010)]</ref>.
Notice that the QuantumEspresso results are slightly different from the Abinit ones. This is due to the different pseudo-potential employed in the calculations if pseudopotentials were the same calculation would have been identical. You can download the script to generate this plot and the converged results [http://www.attaccalite.com/lumen/tutorials/AlAs/AlAs_results.tgz here].

'''Notice that''' : the following parameters are not used in the non-linear response analysis: <code> EnRngeRt</code>, <code>ETStpsRt</code>, <code>DampMode</code>, <code>DampFactor</code>. The damping factor is set directly in the real-time simulation.

'''System of units in Non-linear Optics''': notice that in Yambo the non-linear response functions are in the gaussian system of units, for example the <math> \chi^2 (\omega) </math> is in cm/statvolt. In order to convert the non-linear coefficients between different system of units, you can have a look at the [https://www.attaccalite.com/tutorials_yambo/Appendix_C_Boyd.pdf Appendix C] of the book [https://www.elsevier.com/books/nonlinear-optics/boyd/978-0-12-369470-6 "Non-linear optics" by Robert W. Boyd].

More tutorials on non-linear response (Third harmonic generation, parallelization, spin-orbit etc..) with Yambo can be found here: [http://www.attaccalite.com/lumen/tutorials.html More Tutorials]. 

==Analysis of the results using YamboPy==
The analysis of the result performed in the previous section using <code>ypp_nl</code> can be performed using python script [https://github.com/yambo-code/yambopy YamboPy]. 
In YamboPy we implemented all necessary functions to reads the Yambo databases and post-process the results. Here we show how to get the SHG signal from the previous
simulations. We suppose you correctly installed <code>YamboPy</code> on your PC. Go in the folder where you ran non-linear calculation and type in the python:
 
from yambopy import *
NLDB=YamboNLDB()
pol =NLDB.Polarization[0]
time=NLDB.IO_TIME_points

in this way you read all the Non-linear databases. If your runs are in a different folder then the 'SAVE' one you can specify it using the command:
NLDB=YamboNLDB(calc='MYJOB')

now in the array <code>pol</code> you have all the polarization for all laser frequencies in the three Cartesian directions, while the variable <code>time</code> contains all the time series of your simulation.
Now you can get the non-linear response with the command:

Harmonic_Analysis(NLDB,X_order=4)

this command will perform a Fourier analysis of the results in the same way of <code>ypp_nl</code> and generate new files with all the requested harmonics ''o.YamboPy-X_probe_order_1'', ''o.YamboPy-X_probe_order_2'' etc...
equivalent to the one generated by <code>ypp_nl</code>. Results can be plot with gnuplot using the command:

p 'o.YamboPy-X_probe_order_2' u 1:(sqrt($6**2+$7**2)) w lp ps 1.5 pt 7 lw 1.5

The script that performs non-linear analysis can be found in <code>yambopy/nl/harmonic_analysis.py</code>. We strongly advice you to have a look to this script and modify it according
to your needs and in order to extract other non-linear response functions.

==How to choose the external field direction for the different X2==

In the X2abc response you have three field directions. The two components ''b'' and ''c'' are determined by the external field and the third ''a''
is the direction where you measure the response. 

The external field in Yambo is set using the variable
% Field1_Dir
1.000000 | 0.000000 | 0.000000 | # [NL ExtF] Versor .
%

For example if you set in Yambo field direction as:

1.0 | 0.0 | 0.0 | ---> you calculate all components X2*xx
0.0 | 1.0 | 0.0 | ---> you calculate all components X2*yy
0.0 | 0.0 | 1.0 | ---> you calculate all components X2*zz

the * correspond to the different direction in the response file <code>o.YPP-X_probe_order_2</code>.
In the <code>o.YPP-X_probe_order_2</code> you have seven columns:

The first column is the energy [[omega]],
the 2nd and 3rd columns are the imaginary and real part of X2x**
the 4th and 5th columns are the imaginary and real part of X2y**
the 6th and 7th columns are the imaginary and real part of X2z**

where the ** are the direction of the incoming field, see above.

For example if you want to calculate the <math>\chi^{(2)}_{zxx}</math> you put the external field in the direction <code> 1.0 | 0.0 | 0.0 |</code>
and then plot the column 6 and 7 of the <code>o.YPP-X_probe_order_2</code> file. 

'''Nota bene:''' if you change the direction of the external field you have to remove the corresponding symmetries as explained in the tutorial
on [[Prerequisites for Real Time_propagation with Yambo#Reduce symmetries real-time linear response tutorial]].

In order to get the other components of the X2 the calculation are more involved. For example if you put field in the

1.0 | 1.0 | 0.0 |

this corresponds to <math>E(t)=\frac{1}{\sqrt{2}} [ E_x(t) + E_y(t) ]</math> and so at the second order you will have <math>E^2(t)=\frac{1}{2} [ E^2_x(t) + E^2_y(t) + E_x(t) E_y(t) + E_y(t) E_x(t) ]</math> 
this means that the X2 in the <code>o.YPP-X_probe_order_2</code> will correspond to a linear combination of the following different response functions. 
For example in the the 2nd and 3rd columns are the imaginary and real part of: 

<math>\chi^{(2)}_{x**}=\frac{1}{2} \left [\chi^2_{xxx}+\chi^{(2)}_{xyy} + \chi^{(2)}_{xxy} + \chi^{(2)}_{xyx} \right ]</math>

the same for the other column replacing the first <code>x</code> for <code>y,z</code>.
If you know that some components are zero this allow you to extract the corresponding off-diagonal part of <math>\chi^{(2)}_{abc}</math> otherwise you have to perform different calculations to get the component you are interested in. Hereafter we present a simple example of monolayer hBN (m-hBN). In m-hBN there is only a non-zero component of the $\chi^2$ and all the others are related by symmetry: 
<math>\chi^{(2)}_{yyy}=-\chi^{(2)}_{yxx}=-\chi^{(2)}_{xxy}=-\chi^{(2)}_{xyx}</math>
so if you put the field in the <code>|1|1|0|</code> direction you will get:
<math>\chi^{(2)}_{x**} = \frac{1}{2} \left[\chi^{(2)}_{xxy} + \chi^{(2)}_{xyx} \left] = - \chi^{(2)}_{yyy} </math>
<math>\chi^{(2)}_{y**} =-\chi^{(2)}_{yxx}=-\chi^{(2)}_{xxy}=-\chi^{(2)}_{xyx}</math>

==Non-linear response of low-dimensional structures: 2D or 1D ==

The Yambo code is a 3D periodic code, so when you want to study a low-dimensional system 2D or 1D, you have to use a supercell approach.
For example to simulate the non-linear response in a 2D-crystal one, can put the crystal in the xy plane and choose a larger distance in the z-direction
in order to reduce the interaction between the periodic replica. Clearly in this case k-point sampling will be only in the x,y directions.
For calculations on this type of systems, these two warnings must be taken into account:

* if you calculate GW corrections or include electron-hole interaction in the linear/non-linear response it is a good idea to use a '''Coulomb cutoff''', similar to the 2D BSE case [http://www.yambo-code.org/wiki/index.php?title=How_to_treat_low_dimensional_systems How to treat low dimensional systems]. You can add the cutoff just adding the "-r" in the input generation.

* the calculation of SHG and THG are always performed respect to the supercell, therefore you have to '''re-scale''' the result to the effective thickness of the layer, usually the inter-layer distance of the corresponding bulk material for 2D systems: <math>\chi_{rescaled}(\omega) = L_z/d_{eff} \cdot \chi(\omega) </math> where <math>L_z</math> is the z-dimension of the supercell, and <math>d_{eff}</math> is the effective thickness of the 2D system.

'''Nota bene''': Non-linear response along non-periodic directions is not implemented in Yambo, the code will print zero in these directions for all response functions. We plan to implement it in a future version of the code.

==References==
<references />

==Links for schools==
* Back to [[Rome 2023#Tutorials]]
* Back to [[ICTP2020]]

 
{| style="width:100%" border="1"
|style="width:25%; text-align:left"|Prev: [[Linear response from real time simulations|Linear response from real time simulations]]
|style="width:45%; text-align:center"|Now: [[ICTP2020|ICTP Tutorials]] --> [[Real time approach to non-linear response|Non Linear Response]]
|style="width:50%; text-align:left"|Next: [[Correlation effects in the non-linear response|Correlation effects in the non-linear response ]]
|-
|}

Real time approach to non-linear response (SHG)

2025-09-27T08:36:08Z

Attacc: /* How to choose the external field direction for the different X2 */

== Second Harmonic Generation in AlAs ==
In this tutorial, we will calculate the second harmonic generation of bulk AlAs, the Yambo databases can be downloaded here: [https://media.yambo-code.eu/educational/tutorials/files/AlAs_DBs.tar.gz AlAs_DBs.tar.gz] (10 MB). The first steps of this tutorials are the same as the one on [http://www.yambo-code.eu/wiki/index.php?title=Prerequisites_for_Real_Time_propagation_with_Yambo Prerequisites for Real-Time propagation with Yambo] with the only difference that we will work on AlAs and we will consider an external field in the direction <code> 1.000000 | 1.000000 | 0.000000 |</code>. The DFT input are available here: [https://media.yambo-code.eu/educational/tutorials/files/AlAs_abinit.tar.gz ABINIT] or [https://media.yambo-code.eu/educational/tutorials/files/AlAs_pwscf.tar.gz QuantumEspresso].
You can run the DFT calculation with ABINIT with the command:

abinit < AlAs.in > output_AlAs

or using QuantumEspresso:

pw.x -inp AlAs.scf.in > output_scf
pw.x -inp AlAs.nscf.in > output_scf

and then import the ABINIT wave-function with the command:

a2y -F AlAso_DS2_WFK.nc

and the QuantumEspresso one, in the folder AlAs.save with the command:

p2y
Now we consider an external field in the <code>[1,1,0]</code> direction and remove symmetries not compatible with this field, as explained in the tutorial [http://www.yambo-code.eu/wiki/index.php?title=Prerequisites_for_Real_Time_propagation_with_Yambo Prerequisites for Real-Time propagation with Yambo].

==Real-time simulation for the SHG==

You can generate the input file with the command <code>yambo_nl -u n</code>:

nloptics # [R NL] Non-linear optics
% NLBands
 3 | 6 | # [NL] Bands
%
NLstep= 0.0100 fs # [NL] Real Time step length
NLverbosity= "high" # [NL] Verbosity level (low | high)
NLtime=-1.000000 fs # [NL] Simulation Time
NLintegrator= "INVINT" # [NL] Integrator ("EULEREXP/RK4/RK2EXP/HEUN/INVINT/CRANKNIC")
NLCorrelation= "IPA" # [NL] Correlation ("IPA/HARTREE/TDDFT/LRC/JGM/SEX/HF")
NLLrcAlpha= 0.000000 # [NL] Long Range Correction
% NLEnRange
 1.000000 | 5.000000 | eV # [NL] Energy range
%
NLEnSteps= 5 # [NL] Energy steps
NLDamping= 0.150000 eV # [NL] Damping
% Field1_Dir
 1.000000 | 1.000000 | 0.000000 | # [RT Field1] Versor
Field1_kind= "SOFTSIN" # [NL ExtF] Kind(SIN|SOFTSIN|RES|ANTIRES|GAUSS|DELTA|QSSIN)

The line <code>|1.000000 | 1.000000 | 0.000000 | # [RT Field1] Versor</code> referees to the direction of the external field (x,y,0). At present only an external field is present but the code can be easily generalized to deal with more fields.
The default parameters of Yambo/Lumen are already tuned for second-harmonic generation, so the only thing you have to change is the band range, between 3 and 6 and the energy range between 1.0-5.0 eV and the number of energy steps in this interval that we set to 10. Notice that you cannot set to zero the lowest value of the energy range because this will requires a simulation that lasts infinite time, see below. Finally, consider that Yambo performs a separate calculation for each frequency, so if you set many energy steps the computational time grows linearly with this number.
Notice that we set <code>NLverbosity= "high"</code> in this way the code will produce a file for each laser frequency containing the time dependent polarization.
Run <code>yambo_nl</code>. Calculations will take about fifteen minutes on a single processor PC, you have time to study the next section that explains how non-linear response is extracted from the real-time simulations.
In order to speed up calculations, you can run them in parallel.

==Non-linear response with Yambo==

In order to calculate the non-linear response, the system is excited with different laser fields with a sinusoidal shape at frequencies <math>\omega_1, \omega_2, .... , \omega_n </math> determined by the parameters [[Variables#NLEnRangev|NLEnRange]] and [[Variables#NLEnSteps|NLEnSteps]]. A dephasing term is added to the Hamiltonian <math>\gamma = </math>[[Variables#NLDamping|NLDamping]] to simulate a finite broadening and to remove the eigenmodes that are excited by the sudden turning on of the external field. After the dephasing time the outgoing signal is analyzed to extract the non-linear coefficients as shown in the figure below:

[[File:Pt analysis.png|600px|center|Non-linear response analysis]]

In the report file <code>r_nlinear</code> you will find the length of the dephasing part and of the sampling one:

Dephasing Time [fs]: 52.65695
Sampling Time [fs]: 4.18566
Total simulation time [fs]: 56.84262
The length of the dephasing interval is inversely proportional to the damping term <math>T_{depth} \simeq 1/\gamma</math> while the length of the sampling is dictated by the smallest frequency we are interested in: <math>T_{samp} \simeq 1/\omega_1 </math>. For this reason if <math> \omega_1=0 </math> or <math> \gamma = 0 </math> simulation time goes to infinity. The response at zero frequency can be calculated as limit of small frequency perturbation.
You can have a look to the file <code>src/nloptics/NL_initialize.F</code> to see how simulation lengths are defined.
Calculations can take some time, run them in parallel, the best number of processors = number of frequencies or reduce the number of frequencies step in the SHG.

==Analysis of the results==

In the sampling region we suppose that the polarization can be written as: <math>\bf{P}(t) = \sum_{n=-\infty}^{+\infty} \bf{p}_n e^{-i\omega_n t} </math> where the coefficient <math>\bf{p}_1,...,\bf{p}_n </math> are related to <math>\chi^{(1)},...,\chi^{(n)} </math>. We sample the polarization signal at different times and invert the previous equation by truncating the sum at a finite order <ref>[https://arxiv.org/abs/1309.4012 Nonlinear optics from an ab initio approach by means of the dynamical Berry phase: Application to second- and third-harmonic generation in semiconductors], C. Attaccalite and M. Grüning, Phys. Rev. B 88, 235113(2013)</ref>.
This is done with the command <code>ypp_nl -u</code> that automatically produce an input with the correct values:

nonlinear # [R] NonLinear Optics Post-Processing
Xorder= 4 # Max order of the response functions
% TimeRange
52.65695 | -1.00000 | fs # Time-window where processing is done
%
ETStpsRt= 200 # Total Energy steps
% EnRngeRt
0.00000 | 10.00000 | eV # Energy range
%
DampMode= "NONE" # Damping type ( NONE | LORENTZIAN | GAUSSIAN )
DampFactor= 0.10000 eV # Damping parameter

where <code>Xorder</code> is the order where the previous sum is truncated, and the TimeRange specifies the sampling region. Notice that differently from the first tutorial, in this case, we do not need Damping in <code>ypp_nl</code> because we already included it in the real-time dynamics. Run <code>ypp_nl</code> and it will produce a file called <code>o.YPP-X_probe_order_2</code>. This file contains the different components of <math>\chi^2_{xy*} </math> and in particular the columns 6 and 7 correspond to the imaginary and real part of <math>\chi^2_{xyz} </math>. You can plot the result with gnuplot and the command:

p 'o.YPP-X_probe_order_2' u 1:(sqrt($6**2+$7**2)) w lp ps 1.5 pt 7 lw 1.5

the result should look like

[[File:AlAs results.png|700px|center|SHG in AlAs]]

and compare it with the <math> \chi^2_{zxy} </math> calculated with more frequencies and with the converged result on a <math> 18x18x18</math> k-point grid and bands between 2 and 10. In the figure you can find also the comparison with the results of Ref. <ref>Luppi et al. [https://arxiv.org/abs/1006.2649 PRB B, '''82''', 235201(2010)]</ref>.
Notice that the QuantumEspresso results are slightly different from the Abinit ones. This is due to the different pseudo-potential employed in the calculations if pseudopotentials were the same calculation would have been identical. You can download the script to generate this plot and the converged results [http://www.attaccalite.com/lumen/tutorials/AlAs/AlAs_results.tgz here].

'''Notice that''' : the following parameters are not used in the non-linear response analysis: <code> EnRngeRt</code>, <code>ETStpsRt</code>, <code>DampMode</code>, <code>DampFactor</code>. The damping factor is set directly in the real-time simulation.

'''System of units in Non-linear Optics''': notice that in Yambo the non-linear response functions are in the gaussian system of units, for example the <math> \chi^2 (\omega) </math> is in cm/statvolt. In order to convert the non-linear coefficients between different system of units, you can have a look at the [https://www.attaccalite.com/tutorials_yambo/Appendix_C_Boyd.pdf Appendix C] of the book [https://www.elsevier.com/books/nonlinear-optics/boyd/978-0-12-369470-6 "Non-linear optics" by Robert W. Boyd].

More tutorials on non-linear response (Third harmonic generation, parallelization, spin-orbit etc..) with Yambo can be found here: [http://www.attaccalite.com/lumen/tutorials.html More Tutorials]. 

==Analysis of the results using YamboPy==
The analysis of the result performed in the previous section using <code>ypp_nl</code> can be performed using python script [https://github.com/yambo-code/yambopy YamboPy]. 
In YamboPy we implemented all necessary functions to reads the Yambo databases and post-process the results. Here we show how to get the SHG signal from the previous
simulations. We suppose you correctly installed <code>YamboPy</code> on your PC. Go in the folder where you ran non-linear calculation and type in the python:
 
from yambopy import *
NLDB=YamboNLDB()
pol =NLDB.Polarization[0]
time=NLDB.IO_TIME_points

in this way you read all the Non-linear databases. If your runs are in a different folder then the 'SAVE' one you can specify it using the command:
NLDB=YamboNLDB(calc='MYJOB')

now in the array <code>pol</code> you have all the polarization for all laser frequencies in the three Cartesian directions, while the variable <code>time</code> contains all the time series of your simulation.
Now you can get the non-linear response with the command:

Harmonic_Analysis(NLDB,X_order=4)

this command will perform a Fourier analysis of the results in the same way of <code>ypp_nl</code> and generate new files with all the requested harmonics ''o.YamboPy-X_probe_order_1'', ''o.YamboPy-X_probe_order_2'' etc...
equivalent to the one generated by <code>ypp_nl</code>. Results can be plot with gnuplot using the command:

p 'o.YamboPy-X_probe_order_2' u 1:(sqrt($6**2+$7**2)) w lp ps 1.5 pt 7 lw 1.5

The script that performs non-linear analysis can be found in <code>yambopy/nl/harmonic_analysis.py</code>. We strongly advice you to have a look to this script and modify it according
to your needs and in order to extract other non-linear response functions.

==How to choose the external field direction for the different X2==

In the X2abc response you have three field directions. The two components ''b'' and ''c'' are determined by the external field and the third ''a''
is the direction where you measure the response. 

The external field in Yambo is set using the variable
% Field1_Dir
1.000000 | 0.000000 | 0.000000 | # [NL ExtF] Versor .
%

For example if you set in Yambo field direction as:

1.0 | 0.0 | 0.0 | ---> you calculate all components X2*xx
0.0 | 1.0 | 0.0 | ---> you calculate all components X2*yy
0.0 | 0.0 | 1.0 | ---> you calculate all components X2*zz

the * correspond to the different direction in the response file <code>o.YPP-X_probe_order_2</code>.
In the <code>o.YPP-X_probe_order_2</code> you have seven columns:

The first column is the energy [[omega]],
the 2nd and 3rd columns are the imaginary and real part of X2x**
the 4th and 5th columns are the imaginary and real part of X2y**
the 6th and 7th columns are the imaginary and real part of X2z**

where the ** are the direction of the incoming field, see above.

For example if you want to calculate the <math>\chi^{(2)}_{zxx}</math> you put the external field in the direction <code> 1.0 | 0.0 | 0.0 |</code>
and then plot the column 6 and 7 of the <code>o.YPP-X_probe_order_2</code> file. 

'''Nota bene:''' if you change the direction of the external field you have to remove the corresponding symmetries as explained in the tutorial
on [[Prerequisites for Real Time_propagation with Yambo#Reduce symmetries real-time linear response tutorial]].

In order to get the other components of the X2 the calculation are more involved. For example if you put field in the

1.0 | 1.0 | 0.0 |

this corresponds to <math>E(t)=\frac{1}{\sqrt{2}} [ E_x(t) + E_y(t) ]</math> and so at the second order you will have <math>E^2(t)=\frac{1}{2} [ E^2_x(t) + E^2_y(t) + E_x(t) E_y(t) + E_y(t) E_x(t) ]</math> 
this means that the X2 in the <code>o.YPP-X_probe_order_2</code> will correspond to a linear combination of the following different response functions. 
For example in the the 2nd and 3rd columns are the imaginary and real part of: 

<math>\chi^{(2)}_{x**}=\frac{1}{2} \left [\chi^2_{xxx}+\chi^{(2)}_{xyy} + \chi^{(2)}_{xxy} + \chi^{(2)}_{xyx} \right ]</math>

the same for the other column replacing the first <code>x</code> for <code>y,z</code>.
If you know that some components are zero this allow you to extract the corresponding off-diagonal part of <math>\chi^{(2)}_{abc}</math> otherwise you have to perform different calculations to get the component you are interested in. Hereafter we present a simple example of monolayer hBN (m-hBN). In m-hBN there is only a non-zero component of the $\chi^2$ and all the others are related by symmetry: 
<math>\chi^{(2)}_{yyy}=-\chi^{(2)}_{yxx}=-\chi^{(2)}_{xxy}=-\chi^{(2)}_{xyx}</math>

==Non-linear response of low-dimensional structures: 2D or 1D ==

The Yambo code is a 3D periodic code, so when you want to study a low-dimensional system 2D or 1D, you have to use a supercell approach.
For example to simulate the non-linear response in a 2D-crystal one, can put the crystal in the xy plane and choose a larger distance in the z-direction
in order to reduce the interaction between the periodic replica. Clearly in this case k-point sampling will be only in the x,y directions.
For calculations on this type of systems, these two warnings must be taken into account:

* if you calculate GW corrections or include electron-hole interaction in the linear/non-linear response it is a good idea to use a '''Coulomb cutoff''', similar to the 2D BSE case [http://www.yambo-code.org/wiki/index.php?title=How_to_treat_low_dimensional_systems How to treat low dimensional systems]. You can add the cutoff just adding the "-r" in the input generation.

* the calculation of SHG and THG are always performed respect to the supercell, therefore you have to '''re-scale''' the result to the effective thickness of the layer, usually the inter-layer distance of the corresponding bulk material for 2D systems: <math>\chi_{rescaled}(\omega) = L_z/d_{eff} \cdot \chi(\omega) </math> where <math>L_z</math> is the z-dimension of the supercell, and <math>d_{eff}</math> is the effective thickness of the 2D system.

'''Nota bene''': Non-linear response along non-periodic directions is not implemented in Yambo, the code will print zero in these directions for all response functions. We plan to implement it in a future version of the code.

==References==
<references />

==Links for schools==
* Back to [[Rome 2023#Tutorials]]
* Back to [[ICTP2020]]

 
{| style="width:100%" border="1"
|style="width:25%; text-align:left"|Prev: [[Linear response from real time simulations|Linear response from real time simulations]]
|style="width:45%; text-align:center"|Now: [[ICTP2020|ICTP Tutorials]] --> [[Real time approach to non-linear response|Non Linear Response]]
|style="width:50%; text-align:left"|Next: [[Correlation effects in the non-linear response|Correlation effects in the non-linear response ]]
|-
|}

Real time approach to non-linear response (SHG)

2025-09-27T08:35:52Z

Attacc: /* How to choose the external field direction for the different X2 */

== Second Harmonic Generation in AlAs ==
In this tutorial, we will calculate the second harmonic generation of bulk AlAs, the Yambo databases can be downloaded here: [https://media.yambo-code.eu/educational/tutorials/files/AlAs_DBs.tar.gz AlAs_DBs.tar.gz] (10 MB). The first steps of this tutorials are the same as the one on [http://www.yambo-code.eu/wiki/index.php?title=Prerequisites_for_Real_Time_propagation_with_Yambo Prerequisites for Real-Time propagation with Yambo] with the only difference that we will work on AlAs and we will consider an external field in the direction <code> 1.000000 | 1.000000 | 0.000000 |</code>. The DFT input are available here: [https://media.yambo-code.eu/educational/tutorials/files/AlAs_abinit.tar.gz ABINIT] or [https://media.yambo-code.eu/educational/tutorials/files/AlAs_pwscf.tar.gz QuantumEspresso].
You can run the DFT calculation with ABINIT with the command:

abinit < AlAs.in > output_AlAs

or using QuantumEspresso:

pw.x -inp AlAs.scf.in > output_scf
pw.x -inp AlAs.nscf.in > output_scf

and then import the ABINIT wave-function with the command:

a2y -F AlAso_DS2_WFK.nc

and the QuantumEspresso one, in the folder AlAs.save with the command:

p2y
Now we consider an external field in the <code>[1,1,0]</code> direction and remove symmetries not compatible with this field, as explained in the tutorial [http://www.yambo-code.eu/wiki/index.php?title=Prerequisites_for_Real_Time_propagation_with_Yambo Prerequisites for Real-Time propagation with Yambo].

==Real-time simulation for the SHG==

You can generate the input file with the command <code>yambo_nl -u n</code>:

nloptics # [R NL] Non-linear optics
% NLBands
 3 | 6 | # [NL] Bands
%
NLstep= 0.0100 fs # [NL] Real Time step length
NLverbosity= "high" # [NL] Verbosity level (low | high)
NLtime=-1.000000 fs # [NL] Simulation Time
NLintegrator= "INVINT" # [NL] Integrator ("EULEREXP/RK4/RK2EXP/HEUN/INVINT/CRANKNIC")
NLCorrelation= "IPA" # [NL] Correlation ("IPA/HARTREE/TDDFT/LRC/JGM/SEX/HF")
NLLrcAlpha= 0.000000 # [NL] Long Range Correction
% NLEnRange
 1.000000 | 5.000000 | eV # [NL] Energy range
%
NLEnSteps= 5 # [NL] Energy steps
NLDamping= 0.150000 eV # [NL] Damping
% Field1_Dir
 1.000000 | 1.000000 | 0.000000 | # [RT Field1] Versor
Field1_kind= "SOFTSIN" # [NL ExtF] Kind(SIN|SOFTSIN|RES|ANTIRES|GAUSS|DELTA|QSSIN)

The line <code>|1.000000 | 1.000000 | 0.000000 | # [RT Field1] Versor</code> referees to the direction of the external field (x,y,0). At present only an external field is present but the code can be easily generalized to deal with more fields.
The default parameters of Yambo/Lumen are already tuned for second-harmonic generation, so the only thing you have to change is the band range, between 3 and 6 and the energy range between 1.0-5.0 eV and the number of energy steps in this interval that we set to 10. Notice that you cannot set to zero the lowest value of the energy range because this will requires a simulation that lasts infinite time, see below. Finally, consider that Yambo performs a separate calculation for each frequency, so if you set many energy steps the computational time grows linearly with this number.
Notice that we set <code>NLverbosity= "high"</code> in this way the code will produce a file for each laser frequency containing the time dependent polarization.
Run <code>yambo_nl</code>. Calculations will take about fifteen minutes on a single processor PC, you have time to study the next section that explains how non-linear response is extracted from the real-time simulations.
In order to speed up calculations, you can run them in parallel.

==Non-linear response with Yambo==

In order to calculate the non-linear response, the system is excited with different laser fields with a sinusoidal shape at frequencies <math>\omega_1, \omega_2, .... , \omega_n </math> determined by the parameters [[Variables#NLEnRangev|NLEnRange]] and [[Variables#NLEnSteps|NLEnSteps]]. A dephasing term is added to the Hamiltonian <math>\gamma = </math>[[Variables#NLDamping|NLDamping]] to simulate a finite broadening and to remove the eigenmodes that are excited by the sudden turning on of the external field. After the dephasing time the outgoing signal is analyzed to extract the non-linear coefficients as shown in the figure below:

[[File:Pt analysis.png|600px|center|Non-linear response analysis]]

In the report file <code>r_nlinear</code> you will find the length of the dephasing part and of the sampling one:

Dephasing Time [fs]: 52.65695
Sampling Time [fs]: 4.18566
Total simulation time [fs]: 56.84262
The length of the dephasing interval is inversely proportional to the damping term <math>T_{depth} \simeq 1/\gamma</math> while the length of the sampling is dictated by the smallest frequency we are interested in: <math>T_{samp} \simeq 1/\omega_1 </math>. For this reason if <math> \omega_1=0 </math> or <math> \gamma = 0 </math> simulation time goes to infinity. The response at zero frequency can be calculated as limit of small frequency perturbation.
You can have a look to the file <code>src/nloptics/NL_initialize.F</code> to see how simulation lengths are defined.
Calculations can take some time, run them in parallel, the best number of processors = number of frequencies or reduce the number of frequencies step in the SHG.

==Analysis of the results==

In the sampling region we suppose that the polarization can be written as: <math>\bf{P}(t) = \sum_{n=-\infty}^{+\infty} \bf{p}_n e^{-i\omega_n t} </math> where the coefficient <math>\bf{p}_1,...,\bf{p}_n </math> are related to <math>\chi^{(1)},...,\chi^{(n)} </math>. We sample the polarization signal at different times and invert the previous equation by truncating the sum at a finite order <ref>[https://arxiv.org/abs/1309.4012 Nonlinear optics from an ab initio approach by means of the dynamical Berry phase: Application to second- and third-harmonic generation in semiconductors], C. Attaccalite and M. Grüning, Phys. Rev. B 88, 235113(2013)</ref>.
This is done with the command <code>ypp_nl -u</code> that automatically produce an input with the correct values:

nonlinear # [R] NonLinear Optics Post-Processing
Xorder= 4 # Max order of the response functions
% TimeRange
52.65695 | -1.00000 | fs # Time-window where processing is done
%
ETStpsRt= 200 # Total Energy steps
% EnRngeRt
0.00000 | 10.00000 | eV # Energy range
%
DampMode= "NONE" # Damping type ( NONE | LORENTZIAN | GAUSSIAN )
DampFactor= 0.10000 eV # Damping parameter

where <code>Xorder</code> is the order where the previous sum is truncated, and the TimeRange specifies the sampling region. Notice that differently from the first tutorial, in this case, we do not need Damping in <code>ypp_nl</code> because we already included it in the real-time dynamics. Run <code>ypp_nl</code> and it will produce a file called <code>o.YPP-X_probe_order_2</code>. This file contains the different components of <math>\chi^2_{xy*} </math> and in particular the columns 6 and 7 correspond to the imaginary and real part of <math>\chi^2_{xyz} </math>. You can plot the result with gnuplot and the command:

p 'o.YPP-X_probe_order_2' u 1:(sqrt($6**2+$7**2)) w lp ps 1.5 pt 7 lw 1.5

the result should look like

[[File:AlAs results.png|700px|center|SHG in AlAs]]

and compare it with the <math> \chi^2_{zxy} </math> calculated with more frequencies and with the converged result on a <math> 18x18x18</math> k-point grid and bands between 2 and 10. In the figure you can find also the comparison with the results of Ref. <ref>Luppi et al. [https://arxiv.org/abs/1006.2649 PRB B, '''82''', 235201(2010)]</ref>.
Notice that the QuantumEspresso results are slightly different from the Abinit ones. This is due to the different pseudo-potential employed in the calculations if pseudopotentials were the same calculation would have been identical. You can download the script to generate this plot and the converged results [http://www.attaccalite.com/lumen/tutorials/AlAs/AlAs_results.tgz here].

'''Notice that''' : the following parameters are not used in the non-linear response analysis: <code> EnRngeRt</code>, <code>ETStpsRt</code>, <code>DampMode</code>, <code>DampFactor</code>. The damping factor is set directly in the real-time simulation.

'''System of units in Non-linear Optics''': notice that in Yambo the non-linear response functions are in the gaussian system of units, for example the <math> \chi^2 (\omega) </math> is in cm/statvolt. In order to convert the non-linear coefficients between different system of units, you can have a look at the [https://www.attaccalite.com/tutorials_yambo/Appendix_C_Boyd.pdf Appendix C] of the book [https://www.elsevier.com/books/nonlinear-optics/boyd/978-0-12-369470-6 "Non-linear optics" by Robert W. Boyd].

More tutorials on non-linear response (Third harmonic generation, parallelization, spin-orbit etc..) with Yambo can be found here: [http://www.attaccalite.com/lumen/tutorials.html More Tutorials]. 

==Analysis of the results using YamboPy==
The analysis of the result performed in the previous section using <code>ypp_nl</code> can be performed using python script [https://github.com/yambo-code/yambopy YamboPy]. 
In YamboPy we implemented all necessary functions to reads the Yambo databases and post-process the results. Here we show how to get the SHG signal from the previous
simulations. We suppose you correctly installed <code>YamboPy</code> on your PC. Go in the folder where you ran non-linear calculation and type in the python:
 
from yambopy import *
NLDB=YamboNLDB()
pol =NLDB.Polarization[0]
time=NLDB.IO_TIME_points

in this way you read all the Non-linear databases. If your runs are in a different folder then the 'SAVE' one you can specify it using the command:
NLDB=YamboNLDB(calc='MYJOB')

now in the array <code>pol</code> you have all the polarization for all laser frequencies in the three Cartesian directions, while the variable <code>time</code> contains all the time series of your simulation.
Now you can get the non-linear response with the command:

Harmonic_Analysis(NLDB,X_order=4)

this command will perform a Fourier analysis of the results in the same way of <code>ypp_nl</code> and generate new files with all the requested harmonics ''o.YamboPy-X_probe_order_1'', ''o.YamboPy-X_probe_order_2'' etc...
equivalent to the one generated by <code>ypp_nl</code>. Results can be plot with gnuplot using the command:

p 'o.YamboPy-X_probe_order_2' u 1:(sqrt($6**2+$7**2)) w lp ps 1.5 pt 7 lw 1.5

The script that performs non-linear analysis can be found in <code>yambopy/nl/harmonic_analysis.py</code>. We strongly advice you to have a look to this script and modify it according
to your needs and in order to extract other non-linear response functions.

==How to choose the external field direction for the different X2==

In the X2abc response you have three field directions. The two components ''b'' and ''c'' are determined by the external field and the third ''a''
is the direction where you measure the response. 

The external field in Yambo is set using the variable
% Field1_Dir
1.000000 | 0.000000 | 0.000000 | # [NL ExtF] Versor .
%

For example if you set in Yambo field direction as:

1.0 | 0.0 | 0.0 | ---> you calculate all components X2*xx
0.0 | 1.0 | 0.0 | ---> you calculate all components X2*yy
0.0 | 0.0 | 1.0 | ---> you calculate all components X2*zz

the * correspond to the different direction in the response file <code>o.YPP-X_probe_order_2</code>.
In the <code>o.YPP-X_probe_order_2</code> you have seven columns:

The first column is the energy [[omega]],
the 2nd and 3rd columns are the imaginary and real part of X2x**
the 4th and 5th columns are the imaginary and real part of X2y**
the 6th and 7th columns are the imaginary and real part of X2z**

where the ** are the direction of the incoming field, see above.

For example if you want to calculate the <math>\chi^{(2)}_{zxx}</math> you put the external field in the direction <code> 1.0 | 0.0 | 0.0 |</code>
and then plot the column 6 and 7 of the <code>o.YPP-X_probe_order_2</code> file. 

'''Nota bene:''' if you change the direction of the external field you have to remove the corresponding symmetries as explained in the tutorial
on [[Prerequisites for Real Time_propagation with Yambo#Reduce symmetries real-time linear response tutorial]].

In order to get the other components of the X2 the calculation are more involved. For example if you put field in the

1.0 | 1.0 | 0.0 |

this corresponds to <math>E(t)=\frac{1}{\sqrt{2}} [ E_x(t) + E_y(t) ]</math> and so at the second order you will have <math>E^2(t)=\frac{1}{2} [ E^2_x(t) + E^2_y(t) + E_x(t) E_y(t) + E_y(t) E_x(t) ]</math> 
this means that the X2 in the <code>o.YPP-X_probe_order_2</code> will correspond to a linear combination of the following different response functions. 
For example in the the 2nd and 3rd columns are the imaginary and real part of: 

<math>\chi^{(2)}_{x**}=\frac{1}{2} \left [\chi^2_{xxx}+\chi^{(2)}_{xyy} + \chi^{(2)}_{xxy} + \chi^{(2)}_{xyx} \right ]</math>

the same for the other column replacing the first <code>x</code> for <code>y,z</code>.
If you know that some components are zero this allow you to extract the corresponding off-diagonal part of <math>\chi^{(2)}_{abc}</math> otherwise you have to perform different calculations to get the component you are interested in. Hereafter we present a simple example of monolayer hBN (m-hBN). In m-hBN there is only a non-zero component of the $\chi^2$ and all the others are related by symmetry: 
<math>\chi^{(2)}_{yyy}=-\chi^{(2)}_{yxx}=-\chi^{(2)}_{xxy}=-\chi^{(2)}_{xyx}}</math>

==Non-linear response of low-dimensional structures: 2D or 1D ==

The Yambo code is a 3D periodic code, so when you want to study a low-dimensional system 2D or 1D, you have to use a supercell approach.
For example to simulate the non-linear response in a 2D-crystal one, can put the crystal in the xy plane and choose a larger distance in the z-direction
in order to reduce the interaction between the periodic replica. Clearly in this case k-point sampling will be only in the x,y directions.
For calculations on this type of systems, these two warnings must be taken into account:

* if you calculate GW corrections or include electron-hole interaction in the linear/non-linear response it is a good idea to use a '''Coulomb cutoff''', similar to the 2D BSE case [http://www.yambo-code.org/wiki/index.php?title=How_to_treat_low_dimensional_systems How to treat low dimensional systems]. You can add the cutoff just adding the "-r" in the input generation.

* the calculation of SHG and THG are always performed respect to the supercell, therefore you have to '''re-scale''' the result to the effective thickness of the layer, usually the inter-layer distance of the corresponding bulk material for 2D systems: <math>\chi_{rescaled}(\omega) = L_z/d_{eff} \cdot \chi(\omega) </math> where <math>L_z</math> is the z-dimension of the supercell, and <math>d_{eff}</math> is the effective thickness of the 2D system.

'''Nota bene''': Non-linear response along non-periodic directions is not implemented in Yambo, the code will print zero in these directions for all response functions. We plan to implement it in a future version of the code.

==References==
<references />

==Links for schools==
* Back to [[Rome 2023#Tutorials]]
* Back to [[ICTP2020]]

 
{| style="width:100%" border="1"
|style="width:25%; text-align:left"|Prev: [[Linear response from real time simulations|Linear response from real time simulations]]
|style="width:45%; text-align:center"|Now: [[ICTP2020|ICTP Tutorials]] --> [[Real time approach to non-linear response|Non Linear Response]]
|style="width:50%; text-align:left"|Next: [[Correlation effects in the non-linear response|Correlation effects in the non-linear response ]]
|-
|}

Real time approach to non-linear response (SHG)

2025-09-27T08:34:06Z

Attacc: /* How to choose the external field direction for the different X2 */

== Second Harmonic Generation in AlAs ==
In this tutorial, we will calculate the second harmonic generation of bulk AlAs, the Yambo databases can be downloaded here: [https://media.yambo-code.eu/educational/tutorials/files/AlAs_DBs.tar.gz AlAs_DBs.tar.gz] (10 MB). The first steps of this tutorials are the same as the one on [http://www.yambo-code.eu/wiki/index.php?title=Prerequisites_for_Real_Time_propagation_with_Yambo Prerequisites for Real-Time propagation with Yambo] with the only difference that we will work on AlAs and we will consider an external field in the direction <code> 1.000000 | 1.000000 | 0.000000 |</code>. The DFT input are available here: [https://media.yambo-code.eu/educational/tutorials/files/AlAs_abinit.tar.gz ABINIT] or [https://media.yambo-code.eu/educational/tutorials/files/AlAs_pwscf.tar.gz QuantumEspresso].
You can run the DFT calculation with ABINIT with the command:

abinit < AlAs.in > output_AlAs

or using QuantumEspresso:

pw.x -inp AlAs.scf.in > output_scf
pw.x -inp AlAs.nscf.in > output_scf

and then import the ABINIT wave-function with the command:

a2y -F AlAso_DS2_WFK.nc

and the QuantumEspresso one, in the folder AlAs.save with the command:

p2y
Now we consider an external field in the <code>[1,1,0]</code> direction and remove symmetries not compatible with this field, as explained in the tutorial [http://www.yambo-code.eu/wiki/index.php?title=Prerequisites_for_Real_Time_propagation_with_Yambo Prerequisites for Real-Time propagation with Yambo].

==Real-time simulation for the SHG==

You can generate the input file with the command <code>yambo_nl -u n</code>:

nloptics # [R NL] Non-linear optics
% NLBands
 3 | 6 | # [NL] Bands
%
NLstep= 0.0100 fs # [NL] Real Time step length
NLverbosity= "high" # [NL] Verbosity level (low | high)
NLtime=-1.000000 fs # [NL] Simulation Time
NLintegrator= "INVINT" # [NL] Integrator ("EULEREXP/RK4/RK2EXP/HEUN/INVINT/CRANKNIC")
NLCorrelation= "IPA" # [NL] Correlation ("IPA/HARTREE/TDDFT/LRC/JGM/SEX/HF")
NLLrcAlpha= 0.000000 # [NL] Long Range Correction
% NLEnRange
 1.000000 | 5.000000 | eV # [NL] Energy range
%
NLEnSteps= 5 # [NL] Energy steps
NLDamping= 0.150000 eV # [NL] Damping
% Field1_Dir
 1.000000 | 1.000000 | 0.000000 | # [RT Field1] Versor
Field1_kind= "SOFTSIN" # [NL ExtF] Kind(SIN|SOFTSIN|RES|ANTIRES|GAUSS|DELTA|QSSIN)

The line <code>|1.000000 | 1.000000 | 0.000000 | # [RT Field1] Versor</code> referees to the direction of the external field (x,y,0). At present only an external field is present but the code can be easily generalized to deal with more fields.
The default parameters of Yambo/Lumen are already tuned for second-harmonic generation, so the only thing you have to change is the band range, between 3 and 6 and the energy range between 1.0-5.0 eV and the number of energy steps in this interval that we set to 10. Notice that you cannot set to zero the lowest value of the energy range because this will requires a simulation that lasts infinite time, see below. Finally, consider that Yambo performs a separate calculation for each frequency, so if you set many energy steps the computational time grows linearly with this number.
Notice that we set <code>NLverbosity= "high"</code> in this way the code will produce a file for each laser frequency containing the time dependent polarization.
Run <code>yambo_nl</code>. Calculations will take about fifteen minutes on a single processor PC, you have time to study the next section that explains how non-linear response is extracted from the real-time simulations.
In order to speed up calculations, you can run them in parallel.

==Non-linear response with Yambo==

In order to calculate the non-linear response, the system is excited with different laser fields with a sinusoidal shape at frequencies <math>\omega_1, \omega_2, .... , \omega_n </math> determined by the parameters [[Variables#NLEnRangev|NLEnRange]] and [[Variables#NLEnSteps|NLEnSteps]]. A dephasing term is added to the Hamiltonian <math>\gamma = </math>[[Variables#NLDamping|NLDamping]] to simulate a finite broadening and to remove the eigenmodes that are excited by the sudden turning on of the external field. After the dephasing time the outgoing signal is analyzed to extract the non-linear coefficients as shown in the figure below:

[[File:Pt analysis.png|600px|center|Non-linear response analysis]]

In the report file <code>r_nlinear</code> you will find the length of the dephasing part and of the sampling one:

Dephasing Time [fs]: 52.65695
Sampling Time [fs]: 4.18566
Total simulation time [fs]: 56.84262
The length of the dephasing interval is inversely proportional to the damping term <math>T_{depth} \simeq 1/\gamma</math> while the length of the sampling is dictated by the smallest frequency we are interested in: <math>T_{samp} \simeq 1/\omega_1 </math>. For this reason if <math> \omega_1=0 </math> or <math> \gamma = 0 </math> simulation time goes to infinity. The response at zero frequency can be calculated as limit of small frequency perturbation.
You can have a look to the file <code>src/nloptics/NL_initialize.F</code> to see how simulation lengths are defined.
Calculations can take some time, run them in parallel, the best number of processors = number of frequencies or reduce the number of frequencies step in the SHG.

==Analysis of the results==

In the sampling region we suppose that the polarization can be written as: <math>\bf{P}(t) = \sum_{n=-\infty}^{+\infty} \bf{p}_n e^{-i\omega_n t} </math> where the coefficient <math>\bf{p}_1,...,\bf{p}_n </math> are related to <math>\chi^{(1)},...,\chi^{(n)} </math>. We sample the polarization signal at different times and invert the previous equation by truncating the sum at a finite order <ref>[https://arxiv.org/abs/1309.4012 Nonlinear optics from an ab initio approach by means of the dynamical Berry phase: Application to second- and third-harmonic generation in semiconductors], C. Attaccalite and M. Grüning, Phys. Rev. B 88, 235113(2013)</ref>.
This is done with the command <code>ypp_nl -u</code> that automatically produce an input with the correct values:

nonlinear # [R] NonLinear Optics Post-Processing
Xorder= 4 # Max order of the response functions
% TimeRange
52.65695 | -1.00000 | fs # Time-window where processing is done
%
ETStpsRt= 200 # Total Energy steps
% EnRngeRt
0.00000 | 10.00000 | eV # Energy range
%
DampMode= "NONE" # Damping type ( NONE | LORENTZIAN | GAUSSIAN )
DampFactor= 0.10000 eV # Damping parameter

where <code>Xorder</code> is the order where the previous sum is truncated, and the TimeRange specifies the sampling region. Notice that differently from the first tutorial, in this case, we do not need Damping in <code>ypp_nl</code> because we already included it in the real-time dynamics. Run <code>ypp_nl</code> and it will produce a file called <code>o.YPP-X_probe_order_2</code>. This file contains the different components of <math>\chi^2_{xy*} </math> and in particular the columns 6 and 7 correspond to the imaginary and real part of <math>\chi^2_{xyz} </math>. You can plot the result with gnuplot and the command:

p 'o.YPP-X_probe_order_2' u 1:(sqrt($6**2+$7**2)) w lp ps 1.5 pt 7 lw 1.5

the result should look like

[[File:AlAs results.png|700px|center|SHG in AlAs]]

and compare it with the <math> \chi^2_{zxy} </math> calculated with more frequencies and with the converged result on a <math> 18x18x18</math> k-point grid and bands between 2 and 10. In the figure you can find also the comparison with the results of Ref. <ref>Luppi et al. [https://arxiv.org/abs/1006.2649 PRB B, '''82''', 235201(2010)]</ref>.
Notice that the QuantumEspresso results are slightly different from the Abinit ones. This is due to the different pseudo-potential employed in the calculations if pseudopotentials were the same calculation would have been identical. You can download the script to generate this plot and the converged results [http://www.attaccalite.com/lumen/tutorials/AlAs/AlAs_results.tgz here].

'''Notice that''' : the following parameters are not used in the non-linear response analysis: <code> EnRngeRt</code>, <code>ETStpsRt</code>, <code>DampMode</code>, <code>DampFactor</code>. The damping factor is set directly in the real-time simulation.

'''System of units in Non-linear Optics''': notice that in Yambo the non-linear response functions are in the gaussian system of units, for example the <math> \chi^2 (\omega) </math> is in cm/statvolt. In order to convert the non-linear coefficients between different system of units, you can have a look at the [https://www.attaccalite.com/tutorials_yambo/Appendix_C_Boyd.pdf Appendix C] of the book [https://www.elsevier.com/books/nonlinear-optics/boyd/978-0-12-369470-6 "Non-linear optics" by Robert W. Boyd].

More tutorials on non-linear response (Third harmonic generation, parallelization, spin-orbit etc..) with Yambo can be found here: [http://www.attaccalite.com/lumen/tutorials.html More Tutorials]. 

==Analysis of the results using YamboPy==
The analysis of the result performed in the previous section using <code>ypp_nl</code> can be performed using python script [https://github.com/yambo-code/yambopy YamboPy]. 
In YamboPy we implemented all necessary functions to reads the Yambo databases and post-process the results. Here we show how to get the SHG signal from the previous
simulations. We suppose you correctly installed <code>YamboPy</code> on your PC. Go in the folder where you ran non-linear calculation and type in the python:
 
from yambopy import *
NLDB=YamboNLDB()
pol =NLDB.Polarization[0]
time=NLDB.IO_TIME_points

in this way you read all the Non-linear databases. If your runs are in a different folder then the 'SAVE' one you can specify it using the command:
NLDB=YamboNLDB(calc='MYJOB')

now in the array <code>pol</code> you have all the polarization for all laser frequencies in the three Cartesian directions, while the variable <code>time</code> contains all the time series of your simulation.
Now you can get the non-linear response with the command:

Harmonic_Analysis(NLDB,X_order=4)

this command will perform a Fourier analysis of the results in the same way of <code>ypp_nl</code> and generate new files with all the requested harmonics ''o.YamboPy-X_probe_order_1'', ''o.YamboPy-X_probe_order_2'' etc...
equivalent to the one generated by <code>ypp_nl</code>. Results can be plot with gnuplot using the command:

p 'o.YamboPy-X_probe_order_2' u 1:(sqrt($6**2+$7**2)) w lp ps 1.5 pt 7 lw 1.5

The script that performs non-linear analysis can be found in <code>yambopy/nl/harmonic_analysis.py</code>. We strongly advice you to have a look to this script and modify it according
to your needs and in order to extract other non-linear response functions.

==How to choose the external field direction for the different X2==

In the X2abc response you have three field directions. The two components ''b'' and ''c'' are determined by the external field and the third ''a''
is the direction where you measure the response. 

The external field in Yambo is set using the variable
% Field1_Dir
1.000000 | 0.000000 | 0.000000 | # [NL ExtF] Versor .
%

For example if you set in Yambo field direction as:

1.0 | 0.0 | 0.0 | ---> you calculate all components X2*xx
0.0 | 1.0 | 0.0 | ---> you calculate all components X2*yy
0.0 | 0.0 | 1.0 | ---> you calculate all components X2*zz

the * correspond to the different direction in the response file <code>o.YPP-X_probe_order_2</code>.
In the <code>o.YPP-X_probe_order_2</code> you have seven columns:

The first column is the energy [[omega]],
the 2nd and 3rd columns are the imaginary and real part of X2x**
the 4th and 5th columns are the imaginary and real part of X2y**
the 6th and 7th columns are the imaginary and real part of X2z**

where the ** are the direction of the incoming field, see above.

For example if you want to calculate the X2zxx you put the external field in the direction <code> 1.0 | 0.0 | 0.0 |</code>
and then plot the column 6 and 7 of the <code>o.YPP-X_probe_order_2</code> file. 

'''Nota bene:''' if you change the direction of the external field you have to remove the corresponding symmetries as explained in the tutorial
on [[Prerequisites for Real Time_propagation with Yambo#Reduce symmetries real-time linear response tutorial]].

In order to get the other components of the X2 the calculation are more involved. For example if you put field in the

1.0 | 1.0 | 0.0 |

this corresponds to <math>E(t)=\frac{1}{\sqrt{2}} [ E_x(t) + E_y(t) ]</math> and so at the second order you will have <math>E^2(t)=\frac{1}{2} [ E^2_x(t) + E^2_y(t) + E_x(t) E_y(t) + E_y(t) E_x(t) ]</math> 
this means that the X2 in the <code>o.YPP-X_probe_order_2</code> will correspond to a linear combination of the following different response functions. 
For example in the the 2nd and 3rd columns are the imaginary and real part of: 

<math>\chi^{(2)}_{x**}=\frac{1}{2} \left [\chi^2_{xxx}+\chi^{(2)}_{xyy} + \chi^{(2)}_{xxy} + \chi^{(2)}_{xyx} \right ]</math>

the same for the other column replacing the first <code>x</code> for <code>y,z</code>.
If you know that some components are zero this allow you to extract the corresponding off-diagonal part of <math>\chi^2_{abc}</math> otherwise you have to perform different calculations to get the component you are interested in. Hereafter we present a simple example of monolayer hBN (m-hBN). In m-hBN there is only a non-zero component of the $\chi^2$ and all the others are related by symmetry: 
<math>\chi^{(2)}_{222}=-\chi^{(2)}_{211}=-\chi^{(2)}_{112}=-\chi^{(2)}_{121} \equiv \chi^{(2)}</math>

==Non-linear response of low-dimensional structures: 2D or 1D ==

The Yambo code is a 3D periodic code, so when you want to study a low-dimensional system 2D or 1D, you have to use a supercell approach.
For example to simulate the non-linear response in a 2D-crystal one, can put the crystal in the xy plane and choose a larger distance in the z-direction
in order to reduce the interaction between the periodic replica. Clearly in this case k-point sampling will be only in the x,y directions.
For calculations on this type of systems, these two warnings must be taken into account:

* if you calculate GW corrections or include electron-hole interaction in the linear/non-linear response it is a good idea to use a '''Coulomb cutoff''', similar to the 2D BSE case [http://www.yambo-code.org/wiki/index.php?title=How_to_treat_low_dimensional_systems How to treat low dimensional systems]. You can add the cutoff just adding the "-r" in the input generation.

* the calculation of SHG and THG are always performed respect to the supercell, therefore you have to '''re-scale''' the result to the effective thickness of the layer, usually the inter-layer distance of the corresponding bulk material for 2D systems: <math>\chi_{rescaled}(\omega) = L_z/d_{eff} \cdot \chi(\omega) </math> where <math>L_z</math> is the z-dimension of the supercell, and <math>d_{eff}</math> is the effective thickness of the 2D system.

'''Nota bene''': Non-linear response along non-periodic directions is not implemented in Yambo, the code will print zero in these directions for all response functions. We plan to implement it in a future version of the code.

==References==
<references />

==Links for schools==
* Back to [[Rome 2023#Tutorials]]
* Back to [[ICTP2020]]

 
{| style="width:100%" border="1"
|style="width:25%; text-align:left"|Prev: [[Linear response from real time simulations|Linear response from real time simulations]]
|style="width:45%; text-align:center"|Now: [[ICTP2020|ICTP Tutorials]] --> [[Real time approach to non-linear response|Non Linear Response]]
|style="width:50%; text-align:left"|Next: [[Correlation effects in the non-linear response|Correlation effects in the non-linear response ]]
|-
|}

Real time approach to non-linear response (SHG)

2025-09-27T08:32:57Z

Attacc: /* How to choose the external field direction for the different X2 */

== Second Harmonic Generation in AlAs ==
In this tutorial, we will calculate the second harmonic generation of bulk AlAs, the Yambo databases can be downloaded here: [https://media.yambo-code.eu/educational/tutorials/files/AlAs_DBs.tar.gz AlAs_DBs.tar.gz] (10 MB). The first steps of this tutorials are the same as the one on [http://www.yambo-code.eu/wiki/index.php?title=Prerequisites_for_Real_Time_propagation_with_Yambo Prerequisites for Real-Time propagation with Yambo] with the only difference that we will work on AlAs and we will consider an external field in the direction <code> 1.000000 | 1.000000 | 0.000000 |</code>. The DFT input are available here: [https://media.yambo-code.eu/educational/tutorials/files/AlAs_abinit.tar.gz ABINIT] or [https://media.yambo-code.eu/educational/tutorials/files/AlAs_pwscf.tar.gz QuantumEspresso].
You can run the DFT calculation with ABINIT with the command:

abinit < AlAs.in > output_AlAs

or using QuantumEspresso:

pw.x -inp AlAs.scf.in > output_scf
pw.x -inp AlAs.nscf.in > output_scf

and then import the ABINIT wave-function with the command:

a2y -F AlAso_DS2_WFK.nc

and the QuantumEspresso one, in the folder AlAs.save with the command:

p2y
Now we consider an external field in the <code>[1,1,0]</code> direction and remove symmetries not compatible with this field, as explained in the tutorial [http://www.yambo-code.eu/wiki/index.php?title=Prerequisites_for_Real_Time_propagation_with_Yambo Prerequisites for Real-Time propagation with Yambo].

==Real-time simulation for the SHG==

You can generate the input file with the command <code>yambo_nl -u n</code>:

nloptics # [R NL] Non-linear optics
% NLBands
 3 | 6 | # [NL] Bands
%
NLstep= 0.0100 fs # [NL] Real Time step length
NLverbosity= "high" # [NL] Verbosity level (low | high)
NLtime=-1.000000 fs # [NL] Simulation Time
NLintegrator= "INVINT" # [NL] Integrator ("EULEREXP/RK4/RK2EXP/HEUN/INVINT/CRANKNIC")
NLCorrelation= "IPA" # [NL] Correlation ("IPA/HARTREE/TDDFT/LRC/JGM/SEX/HF")
NLLrcAlpha= 0.000000 # [NL] Long Range Correction
% NLEnRange
 1.000000 | 5.000000 | eV # [NL] Energy range
%
NLEnSteps= 5 # [NL] Energy steps
NLDamping= 0.150000 eV # [NL] Damping
% Field1_Dir
 1.000000 | 1.000000 | 0.000000 | # [RT Field1] Versor
Field1_kind= "SOFTSIN" # [NL ExtF] Kind(SIN|SOFTSIN|RES|ANTIRES|GAUSS|DELTA|QSSIN)

The line <code>|1.000000 | 1.000000 | 0.000000 | # [RT Field1] Versor</code> referees to the direction of the external field (x,y,0). At present only an external field is present but the code can be easily generalized to deal with more fields.
The default parameters of Yambo/Lumen are already tuned for second-harmonic generation, so the only thing you have to change is the band range, between 3 and 6 and the energy range between 1.0-5.0 eV and the number of energy steps in this interval that we set to 10. Notice that you cannot set to zero the lowest value of the energy range because this will requires a simulation that lasts infinite time, see below. Finally, consider that Yambo performs a separate calculation for each frequency, so if you set many energy steps the computational time grows linearly with this number.
Notice that we set <code>NLverbosity= "high"</code> in this way the code will produce a file for each laser frequency containing the time dependent polarization.
Run <code>yambo_nl</code>. Calculations will take about fifteen minutes on a single processor PC, you have time to study the next section that explains how non-linear response is extracted from the real-time simulations.
In order to speed up calculations, you can run them in parallel.

==Non-linear response with Yambo==

In order to calculate the non-linear response, the system is excited with different laser fields with a sinusoidal shape at frequencies <math>\omega_1, \omega_2, .... , \omega_n </math> determined by the parameters [[Variables#NLEnRangev|NLEnRange]] and [[Variables#NLEnSteps|NLEnSteps]]. A dephasing term is added to the Hamiltonian <math>\gamma = </math>[[Variables#NLDamping|NLDamping]] to simulate a finite broadening and to remove the eigenmodes that are excited by the sudden turning on of the external field. After the dephasing time the outgoing signal is analyzed to extract the non-linear coefficients as shown in the figure below:

[[File:Pt analysis.png|600px|center|Non-linear response analysis]]

In the report file <code>r_nlinear</code> you will find the length of the dephasing part and of the sampling one:

Dephasing Time [fs]: 52.65695
Sampling Time [fs]: 4.18566
Total simulation time [fs]: 56.84262
The length of the dephasing interval is inversely proportional to the damping term <math>T_{depth} \simeq 1/\gamma</math> while the length of the sampling is dictated by the smallest frequency we are interested in: <math>T_{samp} \simeq 1/\omega_1 </math>. For this reason if <math> \omega_1=0 </math> or <math> \gamma = 0 </math> simulation time goes to infinity. The response at zero frequency can be calculated as limit of small frequency perturbation.
You can have a look to the file <code>src/nloptics/NL_initialize.F</code> to see how simulation lengths are defined.
Calculations can take some time, run them in parallel, the best number of processors = number of frequencies or reduce the number of frequencies step in the SHG.

==Analysis of the results==

In the sampling region we suppose that the polarization can be written as: <math>\bf{P}(t) = \sum_{n=-\infty}^{+\infty} \bf{p}_n e^{-i\omega_n t} </math> where the coefficient <math>\bf{p}_1,...,\bf{p}_n </math> are related to <math>\chi^{(1)},...,\chi^{(n)} </math>. We sample the polarization signal at different times and invert the previous equation by truncating the sum at a finite order <ref>[https://arxiv.org/abs/1309.4012 Nonlinear optics from an ab initio approach by means of the dynamical Berry phase: Application to second- and third-harmonic generation in semiconductors], C. Attaccalite and M. Grüning, Phys. Rev. B 88, 235113(2013)</ref>.
This is done with the command <code>ypp_nl -u</code> that automatically produce an input with the correct values:

nonlinear # [R] NonLinear Optics Post-Processing
Xorder= 4 # Max order of the response functions
% TimeRange
52.65695 | -1.00000 | fs # Time-window where processing is done
%
ETStpsRt= 200 # Total Energy steps
% EnRngeRt
0.00000 | 10.00000 | eV # Energy range
%
DampMode= "NONE" # Damping type ( NONE | LORENTZIAN | GAUSSIAN )
DampFactor= 0.10000 eV # Damping parameter

where <code>Xorder</code> is the order where the previous sum is truncated, and the TimeRange specifies the sampling region. Notice that differently from the first tutorial, in this case, we do not need Damping in <code>ypp_nl</code> because we already included it in the real-time dynamics. Run <code>ypp_nl</code> and it will produce a file called <code>o.YPP-X_probe_order_2</code>. This file contains the different components of <math>\chi^2_{xy*} </math> and in particular the columns 6 and 7 correspond to the imaginary and real part of <math>\chi^2_{xyz} </math>. You can plot the result with gnuplot and the command:

p 'o.YPP-X_probe_order_2' u 1:(sqrt($6**2+$7**2)) w lp ps 1.5 pt 7 lw 1.5

the result should look like

[[File:AlAs results.png|700px|center|SHG in AlAs]]

and compare it with the <math> \chi^2_{zxy} </math> calculated with more frequencies and with the converged result on a <math> 18x18x18</math> k-point grid and bands between 2 and 10. In the figure you can find also the comparison with the results of Ref. <ref>Luppi et al. [https://arxiv.org/abs/1006.2649 PRB B, '''82''', 235201(2010)]</ref>.
Notice that the QuantumEspresso results are slightly different from the Abinit ones. This is due to the different pseudo-potential employed in the calculations if pseudopotentials were the same calculation would have been identical. You can download the script to generate this plot and the converged results [http://www.attaccalite.com/lumen/tutorials/AlAs/AlAs_results.tgz here].

'''Notice that''' : the following parameters are not used in the non-linear response analysis: <code> EnRngeRt</code>, <code>ETStpsRt</code>, <code>DampMode</code>, <code>DampFactor</code>. The damping factor is set directly in the real-time simulation.

'''System of units in Non-linear Optics''': notice that in Yambo the non-linear response functions are in the gaussian system of units, for example the <math> \chi^2 (\omega) </math> is in cm/statvolt. In order to convert the non-linear coefficients between different system of units, you can have a look at the [https://www.attaccalite.com/tutorials_yambo/Appendix_C_Boyd.pdf Appendix C] of the book [https://www.elsevier.com/books/nonlinear-optics/boyd/978-0-12-369470-6 "Non-linear optics" by Robert W. Boyd].

More tutorials on non-linear response (Third harmonic generation, parallelization, spin-orbit etc..) with Yambo can be found here: [http://www.attaccalite.com/lumen/tutorials.html More Tutorials]. 

==Analysis of the results using YamboPy==
The analysis of the result performed in the previous section using <code>ypp_nl</code> can be performed using python script [https://github.com/yambo-code/yambopy YamboPy]. 
In YamboPy we implemented all necessary functions to reads the Yambo databases and post-process the results. Here we show how to get the SHG signal from the previous
simulations. We suppose you correctly installed <code>YamboPy</code> on your PC. Go in the folder where you ran non-linear calculation and type in the python:
 
from yambopy import *
NLDB=YamboNLDB()
pol =NLDB.Polarization[0]
time=NLDB.IO_TIME_points

in this way you read all the Non-linear databases. If your runs are in a different folder then the 'SAVE' one you can specify it using the command:
NLDB=YamboNLDB(calc='MYJOB')

now in the array <code>pol</code> you have all the polarization for all laser frequencies in the three Cartesian directions, while the variable <code>time</code> contains all the time series of your simulation.
Now you can get the non-linear response with the command:

Harmonic_Analysis(NLDB,X_order=4)

this command will perform a Fourier analysis of the results in the same way of <code>ypp_nl</code> and generate new files with all the requested harmonics ''o.YamboPy-X_probe_order_1'', ''o.YamboPy-X_probe_order_2'' etc...
equivalent to the one generated by <code>ypp_nl</code>. Results can be plot with gnuplot using the command:

p 'o.YamboPy-X_probe_order_2' u 1:(sqrt($6**2+$7**2)) w lp ps 1.5 pt 7 lw 1.5

The script that performs non-linear analysis can be found in <code>yambopy/nl/harmonic_analysis.py</code>. We strongly advice you to have a look to this script and modify it according
to your needs and in order to extract other non-linear response functions.

==How to choose the external field direction for the different X2==

In the X2abc response you have three field directions. The two components ''b'' and ''c'' are determined by the external field and the third ''a''
is the direction where you measure the response. 

The external field in Yambo is set using the variable
% Field1_Dir
1.000000 | 0.000000 | 0.000000 | # [NL ExtF] Versor .
%

For example if you set in Yambo field direction as:

1.0 | 0.0 | 0.0 | ---> you calculate all components X2*xx
0.0 | 1.0 | 0.0 | ---> you calculate all components X2*yy
0.0 | 0.0 | 1.0 | ---> you calculate all components X2*zz

the * correspond to the different direction in the response file <code>o.YPP-X_probe_order_2</code>.
In the <code>o.YPP-X_probe_order_2</code> you have seven columns:

The first column is the energy [[omega]],
the 2nd and 3rd columns are the imaginary and real part of X2x**
the 4th and 5th columns are the imaginary and real part of X2y**
the 6th and 7th columns are the imaginary and real part of X2z**

where the ** are the direction of the incoming field, see above.

For example if you want to calculate the X2zxx you put the external field in the direction <code> 1.0 | 0.0 | 0.0 |</code>
and then plot the column 6 and 7 of the <code>o.YPP-X_probe_order_2</code> file. 

'''Nota bene:''' if you change the direction of the external field you have to remove the corresponding symmetries as explained in the tutorial
on [[Prerequisites for Real Time_propagation with Yambo#Reduce symmetries real-time linear response tutorial]].

In order to get the other components of the X2 the calculation are more involved. For example if you put field in the

1.0 | 1.0 | 0.0 |

this corresponds to <math>E(t)=\frac{1}{\sqrt{2}} [ E_x(t) + E_y(t) ]</math> and so at the second order you will have <math>E^2(t)=\frac{1}{2} [ E^2_x(t) + E^2_y(t) + E_x(t) E_y(t) + E_y(t) E_x(t) ]</math> 
this means that the X2 in the <code>o.YPP-X_probe_order_2</code> will correspond to a linear combination of the following different response functions. 
For example in the the 2nd and 3rd columns are the imaginary and real part of: 

<math>\chi^2_{x**}=\frac{1}{2} \left [\chi^2_{xxx}+\chi^2_{xyy} + \chi^2_{xxy} + \chi^2_{xyx} \right ]</math>

the same for the other column replacing the first <code>x</code> for <code>y,z</code>.
If you know that some components are zero this allow you to extract the corresponding off-diagonal part of <math>\chi^2_{abc}</math> otherwise you have to perform different calculations to get the component you are interested in. Hereafter we present a simple example of monolayer hBN (m-hBN). In m-hBN there is only a non-zero component of the $\chi^2$ and all the others are related by symmetry: 
<math>$\chi^{(2)}_{222}=-\chi^{(2)}_{211}=-\chi^{(2)}_{112}=-\chi^{(2)}_{121} \equiv \chi^{(2)}$</math>

==Non-linear response of low-dimensional structures: 2D or 1D ==

The Yambo code is a 3D periodic code, so when you want to study a low-dimensional system 2D or 1D, you have to use a supercell approach.
For example to simulate the non-linear response in a 2D-crystal one, can put the crystal in the xy plane and choose a larger distance in the z-direction
in order to reduce the interaction between the periodic replica. Clearly in this case k-point sampling will be only in the x,y directions.
For calculations on this type of systems, these two warnings must be taken into account:

* if you calculate GW corrections or include electron-hole interaction in the linear/non-linear response it is a good idea to use a '''Coulomb cutoff''', similar to the 2D BSE case [http://www.yambo-code.org/wiki/index.php?title=How_to_treat_low_dimensional_systems How to treat low dimensional systems]. You can add the cutoff just adding the "-r" in the input generation.

* the calculation of SHG and THG are always performed respect to the supercell, therefore you have to '''re-scale''' the result to the effective thickness of the layer, usually the inter-layer distance of the corresponding bulk material for 2D systems: <math>\chi_{rescaled}(\omega) = L_z/d_{eff} \cdot \chi(\omega) </math> where <math>L_z</math> is the z-dimension of the supercell, and <math>d_{eff}</math> is the effective thickness of the 2D system.

'''Nota bene''': Non-linear response along non-periodic directions is not implemented in Yambo, the code will print zero in these directions for all response functions. We plan to implement it in a future version of the code.

==References==
<references />

==Links for schools==
* Back to [[Rome 2023#Tutorials]]
* Back to [[ICTP2020]]

 
{| style="width:100%" border="1"
|style="width:25%; text-align:left"|Prev: [[Linear response from real time simulations|Linear response from real time simulations]]
|style="width:45%; text-align:center"|Now: [[ICTP2020|ICTP Tutorials]] --> [[Real time approach to non-linear response|Non Linear Response]]
|style="width:50%; text-align:left"|Next: [[Correlation effects in the non-linear response|Correlation effects in the non-linear response ]]
|-
|}

Real time approach to non-linear response (SHG)

2025-09-27T08:30:46Z

Attacc: /* How to choose the external field direction for the different X2 */

== Second Harmonic Generation in AlAs ==
In this tutorial, we will calculate the second harmonic generation of bulk AlAs, the Yambo databases can be downloaded here: [https://media.yambo-code.eu/educational/tutorials/files/AlAs_DBs.tar.gz AlAs_DBs.tar.gz] (10 MB). The first steps of this tutorials are the same as the one on [http://www.yambo-code.eu/wiki/index.php?title=Prerequisites_for_Real_Time_propagation_with_Yambo Prerequisites for Real-Time propagation with Yambo] with the only difference that we will work on AlAs and we will consider an external field in the direction <code> 1.000000 | 1.000000 | 0.000000 |</code>. The DFT input are available here: [https://media.yambo-code.eu/educational/tutorials/files/AlAs_abinit.tar.gz ABINIT] or [https://media.yambo-code.eu/educational/tutorials/files/AlAs_pwscf.tar.gz QuantumEspresso].
You can run the DFT calculation with ABINIT with the command:

abinit < AlAs.in > output_AlAs

or using QuantumEspresso:

pw.x -inp AlAs.scf.in > output_scf
pw.x -inp AlAs.nscf.in > output_scf

and then import the ABINIT wave-function with the command:

a2y -F AlAso_DS2_WFK.nc

and the QuantumEspresso one, in the folder AlAs.save with the command:

p2y
Now we consider an external field in the <code>[1,1,0]</code> direction and remove symmetries not compatible with this field, as explained in the tutorial [http://www.yambo-code.eu/wiki/index.php?title=Prerequisites_for_Real_Time_propagation_with_Yambo Prerequisites for Real-Time propagation with Yambo].

==Real-time simulation for the SHG==

You can generate the input file with the command <code>yambo_nl -u n</code>:

nloptics # [R NL] Non-linear optics
% NLBands
 3 | 6 | # [NL] Bands
%
NLstep= 0.0100 fs # [NL] Real Time step length
NLverbosity= "high" # [NL] Verbosity level (low | high)
NLtime=-1.000000 fs # [NL] Simulation Time
NLintegrator= "INVINT" # [NL] Integrator ("EULEREXP/RK4/RK2EXP/HEUN/INVINT/CRANKNIC")
NLCorrelation= "IPA" # [NL] Correlation ("IPA/HARTREE/TDDFT/LRC/JGM/SEX/HF")
NLLrcAlpha= 0.000000 # [NL] Long Range Correction
% NLEnRange
 1.000000 | 5.000000 | eV # [NL] Energy range
%
NLEnSteps= 5 # [NL] Energy steps
NLDamping= 0.150000 eV # [NL] Damping
% Field1_Dir
 1.000000 | 1.000000 | 0.000000 | # [RT Field1] Versor
Field1_kind= "SOFTSIN" # [NL ExtF] Kind(SIN|SOFTSIN|RES|ANTIRES|GAUSS|DELTA|QSSIN)

The line <code>|1.000000 | 1.000000 | 0.000000 | # [RT Field1] Versor</code> referees to the direction of the external field (x,y,0). At present only an external field is present but the code can be easily generalized to deal with more fields.
The default parameters of Yambo/Lumen are already tuned for second-harmonic generation, so the only thing you have to change is the band range, between 3 and 6 and the energy range between 1.0-5.0 eV and the number of energy steps in this interval that we set to 10. Notice that you cannot set to zero the lowest value of the energy range because this will requires a simulation that lasts infinite time, see below. Finally, consider that Yambo performs a separate calculation for each frequency, so if you set many energy steps the computational time grows linearly with this number.
Notice that we set <code>NLverbosity= "high"</code> in this way the code will produce a file for each laser frequency containing the time dependent polarization.
Run <code>yambo_nl</code>. Calculations will take about fifteen minutes on a single processor PC, you have time to study the next section that explains how non-linear response is extracted from the real-time simulations.
In order to speed up calculations, you can run them in parallel.

==Non-linear response with Yambo==

In order to calculate the non-linear response, the system is excited with different laser fields with a sinusoidal shape at frequencies <math>\omega_1, \omega_2, .... , \omega_n </math> determined by the parameters [[Variables#NLEnRangev|NLEnRange]] and [[Variables#NLEnSteps|NLEnSteps]]. A dephasing term is added to the Hamiltonian <math>\gamma = </math>[[Variables#NLDamping|NLDamping]] to simulate a finite broadening and to remove the eigenmodes that are excited by the sudden turning on of the external field. After the dephasing time the outgoing signal is analyzed to extract the non-linear coefficients as shown in the figure below:

[[File:Pt analysis.png|600px|center|Non-linear response analysis]]

In the report file <code>r_nlinear</code> you will find the length of the dephasing part and of the sampling one:

Dephasing Time [fs]: 52.65695
Sampling Time [fs]: 4.18566
Total simulation time [fs]: 56.84262
The length of the dephasing interval is inversely proportional to the damping term <math>T_{depth} \simeq 1/\gamma</math> while the length of the sampling is dictated by the smallest frequency we are interested in: <math>T_{samp} \simeq 1/\omega_1 </math>. For this reason if <math> \omega_1=0 </math> or <math> \gamma = 0 </math> simulation time goes to infinity. The response at zero frequency can be calculated as limit of small frequency perturbation.
You can have a look to the file <code>src/nloptics/NL_initialize.F</code> to see how simulation lengths are defined.
Calculations can take some time, run them in parallel, the best number of processors = number of frequencies or reduce the number of frequencies step in the SHG.

==Analysis of the results==

In the sampling region we suppose that the polarization can be written as: <math>\bf{P}(t) = \sum_{n=-\infty}^{+\infty} \bf{p}_n e^{-i\omega_n t} </math> where the coefficient <math>\bf{p}_1,...,\bf{p}_n </math> are related to <math>\chi^{(1)},...,\chi^{(n)} </math>. We sample the polarization signal at different times and invert the previous equation by truncating the sum at a finite order <ref>[https://arxiv.org/abs/1309.4012 Nonlinear optics from an ab initio approach by means of the dynamical Berry phase: Application to second- and third-harmonic generation in semiconductors], C. Attaccalite and M. Grüning, Phys. Rev. B 88, 235113(2013)</ref>.
This is done with the command <code>ypp_nl -u</code> that automatically produce an input with the correct values:

nonlinear # [R] NonLinear Optics Post-Processing
Xorder= 4 # Max order of the response functions
% TimeRange
52.65695 | -1.00000 | fs # Time-window where processing is done
%
ETStpsRt= 200 # Total Energy steps
% EnRngeRt
0.00000 | 10.00000 | eV # Energy range
%
DampMode= "NONE" # Damping type ( NONE | LORENTZIAN | GAUSSIAN )
DampFactor= 0.10000 eV # Damping parameter

where <code>Xorder</code> is the order where the previous sum is truncated, and the TimeRange specifies the sampling region. Notice that differently from the first tutorial, in this case, we do not need Damping in <code>ypp_nl</code> because we already included it in the real-time dynamics. Run <code>ypp_nl</code> and it will produce a file called <code>o.YPP-X_probe_order_2</code>. This file contains the different components of <math>\chi^2_{xy*} </math> and in particular the columns 6 and 7 correspond to the imaginary and real part of <math>\chi^2_{xyz} </math>. You can plot the result with gnuplot and the command:

p 'o.YPP-X_probe_order_2' u 1:(sqrt($6**2+$7**2)) w lp ps 1.5 pt 7 lw 1.5

the result should look like

[[File:AlAs results.png|700px|center|SHG in AlAs]]

and compare it with the <math> \chi^2_{zxy} </math> calculated with more frequencies and with the converged result on a <math> 18x18x18</math> k-point grid and bands between 2 and 10. In the figure you can find also the comparison with the results of Ref. <ref>Luppi et al. [https://arxiv.org/abs/1006.2649 PRB B, '''82''', 235201(2010)]</ref>.
Notice that the QuantumEspresso results are slightly different from the Abinit ones. This is due to the different pseudo-potential employed in the calculations if pseudopotentials were the same calculation would have been identical. You can download the script to generate this plot and the converged results [http://www.attaccalite.com/lumen/tutorials/AlAs/AlAs_results.tgz here].

'''Notice that''' : the following parameters are not used in the non-linear response analysis: <code> EnRngeRt</code>, <code>ETStpsRt</code>, <code>DampMode</code>, <code>DampFactor</code>. The damping factor is set directly in the real-time simulation.

'''System of units in Non-linear Optics''': notice that in Yambo the non-linear response functions are in the gaussian system of units, for example the <math> \chi^2 (\omega) </math> is in cm/statvolt. In order to convert the non-linear coefficients between different system of units, you can have a look at the [https://www.attaccalite.com/tutorials_yambo/Appendix_C_Boyd.pdf Appendix C] of the book [https://www.elsevier.com/books/nonlinear-optics/boyd/978-0-12-369470-6 "Non-linear optics" by Robert W. Boyd].

More tutorials on non-linear response (Third harmonic generation, parallelization, spin-orbit etc..) with Yambo can be found here: [http://www.attaccalite.com/lumen/tutorials.html More Tutorials]. 

==Analysis of the results using YamboPy==
The analysis of the result performed in the previous section using <code>ypp_nl</code> can be performed using python script [https://github.com/yambo-code/yambopy YamboPy]. 
In YamboPy we implemented all necessary functions to reads the Yambo databases and post-process the results. Here we show how to get the SHG signal from the previous
simulations. We suppose you correctly installed <code>YamboPy</code> on your PC. Go in the folder where you ran non-linear calculation and type in the python:
 
from yambopy import *
NLDB=YamboNLDB()
pol =NLDB.Polarization[0]
time=NLDB.IO_TIME_points

in this way you read all the Non-linear databases. If your runs are in a different folder then the 'SAVE' one you can specify it using the command:
NLDB=YamboNLDB(calc='MYJOB')

now in the array <code>pol</code> you have all the polarization for all laser frequencies in the three Cartesian directions, while the variable <code>time</code> contains all the time series of your simulation.
Now you can get the non-linear response with the command:

Harmonic_Analysis(NLDB,X_order=4)

this command will perform a Fourier analysis of the results in the same way of <code>ypp_nl</code> and generate new files with all the requested harmonics ''o.YamboPy-X_probe_order_1'', ''o.YamboPy-X_probe_order_2'' etc...
equivalent to the one generated by <code>ypp_nl</code>. Results can be plot with gnuplot using the command:

p 'o.YamboPy-X_probe_order_2' u 1:(sqrt($6**2+$7**2)) w lp ps 1.5 pt 7 lw 1.5

The script that performs non-linear analysis can be found in <code>yambopy/nl/harmonic_analysis.py</code>. We strongly advice you to have a look to this script and modify it according
to your needs and in order to extract other non-linear response functions.

==How to choose the external field direction for the different X2==

In the X2abc response you have three field directions. The two components ''b'' and ''c'' are determined by the external field and the third ''a''
is the direction where you measure the response. 

The external field in Yambo is set using the variable
% Field1_Dir
1.000000 | 0.000000 | 0.000000 | # [NL ExtF] Versor .
%

For example if you set in Yambo field direction as:

1.0 | 0.0 | 0.0 | ---> you calculate all components X2*xx
0.0 | 1.0 | 0.0 | ---> you calculate all components X2*yy
0.0 | 0.0 | 1.0 | ---> you calculate all components X2*zz

the * correspond to the different direction in the response file <code>o.YPP-X_probe_order_2</code>.
In the <code>o.YPP-X_probe_order_2</code> you have seven columns:

The first column is the energy [[omega]],
the 2nd and 3rd columns are the imaginary and real part of X2x**
the 4th and 5th columns are the imaginary and real part of X2y**
the 6th and 7th columns are the imaginary and real part of X2z**

where the ** are the direction of the incoming field, see above.

For example if you want to calculate the X2zxx you put the external field in the direction <code> 1.0 | 0.0 | 0.0 |</code>
and then plot the column 6 and 7 of the <code>o.YPP-X_probe_order_2</code> file. 

'''Nota bene:''' if you change the direction of the external field you have to remove the corresponding symmetries as explained in the tutorial
on [[Prerequisites for Real Time_propagation with Yambo#Reduce symmetries real-time linear response tutorial]].

In order to get the other components of the X2 the calculation are more involved. For example if you put field in the

1.0 | 1.0 | 0.0 |

this corresponds to <math>E(t)=\frac{1}{\sqrt{2}} [ E_x(t) + E_y(t) ]</math> and so at the second order you will have <math>E^2(t)=\frac{1}{2} [ E^2_x(t) + E^2_y(t) + E_x(t) E_y(t) + E_y(t) E_x(t) ]</math> 
this means that the X2 in the <code>o.YPP-X_probe_order_2</code> will correspond to a linear combination of the following different response functions. 
For example in the the 2nd and 3rd columns are the imaginary and real part of: 

<math>\chi^2_{x**}=\frac{1}{2} \left [\chi^2_{xxx}+\chi^2_{xyy} + \chi^2_{xxy} + \chi^2_{xyx} \right ]</math>

the same for the other column replacing the first <code>x</code> for <code>y,z</code>.
If you know that some components are zero this allow you to extract the corresponding off-diagonal part of <math>\chi^2_{abc}</math> otherwise you have to perform different calculations to get the component you are interested in. Hereafter we present a simple example of monolayer hBN (m-hBN). In m-hBN there is only a non-zero component of the $\chi^2$ and all the others are related by symmetry, namely:

==Non-linear response of low-dimensional structures: 2D or 1D ==

The Yambo code is a 3D periodic code, so when you want to study a low-dimensional system 2D or 1D, you have to use a supercell approach.
For example to simulate the non-linear response in a 2D-crystal one, can put the crystal in the xy plane and choose a larger distance in the z-direction
in order to reduce the interaction between the periodic replica. Clearly in this case k-point sampling will be only in the x,y directions.
For calculations on this type of systems, these two warnings must be taken into account:

* if you calculate GW corrections or include electron-hole interaction in the linear/non-linear response it is a good idea to use a '''Coulomb cutoff''', similar to the 2D BSE case [http://www.yambo-code.org/wiki/index.php?title=How_to_treat_low_dimensional_systems How to treat low dimensional systems]. You can add the cutoff just adding the "-r" in the input generation.

* the calculation of SHG and THG are always performed respect to the supercell, therefore you have to '''re-scale''' the result to the effective thickness of the layer, usually the inter-layer distance of the corresponding bulk material for 2D systems: <math>\chi_{rescaled}(\omega) = L_z/d_{eff} \cdot \chi(\omega) </math> where <math>L_z</math> is the z-dimension of the supercell, and <math>d_{eff}</math> is the effective thickness of the 2D system.

'''Nota bene''': Non-linear response along non-periodic directions is not implemented in Yambo, the code will print zero in these directions for all response functions. We plan to implement it in a future version of the code.

==References==
<references />

==Links for schools==
* Back to [[Rome 2023#Tutorials]]
* Back to [[ICTP2020]]

 
{| style="width:100%" border="1"
|style="width:25%; text-align:left"|Prev: [[Linear response from real time simulations|Linear response from real time simulations]]
|style="width:45%; text-align:center"|Now: [[ICTP2020|ICTP Tutorials]] --> [[Real time approach to non-linear response|Non Linear Response]]
|style="width:50%; text-align:left"|Next: [[Correlation effects in the non-linear response|Correlation effects in the non-linear response ]]
|-
|}

Real time approach to non-linear response (SHG)

2025-09-27T08:29:36Z

Attacc: /* How to choose the external field direction for the different X2 */

== Second Harmonic Generation in AlAs ==
In this tutorial, we will calculate the second harmonic generation of bulk AlAs, the Yambo databases can be downloaded here: [https://media.yambo-code.eu/educational/tutorials/files/AlAs_DBs.tar.gz AlAs_DBs.tar.gz] (10 MB). The first steps of this tutorials are the same as the one on [http://www.yambo-code.eu/wiki/index.php?title=Prerequisites_for_Real_Time_propagation_with_Yambo Prerequisites for Real-Time propagation with Yambo] with the only difference that we will work on AlAs and we will consider an external field in the direction <code> 1.000000 | 1.000000 | 0.000000 |</code>. The DFT input are available here: [https://media.yambo-code.eu/educational/tutorials/files/AlAs_abinit.tar.gz ABINIT] or [https://media.yambo-code.eu/educational/tutorials/files/AlAs_pwscf.tar.gz QuantumEspresso].
You can run the DFT calculation with ABINIT with the command:

abinit < AlAs.in > output_AlAs

or using QuantumEspresso:

pw.x -inp AlAs.scf.in > output_scf
pw.x -inp AlAs.nscf.in > output_scf

and then import the ABINIT wave-function with the command:

a2y -F AlAso_DS2_WFK.nc

and the QuantumEspresso one, in the folder AlAs.save with the command:

p2y
Now we consider an external field in the <code>[1,1,0]</code> direction and remove symmetries not compatible with this field, as explained in the tutorial [http://www.yambo-code.eu/wiki/index.php?title=Prerequisites_for_Real_Time_propagation_with_Yambo Prerequisites for Real-Time propagation with Yambo].

==Real-time simulation for the SHG==

You can generate the input file with the command <code>yambo_nl -u n</code>:

nloptics # [R NL] Non-linear optics
% NLBands
 3 | 6 | # [NL] Bands
%
NLstep= 0.0100 fs # [NL] Real Time step length
NLverbosity= "high" # [NL] Verbosity level (low | high)
NLtime=-1.000000 fs # [NL] Simulation Time
NLintegrator= "INVINT" # [NL] Integrator ("EULEREXP/RK4/RK2EXP/HEUN/INVINT/CRANKNIC")
NLCorrelation= "IPA" # [NL] Correlation ("IPA/HARTREE/TDDFT/LRC/JGM/SEX/HF")
NLLrcAlpha= 0.000000 # [NL] Long Range Correction
% NLEnRange
 1.000000 | 5.000000 | eV # [NL] Energy range
%
NLEnSteps= 5 # [NL] Energy steps
NLDamping= 0.150000 eV # [NL] Damping
% Field1_Dir
 1.000000 | 1.000000 | 0.000000 | # [RT Field1] Versor
Field1_kind= "SOFTSIN" # [NL ExtF] Kind(SIN|SOFTSIN|RES|ANTIRES|GAUSS|DELTA|QSSIN)

The line <code>|1.000000 | 1.000000 | 0.000000 | # [RT Field1] Versor</code> referees to the direction of the external field (x,y,0). At present only an external field is present but the code can be easily generalized to deal with more fields.
The default parameters of Yambo/Lumen are already tuned for second-harmonic generation, so the only thing you have to change is the band range, between 3 and 6 and the energy range between 1.0-5.0 eV and the number of energy steps in this interval that we set to 10. Notice that you cannot set to zero the lowest value of the energy range because this will requires a simulation that lasts infinite time, see below. Finally, consider that Yambo performs a separate calculation for each frequency, so if you set many energy steps the computational time grows linearly with this number.
Notice that we set <code>NLverbosity= "high"</code> in this way the code will produce a file for each laser frequency containing the time dependent polarization.
Run <code>yambo_nl</code>. Calculations will take about fifteen minutes on a single processor PC, you have time to study the next section that explains how non-linear response is extracted from the real-time simulations.
In order to speed up calculations, you can run them in parallel.

==Non-linear response with Yambo==

In order to calculate the non-linear response, the system is excited with different laser fields with a sinusoidal shape at frequencies <math>\omega_1, \omega_2, .... , \omega_n </math> determined by the parameters [[Variables#NLEnRangev|NLEnRange]] and [[Variables#NLEnSteps|NLEnSteps]]. A dephasing term is added to the Hamiltonian <math>\gamma = </math>[[Variables#NLDamping|NLDamping]] to simulate a finite broadening and to remove the eigenmodes that are excited by the sudden turning on of the external field. After the dephasing time the outgoing signal is analyzed to extract the non-linear coefficients as shown in the figure below:

[[File:Pt analysis.png|600px|center|Non-linear response analysis]]

In the report file <code>r_nlinear</code> you will find the length of the dephasing part and of the sampling one:

Dephasing Time [fs]: 52.65695
Sampling Time [fs]: 4.18566
Total simulation time [fs]: 56.84262
The length of the dephasing interval is inversely proportional to the damping term <math>T_{depth} \simeq 1/\gamma</math> while the length of the sampling is dictated by the smallest frequency we are interested in: <math>T_{samp} \simeq 1/\omega_1 </math>. For this reason if <math> \omega_1=0 </math> or <math> \gamma = 0 </math> simulation time goes to infinity. The response at zero frequency can be calculated as limit of small frequency perturbation.
You can have a look to the file <code>src/nloptics/NL_initialize.F</code> to see how simulation lengths are defined.
Calculations can take some time, run them in parallel, the best number of processors = number of frequencies or reduce the number of frequencies step in the SHG.

==Analysis of the results==

In the sampling region we suppose that the polarization can be written as: <math>\bf{P}(t) = \sum_{n=-\infty}^{+\infty} \bf{p}_n e^{-i\omega_n t} </math> where the coefficient <math>\bf{p}_1,...,\bf{p}_n </math> are related to <math>\chi^{(1)},...,\chi^{(n)} </math>. We sample the polarization signal at different times and invert the previous equation by truncating the sum at a finite order <ref>[https://arxiv.org/abs/1309.4012 Nonlinear optics from an ab initio approach by means of the dynamical Berry phase: Application to second- and third-harmonic generation in semiconductors], C. Attaccalite and M. Grüning, Phys. Rev. B 88, 235113(2013)</ref>.
This is done with the command <code>ypp_nl -u</code> that automatically produce an input with the correct values:

nonlinear # [R] NonLinear Optics Post-Processing
Xorder= 4 # Max order of the response functions
% TimeRange
52.65695 | -1.00000 | fs # Time-window where processing is done
%
ETStpsRt= 200 # Total Energy steps
% EnRngeRt
0.00000 | 10.00000 | eV # Energy range
%
DampMode= "NONE" # Damping type ( NONE | LORENTZIAN | GAUSSIAN )
DampFactor= 0.10000 eV # Damping parameter

where <code>Xorder</code> is the order where the previous sum is truncated, and the TimeRange specifies the sampling region. Notice that differently from the first tutorial, in this case, we do not need Damping in <code>ypp_nl</code> because we already included it in the real-time dynamics. Run <code>ypp_nl</code> and it will produce a file called <code>o.YPP-X_probe_order_2</code>. This file contains the different components of <math>\chi^2_{xy*} </math> and in particular the columns 6 and 7 correspond to the imaginary and real part of <math>\chi^2_{xyz} </math>. You can plot the result with gnuplot and the command:

p 'o.YPP-X_probe_order_2' u 1:(sqrt($6**2+$7**2)) w lp ps 1.5 pt 7 lw 1.5

the result should look like

[[File:AlAs results.png|700px|center|SHG in AlAs]]

and compare it with the <math> \chi^2_{zxy} </math> calculated with more frequencies and with the converged result on a <math> 18x18x18</math> k-point grid and bands between 2 and 10. In the figure you can find also the comparison with the results of Ref. <ref>Luppi et al. [https://arxiv.org/abs/1006.2649 PRB B, '''82''', 235201(2010)]</ref>.
Notice that the QuantumEspresso results are slightly different from the Abinit ones. This is due to the different pseudo-potential employed in the calculations if pseudopotentials were the same calculation would have been identical. You can download the script to generate this plot and the converged results [http://www.attaccalite.com/lumen/tutorials/AlAs/AlAs_results.tgz here].

'''Notice that''' : the following parameters are not used in the non-linear response analysis: <code> EnRngeRt</code>, <code>ETStpsRt</code>, <code>DampMode</code>, <code>DampFactor</code>. The damping factor is set directly in the real-time simulation.

'''System of units in Non-linear Optics''': notice that in Yambo the non-linear response functions are in the gaussian system of units, for example the <math> \chi^2 (\omega) </math> is in cm/statvolt. In order to convert the non-linear coefficients between different system of units, you can have a look at the [https://www.attaccalite.com/tutorials_yambo/Appendix_C_Boyd.pdf Appendix C] of the book [https://www.elsevier.com/books/nonlinear-optics/boyd/978-0-12-369470-6 "Non-linear optics" by Robert W. Boyd].

More tutorials on non-linear response (Third harmonic generation, parallelization, spin-orbit etc..) with Yambo can be found here: [http://www.attaccalite.com/lumen/tutorials.html More Tutorials]. 

==Analysis of the results using YamboPy==
The analysis of the result performed in the previous section using <code>ypp_nl</code> can be performed using python script [https://github.com/yambo-code/yambopy YamboPy]. 
In YamboPy we implemented all necessary functions to reads the Yambo databases and post-process the results. Here we show how to get the SHG signal from the previous
simulations. We suppose you correctly installed <code>YamboPy</code> on your PC. Go in the folder where you ran non-linear calculation and type in the python:
 
from yambopy import *
NLDB=YamboNLDB()
pol =NLDB.Polarization[0]
time=NLDB.IO_TIME_points

in this way you read all the Non-linear databases. If your runs are in a different folder then the 'SAVE' one you can specify it using the command:
NLDB=YamboNLDB(calc='MYJOB')

now in the array <code>pol</code> you have all the polarization for all laser frequencies in the three Cartesian directions, while the variable <code>time</code> contains all the time series of your simulation.
Now you can get the non-linear response with the command:

Harmonic_Analysis(NLDB,X_order=4)

this command will perform a Fourier analysis of the results in the same way of <code>ypp_nl</code> and generate new files with all the requested harmonics ''o.YamboPy-X_probe_order_1'', ''o.YamboPy-X_probe_order_2'' etc...
equivalent to the one generated by <code>ypp_nl</code>. Results can be plot with gnuplot using the command:

p 'o.YamboPy-X_probe_order_2' u 1:(sqrt($6**2+$7**2)) w lp ps 1.5 pt 7 lw 1.5

The script that performs non-linear analysis can be found in <code>yambopy/nl/harmonic_analysis.py</code>. We strongly advice you to have a look to this script and modify it according
to your needs and in order to extract other non-linear response functions.

==How to choose the external field direction for the different X2==

In the X2abc response you have three field directions. The two components ''b'' and ''c'' are determined by the external field and the third ''a''
is the direction where you measure the response. 

The external field in Yambo is set using the variable
% Field1_Dir
1.000000 | 0.000000 | 0.000000 | # [NL ExtF] Versor .
%

For example if you set in Yambo field direction as:

1.0 | 0.0 | 0.0 | ---> you calculate all components X2*xx
0.0 | 1.0 | 0.0 | ---> you calculate all components X2*yy
0.0 | 0.0 | 1.0 | ---> you calculate all components X2*zz

the * correspond to the different direction in the response file <code>o.YPP-X_probe_order_2</code>.
In the <code>o.YPP-X_probe_order_2</code> you have seven columns:

The first column is the energy [[omega]],
the 2nd and 3rd columns are the imaginary and real part of X2x**
the 4th and 5th columns are the imaginary and real part of X2y**
the 6th and 7th columns are the imaginary and real part of X2z**

where the ** are the direction of the incoming field, see above.

For example if you want to calculate the X2zxx you put the external field in the direction <code> 1.0 | 0.0 | 0.0 |</code>
and then plot the column 6 and 7 of the <code>o.YPP-X_probe_order_2</code> file. 

'''Nota bene:''' if you change the direction of the external field you have to remove the corresponding symmetries as explained in the tutorial
on [[Prerequisites for Real Time_propagation with Yambo#Reduce symmetries real-time linear response tutorial]].

In order to get the other components of the X2 the calculation are more involved. For example if you put field in the

1.0 | 1.0 | 0.0 |

this corresponds to <math>E(t)=\frac{1}{\sqrt{2}} [ E_x(t) + E_y(t) ]</math> and so at the second order you will have <math>E^2(t)=\frac{1}{2} [ E^2_x(t) + E^2_y(t) + E_x(t) E_y(t) + E_y(t) E_x(t) ]</math> 
this means that the X2 in the <code>o.YPP-X_probe_order_2</code> will correspond to a linear combination of the following different response functions. 
For example in the the 2nd and 3rd columns are the imaginary and real part of: 

<math>\chi^2_{x**}=\frac{1}{2} \left [\chi^2_{xxx}+\chi^2_{xyy} + \chi^2_{xxy} + \chi^2_{xyx} \right ]</math>

the same for the other column replacing the first <code>x</code> for <code>y,z</code>.
If you know that some components are zero this allow you to extract the corresponding off-diagonal part of <math>\chi^2_{abc}</math> otherwise you have to perform different calculations to get the component you are interested in. Hereafter we present a simple example of monolayer hBN.

==Non-linear response of low-dimensional structures: 2D or 1D ==

The Yambo code is a 3D periodic code, so when you want to study a low-dimensional system 2D or 1D, you have to use a supercell approach.
For example to simulate the non-linear response in a 2D-crystal one, can put the crystal in the xy plane and choose a larger distance in the z-direction
in order to reduce the interaction between the periodic replica. Clearly in this case k-point sampling will be only in the x,y directions.
For calculations on this type of systems, these two warnings must be taken into account:

* if you calculate GW corrections or include electron-hole interaction in the linear/non-linear response it is a good idea to use a '''Coulomb cutoff''', similar to the 2D BSE case [http://www.yambo-code.org/wiki/index.php?title=How_to_treat_low_dimensional_systems How to treat low dimensional systems]. You can add the cutoff just adding the "-r" in the input generation.

* the calculation of SHG and THG are always performed respect to the supercell, therefore you have to '''re-scale''' the result to the effective thickness of the layer, usually the inter-layer distance of the corresponding bulk material for 2D systems: <math>\chi_{rescaled}(\omega) = L_z/d_{eff} \cdot \chi(\omega) </math> where <math>L_z</math> is the z-dimension of the supercell, and <math>d_{eff}</math> is the effective thickness of the 2D system.

'''Nota bene''': Non-linear response along non-periodic directions is not implemented in Yambo, the code will print zero in these directions for all response functions. We plan to implement it in a future version of the code.

==References==
<references />

==Links for schools==
* Back to [[Rome 2023#Tutorials]]
* Back to [[ICTP2020]]

 
{| style="width:100%" border="1"
|style="width:25%; text-align:left"|Prev: [[Linear response from real time simulations|Linear response from real time simulations]]
|style="width:45%; text-align:center"|Now: [[ICTP2020|ICTP Tutorials]] --> [[Real time approach to non-linear response|Non Linear Response]]
|style="width:50%; text-align:left"|Next: [[Correlation effects in the non-linear response|Correlation effects in the non-linear response ]]
|-
|}

Real time approach to non-linear response (SHG)

2025-09-27T08:22:51Z

Attacc: /* How to choose the external field direction for the different X2 */

== Second Harmonic Generation in AlAs ==
In this tutorial, we will calculate the second harmonic generation of bulk AlAs, the Yambo databases can be downloaded here: [https://media.yambo-code.eu/educational/tutorials/files/AlAs_DBs.tar.gz AlAs_DBs.tar.gz] (10 MB). The first steps of this tutorials are the same as the one on [http://www.yambo-code.eu/wiki/index.php?title=Prerequisites_for_Real_Time_propagation_with_Yambo Prerequisites for Real-Time propagation with Yambo] with the only difference that we will work on AlAs and we will consider an external field in the direction <code> 1.000000 | 1.000000 | 0.000000 |</code>. The DFT input are available here: [https://media.yambo-code.eu/educational/tutorials/files/AlAs_abinit.tar.gz ABINIT] or [https://media.yambo-code.eu/educational/tutorials/files/AlAs_pwscf.tar.gz QuantumEspresso].
You can run the DFT calculation with ABINIT with the command:

abinit < AlAs.in > output_AlAs

or using QuantumEspresso:

pw.x -inp AlAs.scf.in > output_scf
pw.x -inp AlAs.nscf.in > output_scf

and then import the ABINIT wave-function with the command:

a2y -F AlAso_DS2_WFK.nc

and the QuantumEspresso one, in the folder AlAs.save with the command:

p2y
Now we consider an external field in the <code>[1,1,0]</code> direction and remove symmetries not compatible with this field, as explained in the tutorial [http://www.yambo-code.eu/wiki/index.php?title=Prerequisites_for_Real_Time_propagation_with_Yambo Prerequisites for Real-Time propagation with Yambo].

==Real-time simulation for the SHG==

You can generate the input file with the command <code>yambo_nl -u n</code>:

nloptics # [R NL] Non-linear optics
% NLBands
 3 | 6 | # [NL] Bands
%
NLstep= 0.0100 fs # [NL] Real Time step length
NLverbosity= "high" # [NL] Verbosity level (low | high)
NLtime=-1.000000 fs # [NL] Simulation Time
NLintegrator= "INVINT" # [NL] Integrator ("EULEREXP/RK4/RK2EXP/HEUN/INVINT/CRANKNIC")
NLCorrelation= "IPA" # [NL] Correlation ("IPA/HARTREE/TDDFT/LRC/JGM/SEX/HF")
NLLrcAlpha= 0.000000 # [NL] Long Range Correction
% NLEnRange
 1.000000 | 5.000000 | eV # [NL] Energy range
%
NLEnSteps= 5 # [NL] Energy steps
NLDamping= 0.150000 eV # [NL] Damping
% Field1_Dir
 1.000000 | 1.000000 | 0.000000 | # [RT Field1] Versor
Field1_kind= "SOFTSIN" # [NL ExtF] Kind(SIN|SOFTSIN|RES|ANTIRES|GAUSS|DELTA|QSSIN)

The line <code>|1.000000 | 1.000000 | 0.000000 | # [RT Field1] Versor</code> referees to the direction of the external field (x,y,0). At present only an external field is present but the code can be easily generalized to deal with more fields.
The default parameters of Yambo/Lumen are already tuned for second-harmonic generation, so the only thing you have to change is the band range, between 3 and 6 and the energy range between 1.0-5.0 eV and the number of energy steps in this interval that we set to 10. Notice that you cannot set to zero the lowest value of the energy range because this will requires a simulation that lasts infinite time, see below. Finally, consider that Yambo performs a separate calculation for each frequency, so if you set many energy steps the computational time grows linearly with this number.
Notice that we set <code>NLverbosity= "high"</code> in this way the code will produce a file for each laser frequency containing the time dependent polarization.
Run <code>yambo_nl</code>. Calculations will take about fifteen minutes on a single processor PC, you have time to study the next section that explains how non-linear response is extracted from the real-time simulations.
In order to speed up calculations, you can run them in parallel.

==Non-linear response with Yambo==

In order to calculate the non-linear response, the system is excited with different laser fields with a sinusoidal shape at frequencies <math>\omega_1, \omega_2, .... , \omega_n </math> determined by the parameters [[Variables#NLEnRangev|NLEnRange]] and [[Variables#NLEnSteps|NLEnSteps]]. A dephasing term is added to the Hamiltonian <math>\gamma = </math>[[Variables#NLDamping|NLDamping]] to simulate a finite broadening and to remove the eigenmodes that are excited by the sudden turning on of the external field. After the dephasing time the outgoing signal is analyzed to extract the non-linear coefficients as shown in the figure below:

[[File:Pt analysis.png|600px|center|Non-linear response analysis]]

In the report file <code>r_nlinear</code> you will find the length of the dephasing part and of the sampling one:

Dephasing Time [fs]: 52.65695
Sampling Time [fs]: 4.18566
Total simulation time [fs]: 56.84262
The length of the dephasing interval is inversely proportional to the damping term <math>T_{depth} \simeq 1/\gamma</math> while the length of the sampling is dictated by the smallest frequency we are interested in: <math>T_{samp} \simeq 1/\omega_1 </math>. For this reason if <math> \omega_1=0 </math> or <math> \gamma = 0 </math> simulation time goes to infinity. The response at zero frequency can be calculated as limit of small frequency perturbation.
You can have a look to the file <code>src/nloptics/NL_initialize.F</code> to see how simulation lengths are defined.
Calculations can take some time, run them in parallel, the best number of processors = number of frequencies or reduce the number of frequencies step in the SHG.

==Analysis of the results==

In the sampling region we suppose that the polarization can be written as: <math>\bf{P}(t) = \sum_{n=-\infty}^{+\infty} \bf{p}_n e^{-i\omega_n t} </math> where the coefficient <math>\bf{p}_1,...,\bf{p}_n </math> are related to <math>\chi^{(1)},...,\chi^{(n)} </math>. We sample the polarization signal at different times and invert the previous equation by truncating the sum at a finite order <ref>[https://arxiv.org/abs/1309.4012 Nonlinear optics from an ab initio approach by means of the dynamical Berry phase: Application to second- and third-harmonic generation in semiconductors], C. Attaccalite and M. Grüning, Phys. Rev. B 88, 235113(2013)</ref>.
This is done with the command <code>ypp_nl -u</code> that automatically produce an input with the correct values:

nonlinear # [R] NonLinear Optics Post-Processing
Xorder= 4 # Max order of the response functions
% TimeRange
52.65695 | -1.00000 | fs # Time-window where processing is done
%
ETStpsRt= 200 # Total Energy steps
% EnRngeRt
0.00000 | 10.00000 | eV # Energy range
%
DampMode= "NONE" # Damping type ( NONE | LORENTZIAN | GAUSSIAN )
DampFactor= 0.10000 eV # Damping parameter

where <code>Xorder</code> is the order where the previous sum is truncated, and the TimeRange specifies the sampling region. Notice that differently from the first tutorial, in this case, we do not need Damping in <code>ypp_nl</code> because we already included it in the real-time dynamics. Run <code>ypp_nl</code> and it will produce a file called <code>o.YPP-X_probe_order_2</code>. This file contains the different components of <math>\chi^2_{xy*} </math> and in particular the columns 6 and 7 correspond to the imaginary and real part of <math>\chi^2_{xyz} </math>. You can plot the result with gnuplot and the command:

p 'o.YPP-X_probe_order_2' u 1:(sqrt($6**2+$7**2)) w lp ps 1.5 pt 7 lw 1.5

the result should look like

[[File:AlAs results.png|700px|center|SHG in AlAs]]

and compare it with the <math> \chi^2_{zxy} </math> calculated with more frequencies and with the converged result on a <math> 18x18x18</math> k-point grid and bands between 2 and 10. In the figure you can find also the comparison with the results of Ref. <ref>Luppi et al. [https://arxiv.org/abs/1006.2649 PRB B, '''82''', 235201(2010)]</ref>.
Notice that the QuantumEspresso results are slightly different from the Abinit ones. This is due to the different pseudo-potential employed in the calculations if pseudopotentials were the same calculation would have been identical. You can download the script to generate this plot and the converged results [http://www.attaccalite.com/lumen/tutorials/AlAs/AlAs_results.tgz here].

'''Notice that''' : the following parameters are not used in the non-linear response analysis: <code> EnRngeRt</code>, <code>ETStpsRt</code>, <code>DampMode</code>, <code>DampFactor</code>. The damping factor is set directly in the real-time simulation.

'''System of units in Non-linear Optics''': notice that in Yambo the non-linear response functions are in the gaussian system of units, for example the <math> \chi^2 (\omega) </math> is in cm/statvolt. In order to convert the non-linear coefficients between different system of units, you can have a look at the [https://www.attaccalite.com/tutorials_yambo/Appendix_C_Boyd.pdf Appendix C] of the book [https://www.elsevier.com/books/nonlinear-optics/boyd/978-0-12-369470-6 "Non-linear optics" by Robert W. Boyd].

More tutorials on non-linear response (Third harmonic generation, parallelization, spin-orbit etc..) with Yambo can be found here: [http://www.attaccalite.com/lumen/tutorials.html More Tutorials]. 

==Analysis of the results using YamboPy==
The analysis of the result performed in the previous section using <code>ypp_nl</code> can be performed using python script [https://github.com/yambo-code/yambopy YamboPy]. 
In YamboPy we implemented all necessary functions to reads the Yambo databases and post-process the results. Here we show how to get the SHG signal from the previous
simulations. We suppose you correctly installed <code>YamboPy</code> on your PC. Go in the folder where you ran non-linear calculation and type in the python:
 
from yambopy import *
NLDB=YamboNLDB()
pol =NLDB.Polarization[0]
time=NLDB.IO_TIME_points

in this way you read all the Non-linear databases. If your runs are in a different folder then the 'SAVE' one you can specify it using the command:
NLDB=YamboNLDB(calc='MYJOB')

now in the array <code>pol</code> you have all the polarization for all laser frequencies in the three Cartesian directions, while the variable <code>time</code> contains all the time series of your simulation.
Now you can get the non-linear response with the command:

Harmonic_Analysis(NLDB,X_order=4)

this command will perform a Fourier analysis of the results in the same way of <code>ypp_nl</code> and generate new files with all the requested harmonics ''o.YamboPy-X_probe_order_1'', ''o.YamboPy-X_probe_order_2'' etc...
equivalent to the one generated by <code>ypp_nl</code>. Results can be plot with gnuplot using the command:

p 'o.YamboPy-X_probe_order_2' u 1:(sqrt($6**2+$7**2)) w lp ps 1.5 pt 7 lw 1.5

The script that performs non-linear analysis can be found in <code>yambopy/nl/harmonic_analysis.py</code>. We strongly advice you to have a look to this script and modify it according
to your needs and in order to extract other non-linear response functions.

==How to choose the external field direction for the different X2==

In the X2abc response you have three field directions. The two components ''b'' and ''c'' are determined by the external field and the third ''a''
is the direction where you measure the response. 

The external field in Yambo is set using the variable
% Field1_Dir
1.000000 | 0.000000 | 0.000000 | # [NL ExtF] Versor .
%

For example if you set in Yambo field direction as:

1.0 | 0.0 | 0.0 | ---> you calculate all components X2*xx
0.0 | 1.0 | 0.0 | ---> you calculate all components X2*yy
0.0 | 0.0 | 1.0 | ---> you calculate all components X2*zz

the * correspond to the different direction in the response file <code>o.YPP-X_probe_order_2</code>.
In the <code>o.YPP-X_probe_order_2</code> you have seven columns:

The first column is the energy [[omega]],
the 2nd and 3rd columns are the imaginary and real part of X2x**
the 4th and 5th columns are the imaginary and real part of X2y**
the 6th and 7th columns are the imaginary and real part of X2z**

where the ** are the direction of the incoming field, see above.

For example if you want to calculate the X2zxx you put the external field in the direction <code> 1.0 | 0.0 | 0.0 |</code>
and then plot the column 6 and 7 of the <code>o.YPP-X_probe_order_2</code> file. 

'''Nota bene:''' if you change the direction of the external field you have to remove the corresponding symmetries as explained in the tutorial
on [[Prerequisites for Real Time_propagation with Yambo#Reduce symmetries real-time linear response tutorial]].

In order to get the other components of the X2 the calculation are more involved. For example if you put field in the

1.0 | 1.0 | 0.0 |

this corresponds to <math>E(t)=\frac{1}{\sqrt{2}} [ E_x(t) + E_y(t) ]</math> and so at the second order you will have <math>E^2(t)=\frac{1}{2} [ E^2_x(t) + E^2_y(t) + E_x(t) E_y(t) + E_y(t) E_x(t) ]</math> 
this means that the X2 in the <code>o.YPP-X_probe_order_2</code> will correspond to a linear combination of the following different response functions. 
For example in the the 2nd and 3rd columns are the imaginary and real part of: 

<math>\chi^2_{x**}=\frac{1}{2} \left [\chi^2_{xxx}+\chi^2_{xyy} + \chi^2_{xxy} + \chi^2_{xyx} \right ]</math>

the same for the other column replacing the first <code>x</code> for <code>y,z</code>.

==Non-linear response of low-dimensional structures: 2D or 1D ==

The Yambo code is a 3D periodic code, so when you want to study a low-dimensional system 2D or 1D, you have to use a supercell approach.
For example to simulate the non-linear response in a 2D-crystal one, can put the crystal in the xy plane and choose a larger distance in the z-direction
in order to reduce the interaction between the periodic replica. Clearly in this case k-point sampling will be only in the x,y directions.
For calculations on this type of systems, these two warnings must be taken into account:

* if you calculate GW corrections or include electron-hole interaction in the linear/non-linear response it is a good idea to use a '''Coulomb cutoff''', similar to the 2D BSE case [http://www.yambo-code.org/wiki/index.php?title=How_to_treat_low_dimensional_systems How to treat low dimensional systems]. You can add the cutoff just adding the "-r" in the input generation.

* the calculation of SHG and THG are always performed respect to the supercell, therefore you have to '''re-scale''' the result to the effective thickness of the layer, usually the inter-layer distance of the corresponding bulk material for 2D systems: <math>\chi_{rescaled}(\omega) = L_z/d_{eff} \cdot \chi(\omega) </math> where <math>L_z</math> is the z-dimension of the supercell, and <math>d_{eff}</math> is the effective thickness of the 2D system.

'''Nota bene''': Non-linear response along non-periodic directions is not implemented in Yambo, the code will print zero in these directions for all response functions. We plan to implement it in a future version of the code.

==References==
<references />

==Links for schools==
* Back to [[Rome 2023#Tutorials]]
* Back to [[ICTP2020]]

 
{| style="width:100%" border="1"
|style="width:25%; text-align:left"|Prev: [[Linear response from real time simulations|Linear response from real time simulations]]
|style="width:45%; text-align:center"|Now: [[ICTP2020|ICTP Tutorials]] --> [[Real time approach to non-linear response|Non Linear Response]]
|style="width:50%; text-align:left"|Next: [[Correlation effects in the non-linear response|Correlation effects in the non-linear response ]]
|-
|}

Real time approach to non-linear response (SHG)

2025-09-27T08:22:22Z

Attacc: /* How to choose the external field direction for the different X2 */

== Second Harmonic Generation in AlAs ==
In this tutorial, we will calculate the second harmonic generation of bulk AlAs, the Yambo databases can be downloaded here: [https://media.yambo-code.eu/educational/tutorials/files/AlAs_DBs.tar.gz AlAs_DBs.tar.gz] (10 MB). The first steps of this tutorials are the same as the one on [http://www.yambo-code.eu/wiki/index.php?title=Prerequisites_for_Real_Time_propagation_with_Yambo Prerequisites for Real-Time propagation with Yambo] with the only difference that we will work on AlAs and we will consider an external field in the direction <code> 1.000000 | 1.000000 | 0.000000 |</code>. The DFT input are available here: [https://media.yambo-code.eu/educational/tutorials/files/AlAs_abinit.tar.gz ABINIT] or [https://media.yambo-code.eu/educational/tutorials/files/AlAs_pwscf.tar.gz QuantumEspresso].
You can run the DFT calculation with ABINIT with the command:

abinit < AlAs.in > output_AlAs

or using QuantumEspresso:

pw.x -inp AlAs.scf.in > output_scf
pw.x -inp AlAs.nscf.in > output_scf

and then import the ABINIT wave-function with the command:

a2y -F AlAso_DS2_WFK.nc

and the QuantumEspresso one, in the folder AlAs.save with the command:

p2y
Now we consider an external field in the <code>[1,1,0]</code> direction and remove symmetries not compatible with this field, as explained in the tutorial [http://www.yambo-code.eu/wiki/index.php?title=Prerequisites_for_Real_Time_propagation_with_Yambo Prerequisites for Real-Time propagation with Yambo].

==Real-time simulation for the SHG==

You can generate the input file with the command <code>yambo_nl -u n</code>:

nloptics # [R NL] Non-linear optics
% NLBands
 3 | 6 | # [NL] Bands
%
NLstep= 0.0100 fs # [NL] Real Time step length
NLverbosity= "high" # [NL] Verbosity level (low | high)
NLtime=-1.000000 fs # [NL] Simulation Time
NLintegrator= "INVINT" # [NL] Integrator ("EULEREXP/RK4/RK2EXP/HEUN/INVINT/CRANKNIC")
NLCorrelation= "IPA" # [NL] Correlation ("IPA/HARTREE/TDDFT/LRC/JGM/SEX/HF")
NLLrcAlpha= 0.000000 # [NL] Long Range Correction
% NLEnRange
 1.000000 | 5.000000 | eV # [NL] Energy range
%
NLEnSteps= 5 # [NL] Energy steps
NLDamping= 0.150000 eV # [NL] Damping
% Field1_Dir
 1.000000 | 1.000000 | 0.000000 | # [RT Field1] Versor
Field1_kind= "SOFTSIN" # [NL ExtF] Kind(SIN|SOFTSIN|RES|ANTIRES|GAUSS|DELTA|QSSIN)

The line <code>|1.000000 | 1.000000 | 0.000000 | # [RT Field1] Versor</code> referees to the direction of the external field (x,y,0). At present only an external field is present but the code can be easily generalized to deal with more fields.
The default parameters of Yambo/Lumen are already tuned for second-harmonic generation, so the only thing you have to change is the band range, between 3 and 6 and the energy range between 1.0-5.0 eV and the number of energy steps in this interval that we set to 10. Notice that you cannot set to zero the lowest value of the energy range because this will requires a simulation that lasts infinite time, see below. Finally, consider that Yambo performs a separate calculation for each frequency, so if you set many energy steps the computational time grows linearly with this number.
Notice that we set <code>NLverbosity= "high"</code> in this way the code will produce a file for each laser frequency containing the time dependent polarization.
Run <code>yambo_nl</code>. Calculations will take about fifteen minutes on a single processor PC, you have time to study the next section that explains how non-linear response is extracted from the real-time simulations.
In order to speed up calculations, you can run them in parallel.

==Non-linear response with Yambo==

In order to calculate the non-linear response, the system is excited with different laser fields with a sinusoidal shape at frequencies <math>\omega_1, \omega_2, .... , \omega_n </math> determined by the parameters [[Variables#NLEnRangev|NLEnRange]] and [[Variables#NLEnSteps|NLEnSteps]]. A dephasing term is added to the Hamiltonian <math>\gamma = </math>[[Variables#NLDamping|NLDamping]] to simulate a finite broadening and to remove the eigenmodes that are excited by the sudden turning on of the external field. After the dephasing time the outgoing signal is analyzed to extract the non-linear coefficients as shown in the figure below:

[[File:Pt analysis.png|600px|center|Non-linear response analysis]]

In the report file <code>r_nlinear</code> you will find the length of the dephasing part and of the sampling one:

Dephasing Time [fs]: 52.65695
Sampling Time [fs]: 4.18566
Total simulation time [fs]: 56.84262
The length of the dephasing interval is inversely proportional to the damping term <math>T_{depth} \simeq 1/\gamma</math> while the length of the sampling is dictated by the smallest frequency we are interested in: <math>T_{samp} \simeq 1/\omega_1 </math>. For this reason if <math> \omega_1=0 </math> or <math> \gamma = 0 </math> simulation time goes to infinity. The response at zero frequency can be calculated as limit of small frequency perturbation.
You can have a look to the file <code>src/nloptics/NL_initialize.F</code> to see how simulation lengths are defined.
Calculations can take some time, run them in parallel, the best number of processors = number of frequencies or reduce the number of frequencies step in the SHG.

==Analysis of the results==

In the sampling region we suppose that the polarization can be written as: <math>\bf{P}(t) = \sum_{n=-\infty}^{+\infty} \bf{p}_n e^{-i\omega_n t} </math> where the coefficient <math>\bf{p}_1,...,\bf{p}_n </math> are related to <math>\chi^{(1)},...,\chi^{(n)} </math>. We sample the polarization signal at different times and invert the previous equation by truncating the sum at a finite order <ref>[https://arxiv.org/abs/1309.4012 Nonlinear optics from an ab initio approach by means of the dynamical Berry phase: Application to second- and third-harmonic generation in semiconductors], C. Attaccalite and M. Grüning, Phys. Rev. B 88, 235113(2013)</ref>.
This is done with the command <code>ypp_nl -u</code> that automatically produce an input with the correct values:

nonlinear # [R] NonLinear Optics Post-Processing
Xorder= 4 # Max order of the response functions
% TimeRange
52.65695 | -1.00000 | fs # Time-window where processing is done
%
ETStpsRt= 200 # Total Energy steps
% EnRngeRt
0.00000 | 10.00000 | eV # Energy range
%
DampMode= "NONE" # Damping type ( NONE | LORENTZIAN | GAUSSIAN )
DampFactor= 0.10000 eV # Damping parameter

where <code>Xorder</code> is the order where the previous sum is truncated, and the TimeRange specifies the sampling region. Notice that differently from the first tutorial, in this case, we do not need Damping in <code>ypp_nl</code> because we already included it in the real-time dynamics. Run <code>ypp_nl</code> and it will produce a file called <code>o.YPP-X_probe_order_2</code>. This file contains the different components of <math>\chi^2_{xy*} </math> and in particular the columns 6 and 7 correspond to the imaginary and real part of <math>\chi^2_{xyz} </math>. You can plot the result with gnuplot and the command:

p 'o.YPP-X_probe_order_2' u 1:(sqrt($6**2+$7**2)) w lp ps 1.5 pt 7 lw 1.5

the result should look like

[[File:AlAs results.png|700px|center|SHG in AlAs]]

and compare it with the <math> \chi^2_{zxy} </math> calculated with more frequencies and with the converged result on a <math> 18x18x18</math> k-point grid and bands between 2 and 10. In the figure you can find also the comparison with the results of Ref. <ref>Luppi et al. [https://arxiv.org/abs/1006.2649 PRB B, '''82''', 235201(2010)]</ref>.
Notice that the QuantumEspresso results are slightly different from the Abinit ones. This is due to the different pseudo-potential employed in the calculations if pseudopotentials were the same calculation would have been identical. You can download the script to generate this plot and the converged results [http://www.attaccalite.com/lumen/tutorials/AlAs/AlAs_results.tgz here].

'''Notice that''' : the following parameters are not used in the non-linear response analysis: <code> EnRngeRt</code>, <code>ETStpsRt</code>, <code>DampMode</code>, <code>DampFactor</code>. The damping factor is set directly in the real-time simulation.

'''System of units in Non-linear Optics''': notice that in Yambo the non-linear response functions are in the gaussian system of units, for example the <math> \chi^2 (\omega) </math> is in cm/statvolt. In order to convert the non-linear coefficients between different system of units, you can have a look at the [https://www.attaccalite.com/tutorials_yambo/Appendix_C_Boyd.pdf Appendix C] of the book [https://www.elsevier.com/books/nonlinear-optics/boyd/978-0-12-369470-6 "Non-linear optics" by Robert W. Boyd].

More tutorials on non-linear response (Third harmonic generation, parallelization, spin-orbit etc..) with Yambo can be found here: [http://www.attaccalite.com/lumen/tutorials.html More Tutorials]. 

==Analysis of the results using YamboPy==
The analysis of the result performed in the previous section using <code>ypp_nl</code> can be performed using python script [https://github.com/yambo-code/yambopy YamboPy]. 
In YamboPy we implemented all necessary functions to reads the Yambo databases and post-process the results. Here we show how to get the SHG signal from the previous
simulations. We suppose you correctly installed <code>YamboPy</code> on your PC. Go in the folder where you ran non-linear calculation and type in the python:
 
from yambopy import *
NLDB=YamboNLDB()
pol =NLDB.Polarization[0]
time=NLDB.IO_TIME_points

in this way you read all the Non-linear databases. If your runs are in a different folder then the 'SAVE' one you can specify it using the command:
NLDB=YamboNLDB(calc='MYJOB')

now in the array <code>pol</code> you have all the polarization for all laser frequencies in the three Cartesian directions, while the variable <code>time</code> contains all the time series of your simulation.
Now you can get the non-linear response with the command:

Harmonic_Analysis(NLDB,X_order=4)

this command will perform a Fourier analysis of the results in the same way of <code>ypp_nl</code> and generate new files with all the requested harmonics ''o.YamboPy-X_probe_order_1'', ''o.YamboPy-X_probe_order_2'' etc...
equivalent to the one generated by <code>ypp_nl</code>. Results can be plot with gnuplot using the command:

p 'o.YamboPy-X_probe_order_2' u 1:(sqrt($6**2+$7**2)) w lp ps 1.5 pt 7 lw 1.5

The script that performs non-linear analysis can be found in <code>yambopy/nl/harmonic_analysis.py</code>. We strongly advice you to have a look to this script and modify it according
to your needs and in order to extract other non-linear response functions.

==How to choose the external field direction for the different X2==

In the X2abc response you have three field directions. The two components ''b'' and ''c'' are determined by the external field and the third ''a''
is the direction where you measure the response. 

The external field in Yambo is set using the variable
% Field1_Dir
1.000000 | 0.000000 | 0.000000 | # [NL ExtF] Versor .
%

For example if you set in Yambo field direction as:

1.0 | 0.0 | 0.0 | ---> you calculate all components X2*xx
0.0 | 1.0 | 0.0 | ---> you calculate all components X2*yy
0.0 | 0.0 | 1.0 | ---> you calculate all components X2*zz

the * correspond to the different direction in the response file <code>o.YPP-X_probe_order_2</code>.
In the <code>o.YPP-X_probe_order_2</code> you have seven columns:

The first column is the energy [[omega]],
the 2nd and 3rd columns are the imaginary and real part of X2x**
the 4th and 5th columns are the imaginary and real part of X2y**
the 6th and 7th columns are the imaginary and real part of X2z**

where the ** are the direction of the incoming field, see above.

For example if you want to calculate the X2zxx you put the external field in the direction <code> 1.0 | 0.0 | 0.0 |</code>
and then plot the column 6 and 7 of the <code>o.YPP-X_probe_order_2</code> file. 

'''Nota bene:''' if you change the direction of the external field you have to remove the corresponding symmetries as explained in the tutorial
on [[Prerequisites for Real Time_propagation with Yambo#Reduce symmetries real-time linear response tutorial]].

In order to get the other components of the X2 the calculation are more involved. For example if you put field in the

1.0 | 1.0 | 0.0 |

this corresponds to <math>E(t)=\frac{1}{\sqrt{2}} [ E_x(t) + E_y(t) ]</math> and so at the second order you will have <math>E^2(t)=\frac{1}{2} [ E^2_x(t) + E^2_y(t) + E_x(t) E_y(t) + E_y(t) E_x(t) ]</math> 
this means that the X2 in the <code>o.YPP-X_probe_order_2</code> will correspond to a linear combination of the following different response functions. 
For example in the the 2nd and 3rd columns are the imaginary and real part of: 
<math>\chi^2_{x**}=\frac{1}{2}\chi^2_{xxx}+\chi^2_{xyy} + \chi^2_{xxy} + \chi^2_{xyx}</math>

the same for the other column replacing the first <code>x</code> for <code>y,z</code>.

==Non-linear response of low-dimensional structures: 2D or 1D ==

The Yambo code is a 3D periodic code, so when you want to study a low-dimensional system 2D or 1D, you have to use a supercell approach.
For example to simulate the non-linear response in a 2D-crystal one, can put the crystal in the xy plane and choose a larger distance in the z-direction
in order to reduce the interaction between the periodic replica. Clearly in this case k-point sampling will be only in the x,y directions.
For calculations on this type of systems, these two warnings must be taken into account:

* if you calculate GW corrections or include electron-hole interaction in the linear/non-linear response it is a good idea to use a '''Coulomb cutoff''', similar to the 2D BSE case [http://www.yambo-code.org/wiki/index.php?title=How_to_treat_low_dimensional_systems How to treat low dimensional systems]. You can add the cutoff just adding the "-r" in the input generation.

* the calculation of SHG and THG are always performed respect to the supercell, therefore you have to '''re-scale''' the result to the effective thickness of the layer, usually the inter-layer distance of the corresponding bulk material for 2D systems: <math>\chi_{rescaled}(\omega) = L_z/d_{eff} \cdot \chi(\omega) </math> where <math>L_z</math> is the z-dimension of the supercell, and <math>d_{eff}</math> is the effective thickness of the 2D system.

'''Nota bene''': Non-linear response along non-periodic directions is not implemented in Yambo, the code will print zero in these directions for all response functions. We plan to implement it in a future version of the code.

==References==
<references />

==Links for schools==
* Back to [[Rome 2023#Tutorials]]
* Back to [[ICTP2020]]

 
{| style="width:100%" border="1"
|style="width:25%; text-align:left"|Prev: [[Linear response from real time simulations|Linear response from real time simulations]]
|style="width:45%; text-align:center"|Now: [[ICTP2020|ICTP Tutorials]] --> [[Real time approach to non-linear response|Non Linear Response]]
|style="width:50%; text-align:left"|Next: [[Correlation effects in the non-linear response|Correlation effects in the non-linear response ]]
|-
|}