The Yambo Project - User contributions [en]

Real time Bethe-Salpeter Equation (TDSE)

2021-01-14T08:20:21Z

Claudio: /* The Real Time Collisions */

==Introduction==

This tutorial will show how to perform a real-time calculation with Yambo on hBN monolayer. We will go through different approximations for the many body self--energy (HXC potential in the yambo language) up to the HSEX approximation which captures the physics of the exciton. For approximations local in space, like "TD-HARTREE" and "TD-DFT", the HXC potential can be evaluated directly during the simulation from real space quantities. On the contrary for approximations non local in space, one first need to compute the "real time collisions".

The same DFT inputs used to generate the [http://www.yambo-code.org/educational/tutorials/files/hBN-2D-RT.tar.gz hBN-2D-RT.tar.gz], are sufficient to converge the energy of the first exciton. You will need to increase the number of k-points to converge higher energy excitons.

==TD Hartree and TD DFT==

=== TD Hartree===
yambo_rt -n p -v hartree -F Inputs_rt/02_td_hartree.in

negf # [R] Real-Time dynamics
HXC_Potential= "HARTREE" # [SC] SC HXC Potential
HARRLvcs= 1000 mHa # [HA] Hartree RL components
VXCRLvcs= 0. mHa # [HA] DFT RL components
% RTBands
3 | 5 | # [RT] Bands
%
Integrator= "RK2" # [RT] Integrator. Use keywords space separated ( "EULER/EXPn/INV" "SIMPLE/RK2/RK4/HEUN" "RWA")
PhLifeTime= 100.0000 fs # [RT] Dephasing Time
RTstep=10.000000 as # [RT] Real Time step length
NETime= 20.00000 fs # [RT] Simulation Time
% IOtime
0.01 | 1.00 | 0.01 | fs # [RT] Time between to consecutive I/O (OBSERVABLEs,CARRIERs - GF - OUTPUT)
%
% Field1_Freq
0.00 | 0.00 | eV # [RT Field1] Frequency
%
Field1_Int= 1.E3 kWLm2 # [RT Field1] Intensity
Field1_Width= 0.000000 fs # [RT Field1] Width
Field1_kind= "DELTA" # [RT Field1] Kind(SIN|RES|ANTIRES|GAUSS|DELTA|QSSIN)
Field1_pol= "linear" # [RT Field1] Pol(linear|circular)
% Field1_Dir
0.000000 | 1.000000 | 0.000000 | # [RT Field1] Versor
%
% Field1_Dir_circ
0.000000 | 1.000000 | 0.000000 | # [RT Field1] Versor_circ
%
Field1_Tstart= 0.000000fs # [RT Field1] Initial Time

We set the cut-off on the Hartree potential to 1000 mHa. This defines the cutoff used to evaluate the Hartree potential at each time step.
Notice also the need of setting the cutoff to Vxc to zero.
This time we will propagate for just 20 fs. It is useful to run the simulation in background and then monitor the output file

nohup yambo_rt -F Inputs_rt/02_td_hartree.in -J TD-HARTREE_1000mHa -C TD-HARTREE_1000mHa &
tail -f TD-HARTREE_1000mHa/o-TD-HARTREE_1000mHa.polarization

We can even have check the output on the fly.
To interrupt <code>tail -f </code>
ctrl+C
Then
gnuplot
plot "TD-IP_rt/o-TD-IP_rt.polarization" u 1:3 w l
set xrange [0:20]
rep "TD-HARTREE_1000mHa/o-TD-HARTREE_1000mHa.polarization" u 1:3 w l

[[File:TD-Hartree Pol along y.png|thumb|center|900px|Time dependent polarization of hBN obtained within time depndent hartree]]

We can already see from the output that the polarization is not very different from the IP one.
The major difference is indeed due to the presence of a damping (or dephasing term) in the output (<code>PhLifeTime</code>, i.e. the life-time of the phase).
If we check the timing of the simulation we see that most of the time is spent in the following subroutines:
el_density_matrix : 7.5074 s CPU ( 4002 calls, 0.0019 s avg)
V_Hartree : 1.0405 s CPU ( 4002 calls, 0.0003 s avg)
V_real_space_to_H : 23.8210 s CPU ( 220220 calls, 0.0001 s avg)
RT Hamiltonian : 32.5007 s CPU ( 4001 calls, 0.0081 s avg)
The evaluation of the Hartree potential by itself does not take too much time. It is more consuming to evaluate the real space density.
However it is the projection of the potential into the transition space (V_real_space_to_H) which takes most of the time.
RT_Hamiltonian is just (roughly) the sum of the two previous subroutines. You can see how these timings change if you increase the cutoff on the Hartree potential.

Thus we can expect that also the absorption will be quite similar. Indeed hBN is uniform in the plane.
As previously you can now to a post-processing of the polarization. The input file is exactly the same
ypp_rt -F Inputs_rt/ypp_abs.in -J TD-HARTREE_1000mHa -C TD-HARTREE_1000mHa
gnuplot
plot "TD-IP_rt/o-TD-IP_rt.YPP-eps_along_E" u 1:2 w l
rep "TD-HARTREE_1000mHa/o-TD-HARTREE_1000mHa.YPP-eps_along_E" u 1:2 w l
set xrange [2:10]
rep

[[File:Absorption along y.png|thumb|center|900px|hBN absorption within time dependent hartree]]

The situation would be completely different if we computed the polarization out of plane at both the TD-IP and the TD-Hartree level.
You can try if you wish, but remember that you have to go back to the original SAVE folder and remove the symmetries not consistent with a field along the z direction this time:
(see [[Prerequisites_for_Real_Time_propagation_with_Yambo|Prerequisites]]))

=== TD DFT===
You can now try to perform a TDDFT simulation.
Let's use the previous input file
cp Inputs_rt/02_td_hartree.in Inputs_rt/03_td_dft.in
and modify it
vim Input_rt/03_td_dft.in

negf # [R] Real-Time dynamics
HXC_Potential= "HARTREE+GS_XC" # [SC] SC HXC Potential
HARRLvcs= 1.E3 mHa # [HA] Hartree RL components
VXCRLvcs= 1.E3 mHa

We can now run the TD-DFT simulation
nohup yambo_rt -F Inputs_rt/03_td_dft.in -J TD-DFT_1000mHA -C TD-DFT_1000mHA &
tail -f TD-DFT_1000mHA/o-TD-DFT_1000mHA.polarization

and once it is over do the post processing
ctrl+C
ypp_rt_4.5_gpl -F Inputs_rt/ypp_abs.in -J TD-DFT_1000mHA -C TD-DFT_1000mHA
gnuplot
gnuplot> plot "TD-HARTREE_1000mHa/o-TD-HARTREE_1000mHa.YPP-eps_along_E" u 1:2 w l
gnuplot> rep "TD-DFT_1000mHA/o-TD-DFT_1000mHA.YPP-eps_along_E" u 1:2 w l

[[File:Absorpion hBN TDDFT.png|center|900px|thumb|Absorption of hBN in plane. Comparison between TD-HARTREE and TDDFT]]

As expected TDDFT does not improve much over TD-HARTREE in extended systems

==The Real Time Collisions==

We next move to the evaluation of the collisions. (see [[Introduction to Real Time propagation in Yambo]] to remember what are the collisions)
This part is common in between the <code>yambo_nl</code> and the <code>yambo_rt</code>.

Then generate the input file to calculate the collisions (see appendix of Ref. <ref name="prb88">[https://arxiv.org/abs/1109.2424 C. Attaccalite, M. Grüning, and A. Marini PRB '''84''', 245110 (2011)]</ref>) use the command :
yambo_rt -X s -e -v hsex -F Inputs/03_coll_hsex.in

The flag -b will tell the code to calculate the dielectric constant that is required for the screened interaction.
It could be even computed in an independent calculation and then loaded using the <code>-J</code> flags

em1s # [R Xs] Static Inverse Dielectric Matrix
dipoles # [R ] Compute the dipoles
Chimod= "HARTREE" # [X] IP/Hartree/ALDA/LRC/PF/BSfxc
% BndsRnXs
1 | 20 | # [Xs] Polarization function bands
%
NGsBlkXs= 1000 mHa # [Xs] Response block size
% DmRngeXs
0.10000 | 0.10000 | eV # [Xs] Damping range
%
% LongDrXs
1.000000 | 0.000000 | 0.000000 | # [Xs] [cc] Electric Field
%

While this is the part of the input file specific for the evaluation of the collisions
collisions # [R] Eval the extended Collisions
% [[Variables#COLLBands|COLLBands]]
4 | 5 | # [COLL] Bands for the collisions
%
HXC_Potential= "HARTREE+SEX" # [SC] SC HXC Potential
[[Variables#HARRLvcs|HARRLvcs]]= 1000 mHa # [HA] Hartree RL components
[[Variables#EXXRLvcs|EXXRLvcs]]= 1000 mHa # [XX] Exchange RL components
[[Variables#CORRLvcs|CORRLvcs]]= 1000 mHa # [GW] Correlation RL components

With this input, we calculate the HARTREE plus SEX collisions integrals. Notice that the HARTREE term in principle can be calculated on the fly, but in this way it is more efficient especially for the non-linear response.
Here one has to converge the cutoff for the Hartree and the Screened Exchange. Around <code>5000 mHa</code> is a reasonable value for hBN. In this example we will use <code>1000 mHa</code> to speed up calculations. The collisions bands <code>COLLBands</code> have to be the same number of bands you want to use in the linear/nonlinear response.
The you can run
yambo_rt -F Inputs/03_coll_hsex.in -J COLL_HSEX -C COLL_HSEX

The calculation will take about 1 minute in serial.
It produced many binary files <code>ndb.COLLISIONS_HXC_fragment_*</code> which will be needed to perform TD-HSEX simulations.
Notice that, if you want, you can also compute simple HARTREE collisions and use them in a TD-HARTREE simulation.

=== TD-HARTREE with collisions (facultative) ===
Then generate the input file to calculate the collisions (see appendix of Ref. <ref name="prb88"></ref>) use the command :
yambo_rt -e -v h -F Inputs/03_coll_hartree.in

with a simpler input file
collisions # [R] Eval the extended Collisions
% [[Variables#COLLBands|COLLBands]]
4 | 5 | # [COLL] Bands for the collisions
%
HXC_Potential= "HARTREE" # [SC] SC HXC Potential
[[Variables#HARRLvcs|HARRLvcs]]= 1000 mHa # [HA] Hartree RL components

yambo_rt -F Inputs/03_coll_hartree.in -J COLL_HARTREE -C COLL_HARTREE
yambo_rt -F Inputs_rt/02_td_hartree.in -J "TD-HARTREE_COLL,COLL_HARTREE" -C TD-HARTREE_COLL

and compare the run with the simulation without collision.
One major difference, is that, when the collisions are used, yambo does not need to load the wave--function anymore and the simulation is much faster.
The drawback is that for big systems the folder COLL_HARTREE may become huge, thus requiring a lot of disk space.

==Time dependent Bethe Salpeter equation==

=== Approach based on the density matrix ===

To generate the input for the real-time simulation you can run
yambo_rt -n p -v hsex -V qp -F Inputs_rt/04_td_hsex.in

As you can see this time the extra verbosity for quasi-particles is used <code>-V qp</code>
The reason is that, to be consistent with the TD-HSEX, simulation we need to apply quasi-particles corrections.
The input file is

negf # [R] NEQ Real-time dynamics
HXC_Potential= "SEX+HARTREE" # [SC] SC HXC Potential
% RTBands
3 | 5 | # [RT] Bands
%
Integrator= "RK2" # [RT] Integrator. Use keywords space separated ( "EULER/EXPn/INV" "SIMPLE/RK2/RK4/HEUN" "RWA")
PhLifeTime= 100.0000 fs # [RT] Dephasing Time
RTstep=10.000000 as # [RT] Real Time step length
NETime= 30.00000 fs # [RT] Simulation Time
% IOtime
0.01 | 1.00 | 0.05 | fs # [RT] Time between to consecutive I/O (OBSERVABLEs,CARRIERs - GF - OUTPUT)
%
HARRLvcs= 1000 mHa # [HA] Hartree RL components
EXXRLvcs= 1000 mHa # [XX] Exchange RL components
CORRLvcs= 1000 mHa # [GW] Correlation RL components

% GfnQP_E
3.000000 | 1.000000 | 1.000000 | # [EXTQP G] E parameters (c/v) eV|adim|adim
%

% Field1_Freq
0.00 | 0.00 | eV # [RT Field1] Frequency
%
Field1_Int= 1.E3 kWLm2 # [RT Field1] Intensity
Field1_Width= 0.000000 fs # [RT Field1] Width
Field1_kind= "DELTA" # [RT Field1] Kind(SIN|RES|ANTIRES|GAUSS|DELTA|QSSIN)
Field1_pol= "linear" # [RT Field1] Pol(linear|circular)
% Field1_Dir
0.000000 | 1.000000 | 0.000000 | # [RT Field1] Versor
%
% Field1_Dir_circ
0.000000 | 1.000000 | 0.000000 | # [RT Field1] Versor_circ
%
Field1_Tstart= 0.000000fs # [RT Field1] Initial Time

and then run the code. Notice the presence of the <code>COLL_SEX</code> among the options after <code>-J</code>

nohup yambo_rt -F Inputs_rt/04_td_hsex.in -J "TD-SEX_rt,COLL_SEX" -C TD-SEX_rt

=== Approach based on the Berry Phase ===

To generate the input for the real-time simulation you can run
yambo_nl -u -V qp -F Inputs_nl/04_td-sex.in

The input file is

nloptics # [R NL] Non-linear optics
DIP_Threads=0 # [OPENMP/X] Number of threads for dipoles
NL_Threads=0 # [OPENMP/NL] Number of threads for nl-optics
% NLBands
4 | 5 | # [NL] Bands
%
NLverbosity= "low" # [NL] Verbosity level (low | high)
NLstep= 0.0100 fs # [NL] Real Time step length
NLtime= 20.00000 fs # [NL] Simulation Time
NLintegrator= "CRANKNIC" # [NL] Integrator ("EULEREXP/RK2/RK4/RK2EXP/HEUN/INVINT/CRANKNIC")
NLCorrelation= "SEX" # [NL] Correlation ("IPA/HARTREE/TDDFT/LRC/LRW/JGM/SEX")
NLLrcAlpha= 0.000000 # [NL] Long Range Correction
% NLEnRange
0.200000 | 8.000000 | eV # [NL] Energy range
%
NLEnSteps= 1 # [NL] Energy steps
NLDamping= 0.10000 eV # [NL] Damping
#UseDipoles # [NL] Use Covariant Dipoles (just for test purpose)
#FrSndOrd # [NL] Force second order in Covariant Dipoles
#EvalCurrent # [NL] Evaluate the current
HARRLvcs= 1000 mHa # [HA] Hartree RL components
EXXRLvcs= 1000 mHa # [XX] Exchange RL components

% ExtF_Dir
0.000000 | 1.000000 | 0.000000 | # [NL ExtF] Versor
%
ExtF_Int= 1000. kWLm2 # [NL ExtF] Intensity
ExtF_Width= 0.000000 fs # [NL ExtF] Field Width
ExtF_kind= "DELTA" # [NL ExtF] Kind(SIN|SOFTSIN|RES|ANTIRES|GAUSS|DELTA|QSSIN)
ExtF_Tstart= 0.0100 fs # [NL ExtF] Initial Time
% GfnQP_E
3.000000 | 1.000000 | 1.000000 | # [EXTQP G] E parameters (c/v) eV|adim|adim
%

Notice that we introduced a scissor operator (a rigid shift of the conduction bands) of 3.0 eV. In principle, it is possible to perform a G0W0 calculation with Yambo and use the Quasi-particle band structure instead of the rigid shift. Run this calculation and then analyze the result in the same way of linear response tutorial, you will get a nice exciton in hBN, as the one plotted below in the old tutorial. You can repeat the same kind of calculations for the non-linear response.
Notice that in the calculation we decreased the number of G-vectors in the Hartree term, [[Variables#HARRLvcs|HARRLvcs]] to speed up the calculation, in case of BN this does not change the result because local field effects are very small in h-BN along the plane.

nohup yambo_nl -F Inputs_nl/04_td_hsex.in -J "TD-SEX_nl,COLL_SEX" -C TD-SEX_nl

=== Final post processing ===

Now you can analyze the response with
ypp_rt -F Inputs_rt/ypp_abs.in -J TD-sex_rt -C TD-SEX_rt
ypp_nl -F Inputs_nl/ypp_abs.in -J TD-SEX_nl -C TD-SEX_nl
as it was done the linear response tutorial and compare with the TD-IP run (and eventually against the standard Bethe-Salpeter):

gnuplot> plot "TD-HSEX_rt/o-TD-HSEX_rt.YPP-eps_along_E" u 1:2 w l
gnuplot> rep "TD-HSEX_nl/o-TD-HSEX_nl.YPP-eps_along_E" u 1:2 w l
gnuplot> set xrange [3:10]
gnuplot> set yrange [0:12]
gnuplot> rep "TD-IP_rt/o-TD-IP_rt.YPP-eps_along_E" u ($1+3):2 w l

[[File:HBN HSEX absorption.png|thumb|900px|center|In plane absorption of hBN at the TD-HSEX level compared with IP absorption]]

Linear response results can be obtained following the [[How to obtain an optical spectrum|BSE tutorial]].
Notice that you can use the SEX approximation for the non-linear response too (see the following tutorials on non-linear response).

==References==
<references />

 
{| style="width:100%" border="1"
|style="width:15%; text-align:left"|Prev: [[Real time approach to linear response|Independent Particles ]]
|style="width:70%; text-align:center"|Now: [[Tutorials|Tutorials]] --> [[Linear response from real time simulations|Linear Response]] --> [[Real time Bethe-Salpeter Equation (TDSE)]]
|style="width:35%; text-align:right"|Next: If you did all steps you can go back to the previous level
|-
|}

Identify what's causing segmentation fault in Yambo

2021-01-11T08:11:12Z

Claudio:

There may be different reasons why the Yambo code generates segmentation faults in a run. 
To help Yambo developers understand where the problem lies and help you, please follow the steps below.
If one of the step solves your problem and please report the result in the [http://www.yambo-code.org/forum/ forum].

'''Rule out possible causes of the segmentation fault:'''

# '''GPU''': recompile without GPU support, remove the <code>--enable-cuda</code> flag. If this solve the problem report the bug in forum GPU section [http://www.yambo-code.org/forum/viewforum.php?f=38 Yambo on GPU machines].
# '''OPEN-MP''': compile and run Yambo without open-mp support, no <code>--enable-open-mp</code> flag in the configure and <code>OMP_NUM_THREADS="1"</code>.
# '''Lapack/Blas''': use internal Lapack/Blas. Reconfigure Yambo with the flag <code>--enable-int-linalg</code>, recompile and run our job again.
# '''FFT''': compile Yambo with internal FFT libraries <code>--enable-internal-fftsg</code> .
# '''Scalapack''': compile without Scalpack, unset the flag <code>--with-scalapack-libs</code>.
# '''Parallelism'''
## Change the number of processors
## Use automatic parallelization, unset all parallel variable in input
## Try to disable MPI parallelism by doing <code>yambo -nompi</code> and/or OPEN-MP parallelism by doing <code>yambo -noopenmp</code>
## Compile yambo without MPI and run in serial
# '''Optimization''': use a lower optimization level for example -O1 or -O0, by doing <code>./configure FCFLAGS="-O0" FFLAGS="-O1"</code>
# '''Compilers''': change C/Fortran compiler if it is possible, move form intel fortran to gfortran or vice-versa. In order to set compilers in the configure use <code>./configure FC=ifort F77=ifort CC=icc</code> for Intel and <code>./configure FC=gfortran F77=gfortran CC=gcc</code> for gfortran.
 
If no one of the previous steps solved your problem, contact us again in the [http://www.yambo-code.org/forum/ forum]. 
If you want you can try to debug Yambo and identity the origin of segmentation fault following the steps below. This will help developers to find a solution to the problem more quickly: 

'''Debugging the segmentation fault:'''

# '''Checking options''': compile Yambo with the compiler checking options and run again your simulation, then report the result in the forum:
## for g-fortran compiler <code>./configure FCFLAGS="-O1 -g -fcheck=all" UFLAGS="-O0 -g -fcheck=all" FFLAGS="-O1 -g -fcheck=all" --enable-keep-src"</code>
## for intel fortran <code>./configure FCFLAGS="-O1 -g -CB -CA -debug" UFLAGS="-O0 -g -CB -CA -debug" FFLAGS="-O1 -g -CB -CA -debug" --enable-keep-src"</code>
# '''Use a debugger''': Compile with debugging options for g-fortran compiler <code>./configure FCFLAGS="-Og -g" UFLAGS="-Og -g" FFLAGS="-Og -g" --enable-keep-src" CFLAGS="-g"</code> for intel fortran <code>./configure FCFLAGS="-O1 -g -debug" UFLAGS="-O0 -g -debug" FFLAGS="-O1 -g -debug" --enable-keep-src" CFLAGS="-g -debug"</code> then execute the job in a debugger for example <code>[https://www.gnu.org/software/gdb/ gdb] --args yambo -F yambo_input.in</code>. It can work also in parallel see [https://www.open-mpi.org/faq/?category=debugging here] and [https://stackoverflow.com/questions/329259/how-do-i-debug-an-mpi-program here]
# '''Memory leaks''': [only for experts] compile Yambo with debugging options then run your job with [https://valgrind.org/ valgrind]: <code>valgrind --tool=memcheck --leak-check=summary ./yambo</code>

Identify what's causing segmentation fault in Yambo

2021-01-11T08:10:57Z

Claudio:

There may be different reasons why the Yambo code generates segmentation faults in a run. 
To help Yambo developers understand where the problem lies and help you, please follow the steps below.
If one of the step solves your problem and please report the result in the [http://www.yambo-code.org/forum/ forum].

'''Rule out possible causes of the segmentation fault:'''

# '''GPU''': recompile without GPU support, remove the <code>--enable-cuda</code> flag. If this solve the problem report the bug in forum GPU section [http://www.yambo-code.org/forum/viewforum.php?f=38 Yambo on GPU machines].
# '''OPEN-MP''': compile and run Yambo without open-mp support, no <code>--enable-open-mp</code> flag in the configure and <code>OMP_NUM_THREADS="1"</code>.
# '''Lapack/Blas''': use internal Lapack/Blas. Reconfigure Yambo with the flag <code>--enable-int-linalg</code>, recompile and run our job again.
# '''FFT''': compile Yambo with internal FFT libraries <code>--enable-internal-fftsg</code> .
# '''Scalapack''': compile without Scalpack, unset the flag <code>--with-scalapack-libs</code>.
# '''Parallelism'''
## Change the number of processors
## Use automatic parallelization, unset all parallel variable in input
## Try to disable MPI parallelism by doing <code>yambo -nompi</cope> and/or OPEN-MP parallelism by doing <code>yambo -noopenmp</code>
## Compile yambo without MPI and run in serial
# '''Optimization''': use a lower optimization level for example -O1 or -O0, by doing <code>./configure FCFLAGS="-O0" FFLAGS="-O1"</code>
# '''Compilers''': change C/Fortran compiler if it is possible, move form intel fortran to gfortran or vice-versa. In order to set compilers in the configure use <code>./configure FC=ifort F77=ifort CC=icc</code> for Intel and <code>./configure FC=gfortran F77=gfortran CC=gcc</code> for gfortran.
 
If no one of the previous steps solved your problem, contact us again in the [http://www.yambo-code.org/forum/ forum]. 
If you want you can try to debug Yambo and identity the origin of segmentation fault following the steps below. This will help developers to find a solution to the problem more quickly: 

'''Debugging the segmentation fault:'''

# '''Checking options''': compile Yambo with the compiler checking options and run again your simulation, then report the result in the forum:
## for g-fortran compiler <code>./configure FCFLAGS="-O1 -g -fcheck=all" UFLAGS="-O0 -g -fcheck=all" FFLAGS="-O1 -g -fcheck=all" --enable-keep-src"</code>
## for intel fortran <code>./configure FCFLAGS="-O1 -g -CB -CA -debug" UFLAGS="-O0 -g -CB -CA -debug" FFLAGS="-O1 -g -CB -CA -debug" --enable-keep-src"</code>
# '''Use a debugger''': Compile with debugging options for g-fortran compiler <code>./configure FCFLAGS="-Og -g" UFLAGS="-Og -g" FFLAGS="-Og -g" --enable-keep-src" CFLAGS="-g"</code> for intel fortran <code>./configure FCFLAGS="-O1 -g -debug" UFLAGS="-O0 -g -debug" FFLAGS="-O1 -g -debug" --enable-keep-src" CFLAGS="-g -debug"</code> then execute the job in a debugger for example <code>[https://www.gnu.org/software/gdb/ gdb] --args yambo -F yambo_input.in</code>. It can work also in parallel see [https://www.open-mpi.org/faq/?category=debugging here] and [https://stackoverflow.com/questions/329259/how-do-i-debug-an-mpi-program here]
# '''Memory leaks''': [only for experts] compile Yambo with debugging options then run your job with [https://valgrind.org/ valgrind]: <code>valgrind --tool=memcheck --leak-check=summary ./yambo</code>

Identify what's causing segmentation fault in Yambo

2021-01-11T08:06:23Z

Claudio:

There may be different reasons why the Yambo code generates segmentation faults in a run. 
To help Yambo developers understand where the problem lies and help you, please follow the steps below.
If one of the step solves your problem and please report the result in the [http://www.yambo-code.org/forum/ forum].

'''Rule out possible causes of the segmentation fault:'''

# '''GPU''': recompile without GPU support, remove the <code>--enable-cuda</code> flag. If this solve the problem report the bug in forum GPU section [http://www.yambo-code.org/forum/viewforum.php?f=38 Yambo on GPU machines].
# '''OPEN-MP''': compile and run Yambo without open-mp support, no <code>--enable-open-mp</code> flag in the configure and <code>OMP_NUM_THREADS="1"</code>.
# '''Lapack/Blas''': use internal Lapack/Blas. Reconfigure Yambo with the flag <code>--enable-int-linalg</code>, recompile and run our job again.
# '''FFT''': compile Yambo with internal FFT libraries <code>--enable-internal-fftsg</code> .
# '''Scalapack''': compile without Scalpack, unset the flag <code>--with-scalapack-libs</code>.
# '''Parallelism'''
## Change the number of processors
## Use automatic parallelization, unset all parallel variable in input
## Run in serial
# '''Optimization''': use a lower optimization level for example -O1 or -O0, by doing <code>./configure FCFLAGS="-O0" FFLAGS="-O1"</code>
# '''Compilers''': change C/Fortran compiler if it is possible, move form intel fortran to gfortran or vice-versa. In order to set compilers in the configure use <code>./configure FC=ifort F77=ifort CC=icc</code> for Intel and <code>./configure FC=gfortran F77=gfortran CC=gcc</code> for gfortran.
 
If no one of the previous steps solved your problem, contact us again in the [http://www.yambo-code.org/forum/ forum]. 
If you want you can try to debug Yambo and identity the origin of segmentation fault following the steps below. This will help developers to find a solution to the problem more quickly: 

'''Debugging the segmentation fault:'''

# '''Checking options''': compile Yambo with the compiler checking options and run again your simulation, then report the result in the forum:
## for g-fortran compiler <code>./configure FCFLAGS="-O1 -g -fcheck=all" UFLAGS="-O0 -g -fcheck=all" FFLAGS="-O1 -g -fcheck=all" --enable-keep-src"</code>
## for intel fortran <code>./configure FCFLAGS="-O1 -g -CB -CA -debug" UFLAGS="-O0 -g -CB -CA -debug" FFLAGS="-O1 -g -CB -CA -debug" --enable-keep-src"</code>
# '''Use a debugger''': Compile with debugging options for g-fortran compiler <code>./configure FCFLAGS="-Og -g" UFLAGS="-Og -g" FFLAGS="-Og -g" --enable-keep-src" CFLAGS="-g"</code> for intel fortran <code>./configure FCFLAGS="-O1 -g -debug" UFLAGS="-O0 -g -debug" FFLAGS="-O1 -g -debug" --enable-keep-src" CFLAGS="-g -debug"</code> then execute the job in a debugger for example <code>[https://www.gnu.org/software/gdb/ gdb] --args yambo -F yambo_input.in</code>. It can work also in parallel see [https://www.open-mpi.org/faq/?category=debugging here] and [https://stackoverflow.com/questions/329259/how-do-i-debug-an-mpi-program here]
# '''Memory leaks''': [only for experts] compile Yambo with debugging options then run your job with [https://valgrind.org/ valgrind]: <code>valgrind --tool=memcheck --leak-check=summary ./yambo</code>

Electron Phonon Coupling

2021-01-04T08:39:15Z

Claudio: /* Optical properties */

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

== Electron-phonon matrix elements ==

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

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

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

1. In '''scf''' we run a standard scf calculation choosing the a large k-grid in such a way to converge density. Do not forget to set ''force_symmorphic=.true.'', because not symmorphic symmetries are not supported yet in Yambo. Notice that if you are working with 2D systems, not our case, we have to add the flag ''assume_isolated="2D"'' in such a way correct 2D phonons.

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

.....
number of k points= 8
cart. coord. in units 2pi/alat
k( 1) = ( 0.0000000 0.0000000 0.0000000), wk = 0.0312500
k( 2) = ( 0.1250000 0.1250000 -0.1250000), wk = 0.2500000
k( 3) = ( -0.2500000 -0.2500000 0.2500000), wk = 0.1250000
k( 4) = ( 0.2500000 0.0000000 0.0000000), wk = 0.1875000
k( 5) = ( -0.1250000 -0.3750000 0.3750000), wk = 0.7500000
k( 6) = ( 0.0000000 -0.2500000 0.2500000), wk = 0.3750000
k( 7) = ( -0.5000000 0.0000000 0.0000000), wk = 0.0937500
k( 8) = ( -0.5000000 0.2500000 0.0000000), wk = 0.1875000
.....

3. Go in the '''phonon''' directory. You have to copy the k-points list in the ''2pi/alat'' units from the previous nscf run and use it as q-grid for the phonon calculations. Notice that due to an internal convection of Yambo the q-points have to be multiplied for -1 before add them to the phonons input. You can use this simple python script [http://www.yambo-code.org/educational/tutorials/files/minus_kpoints.py minuq_kpoints.py] to read k-points from the QE output and multiply them by minus one.
The final input will be:
&inputph
verbosity = 'high'
tr2_ph = 1e-12h
prefix = 'si'
fildvscf = 'si-dvscf'
fildyn = 'si.dyn',
electron_phonon = 'dvscf',
epsil = .true.
trans = .true.
ldisp = .false.
qplot = .true.
/
8
0.000000000 0.000000000 0.000000000 1
-0.125000000 -0.125000000 0.125000000 1
0.250000000 0.250000000 -0.250000000 1
-0.250000000 0.000000000 0.000000000 1
-0.375000000 -0.125000000 0.125000000 1
0.000000000 0.250000000 -0.250000000 1
0.500000000 0.000000000 0.000000000 1
0.500000000 -0.250000000 0.000000000 1

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

&inputph
verbosity = 'high'
tr2_ph = 1e-12
prefix = 'si'
fildvscf = 'si-dvscf'
fildyn = 'si.dyn'
electron_phonon = 'yambo',
epsil = .true.
trans = .false.
ldisp = .false.
qplot = .true.
/
8
0.000000000 0.000000000 0.000000000 1
-0.125000000 -0.125000000 0.125000000 1
0.250000000 0.250000000 -0.250000000 1
-0.250000000 0.000000000 0.000000000 1
-0.375000000 -0.125000000 0.125000000 1
0.000000000 0.250000000 -0.250000000 1
0.500000000 0.000000000 0.000000000 1
0.500000000 -0.250000000 0.000000000 1

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

5. Now you have to read the wave-functions. Go in the ''dvscf/si.save'' folder, do ''p2y'', then ''yambo_ph -i -V kpt'' and turn on the flag BSEscatt, then run the setup. Now you use ypp_ph to import electron-phonon coupling, by doing ''ypp_ph -g' and the the PW el-ph folder:

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

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

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

== Quasi-particle band structure ==
The first quantity we will calculate is the correction to the band structure induced by the electron-phonon coupling. In order to generate the corresponding input do ''yambo_ph -g n -p fan -c p -V gen'' (in the newer versions of Yambo this line will be changed in ''yambo_ph -g n -p ep -c p -V gen''). In the input we require the correction only at gamma point:

dyson # [R] Dyson Equation solver
gw0 # [R] GW approximation
el_ph_corr # [R] Electron-Phonon Correlation
Nelectro= 8.000000 # Electrons number
ElecTemp= 0.000000 eV # Electronic Temperature
BoseTemp= 0.000000 eV # Bosonic Temperature
OccTresh= 0.100000E-4 # Occupation treshold (metallic bands)
SE_Threads=0 # [OPENMP/GW] Number of threads for self-energy
DysSolver= "n" # [GW] Dyson Equation solver ("n","s","g")
GphBRnge= 12 # [ELPH] G[W] bands range
% ElPhModes
1 | 6 | # [ELPH] Phonon modes included
%
RandQpts=0 # [RIM] Number of random q-points in the BZ
#WRgFsq # [ELPH] Dump on file gFsq coefficients
%QPkrange # [GW] QP generalized Kpoint/Band indices
1|1|4|5|
%

If you run yambo_ph -J T0 you will get correction at zero kelvin to the band structure. You can change the temperature to 300 K by doing:

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

== Optical properties ==

Now you repeat the previous calculation but including all k-points, the last 3 valence and the first 3 conduction bands:

.....
%QPkrange # [GW] QP generalized Kpoint/Band indices
1|8|2|7|
%
....
and save the results of the 0K and 300K temperature in two separate folder with the -J option.
Now you can use the correction to the energy levels and the induced width to calculate the optical absorption at finite temperature. Generate the input with the command ''yambo_ph -o c -V qp''

optics # [R] Linear Response optical properties
chi # [R][CHI] Dyson equation for Chi.
dipoles # [R] Oscillator strenghts (or dipoles)
Chimod= "IP" # [X] IP/Hartree/ALDA/LRC/PF/BSfxc
% QpntsRXd
1 | 1 | # [Xd] Transferred momenta
%
% BndsRnXd
2 | 7 | # [Xd] Polarization function bands
%
% EnRngeXd
0.000000 | 5.000000 | eV # [Xd] Energy range
%
% DmRngeXd
0.0100000 | 0.0100000 | eV # [Xd] Damping range
%
ETStpsXd= 500 # [Xd] Total Energy steps
% LongDrXd
1.000000 | 0.000000 | 0.000000 | # [Xd] [cc] Electric Field
%
XfnQPdb= "E W < T300/ndb.QP" # [EXTQP Xd] Database action

set the path of the ''ndb.QP'' you want to read and perform the calculations. Notice that from the QP database we read two quantities the correction to the energy levels E and the width W. In this calculation we also included a small smearing 0.01eV to mimic the electronic smearing. Hereafter the result without and with electron-phonon coupling at two different temperatures:
[[File:Si absorption finite t.png|800px|center |Absorption of bulk silicon at finite temperature]]

The same procedure can be applied to the Bethe-Salpeter calculations. However in this case results can be slightly wrong. If fact electron-phonon matrix elements should be rotate in the excitonic space, as it was done in ref. <ref> see Supp. Mat. of [https://journals.aps.org/prb/abstract/10.1103/PhysRevB.99.081109 Phys. Rev. B '''99''', 081109(R) (2019)]</ref><ref>F. Paleari, [https://orbilu.uni.lu/handle/10993/41058 Phd Thesis (2019)]</ref>, while at present Yambo calculate the exciton width from the correction to the single particle bands, see ref. <ref name=marini>A. Marini, [https://arxiv.org/abs/0712.3365 Phys. Rev. Lett. '''101''' 106405 (2008)]</ref> . This approximation is correct in case of not-strong bounded excitons, and unfortunately this is not the case.

== Convergence ==

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

== Double-grid method for the electron-phonon coupling ==

To be done

== Miscellaneous and post-processing ==
There are a list of utilities to analyze electron-phonon coupling results:

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

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

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

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

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

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

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

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

For the excitonic Eliashberg functions use the command ''ypp_ph -e e'', an example of these functions can be found in ref.<ref name=marini></ref>.

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

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

==References==
<references />

Electron Phonon Coupling

2021-01-04T08:38:12Z

Claudio: /* Optical properties */

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

== Electron-phonon matrix elements ==

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

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

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

1. In '''scf''' we run a standard scf calculation choosing the a large k-grid in such a way to converge density. Do not forget to set ''force_symmorphic=.true.'', because not symmorphic symmetries are not supported yet in Yambo. Notice that if you are working with 2D systems, not our case, we have to add the flag ''assume_isolated="2D"'' in such a way correct 2D phonons.

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

.....
number of k points= 8
cart. coord. in units 2pi/alat
k( 1) = ( 0.0000000 0.0000000 0.0000000), wk = 0.0312500
k( 2) = ( 0.1250000 0.1250000 -0.1250000), wk = 0.2500000
k( 3) = ( -0.2500000 -0.2500000 0.2500000), wk = 0.1250000
k( 4) = ( 0.2500000 0.0000000 0.0000000), wk = 0.1875000
k( 5) = ( -0.1250000 -0.3750000 0.3750000), wk = 0.7500000
k( 6) = ( 0.0000000 -0.2500000 0.2500000), wk = 0.3750000
k( 7) = ( -0.5000000 0.0000000 0.0000000), wk = 0.0937500
k( 8) = ( -0.5000000 0.2500000 0.0000000), wk = 0.1875000
.....

3. Go in the '''phonon''' directory. You have to copy the k-points list in the ''2pi/alat'' units from the previous nscf run and use it as q-grid for the phonon calculations. Notice that due to an internal convection of Yambo the q-points have to be multiplied for -1 before add them to the phonons input. You can use this simple python script [http://www.yambo-code.org/educational/tutorials/files/minus_kpoints.py minuq_kpoints.py] to read k-points from the QE output and multiply them by minus one.
The final input will be:
&inputph
verbosity = 'high'
tr2_ph = 1e-12h
prefix = 'si'
fildvscf = 'si-dvscf'
fildyn = 'si.dyn',
electron_phonon = 'dvscf',
epsil = .true.
trans = .true.
ldisp = .false.
qplot = .true.
/
8
0.000000000 0.000000000 0.000000000 1
-0.125000000 -0.125000000 0.125000000 1
0.250000000 0.250000000 -0.250000000 1
-0.250000000 0.000000000 0.000000000 1
-0.375000000 -0.125000000 0.125000000 1
0.000000000 0.250000000 -0.250000000 1
0.500000000 0.000000000 0.000000000 1
0.500000000 -0.250000000 0.000000000 1

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

&inputph
verbosity = 'high'
tr2_ph = 1e-12
prefix = 'si'
fildvscf = 'si-dvscf'
fildyn = 'si.dyn'
electron_phonon = 'yambo',
epsil = .true.
trans = .false.
ldisp = .false.
qplot = .true.
/
8
0.000000000 0.000000000 0.000000000 1
-0.125000000 -0.125000000 0.125000000 1
0.250000000 0.250000000 -0.250000000 1
-0.250000000 0.000000000 0.000000000 1
-0.375000000 -0.125000000 0.125000000 1
0.000000000 0.250000000 -0.250000000 1
0.500000000 0.000000000 0.000000000 1
0.500000000 -0.250000000 0.000000000 1

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

5. Now you have to read the wave-functions. Go in the ''dvscf/si.save'' folder, do ''p2y'', then ''yambo_ph -i -V kpt'' and turn on the flag BSEscatt, then run the setup. Now you use ypp_ph to import electron-phonon coupling, by doing ''ypp_ph -g' and the the PW el-ph folder:

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

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

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

== Quasi-particle band structure ==
The first quantity we will calculate is the correction to the band structure induced by the electron-phonon coupling. In order to generate the corresponding input do ''yambo_ph -g n -p fan -c p -V gen'' (in the newer versions of Yambo this line will be changed in ''yambo_ph -g n -p ep -c p -V gen''). In the input we require the correction only at gamma point:

dyson # [R] Dyson Equation solver
gw0 # [R] GW approximation
el_ph_corr # [R] Electron-Phonon Correlation
Nelectro= 8.000000 # Electrons number
ElecTemp= 0.000000 eV # Electronic Temperature
BoseTemp= 0.000000 eV # Bosonic Temperature
OccTresh= 0.100000E-4 # Occupation treshold (metallic bands)
SE_Threads=0 # [OPENMP/GW] Number of threads for self-energy
DysSolver= "n" # [GW] Dyson Equation solver ("n","s","g")
GphBRnge= 12 # [ELPH] G[W] bands range
% ElPhModes
1 | 6 | # [ELPH] Phonon modes included
%
RandQpts=0 # [RIM] Number of random q-points in the BZ
#WRgFsq # [ELPH] Dump on file gFsq coefficients
%QPkrange # [GW] QP generalized Kpoint/Band indices
1|1|4|5|
%

If you run yambo_ph -J T0 you will get correction at zero kelvin to the band structure. You can change the temperature to 300 K by doing:

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

== Optical properties ==

Now you repeat the previous calculation but including all k-points, the last 3 valence and the first 3 conduction bands:

.....
%QPkrange # [GW] QP generalized Kpoint/Band indices
1|8|2|7|
%
....
and save the results of the 0K and 300K temperature in two separate folder with the -J option.
Now you can use the correction to the energy levels and the induced width to calculate the optical absorption at finite temperature. Generate the input with the command ''yambo_ph -o c -V qp''

optics # [R] Linear Response optical properties
chi # [R][CHI] Dyson equation for Chi.
dipoles # [R] Oscillator strenghts (or dipoles)
Chimod= "IP" # [X] IP/Hartree/ALDA/LRC/PF/BSfxc
% QpntsRXd
1 | 1 | # [Xd] Transferred momenta
%
% BndsRnXd
2 | 7 | # [Xd] Polarization function bands
%
% EnRngeXd
0.000000 | 5.000000 | eV # [Xd] Energy range
%
% DmRngeXd
0.0100000 | 0.0100000 | eV # [Xd] Damping range
%
ETStpsXd= 500 # [Xd] Total Energy steps
% LongDrXd
1.000000 | 0.000000 | 0.000000 | # [Xd] [cc] Electric Field
%
XfnQPdb= "E W < T300/ndb.QP" # [EXTQP Xd] Database action

set the path of the ''ndb.QP'' you want to read and perform the calculations. Notice that from the QP database we read two quantities the correction to the energy levels E and the width W. In this calculation we also included a small smearing 0.01eV to mimic the electronic smearing. Hereafter the result without and with electron-phonon coupling at two different temperatures:
[[File:Si absorption finite t.png|800px|center |Absorption of bulk silicon at finite temperature]]

The same procedure can be applied to the Bethe-Salpeter calculations. However in this case results can be slightly wrong. If fact electron-phonon matrix elements should be rotate in the excitonic space, as it was done in ref. <ref> see Supp. Mat. of [https://journals.aps.org/prb/abstract/10.1103/PhysRevB.99.081109 Phys. Rev. B '''99''', 081109(R) (2019)]</ref><ref>F. Paleari, [https://orbilu.uni.lu/handle/10993/41058 Phd Thesis]</ref>, while at present Yambo calculate the exciton width from the correction to the single particle bands, see ref. <ref name=marini>A. Marini, [https://arxiv.org/abs/0712.3365 Phys. Rev. Lett. '''101''' 106405 (2008)]</ref> . This approximation is correct in case of not-strong bounded excitons, and unfortunately this is not the case.

== Convergence ==

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

== Double-grid method for the electron-phonon coupling ==

To be done

== Miscellaneous and post-processing ==
There are a list of utilities to analyze electron-phonon coupling results:

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

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

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

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

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

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

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

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

For the excitonic Eliashberg functions use the command ''ypp_ph -e e'', an example of these functions can be found in ref.<ref name=marini></ref>.

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

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

==References==
<references />

Electron Phonon Coupling

2021-01-04T08:37:41Z

Claudio: /* Optical properties */

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

== Electron-phonon matrix elements ==

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

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

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

1. In '''scf''' we run a standard scf calculation choosing the a large k-grid in such a way to converge density. Do not forget to set ''force_symmorphic=.true.'', because not symmorphic symmetries are not supported yet in Yambo. Notice that if you are working with 2D systems, not our case, we have to add the flag ''assume_isolated="2D"'' in such a way correct 2D phonons.

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

.....
number of k points= 8
cart. coord. in units 2pi/alat
k( 1) = ( 0.0000000 0.0000000 0.0000000), wk = 0.0312500
k( 2) = ( 0.1250000 0.1250000 -0.1250000), wk = 0.2500000
k( 3) = ( -0.2500000 -0.2500000 0.2500000), wk = 0.1250000
k( 4) = ( 0.2500000 0.0000000 0.0000000), wk = 0.1875000
k( 5) = ( -0.1250000 -0.3750000 0.3750000), wk = 0.7500000
k( 6) = ( 0.0000000 -0.2500000 0.2500000), wk = 0.3750000
k( 7) = ( -0.5000000 0.0000000 0.0000000), wk = 0.0937500
k( 8) = ( -0.5000000 0.2500000 0.0000000), wk = 0.1875000
.....

3. Go in the '''phonon''' directory. You have to copy the k-points list in the ''2pi/alat'' units from the previous nscf run and use it as q-grid for the phonon calculations. Notice that due to an internal convection of Yambo the q-points have to be multiplied for -1 before add them to the phonons input. You can use this simple python script [http://www.yambo-code.org/educational/tutorials/files/minus_kpoints.py minuq_kpoints.py] to read k-points from the QE output and multiply them by minus one.
The final input will be:
&inputph
verbosity = 'high'
tr2_ph = 1e-12h
prefix = 'si'
fildvscf = 'si-dvscf'
fildyn = 'si.dyn',
electron_phonon = 'dvscf',
epsil = .true.
trans = .true.
ldisp = .false.
qplot = .true.
/
8
0.000000000 0.000000000 0.000000000 1
-0.125000000 -0.125000000 0.125000000 1
0.250000000 0.250000000 -0.250000000 1
-0.250000000 0.000000000 0.000000000 1
-0.375000000 -0.125000000 0.125000000 1
0.000000000 0.250000000 -0.250000000 1
0.500000000 0.000000000 0.000000000 1
0.500000000 -0.250000000 0.000000000 1

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

&inputph
verbosity = 'high'
tr2_ph = 1e-12
prefix = 'si'
fildvscf = 'si-dvscf'
fildyn = 'si.dyn'
electron_phonon = 'yambo',
epsil = .true.
trans = .false.
ldisp = .false.
qplot = .true.
/
8
0.000000000 0.000000000 0.000000000 1
-0.125000000 -0.125000000 0.125000000 1
0.250000000 0.250000000 -0.250000000 1
-0.250000000 0.000000000 0.000000000 1
-0.375000000 -0.125000000 0.125000000 1
0.000000000 0.250000000 -0.250000000 1
0.500000000 0.000000000 0.000000000 1
0.500000000 -0.250000000 0.000000000 1

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

5. Now you have to read the wave-functions. Go in the ''dvscf/si.save'' folder, do ''p2y'', then ''yambo_ph -i -V kpt'' and turn on the flag BSEscatt, then run the setup. Now you use ypp_ph to import electron-phonon coupling, by doing ''ypp_ph -g' and the the PW el-ph folder:

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

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

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

== Quasi-particle band structure ==
The first quantity we will calculate is the correction to the band structure induced by the electron-phonon coupling. In order to generate the corresponding input do ''yambo_ph -g n -p fan -c p -V gen'' (in the newer versions of Yambo this line will be changed in ''yambo_ph -g n -p ep -c p -V gen''). In the input we require the correction only at gamma point:

dyson # [R] Dyson Equation solver
gw0 # [R] GW approximation
el_ph_corr # [R] Electron-Phonon Correlation
Nelectro= 8.000000 # Electrons number
ElecTemp= 0.000000 eV # Electronic Temperature
BoseTemp= 0.000000 eV # Bosonic Temperature
OccTresh= 0.100000E-4 # Occupation treshold (metallic bands)
SE_Threads=0 # [OPENMP/GW] Number of threads for self-energy
DysSolver= "n" # [GW] Dyson Equation solver ("n","s","g")
GphBRnge= 12 # [ELPH] G[W] bands range
% ElPhModes
1 | 6 | # [ELPH] Phonon modes included
%
RandQpts=0 # [RIM] Number of random q-points in the BZ
#WRgFsq # [ELPH] Dump on file gFsq coefficients
%QPkrange # [GW] QP generalized Kpoint/Band indices
1|1|4|5|
%

If you run yambo_ph -J T0 you will get correction at zero kelvin to the band structure. You can change the temperature to 300 K by doing:

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

== Optical properties ==

Now you repeat the previous calculation but including all k-points, the last 3 valence and the first 3 conduction bands:

.....
%QPkrange # [GW] QP generalized Kpoint/Band indices
1|8|2|7|
%
....
and save the results of the 0K and 300K temperature in two separate folder with the -J option.
Now you can use the correction to the energy levels and the induced width to calculate the optical absorption at finite temperature. Generate the input with the command ''yambo_ph -o c -V qp''

optics # [R] Linear Response optical properties
chi # [R][CHI] Dyson equation for Chi.
dipoles # [R] Oscillator strenghts (or dipoles)
Chimod= "IP" # [X] IP/Hartree/ALDA/LRC/PF/BSfxc
% QpntsRXd
1 | 1 | # [Xd] Transferred momenta
%
% BndsRnXd
2 | 7 | # [Xd] Polarization function bands
%
% EnRngeXd
0.000000 | 5.000000 | eV # [Xd] Energy range
%
% DmRngeXd
0.0100000 | 0.0100000 | eV # [Xd] Damping range
%
ETStpsXd= 500 # [Xd] Total Energy steps
% LongDrXd
1.000000 | 0.000000 | 0.000000 | # [Xd] [cc] Electric Field
%
XfnQPdb= "E W < T300/ndb.QP" # [EXTQP Xd] Database action

set the path of the ''ndb.QP'' you want to read and perform the calculations. Notice that from the QP database we read two quantities the correction to the energy levels E and the width W. In this calculation we also included a small smearing 0.01eV to mimic the electronic smearing. Hereafter the result without and with electron-phonon coupling at two different temperatures:
[[File:Si absorption finite t.png|800px|center |Absorption of bulk silicon at finite temperature]]

The same procedure can be applied to the Bethe-Salpeter calculations. However in this case results can be slightly wrong. If fact electron-phonon matrix elements should be rotate in the excitonic space, as it was done in ref. <ref> see Supp. Mat. of [https://journals.aps.org/prb/abstract/10.1103/PhysRevB.99.081109 Phys. Rev. B '''99''', 081109(R) (2019)]</ref><ref>F. Paleari [https://orbilu.uni.lu/handle/10993/41058 Phd Thesis]</ref>, while at present Yambo calculate the exciton width from the correction to the single particle bands, see ref. <ref name=marini>A. Marini, [https://arxiv.org/abs/0712.3365 Phys. Rev. Lett. '''101''' 106405 (2008)]</ref> . This approximation is correct in case of not-strong bounded excitons, and unfortunately this is not the case.

== Convergence ==

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

== Double-grid method for the electron-phonon coupling ==

To be done

== Miscellaneous and post-processing ==
There are a list of utilities to analyze electron-phonon coupling results:

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

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

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

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

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

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

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

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

For the excitonic Eliashberg functions use the command ''ypp_ph -e e'', an example of these functions can be found in ref.<ref name=marini></ref>.

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

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

==References==
<references />

Electron Phonon Coupling

2021-01-04T08:35:32Z

Claudio: Undo revision 4063 by Claudio (talk)

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

== Electron-phonon matrix elements ==

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

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

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

1. In '''scf''' we run a standard scf calculation choosing the a large k-grid in such a way to converge density. Do not forget to set ''force_symmorphic=.true.'', because not symmorphic symmetries are not supported yet in Yambo. Notice that if you are working with 2D systems, not our case, we have to add the flag ''assume_isolated="2D"'' in such a way correct 2D phonons.

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

.....
number of k points= 8
cart. coord. in units 2pi/alat
k( 1) = ( 0.0000000 0.0000000 0.0000000), wk = 0.0312500
k( 2) = ( 0.1250000 0.1250000 -0.1250000), wk = 0.2500000
k( 3) = ( -0.2500000 -0.2500000 0.2500000), wk = 0.1250000
k( 4) = ( 0.2500000 0.0000000 0.0000000), wk = 0.1875000
k( 5) = ( -0.1250000 -0.3750000 0.3750000), wk = 0.7500000
k( 6) = ( 0.0000000 -0.2500000 0.2500000), wk = 0.3750000
k( 7) = ( -0.5000000 0.0000000 0.0000000), wk = 0.0937500
k( 8) = ( -0.5000000 0.2500000 0.0000000), wk = 0.1875000
.....

3. Go in the '''phonon''' directory. You have to copy the k-points list in the ''2pi/alat'' units from the previous nscf run and use it as q-grid for the phonon calculations. Notice that due to an internal convection of Yambo the q-points have to be multiplied for -1 before add them to the phonons input. You can use this simple python script [http://www.yambo-code.org/educational/tutorials/files/minus_kpoints.py minuq_kpoints.py] to read k-points from the QE output and multiply them by minus one.
The final input will be:
&inputph
verbosity = 'high'
tr2_ph = 1e-12h
prefix = 'si'
fildvscf = 'si-dvscf'
fildyn = 'si.dyn',
electron_phonon = 'dvscf',
epsil = .true.
trans = .true.
ldisp = .false.
qplot = .true.
/
8
0.000000000 0.000000000 0.000000000 1
-0.125000000 -0.125000000 0.125000000 1
0.250000000 0.250000000 -0.250000000 1
-0.250000000 0.000000000 0.000000000 1
-0.375000000 -0.125000000 0.125000000 1
0.000000000 0.250000000 -0.250000000 1
0.500000000 0.000000000 0.000000000 1
0.500000000 -0.250000000 0.000000000 1

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

&inputph
verbosity = 'high'
tr2_ph = 1e-12
prefix = 'si'
fildvscf = 'si-dvscf'
fildyn = 'si.dyn'
electron_phonon = 'yambo',
epsil = .true.
trans = .false.
ldisp = .false.
qplot = .true.
/
8
0.000000000 0.000000000 0.000000000 1
-0.125000000 -0.125000000 0.125000000 1
0.250000000 0.250000000 -0.250000000 1
-0.250000000 0.000000000 0.000000000 1
-0.375000000 -0.125000000 0.125000000 1
0.000000000 0.250000000 -0.250000000 1
0.500000000 0.000000000 0.000000000 1
0.500000000 -0.250000000 0.000000000 1

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

5. Now you have to read the wave-functions. Go in the ''dvscf/si.save'' folder, do ''p2y'', then ''yambo_ph -i -V kpt'' and turn on the flag BSEscatt, then run the setup. Now you use ypp_ph to import electron-phonon coupling, by doing ''ypp_ph -g' and the the PW el-ph folder:

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

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

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

== Quasi-particle band structure ==
The first quantity we will calculate is the correction to the band structure induced by the electron-phonon coupling. In order to generate the corresponding input do ''yambo_ph -g n -p fan -c p -V gen'' (in the newer versions of Yambo this line will be changed in ''yambo_ph -g n -p ep -c p -V gen''). In the input we require the correction only at gamma point:

dyson # [R] Dyson Equation solver
gw0 # [R] GW approximation
el_ph_corr # [R] Electron-Phonon Correlation
Nelectro= 8.000000 # Electrons number
ElecTemp= 0.000000 eV # Electronic Temperature
BoseTemp= 0.000000 eV # Bosonic Temperature
OccTresh= 0.100000E-4 # Occupation treshold (metallic bands)
SE_Threads=0 # [OPENMP/GW] Number of threads for self-energy
DysSolver= "n" # [GW] Dyson Equation solver ("n","s","g")
GphBRnge= 12 # [ELPH] G[W] bands range
% ElPhModes
1 | 6 | # [ELPH] Phonon modes included
%
RandQpts=0 # [RIM] Number of random q-points in the BZ
#WRgFsq # [ELPH] Dump on file gFsq coefficients
%QPkrange # [GW] QP generalized Kpoint/Band indices
1|1|4|5|
%

If you run yambo_ph -J T0 you will get correction at zero kelvin to the band structure. You can change the temperature to 300 K by doing:

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

== Optical properties ==

Now you repeat the previous calculation but including all k-points, the last 3 valence and the first 3 conduction bands:

.....
%QPkrange # [GW] QP generalized Kpoint/Band indices
1|8|2|7|
%
....
and save the results of the 0K and 300K temperature in two separate folder with the -J option.
Now you can use the correction to the energy levels and the induced width to calculate the optical absorption at finite temperature. Generate the input with the command ''yambo_ph -o c -V qp''

optics # [R] Linear Response optical properties
chi # [R][CHI] Dyson equation for Chi.
dipoles # [R] Oscillator strenghts (or dipoles)
Chimod= "IP" # [X] IP/Hartree/ALDA/LRC/PF/BSfxc
% QpntsRXd
1 | 1 | # [Xd] Transferred momenta
%
% BndsRnXd
2 | 7 | # [Xd] Polarization function bands
%
% EnRngeXd
0.000000 | 5.000000 | eV # [Xd] Energy range
%
% DmRngeXd
0.0100000 | 0.0100000 | eV # [Xd] Damping range
%
ETStpsXd= 500 # [Xd] Total Energy steps
% LongDrXd
1.000000 | 0.000000 | 0.000000 | # [Xd] [cc] Electric Field
%
XfnQPdb= "E W < T300/ndb.QP" # [EXTQP Xd] Database action

set the path of the ''ndb.QP'' you want to read and perform the calculations. Notice that from the QP database we read two quantities the correction to the energy levels E and the width W. In this calculation we also included a small smearing 0.01eV to mimic the electronic smearing. Hereafter the result without and with electron-phonon coupling at two different temperatures:
[[File:Si absorption finite t.png|800px|center |Absorption of bulk silicon at finite temperature]]

The same procedure can be applied to the Bethe-Salpeter calculations. However in this case results can be slightly wrong. If fact electron-phonon matrix elements should be rotate in the excitonic space, as it was done in ref. <ref> H. Chen, D. Sangalli, and M. Bernardi, [https://arxiv.org/abs/2002.08913 Phys. Rev. Lett. '''125''' 107401 (2020)]</ref>, while at present Yambo calculate the exciton width from the correction to the single particle bands, see ref. <ref name=marini>A. Marini, [https://arxiv.org/abs/0712.3365 Phys. Rev. Lett. '''101''' 106405 (2008)]</ref> . This approximation is correct in case of not-strong bounded excitons, and unfortunately this is not the case.

== Convergence ==

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

== Double-grid method for the electron-phonon coupling ==

To be done

== Miscellaneous and post-processing ==
There are a list of utilities to analyze electron-phonon coupling results:

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

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

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

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

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

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

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

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

For the excitonic Eliashberg functions use the command ''ypp_ph -e e'', an example of these functions can be found in ref.<ref name=marini></ref>.

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

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

==References==
<references />

Electron Phonon Coupling

2021-01-04T08:34:44Z

Claudio: /* Optical properties */

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

== Electron-phonon matrix elements ==

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

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

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

1. In '''scf''' we run a standard scf calculation choosing the a large k-grid in such a way to converge density. Do not forget to set ''force_symmorphic=.true.'', because not symmorphic symmetries are not supported yet in Yambo. Notice that if you are working with 2D systems, not our case, we have to add the flag ''assume_isolated="2D"'' in such a way correct 2D phonons.

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

.....
number of k points= 8
cart. coord. in units 2pi/alat
k( 1) = ( 0.0000000 0.0000000 0.0000000), wk = 0.0312500
k( 2) = ( 0.1250000 0.1250000 -0.1250000), wk = 0.2500000
k( 3) = ( -0.2500000 -0.2500000 0.2500000), wk = 0.1250000
k( 4) = ( 0.2500000 0.0000000 0.0000000), wk = 0.1875000
k( 5) = ( -0.1250000 -0.3750000 0.3750000), wk = 0.7500000
k( 6) = ( 0.0000000 -0.2500000 0.2500000), wk = 0.3750000
k( 7) = ( -0.5000000 0.0000000 0.0000000), wk = 0.0937500
k( 8) = ( -0.5000000 0.2500000 0.0000000), wk = 0.1875000
.....

3. Go in the '''phonon''' directory. You have to copy the k-points list in the ''2pi/alat'' units from the previous nscf run and use it as q-grid for the phonon calculations. Notice that due to an internal convection of Yambo the q-points have to be multiplied for -1 before add them to the phonons input. You can use this simple python script [http://www.yambo-code.org/educational/tutorials/files/minus_kpoints.py minuq_kpoints.py] to read k-points from the QE output and multiply them by minus one.
The final input will be:
&inputph
verbosity = 'high'
tr2_ph = 1e-12h
prefix = 'si'
fildvscf = 'si-dvscf'
fildyn = 'si.dyn',
electron_phonon = 'dvscf',
epsil = .true.
trans = .true.
ldisp = .false.
qplot = .true.
/
8
0.000000000 0.000000000 0.000000000 1
-0.125000000 -0.125000000 0.125000000 1
0.250000000 0.250000000 -0.250000000 1
-0.250000000 0.000000000 0.000000000 1
-0.375000000 -0.125000000 0.125000000 1
0.000000000 0.250000000 -0.250000000 1
0.500000000 0.000000000 0.000000000 1
0.500000000 -0.250000000 0.000000000 1

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

&inputph
verbosity = 'high'
tr2_ph = 1e-12
prefix = 'si'
fildvscf = 'si-dvscf'
fildyn = 'si.dyn'
electron_phonon = 'yambo',
epsil = .true.
trans = .false.
ldisp = .false.
qplot = .true.
/
8
0.000000000 0.000000000 0.000000000 1
-0.125000000 -0.125000000 0.125000000 1
0.250000000 0.250000000 -0.250000000 1
-0.250000000 0.000000000 0.000000000 1
-0.375000000 -0.125000000 0.125000000 1
0.000000000 0.250000000 -0.250000000 1
0.500000000 0.000000000 0.000000000 1
0.500000000 -0.250000000 0.000000000 1

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

5. Now you have to read the wave-functions. Go in the ''dvscf/si.save'' folder, do ''p2y'', then ''yambo_ph -i -V kpt'' and turn on the flag BSEscatt, then run the setup. Now you use ypp_ph to import electron-phonon coupling, by doing ''ypp_ph -g' and the the PW el-ph folder:

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

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

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

== Quasi-particle band structure ==
The first quantity we will calculate is the correction to the band structure induced by the electron-phonon coupling. In order to generate the corresponding input do ''yambo_ph -g n -p fan -c p -V gen'' (in the newer versions of Yambo this line will be changed in ''yambo_ph -g n -p ep -c p -V gen''). In the input we require the correction only at gamma point:

dyson # [R] Dyson Equation solver
gw0 # [R] GW approximation
el_ph_corr # [R] Electron-Phonon Correlation
Nelectro= 8.000000 # Electrons number
ElecTemp= 0.000000 eV # Electronic Temperature
BoseTemp= 0.000000 eV # Bosonic Temperature
OccTresh= 0.100000E-4 # Occupation treshold (metallic bands)
SE_Threads=0 # [OPENMP/GW] Number of threads for self-energy
DysSolver= "n" # [GW] Dyson Equation solver ("n","s","g")
GphBRnge= 12 # [ELPH] G[W] bands range
% ElPhModes
1 | 6 | # [ELPH] Phonon modes included
%
RandQpts=0 # [RIM] Number of random q-points in the BZ
#WRgFsq # [ELPH] Dump on file gFsq coefficients
%QPkrange # [GW] QP generalized Kpoint/Band indices
1|1|4|5|
%

If you run yambo_ph -J T0 you will get correction at zero kelvin to the band structure. You can change the temperature to 300 K by doing:

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

== Optical properties ==

Now you repeat the previous calculation but including all k-points, the last 3 valence and the first 3 conduction bands:

.....
%QPkrange # [GW] QP generalized Kpoint/Band indices
1|8|2|7|
%
....
and save the results of the 0K and 300K temperature in two separate folder with the -J option.
Now you can use the correction to the energy levels and the induced width to calculate the optical absorption at finite temperature. Generate the input with the command ''yambo_ph -o c -V qp''

optics # [R] Linear Response optical properties
chi # [R][CHI] Dyson equation for Chi.
dipoles # [R] Oscillator strenghts (or dipoles)
Chimod= "IP" # [X] IP/Hartree/ALDA/LRC/PF/BSfxc
% QpntsRXd
1 | 1 | # [Xd] Transferred momenta
%
% BndsRnXd
2 | 7 | # [Xd] Polarization function bands
%
% EnRngeXd
0.000000 | 5.000000 | eV # [Xd] Energy range
%
% DmRngeXd
0.0100000 | 0.0100000 | eV # [Xd] Damping range
%
ETStpsXd= 500 # [Xd] Total Energy steps
% LongDrXd
1.000000 | 0.000000 | 0.000000 | # [Xd] [cc] Electric Field
%
XfnQPdb= "E W < T300/ndb.QP" # [EXTQP Xd] Database action

set the path of the ''ndb.QP'' you want to read and perform the calculations. Notice that from the QP database we read two quantities the correction to the energy levels E and the width W. In this calculation we also included a small smearing 0.01eV to mimic the electronic smearing. Hereafter the result without and with electron-phonon coupling at two different temperatures:
[[File:Si absorption finite t.png|800px|center |Absorption of bulk silicon at finite temperature]]

The same procedure can be applied to the Bethe-Salpeter calculations. However in this case results can be slightly wrong. If fact electron-phonon matrix elements should be rotate in the excitonic space, as it was done in ref. <ref> see Supp. Mat. of E. Cannuccia, B. Monserrat, and C. Attaccalite [https://journals.aps.org/prb/abstract/10.1103/PhysRevB.99.081109
Phys. Rev. B 99, 081109(R)]<ref>, while at present Yambo calculate the exciton width from the correction to the single particle bands, see ref. <ref name=marini>A. Marini, [https://arxiv.org/abs/0712.3365 Phys. Rev. Lett. '''101''' 106405 (2008)]</ref> . This approximation is correct in case of not-strong bounded excitons, and unfortunately this is not the case.

== Convergence ==

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

== Double-grid method for the electron-phonon coupling ==

To be done

== Miscellaneous and post-processing ==
There are a list of utilities to analyze electron-phonon coupling results:

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

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

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

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

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

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

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

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

For the excitonic Eliashberg functions use the command ''ypp_ph -e e'', an example of these functions can be found in ref.<ref name=marini></ref>.

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

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

==References==
<references />

Electron Phonon Coupling

2020-12-18T17:11:00Z

Claudio: /* Electron-phonon matrix elements */

File:Si gap finite t.png

2020-12-18T17:04:59Z

Claudio: Claudio uploaded a new version of File:Si gap finite t.png

=={{int:filedesc}}==
{{Information
|description={{en|1=Yambo tutorial image}}
|date=2020-12-18
|source={{own}}
|author=[[User:Claudio|Claudio]]
|permission=
|other versions=
}}

=={{int:license-header}}==
{{self|cc-by-sa-4.0}}

This file was uploaded with the UploadWizard extension.

[[Category:Uploaded with UploadWizard]]

File:Si gap finite t.png

2020-12-18T17:02:40Z

Claudio: Claudio uploaded a new version of File:Si gap finite t.png

Electron Phonon Coupling

2020-12-18T17:00:05Z

Claudio: /* Quasi-particle band structure */

Electron Phonon Coupling

2020-12-18T16:59:30Z

Claudio: /* Quasi-particle band structure */

Electron Phonon Coupling

2020-12-18T16:58:05Z

Claudio: /* Quasi-particle band structure */

File:Si gap finite t.png

2020-12-18T16:54:24Z

Claudio: User created page with UploadWizard

Electron Phonon Coupling

2020-12-18T16:46:41Z

Claudio: /* Quasi-particle band structure */

Electron Phonon Coupling

2020-12-18T16:44:38Z

Claudio: /* Electron-phonon matrix elements */

Electron Phonon Coupling

2020-12-18T16:43:53Z

Claudio: /* Electron-phonon matrix elements */

Electron Phonon Coupling

2020-12-18T16:43:18Z

Claudio: /* Electron-phonon matrix elements */

Electron Phonon Coupling

2020-12-18T16:42:55Z

Claudio: /* Electron-phonon matrix elements */

Electron Phonon Coupling

2020-12-18T15:58:29Z

Claudio: /* Electron-phonon matrix elements */

Electron Phonon Coupling

2020-12-18T15:55:40Z

Claudio: /* Electron-phonon matrix elements */

Electron Phonon Coupling

2020-12-18T15:32:23Z

Claudio: /* Electron-phonon matrix elements */

Electron Phonon Coupling

2020-12-18T15:31:52Z

Claudio: /* Electron-phonon matrix elements */

Electron Phonon Coupling

2020-12-18T15:17:49Z

Claudio: /* Optical properties */

Electron Phonon Coupling

2020-12-18T15:17:18Z

Claudio: /* Optical properties */

Electron Phonon Coupling

2020-12-18T15:15:05Z

Claudio:

Electron Phonon Coupling

2020-12-18T14:09:35Z

Claudio: /* Electron-phonon matrix elements */

Electron Phonon Coupling

2020-12-18T11:54:55Z

Claudio: /* Special note for FCC cells */

Electron Phonon Coupling

2020-12-18T09:38:04Z

Claudio: /* Special note for FCC cells */

Here we show step-by-step how to use [https://www.quantum-espresso.org/ Quantum Espresso] to calculate phonons and electron-phonon matrix-elements on a regular q-grid,
with the final aim to allow Yambo to read these databases and calculate the temperature-dependent correction to the electronic states.
This tutorial is quite complicated, take your time to follow all the steps

== Electron-phonon matrix elements ==

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

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

In this tutorial we will show how to calculate electron-phonon induced corrections to the bands and optical properties of 2D hexagonal boron nitride.
All input file are availabe in the following tgz file: [http://www.yambo-code.org/educational/tutorials/files/hBN.epc.tgz hBN.epc.tgz]

1. In '''scf''' we run a standard scf calculation choosing the a large k-grid in such a way to converge density. Do not forget to set ''force_symmorphic=.true.'', because not symmorphic symmetries are not supported yet in Yambo. Notice that because the present system is two-dimensional we added the flag ''assume_isolated="2D"'' in such a way correct phonons in 2D, remove this flag is you have a system with a different dimensionality (a bulk, a molecule etc...)

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

.....
number of k points= 12
cart. coord. in units 2pi/alat
k( 1) = ( 0.0000000 0.0000000 0.0000000), wk = 0.0246914
k( 2) = ( 0.0000000 0.1283001 0.0000000), wk = 0.1481481
k( 3) = ( 0.0000000 0.2566001 0.0000000), wk = 0.1481481
k( 4) = ( 0.0000000 0.3849002 0.0000000), wk = 0.1481481
k( 5) = ( 0.0000000 0.5132002 0.0000000), wk = 0.1481481
k( 6) = ( 0.1111111 0.1924501 0.0000000), wk = 0.1481481
k( 7) = ( 0.1111111 0.3207501 0.0000000), wk = 0.2962963
k( 8) = ( 0.1111111 0.4490502 0.0000000), wk = 0.2962963
k( 9) = ( 0.1111111 0.5773503 0.0000000), wk = 0.1481481
k( 10) = ( 0.2222222 0.3849002 0.0000000), wk = 0.1481481
k( 11) = ( 0.2222222 0.5132002 0.0000000), wk = 0.2962963
k( 12) = ( 0.3333333 0.5773503 0.0000000), wk = 0.0493827
.....

3. Go in the '''phonon''' directory. You have to copy the k-points list in the ''2pi/alat'' units from the previous nscf run and provide it as q-grid for the phonon calculations. Notice that due to an internal convection of Yambo the q-points have to be multiplied for -1 before add them to the phonons input. In the last Yambo version you can also generate the k/q list with the minus sign using the ''ypp -k q'' and turning one the MinusQ flag. The final input will be:
&inputph
verbosity = 'high'
tr2_ph = 1e-12h
prefix = 'bn'
fildvscf = 'bn-dvscf'
fildyn = 'bn.dyn',
electron_phonon = 'dvscf',
epsil = .true.
trans = .true.
ldisp = .false.
qplot = .true.
/
12
0.0000000 0.0000000 0.0000000 1
0.0000000 -0.1283001 0.0000000 1
0.0000000 -0.2566001 0.0000000 1
0.0000000 -0.3849002 0.0000000 1
0.0000000 -0.5132002 0.0000000 1
-0.1111111 -0.1924501 0.0000000 1
-0.1111111 -0.3207501 0.0000000 1
-0.1111111 -0.4490502 0.0000000 1
-0.1111111 -0.5773503 0.0000000 1
-0.2222222 -0.3849002 0.0000000 1
-0.2222222 -0.5132002 0.0000000 1
-0.3333333 -0.5773503 0.0000000 1

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

&inputph
verbosity = 'high'
tr2_ph = 1e-12
prefix = 'bn'
fildvscf = 'bn-dvscf'
fildyn = 'bn.dyn'
electron_phonon = 'yambo',
epsil = .true.
trans = .false.
ldisp = .false.
qplot = .true.
/
12
0.0000000 0.0000000 0.0000000 1
0.0000000 -0.1283001 0.0000000 1
0.0000000 -0.2566001 0.0000000 1
0.0000000 -0.3849002 0.0000000 1
0.0000000 -0.5132002 0.0000000 1
-0.1111111 -0.1924501 0.0000000 1
-0.1111111 -0.3207501 0.0000000 1
-0.1111111 -0.4490502 0.0000000 1
-0.1111111 -0.5773503 0.0000000 1
-0.2222222 -0.3849002 0.0000000 1
-0.2222222 -0.5132002 0.0000000 1
-0.3333333 -0.5773503 0.0000000 1

this run will generate a new folder ''elph_dir'' with all electron-phonon matrix elements in a format compatible with Yambo.

5. Now you have to read the wave-functions. Go in the ''dvscf/bn.save'' folder, do ''p2y'', then ''yambo_ph -i -V kpt'' and turn on the flag BSEscatt, then run the setup. Now you use ypp_ph to import electron-phonon coupling, by doing ''ypp_ph -g' and the the PW el-ph folder:

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

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

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

== Quasi-particle band structure ==
The first quantity we will calculate is the correction to the band structure induced by the electron-phonon coupling. In order to generate the corresponding input do ''yambo_ph -g n -p fan -c p -V gen'' (in the newer versions of Yambo this line will be changed in ''yambo_ph -g n -p ep -c p -V gen''):

dyson # [R] Dyson Equation solver
gw0 # [R] GW approximation
el_ph_corr # [R] Electron-Phonon Correlation
Nelectro= 8.000000 # Electrons number
ElecTemp= 0.000000 eV # Electronic Temperature
BoseTemp= 0.000000 eV # Bosonic Temperature
OccTresh= 0.100000E-4 # Occupation treshold (metallic bands)
SE_Threads=0 # [OPENMP/GW] Number of threads for self-energy
DysSolver= "n" # [GW] Dyson Equation solver ("n","s","g")
GphBRnge= 8 # [ELPH] G[W] bands range
% ElPhModes
1 | 6 | # [ELPH] Phonon modes included
%
RandQpts=0 # [RIM] Number of random q-points in the BZ
#WRgFsq # [ELPH] Dump on file gFsq coefficients
%QPkrange # [GW] QP generalized Kpoint/Band indices
1|12|1|8|
%

If you run yambo_ph -J T0 you will get correction at zero kelvin to the band structure. You can change the temperature to 300 K by doing:

dyson # [R] Dyson Equation solver
gw0 # [R] GW approximation
el_ph_corr # [R] Electron-Phonon Correlation
Nelectro= 8.000000 # Electrons number
ElecTemp= 0.000000 eV # Electronic Temperature
BoseTemp= 300.0 K # Bosonic Temperature
OccTresh= 0.100000E-4 # Occupation treshold (metallic bands)
SE_Threads=0 # [OPENMP/GW] Number of threads for self-energy
DysSolver= "n" # [GW] Dyson Equation solver ("n","s","g")
GphBRnge= 8 # [ELPH] G[W] bands range
% ElPhModes
1 | 6 | # [ELPH] Phonon modes included
%
RandQpts=0 # [RIM] Number of random q-points in the BZ
#WRgFsq # [ELPH] Dump on file gFsq coefficients
%QPkrange # [GW] QP generalized Kpoint/Band indices
1|12|1|8|
%
run again ''yambo_ph -J T300'' and compare the two output file o-T0.qp and o-T300.qp, to find how much the gap change with the temperature.

== Optical properties ==

You can use the previous calculate quasi-particle band structure to get optical properties, by doing ''yambo_ph -o b -k sex -y d -V qp -X s'' and then reading the corresponding ndb.QP database KfnQPdb= "E < SAVE/ndb.QP"

Nota bene: Calculation of exciton width is not completely correct. If fact electron-phonon matrix elements should be rotate in the excitonic space, as it was done in Ref. [https://journals.aps.org/prl/abstract/10.1103/PhysRevLett.125.107401 Phys. Rev. Lett. '''125''' 107401 (2020)], while at present Yambo calculate the exciton width from the correction to the single particle bands, see ref. [https://journals.aps.org/prl/abstract/10.1103/PhysRevLett.101.106405 Phys. Rev. Lett. '''101''' 106405 (2008)]. This approximation is correct in case of not-strong bounded excitons, and unfortunately this is not the case.

== Convergence ==

The results of this tutorial are not converged, and if you check output there are also some phonon mode with negative energies. This is due to the poor parameters used in this tutorial. In order to have converged results, first of all be sure to have converged phonons, increase the plane-wave cutoff, the number of k-points and if necessary reduce ''tr2_ph''.
Then change the paramters for the Yambo calculations, increasing the number of '''k''' and '''q''' points and the number of bands. If you want to increase only the number of bands, just repeat the '''nscf''' and '''dvscf''' calculations without recalculate the '''phonons'''.

== Miscellaneous and post-processing ==
There are a list of utilities to analyze electron-phonon coupling results:
* ''ypp_ph -p d'' -> to plot the phonon density of states
* ''ypp_ph -p e'' -> to plot Eliashberg Functions
* ''ypp_ph -p a'' -> to analyze single atom amplitudes (to be fixed)

== Special note for FCC cells ==

In QuantumEspresso there is a different convention respect to Yambo and other codes in the definition of FCC units cell (ibrav=2, 3, and -3), this results in alat parameter two time smaller than the expected one in Yambo.
If you import WF from these calculation please ''p2y -a 2.0''. Otherwise a better solution is to define the FCC cell in a standard way, for example the silicon input becomes:

Electron Phonon Coupling

2020-12-18T09:37:46Z

Claudio: /* Special note for FCC cells */

Here we show step-by-step how to use [https://www.quantum-espresso.org/ Quantum Espresso] to calculate phonons and electron-phonon matrix-elements on a regular q-grid,
with the final aim to allow Yambo to read these databases and calculate the temperature-dependent correction to the electronic states.
This tutorial is quite complicated, take your time to follow all the steps

== Electron-phonon matrix elements ==

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

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

In this tutorial we will show how to calculate electron-phonon induced corrections to the bands and optical properties of 2D hexagonal boron nitride.
All input file are availabe in the following tgz file: [http://www.yambo-code.org/educational/tutorials/files/hBN.epc.tgz hBN.epc.tgz]

1. In '''scf''' we run a standard scf calculation choosing the a large k-grid in such a way to converge density. Do not forget to set ''force_symmorphic=.true.'', because not symmorphic symmetries are not supported yet in Yambo. Notice that because the present system is two-dimensional we added the flag ''assume_isolated="2D"'' in such a way correct phonons in 2D, remove this flag is you have a system with a different dimensionality (a bulk, a molecule etc...)

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

.....
number of k points= 12
cart. coord. in units 2pi/alat
k( 1) = ( 0.0000000 0.0000000 0.0000000), wk = 0.0246914
k( 2) = ( 0.0000000 0.1283001 0.0000000), wk = 0.1481481
k( 3) = ( 0.0000000 0.2566001 0.0000000), wk = 0.1481481
k( 4) = ( 0.0000000 0.3849002 0.0000000), wk = 0.1481481
k( 5) = ( 0.0000000 0.5132002 0.0000000), wk = 0.1481481
k( 6) = ( 0.1111111 0.1924501 0.0000000), wk = 0.1481481
k( 7) = ( 0.1111111 0.3207501 0.0000000), wk = 0.2962963
k( 8) = ( 0.1111111 0.4490502 0.0000000), wk = 0.2962963
k( 9) = ( 0.1111111 0.5773503 0.0000000), wk = 0.1481481
k( 10) = ( 0.2222222 0.3849002 0.0000000), wk = 0.1481481
k( 11) = ( 0.2222222 0.5132002 0.0000000), wk = 0.2962963
k( 12) = ( 0.3333333 0.5773503 0.0000000), wk = 0.0493827
.....

3. Go in the '''phonon''' directory. You have to copy the k-points list in the ''2pi/alat'' units from the previous nscf run and provide it as q-grid for the phonon calculations. Notice that due to an internal convection of Yambo the q-points have to be multiplied for -1 before add them to the phonons input. In the last Yambo version you can also generate the k/q list with the minus sign using the ''ypp -k q'' and turning one the MinusQ flag. The final input will be:
&inputph
verbosity = 'high'
tr2_ph = 1e-12h
prefix = 'bn'
fildvscf = 'bn-dvscf'
fildyn = 'bn.dyn',
electron_phonon = 'dvscf',
epsil = .true.
trans = .true.
ldisp = .false.
qplot = .true.
/
12
0.0000000 0.0000000 0.0000000 1
0.0000000 -0.1283001 0.0000000 1
0.0000000 -0.2566001 0.0000000 1
0.0000000 -0.3849002 0.0000000 1
0.0000000 -0.5132002 0.0000000 1
-0.1111111 -0.1924501 0.0000000 1
-0.1111111 -0.3207501 0.0000000 1
-0.1111111 -0.4490502 0.0000000 1
-0.1111111 -0.5773503 0.0000000 1
-0.2222222 -0.3849002 0.0000000 1
-0.2222222 -0.5132002 0.0000000 1
-0.3333333 -0.5773503 0.0000000 1

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

&inputph
verbosity = 'high'
tr2_ph = 1e-12
prefix = 'bn'
fildvscf = 'bn-dvscf'
fildyn = 'bn.dyn'
electron_phonon = 'yambo',
epsil = .true.
trans = .false.
ldisp = .false.
qplot = .true.
/
12
0.0000000 0.0000000 0.0000000 1
0.0000000 -0.1283001 0.0000000 1
0.0000000 -0.2566001 0.0000000 1
0.0000000 -0.3849002 0.0000000 1
0.0000000 -0.5132002 0.0000000 1
-0.1111111 -0.1924501 0.0000000 1
-0.1111111 -0.3207501 0.0000000 1
-0.1111111 -0.4490502 0.0000000 1
-0.1111111 -0.5773503 0.0000000 1
-0.2222222 -0.3849002 0.0000000 1
-0.2222222 -0.5132002 0.0000000 1
-0.3333333 -0.5773503 0.0000000 1

this run will generate a new folder ''elph_dir'' with all electron-phonon matrix elements in a format compatible with Yambo.

5. Now you have to read the wave-functions. Go in the ''dvscf/bn.save'' folder, do ''p2y'', then ''yambo_ph -i -V kpt'' and turn on the flag BSEscatt, then run the setup. Now you use ypp_ph to import electron-phonon coupling, by doing ''ypp_ph -g' and the the PW el-ph folder:

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

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

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

== Quasi-particle band structure ==
The first quantity we will calculate is the correction to the band structure induced by the electron-phonon coupling. In order to generate the corresponding input do ''yambo_ph -g n -p fan -c p -V gen'' (in the newer versions of Yambo this line will be changed in ''yambo_ph -g n -p ep -c p -V gen''):

dyson # [R] Dyson Equation solver
gw0 # [R] GW approximation
el_ph_corr # [R] Electron-Phonon Correlation
Nelectro= 8.000000 # Electrons number
ElecTemp= 0.000000 eV # Electronic Temperature
BoseTemp= 0.000000 eV # Bosonic Temperature
OccTresh= 0.100000E-4 # Occupation treshold (metallic bands)
SE_Threads=0 # [OPENMP/GW] Number of threads for self-energy
DysSolver= "n" # [GW] Dyson Equation solver ("n","s","g")
GphBRnge= 8 # [ELPH] G[W] bands range
% ElPhModes
1 | 6 | # [ELPH] Phonon modes included
%
RandQpts=0 # [RIM] Number of random q-points in the BZ
#WRgFsq # [ELPH] Dump on file gFsq coefficients
%QPkrange # [GW] QP generalized Kpoint/Band indices
1|12|1|8|
%

If you run yambo_ph -J T0 you will get correction at zero kelvin to the band structure. You can change the temperature to 300 K by doing:

dyson # [R] Dyson Equation solver
gw0 # [R] GW approximation
el_ph_corr # [R] Electron-Phonon Correlation
Nelectro= 8.000000 # Electrons number
ElecTemp= 0.000000 eV # Electronic Temperature
BoseTemp= 300.0 K # Bosonic Temperature
OccTresh= 0.100000E-4 # Occupation treshold (metallic bands)
SE_Threads=0 # [OPENMP/GW] Number of threads for self-energy
DysSolver= "n" # [GW] Dyson Equation solver ("n","s","g")
GphBRnge= 8 # [ELPH] G[W] bands range
% ElPhModes
1 | 6 | # [ELPH] Phonon modes included
%
RandQpts=0 # [RIM] Number of random q-points in the BZ
#WRgFsq # [ELPH] Dump on file gFsq coefficients
%QPkrange # [GW] QP generalized Kpoint/Band indices
1|12|1|8|
%
run again ''yambo_ph -J T300'' and compare the two output file o-T0.qp and o-T300.qp, to find how much the gap change with the temperature.

== Optical properties ==

You can use the previous calculate quasi-particle band structure to get optical properties, by doing ''yambo_ph -o b -k sex -y d -V qp -X s'' and then reading the corresponding ndb.QP database KfnQPdb= "E < SAVE/ndb.QP"

Nota bene: Calculation of exciton width is not completely correct. If fact electron-phonon matrix elements should be rotate in the excitonic space, as it was done in Ref. [https://journals.aps.org/prl/abstract/10.1103/PhysRevLett.125.107401 Phys. Rev. Lett. '''125''' 107401 (2020)], while at present Yambo calculate the exciton width from the correction to the single particle bands, see ref. [https://journals.aps.org/prl/abstract/10.1103/PhysRevLett.101.106405 Phys. Rev. Lett. '''101''' 106405 (2008)]. This approximation is correct in case of not-strong bounded excitons, and unfortunately this is not the case.

== Convergence ==

The results of this tutorial are not converged, and if you check output there are also some phonon mode with negative energies. This is due to the poor parameters used in this tutorial. In order to have converged results, first of all be sure to have converged phonons, increase the plane-wave cutoff, the number of k-points and if necessary reduce ''tr2_ph''.
Then change the paramters for the Yambo calculations, increasing the number of '''k''' and '''q''' points and the number of bands. If you want to increase only the number of bands, just repeat the '''nscf''' and '''dvscf''' calculations without recalculate the '''phonons'''.

== Miscellaneous and post-processing ==
There are a list of utilities to analyze electron-phonon coupling results:
* ''ypp_ph -p d'' -> to plot the phonon density of states
* ''ypp_ph -p e'' -> to plot Eliashberg Functions
* ''ypp_ph -p a'' -> to analyze single atom amplitudes (to be fixed)

== Special note for FCC cells ==

In QuantumEspresso there is a different convention respect to Yambo and other codes in the definition of FCC units cell (ibrav=2, 3, and -3), this results in alat parameter two time smaller than the expected one in Yambo.
If you import WF from these calculation please ''p2y -a 2.0''. Otherwise a better solution is to define the FCC cell in a standard way, for example the silicon input becomes:

Electron Phonon Coupling

2020-12-18T09:35:46Z

Claudio: /* Special note for FCC cells */

Here we show step-by-step how to use [https://www.quantum-espresso.org/ Quantum Espresso] to calculate phonons and electron-phonon matrix-elements on a regular q-grid,
with the final aim to allow Yambo to read these databases and calculate the temperature-dependent correction to the electronic states.
This tutorial is quite complicated, take your time to follow all the steps

== Electron-phonon matrix elements ==

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

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

In this tutorial we will show how to calculate electron-phonon induced corrections to the bands and optical properties of 2D hexagonal boron nitride.
All input file are availabe in the following tgz file: [http://www.yambo-code.org/educational/tutorials/files/hBN.epc.tgz hBN.epc.tgz]

1. In '''scf''' we run a standard scf calculation choosing the a large k-grid in such a way to converge density. Do not forget to set ''force_symmorphic=.true.'', because not symmorphic symmetries are not supported yet in Yambo. Notice that because the present system is two-dimensional we added the flag ''assume_isolated="2D"'' in such a way correct phonons in 2D, remove this flag is you have a system with a different dimensionality (a bulk, a molecule etc...)

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

.....
number of k points= 12
cart. coord. in units 2pi/alat
k( 1) = ( 0.0000000 0.0000000 0.0000000), wk = 0.0246914
k( 2) = ( 0.0000000 0.1283001 0.0000000), wk = 0.1481481
k( 3) = ( 0.0000000 0.2566001 0.0000000), wk = 0.1481481
k( 4) = ( 0.0000000 0.3849002 0.0000000), wk = 0.1481481
k( 5) = ( 0.0000000 0.5132002 0.0000000), wk = 0.1481481
k( 6) = ( 0.1111111 0.1924501 0.0000000), wk = 0.1481481
k( 7) = ( 0.1111111 0.3207501 0.0000000), wk = 0.2962963
k( 8) = ( 0.1111111 0.4490502 0.0000000), wk = 0.2962963
k( 9) = ( 0.1111111 0.5773503 0.0000000), wk = 0.1481481
k( 10) = ( 0.2222222 0.3849002 0.0000000), wk = 0.1481481
k( 11) = ( 0.2222222 0.5132002 0.0000000), wk = 0.2962963
k( 12) = ( 0.3333333 0.5773503 0.0000000), wk = 0.0493827
.....

3. Go in the '''phonon''' directory. You have to copy the k-points list in the ''2pi/alat'' units from the previous nscf run and provide it as q-grid for the phonon calculations. Notice that due to an internal convection of Yambo the q-points have to be multiplied for -1 before add them to the phonons input. In the last Yambo version you can also generate the k/q list with the minus sign using the ''ypp -k q'' and turning one the MinusQ flag. The final input will be:
&inputph
verbosity = 'high'
tr2_ph = 1e-12h
prefix = 'bn'
fildvscf = 'bn-dvscf'
fildyn = 'bn.dyn',
electron_phonon = 'dvscf',
epsil = .true.
trans = .true.
ldisp = .false.
qplot = .true.
/
12
0.0000000 0.0000000 0.0000000 1
0.0000000 -0.1283001 0.0000000 1
0.0000000 -0.2566001 0.0000000 1
0.0000000 -0.3849002 0.0000000 1
0.0000000 -0.5132002 0.0000000 1
-0.1111111 -0.1924501 0.0000000 1
-0.1111111 -0.3207501 0.0000000 1
-0.1111111 -0.4490502 0.0000000 1
-0.1111111 -0.5773503 0.0000000 1
-0.2222222 -0.3849002 0.0000000 1
-0.2222222 -0.5132002 0.0000000 1
-0.3333333 -0.5773503 0.0000000 1

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

&inputph
verbosity = 'high'
tr2_ph = 1e-12
prefix = 'bn'
fildvscf = 'bn-dvscf'
fildyn = 'bn.dyn'
electron_phonon = 'yambo',
epsil = .true.
trans = .false.
ldisp = .false.
qplot = .true.
/
12
0.0000000 0.0000000 0.0000000 1
0.0000000 -0.1283001 0.0000000 1
0.0000000 -0.2566001 0.0000000 1
0.0000000 -0.3849002 0.0000000 1
0.0000000 -0.5132002 0.0000000 1
-0.1111111 -0.1924501 0.0000000 1
-0.1111111 -0.3207501 0.0000000 1
-0.1111111 -0.4490502 0.0000000 1
-0.1111111 -0.5773503 0.0000000 1
-0.2222222 -0.3849002 0.0000000 1
-0.2222222 -0.5132002 0.0000000 1
-0.3333333 -0.5773503 0.0000000 1

this run will generate a new folder ''elph_dir'' with all electron-phonon matrix elements in a format compatible with Yambo.

5. Now you have to read the wave-functions. Go in the ''dvscf/bn.save'' folder, do ''p2y'', then ''yambo_ph -i -V kpt'' and turn on the flag BSEscatt, then run the setup. Now you use ypp_ph to import electron-phonon coupling, by doing ''ypp_ph -g' and the the PW el-ph folder:

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

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

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

== Quasi-particle band structure ==
The first quantity we will calculate is the correction to the band structure induced by the electron-phonon coupling. In order to generate the corresponding input do ''yambo_ph -g n -p fan -c p -V gen'' (in the newer versions of Yambo this line will be changed in ''yambo_ph -g n -p ep -c p -V gen''):

dyson # [R] Dyson Equation solver
gw0 # [R] GW approximation
el_ph_corr # [R] Electron-Phonon Correlation
Nelectro= 8.000000 # Electrons number
ElecTemp= 0.000000 eV # Electronic Temperature
BoseTemp= 0.000000 eV # Bosonic Temperature
OccTresh= 0.100000E-4 # Occupation treshold (metallic bands)
SE_Threads=0 # [OPENMP/GW] Number of threads for self-energy
DysSolver= "n" # [GW] Dyson Equation solver ("n","s","g")
GphBRnge= 8 # [ELPH] G[W] bands range
% ElPhModes
1 | 6 | # [ELPH] Phonon modes included
%
RandQpts=0 # [RIM] Number of random q-points in the BZ
#WRgFsq # [ELPH] Dump on file gFsq coefficients
%QPkrange # [GW] QP generalized Kpoint/Band indices
1|12|1|8|
%

If you run yambo_ph -J T0 you will get correction at zero kelvin to the band structure. You can change the temperature to 300 K by doing:

dyson # [R] Dyson Equation solver
gw0 # [R] GW approximation
el_ph_corr # [R] Electron-Phonon Correlation
Nelectro= 8.000000 # Electrons number
ElecTemp= 0.000000 eV # Electronic Temperature
BoseTemp= 300.0 K # Bosonic Temperature
OccTresh= 0.100000E-4 # Occupation treshold (metallic bands)
SE_Threads=0 # [OPENMP/GW] Number of threads for self-energy
DysSolver= "n" # [GW] Dyson Equation solver ("n","s","g")
GphBRnge= 8 # [ELPH] G[W] bands range
% ElPhModes
1 | 6 | # [ELPH] Phonon modes included
%
RandQpts=0 # [RIM] Number of random q-points in the BZ
#WRgFsq # [ELPH] Dump on file gFsq coefficients
%QPkrange # [GW] QP generalized Kpoint/Band indices
1|12|1|8|
%
run again ''yambo_ph -J T300'' and compare the two output file o-T0.qp and o-T300.qp, to find how much the gap change with the temperature.

== Optical properties ==

You can use the previous calculate quasi-particle band structure to get optical properties, by doing ''yambo_ph -o b -k sex -y d -V qp -X s'' and then reading the corresponding ndb.QP database KfnQPdb= "E < SAVE/ndb.QP"

Nota bene: Calculation of exciton width is not completely correct. If fact electron-phonon matrix elements should be rotate in the excitonic space, as it was done in Ref. [https://journals.aps.org/prl/abstract/10.1103/PhysRevLett.125.107401 Phys. Rev. Lett. '''125''' 107401 (2020)], while at present Yambo calculate the exciton width from the correction to the single particle bands, see ref. [https://journals.aps.org/prl/abstract/10.1103/PhysRevLett.101.106405 Phys. Rev. Lett. '''101''' 106405 (2008)]. This approximation is correct in case of not-strong bounded excitons, and unfortunately this is not the case.

== Convergence ==

The results of this tutorial are not converged, and if you check output there are also some phonon mode with negative energies. This is due to the poor parameters used in this tutorial. In order to have converged results, first of all be sure to have converged phonons, increase the plane-wave cutoff, the number of k-points and if necessary reduce ''tr2_ph''.
Then change the paramters for the Yambo calculations, increasing the number of '''k''' and '''q''' points and the number of bands. If you want to increase only the number of bands, just repeat the '''nscf''' and '''dvscf''' calculations without recalculate the '''phonons'''.

== Miscellaneous and post-processing ==
There are a list of utilities to analyze electron-phonon coupling results:
* ''ypp_ph -p d'' -> to plot the phonon density of states
* ''ypp_ph -p e'' -> to plot Eliashberg Functions
* ''ypp_ph -p a'' -> to analyze single atom amplitudes (to be fixed)

== Special note for FCC cells ==

In QuantumEspresso there is a different convention respect to Yambo and other codes in the definition of FCC units cell (ibrav=2, 3, and -3), this results in alat parameter two time smaller than the expected one in Yambo.
If you import WF from these calculation please ''p2y -a 2.0''. Otherwise a better solution is to define the FCC cell in a standard way, for example the silicon input becomes:

Electron Phonon Coupling

2020-12-18T09:33:36Z

Claudio: /* Special note for FCC cells */

Here we show step-by-step how to use [https://www.quantum-espresso.org/ Quantum Espresso] to calculate phonons and electron-phonon matrix-elements on a regular q-grid,
with the final aim to allow Yambo to read these databases and calculate the temperature-dependent correction to the electronic states.
This tutorial is quite complicated, take your time to follow all the steps

== Electron-phonon matrix elements ==

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

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

In this tutorial we will show how to calculate electron-phonon induced corrections to the bands and optical properties of 2D hexagonal boron nitride.
All input file are availabe in the following tgz file: [http://www.yambo-code.org/educational/tutorials/files/hBN.epc.tgz hBN.epc.tgz]

1. In '''scf''' we run a standard scf calculation choosing the a large k-grid in such a way to converge density. Do not forget to set ''force_symmorphic=.true.'', because not symmorphic symmetries are not supported yet in Yambo. Notice that because the present system is two-dimensional we added the flag ''assume_isolated="2D"'' in such a way correct phonons in 2D, remove this flag is you have a system with a different dimensionality (a bulk, a molecule etc...)

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

.....
number of k points= 12
cart. coord. in units 2pi/alat
k( 1) = ( 0.0000000 0.0000000 0.0000000), wk = 0.0246914
k( 2) = ( 0.0000000 0.1283001 0.0000000), wk = 0.1481481
k( 3) = ( 0.0000000 0.2566001 0.0000000), wk = 0.1481481
k( 4) = ( 0.0000000 0.3849002 0.0000000), wk = 0.1481481
k( 5) = ( 0.0000000 0.5132002 0.0000000), wk = 0.1481481
k( 6) = ( 0.1111111 0.1924501 0.0000000), wk = 0.1481481
k( 7) = ( 0.1111111 0.3207501 0.0000000), wk = 0.2962963
k( 8) = ( 0.1111111 0.4490502 0.0000000), wk = 0.2962963
k( 9) = ( 0.1111111 0.5773503 0.0000000), wk = 0.1481481
k( 10) = ( 0.2222222 0.3849002 0.0000000), wk = 0.1481481
k( 11) = ( 0.2222222 0.5132002 0.0000000), wk = 0.2962963
k( 12) = ( 0.3333333 0.5773503 0.0000000), wk = 0.0493827
.....

3. Go in the '''phonon''' directory. You have to copy the k-points list in the ''2pi/alat'' units from the previous nscf run and provide it as q-grid for the phonon calculations. Notice that due to an internal convection of Yambo the q-points have to be multiplied for -1 before add them to the phonons input. In the last Yambo version you can also generate the k/q list with the minus sign using the ''ypp -k q'' and turning one the MinusQ flag. The final input will be:
&inputph
verbosity = 'high'
tr2_ph = 1e-12h
prefix = 'bn'
fildvscf = 'bn-dvscf'
fildyn = 'bn.dyn',
electron_phonon = 'dvscf',
epsil = .true.
trans = .true.
ldisp = .false.
qplot = .true.
/
12
0.0000000 0.0000000 0.0000000 1
0.0000000 -0.1283001 0.0000000 1
0.0000000 -0.2566001 0.0000000 1
0.0000000 -0.3849002 0.0000000 1
0.0000000 -0.5132002 0.0000000 1
-0.1111111 -0.1924501 0.0000000 1
-0.1111111 -0.3207501 0.0000000 1
-0.1111111 -0.4490502 0.0000000 1
-0.1111111 -0.5773503 0.0000000 1
-0.2222222 -0.3849002 0.0000000 1
-0.2222222 -0.5132002 0.0000000 1
-0.3333333 -0.5773503 0.0000000 1

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

&inputph
verbosity = 'high'
tr2_ph = 1e-12
prefix = 'bn'
fildvscf = 'bn-dvscf'
fildyn = 'bn.dyn'
electron_phonon = 'yambo',
epsil = .true.
trans = .false.
ldisp = .false.
qplot = .true.
/
12
0.0000000 0.0000000 0.0000000 1
0.0000000 -0.1283001 0.0000000 1
0.0000000 -0.2566001 0.0000000 1
0.0000000 -0.3849002 0.0000000 1
0.0000000 -0.5132002 0.0000000 1
-0.1111111 -0.1924501 0.0000000 1
-0.1111111 -0.3207501 0.0000000 1
-0.1111111 -0.4490502 0.0000000 1
-0.1111111 -0.5773503 0.0000000 1
-0.2222222 -0.3849002 0.0000000 1
-0.2222222 -0.5132002 0.0000000 1
-0.3333333 -0.5773503 0.0000000 1

this run will generate a new folder ''elph_dir'' with all electron-phonon matrix elements in a format compatible with Yambo.

5. Now you have to read the wave-functions. Go in the ''dvscf/bn.save'' folder, do ''p2y'', then ''yambo_ph -i -V kpt'' and turn on the flag BSEscatt, then run the setup. Now you use ypp_ph to import electron-phonon coupling, by doing ''ypp_ph -g' and the the PW el-ph folder:

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

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

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

== Quasi-particle band structure ==
The first quantity we will calculate is the correction to the band structure induced by the electron-phonon coupling. In order to generate the corresponding input do ''yambo_ph -g n -p fan -c p -V gen'' (in the newer versions of Yambo this line will be changed in ''yambo_ph -g n -p ep -c p -V gen''):

dyson # [R] Dyson Equation solver
gw0 # [R] GW approximation
el_ph_corr # [R] Electron-Phonon Correlation
Nelectro= 8.000000 # Electrons number
ElecTemp= 0.000000 eV # Electronic Temperature
BoseTemp= 0.000000 eV # Bosonic Temperature
OccTresh= 0.100000E-4 # Occupation treshold (metallic bands)
SE_Threads=0 # [OPENMP/GW] Number of threads for self-energy
DysSolver= "n" # [GW] Dyson Equation solver ("n","s","g")
GphBRnge= 8 # [ELPH] G[W] bands range
% ElPhModes
1 | 6 | # [ELPH] Phonon modes included
%
RandQpts=0 # [RIM] Number of random q-points in the BZ
#WRgFsq # [ELPH] Dump on file gFsq coefficients
%QPkrange # [GW] QP generalized Kpoint/Band indices
1|12|1|8|
%

If you run yambo_ph -J T0 you will get correction at zero kelvin to the band structure. You can change the temperature to 300 K by doing:

dyson # [R] Dyson Equation solver
gw0 # [R] GW approximation
el_ph_corr # [R] Electron-Phonon Correlation
Nelectro= 8.000000 # Electrons number
ElecTemp= 0.000000 eV # Electronic Temperature
BoseTemp= 300.0 K # Bosonic Temperature
OccTresh= 0.100000E-4 # Occupation treshold (metallic bands)
SE_Threads=0 # [OPENMP/GW] Number of threads for self-energy
DysSolver= "n" # [GW] Dyson Equation solver ("n","s","g")
GphBRnge= 8 # [ELPH] G[W] bands range
% ElPhModes
1 | 6 | # [ELPH] Phonon modes included
%
RandQpts=0 # [RIM] Number of random q-points in the BZ
#WRgFsq # [ELPH] Dump on file gFsq coefficients
%QPkrange # [GW] QP generalized Kpoint/Band indices
1|12|1|8|
%
run again ''yambo_ph -J T300'' and compare the two output file o-T0.qp and o-T300.qp, to find how much the gap change with the temperature.

== Optical properties ==

You can use the previous calculate quasi-particle band structure to get optical properties, by doing ''yambo_ph -o b -k sex -y d -V qp -X s'' and then reading the corresponding ndb.QP database KfnQPdb= "E < SAVE/ndb.QP"

Nota bene: Calculation of exciton width is not completely correct. If fact electron-phonon matrix elements should be rotate in the excitonic space, as it was done in Ref. [https://journals.aps.org/prl/abstract/10.1103/PhysRevLett.125.107401 Phys. Rev. Lett. '''125''' 107401 (2020)], while at present Yambo calculate the exciton width from the correction to the single particle bands, see ref. [https://journals.aps.org/prl/abstract/10.1103/PhysRevLett.101.106405 Phys. Rev. Lett. '''101''' 106405 (2008)]. This approximation is correct in case of not-strong bounded excitons, and unfortunately this is not the case.

== Convergence ==

The results of this tutorial are not converged, and if you check output there are also some phonon mode with negative energies. This is due to the poor parameters used in this tutorial. In order to have converged results, first of all be sure to have converged phonons, increase the plane-wave cutoff, the number of k-points and if necessary reduce ''tr2_ph''.
Then change the paramters for the Yambo calculations, increasing the number of '''k''' and '''q''' points and the number of bands. If you want to increase only the number of bands, just repeat the '''nscf''' and '''dvscf''' calculations without recalculate the '''phonons'''.

== Miscellaneous and post-processing ==
There are a list of utilities to analyze electron-phonon coupling results:
* ''ypp_ph -p d'' -> to plot the phonon density of states
* ''ypp_ph -p e'' -> to plot Eliashberg Functions
* ''ypp_ph -p a'' -> to analyze single atom amplitudes (to be fixed)

== Special note for FCC cells ==

In QuantumEspresso there is a different convention respect to Yambo and other codes in the definition of FCC units cell (ibrav=2, 3, and -3), this results in alat parameter two time smaller than the expected one in Yambo.
If you import WF from these calculation please ''p2y -a 2.0''. Otherwise a better solution is to define the FCC cell in a standard way, for example the silicon input becomes:

Electron Phonon Coupling

2020-12-18T09:16:23Z

Claudio: /* Special note for FCC cells */

Here we show step-by-step how to use [https://www.quantum-espresso.org/ Quantum Espresso] to calculate phonons and electron-phonon matrix-elements on a regular q-grid,
with the final aim to allow Yambo to read these databases and calculate the temperature-dependent correction to the electronic states.
This tutorial is quite complicated, take your time to follow all the steps

== Electron-phonon matrix elements ==

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

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

In this tutorial we will show how to calculate electron-phonon induced corrections to the bands and optical properties of 2D hexagonal boron nitride.
All input file are availabe in the following tgz file: [http://www.yambo-code.org/educational/tutorials/files/hBN.epc.tgz hBN.epc.tgz]

1. In '''scf''' we run a standard scf calculation choosing the a large k-grid in such a way to converge density. Do not forget to set ''force_symmorphic=.true.'', because not symmorphic symmetries are not supported yet in Yambo. Notice that because the present system is two-dimensional we added the flag ''assume_isolated="2D"'' in such a way correct phonons in 2D, remove this flag is you have a system with a different dimensionality (a bulk, a molecule etc...)

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

.....
number of k points= 12
cart. coord. in units 2pi/alat
k( 1) = ( 0.0000000 0.0000000 0.0000000), wk = 0.0246914
k( 2) = ( 0.0000000 0.1283001 0.0000000), wk = 0.1481481
k( 3) = ( 0.0000000 0.2566001 0.0000000), wk = 0.1481481
k( 4) = ( 0.0000000 0.3849002 0.0000000), wk = 0.1481481
k( 5) = ( 0.0000000 0.5132002 0.0000000), wk = 0.1481481
k( 6) = ( 0.1111111 0.1924501 0.0000000), wk = 0.1481481
k( 7) = ( 0.1111111 0.3207501 0.0000000), wk = 0.2962963
k( 8) = ( 0.1111111 0.4490502 0.0000000), wk = 0.2962963
k( 9) = ( 0.1111111 0.5773503 0.0000000), wk = 0.1481481
k( 10) = ( 0.2222222 0.3849002 0.0000000), wk = 0.1481481
k( 11) = ( 0.2222222 0.5132002 0.0000000), wk = 0.2962963
k( 12) = ( 0.3333333 0.5773503 0.0000000), wk = 0.0493827
.....

3. Go in the '''phonon''' directory. You have to copy the k-points list in the ''2pi/alat'' units from the previous nscf run and provide it as q-grid for the phonon calculations. Notice that due to an internal convection of Yambo the q-points have to be multiplied for -1 before add them to the phonons input. In the last Yambo version you can also generate the k/q list with the minus sign using the ''ypp -k q'' and turning one the MinusQ flag. The final input will be:
&inputph
verbosity = 'high'
tr2_ph = 1e-12h
prefix = 'bn'
fildvscf = 'bn-dvscf'
fildyn = 'bn.dyn',
electron_phonon = 'dvscf',
epsil = .true.
trans = .true.
ldisp = .false.
qplot = .true.
/
12
0.0000000 0.0000000 0.0000000 1
0.0000000 -0.1283001 0.0000000 1
0.0000000 -0.2566001 0.0000000 1
0.0000000 -0.3849002 0.0000000 1
0.0000000 -0.5132002 0.0000000 1
-0.1111111 -0.1924501 0.0000000 1
-0.1111111 -0.3207501 0.0000000 1
-0.1111111 -0.4490502 0.0000000 1
-0.1111111 -0.5773503 0.0000000 1
-0.2222222 -0.3849002 0.0000000 1
-0.2222222 -0.5132002 0.0000000 1
-0.3333333 -0.5773503 0.0000000 1

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

&inputph
verbosity = 'high'
tr2_ph = 1e-12
prefix = 'bn'
fildvscf = 'bn-dvscf'
fildyn = 'bn.dyn'
electron_phonon = 'yambo',
epsil = .true.
trans = .false.
ldisp = .false.
qplot = .true.
/
12
0.0000000 0.0000000 0.0000000 1
0.0000000 -0.1283001 0.0000000 1
0.0000000 -0.2566001 0.0000000 1
0.0000000 -0.3849002 0.0000000 1
0.0000000 -0.5132002 0.0000000 1
-0.1111111 -0.1924501 0.0000000 1
-0.1111111 -0.3207501 0.0000000 1
-0.1111111 -0.4490502 0.0000000 1
-0.1111111 -0.5773503 0.0000000 1
-0.2222222 -0.3849002 0.0000000 1
-0.2222222 -0.5132002 0.0000000 1
-0.3333333 -0.5773503 0.0000000 1

this run will generate a new folder ''elph_dir'' with all electron-phonon matrix elements in a format compatible with Yambo.

5. Now you have to read the wave-functions. Go in the ''dvscf/bn.save'' folder, do ''p2y'', then ''yambo_ph -i -V kpt'' and turn on the flag BSEscatt, then run the setup. Now you use ypp_ph to import electron-phonon coupling, by doing ''ypp_ph -g' and the the PW el-ph folder:

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

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

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

== Quasi-particle band structure ==
The first quantity we will calculate is the correction to the band structure induced by the electron-phonon coupling. In order to generate the corresponding input do ''yambo_ph -g n -p fan -c p -V gen'' (in the newer versions of Yambo this line will be changed in ''yambo_ph -g n -p ep -c p -V gen''):

dyson # [R] Dyson Equation solver
gw0 # [R] GW approximation
el_ph_corr # [R] Electron-Phonon Correlation
Nelectro= 8.000000 # Electrons number
ElecTemp= 0.000000 eV # Electronic Temperature
BoseTemp= 0.000000 eV # Bosonic Temperature
OccTresh= 0.100000E-4 # Occupation treshold (metallic bands)
SE_Threads=0 # [OPENMP/GW] Number of threads for self-energy
DysSolver= "n" # [GW] Dyson Equation solver ("n","s","g")
GphBRnge= 8 # [ELPH] G[W] bands range
% ElPhModes
1 | 6 | # [ELPH] Phonon modes included
%
RandQpts=0 # [RIM] Number of random q-points in the BZ
#WRgFsq # [ELPH] Dump on file gFsq coefficients
%QPkrange # [GW] QP generalized Kpoint/Band indices
1|12|1|8|
%

If you run yambo_ph -J T0 you will get correction at zero kelvin to the band structure. You can change the temperature to 300 K by doing:

dyson # [R] Dyson Equation solver
gw0 # [R] GW approximation
el_ph_corr # [R] Electron-Phonon Correlation
Nelectro= 8.000000 # Electrons number
ElecTemp= 0.000000 eV # Electronic Temperature
BoseTemp= 300.0 K # Bosonic Temperature
OccTresh= 0.100000E-4 # Occupation treshold (metallic bands)
SE_Threads=0 # [OPENMP/GW] Number of threads for self-energy
DysSolver= "n" # [GW] Dyson Equation solver ("n","s","g")
GphBRnge= 8 # [ELPH] G[W] bands range
% ElPhModes
1 | 6 | # [ELPH] Phonon modes included
%
RandQpts=0 # [RIM] Number of random q-points in the BZ
#WRgFsq # [ELPH] Dump on file gFsq coefficients
%QPkrange # [GW] QP generalized Kpoint/Band indices
1|12|1|8|
%
run again ''yambo_ph -J T300'' and compare the two output file o-T0.qp and o-T300.qp, to find how much the gap change with the temperature.

== Optical properties ==

You can use the previous calculate quasi-particle band structure to get optical properties, by doing ''yambo_ph -o b -k sex -y d -V qp -X s'' and then reading the corresponding ndb.QP database KfnQPdb= "E < SAVE/ndb.QP"

Nota bene: Calculation of exciton width is not completely correct. If fact electron-phonon matrix elements should be rotate in the excitonic space, as it was done in Ref. [https://journals.aps.org/prl/abstract/10.1103/PhysRevLett.125.107401 Phys. Rev. Lett. '''125''' 107401 (2020)], while at present Yambo calculate the exciton width from the correction to the single particle bands, see ref. [https://journals.aps.org/prl/abstract/10.1103/PhysRevLett.101.106405 Phys. Rev. Lett. '''101''' 106405 (2008)]. This approximation is correct in case of not-strong bounded excitons, and unfortunately this is not the case.

== Convergence ==

The results of this tutorial are not converged, and if you check output there are also some phonon mode with negative energies. This is due to the poor parameters used in this tutorial. In order to have converged results, first of all be sure to have converged phonons, increase the plane-wave cutoff, the number of k-points and if necessary reduce ''tr2_ph''.
Then change the paramters for the Yambo calculations, increasing the number of '''k''' and '''q''' points and the number of bands. If you want to increase only the number of bands, just repeat the '''nscf''' and '''dvscf''' calculations without recalculate the '''phonons'''.

== Miscellaneous and post-processing ==
There are a list of utilities to analyze electron-phonon coupling results:
* ''ypp_ph -p d'' -> to plot the phonon density of states
* ''ypp_ph -p e'' -> to plot Eliashberg Functions
* ''ypp_ph -p a'' -> to analyze single atom amplitudes (to be fixed)

== Special note for FCC cells ==

In QuantumEspresso there is a different convention respect to Yambo and other codes in the definition of FCC units cell (ibrav=2, 3, and -3), this results in alat parameter two time smaller than the expected one in Yambo.
If you import WF from these calculation please ''p2y-a 2.0''. Otherwise a better solution is to define the FCC cell in a standard way, for example the silicon input becomes:

Electron Phonon Coupling

2020-12-18T09:00:17Z

Claudio:

Using Yambo in parallel

2020-12-15T10:58:08Z

Claudio: /* RPA response in parallel */

This module presents examples of how to run Yambo in a parallel environment.
== Prerequisites ==
'''Previous modules'''
* Initialization for [[Bulk_material:_h-BN|bulk hBN]].

'''You will need''':
* The <code>SAVE</code> databases for bulk hBN
* The <code>yambo</code> executable

==Yambo Parallelism in a nutshell==
Yambo implements a hybrid [https://en.wikipedia.org/wiki/Message_Passing_Interface MPI]+[https://en.wikipedia.org/wiki/OpenMP OpenMP] parallel scheme, suited to run
on large partitions of HPC machines. For instance, runs over several tens of thousands of cores on the Marconi KNL partition (CINECA, IT) have been achieved, with a computational power ~ 3 PFl/s, as well as large scale runs on accelerated machines such as Piz-Daint at CSCS (CH), featuring NVIDIA GPUs.
* '''MPI''' is particularly suited to distribute both memory and computation, and has a very efficient implementation in Yambo, which needs very few communications though may be prone to load unbalance (see [[GW_parallel_strategies| GW parallel strategies]]).
* '''OpenMP''' instead works within a shared memory paradigm, meaning that multiple threads perform computation in parallel on the same data in memory (no memory replica, at least in principle).
* Concerning '''Yambo''', tend to use MPI parallelism as much as possible (i.e. as much as memory allows), then resort to OpenMP parallelism in order not to increase memory usage any further while exploiting more cores and computing power.
* '''GPU''' support is extremely efficient in Yambo, meaning that when you are running on GPU accelerated machines it is always a good idea to exploit the GPUs. In general, one needs to set 1 MPI task for each available GPU card, also including OpenMP threads to fully exploit the capabilities of the host. While a very relevant speed up can be achieved, device memory (eg 12, 16, 32 GB on currently available devices) may become a problem and needs to be controlled (eg increasing the number of required nodes and further distributing data across them).
* The number of '''MPI tasks''' and '''OpenMP threads''' per task can be controlled in a standard way, e.g. as
$ export OMP_NUM_THREADS=4
$ mpirun -np 12 yambo -F yambo.in -J label
resulting in a run exploiting up to 48 threads (best fit on 48 physical cores, though hyper-threading, i.e. more threads than cores, can be exploited to feed computing units at best)
* TIP: In order to control the number of OpenMP threads via the OMP_NUM_THREADS environment variable, make sure that the thread-related variables in the yambo input file (e.g. X_Threads, DIP_Threads, SE_Threads) are set to zero or not set. When set, these variables will overwrite the value given to OMP_NUM_THREADS.
* A fine tuning of the parallel structure of Yambo (both MPI and OpenMP) can be obtained by operating on specific input variables (run level dependent), which can be activated, during input generation, via the flag <code> -V par</code> (verbosity high on parallel variables).
* Yambo can take advantage of parallel dense linear algebra (e.g. via [[https://en.wikipedia.org/wiki/ScaLAPACK ScaLAPACK]], SLK in the following). Control is provided by input variables
(see e.g. [[Using_Yambo_in_parallel#RPA response in parallel|RPA response in parallel]])
* When running in parallel, one report file is written, while multiple log files are dumped (one per MPI task, by default), and stored in a newly created <code>./LOG</code> folder. When running with thousands of MPI tasks, the number of log files can be reduced by setting, in the input file, something like:
NLogCPUs = 4 # [PARALLEL] Live-timing CPU`s (0 for all)

In the following we give direct examples of parallel setup for some among the most standard Yambo kernels.

==HF run in parallel==
Full theory and instructions about how to run HF (or, better, exchange self-energy) calculations are given in the [[Hartree Fock]] module.

Concerning parallelism, the quantities to be computed are:

[[File:Sx.png|none|x50px|caption]]
Basically, for every orbital ''nk'' we want to compute the exchange contribution to the qp correction. In order to to this, we need to perform a sum over q vectors and a sum over occupied bands (to build the density matrix).

* Generate the input file asking for parallel verbosity:
$ yambo -x -V par -F hf.in
* By default, OpenMP acts on spatial degrees of freedom (both direct and reciprocal space) and takes care of FFTs. Do not forget to set the <code>OMP_NUM_THREADS</code> variable (to 1 to avoid OpenMP parallelism)
$ export OMP_NUM_THREADS=1 or
$ export OMP_NUM_THREADS= <integer_larger_than_one>
* By default, the MPI parallelism will distribute both computation and memory over the bands in the inner sum (b). Without editing the input file, simply run:
$ mpirun -np 4 yambo -F hf.in -J <run_label>
* Alternatively, MPI parallelism can work over three different levels <code>q,qp,b</code> at the same time:
q parallelism over transferred momenta (q in Eq. above)
qp parallelism over qp corrections to be computed (nk in Eq.)
b parallelism over (occupied) density matrix (or Green's function) bands (m in Eq.)

Taking the case of hBN, in order to exploit this parallelism over 8 MPI tasks, set e.g.:
SE_CPU= " 1 2 4" # [PARALLEL] CPUs for each role
SE_ROLEs= "q qp b" # [PARALLEL] CPUs roles (q,qp,b)
Then run as
$ mpirun -np 8 yambo -F hf.in -J run_mpi8_omp1
Note that the product of the numbers in SE_CPU needs to be equal to the total number of MPI tasks, otherwise yambo will switch back to default parallelism (a warning is provided in the log).

Having a look at the report file, <code>r-run_mpi8_omp1_HF_and_locXC</code> here, one finds:
[01] CPU structure, Files & I/O Directories
===========================================

* CPU-Threads :8(CPU)-1(threads)-1(threads@SE)
* CPU-Threads :SE(environment)- 1 2 4(CPUs)-q qp b(ROLEs)
* MPI CPU : 8
* THREADS (max): 1
* THREADS TOT(max): 8

Now we can inspect the files created in the <code>./LOG</code> directory, e.g. <code>./LOG/l-run_mpi8_omp1_HF_and_locXC_CPU_1</code>, where we find:
<---> P0001: [01] CPU structure, Files & I/O Directories
<---> P0001: CPU-Threads:8(CPU)-1(threads)-1(threads@SE)
<---> P0001: CPU-Threads:SE(environment)- 1 2 4(CPUs)-q qp b(ROLEs)
...
<---> P0001: [PARALLEL Self_Energy for QPs on 2 CPU] Loaded/Total (Percentual):70/140(50%)
<---> P0001: [PARALLEL Self_Energy for Q(ibz) on 1 CPU] Loaded/Total (Percentual):14/14(100%)
<---> P0001: [PARALLEL Self_Energy for G bands on 4 CPU] Loaded/Total (Percentual):3/10(30%)
<---> P0001: [PARALLEL distribution for Wave-Function states] Loaded/Total(Percentual):84/140(60%)
providing the details of memory and computation distributions for the different levels. This report is from processor 1 (as highlighted about <code>_CPU_1</code> suffix). Similar pieces of information are provided for all CPUs. If different CPUs show very different distribution levels, it is likely that load unbalance occurs (e.g., try with 6 MPI tasks parallel over bands).

For Yambo version <= 4.1.2, Yambo may not be able to find a proper default parallel structure (try e.g. the above example asking for 20 MPI tasks, while you only have 8 bands to parallelise over). In These cases the calculation crashes and an error message is provided in the report file:
[ERROR]Impossible to define an appropriate parallel structure

In these cases it is then mandatory to specify a proper parallel structure. This has been mostly overcome by Yambo v. 4.2 on.

==RPA response in parallel==
Full theory and instructions about how to run independent particle (IP) or RPA linear response calculations are given e.g. in [[Optics at the independent particle level]] or [[Dynamic screening (PPA)]].

'''IP linear response'''

Concerning parallelism, let us focus at first on a q-resolved quantity like the IP optical response:
[[File:CH1.png|none|x60px|Yambo tutorial image]]

* Here, in order to obtain the dielectric function, either in the optical limit (q->0) or at finite q, one basically needs to sum over valence-conduction transitions (v,c) for each k point in the BZ. The calculation can be made easily parallel over these indexes.
* This is done at the '''MPI level''' (distributing both memory and computation), and also by '''OpenMP threads''', just distributing the computational load.
* In this very specific case, OpenMP also requires some extra memory workspace (i.e. by increasing the number of OMP threads, the memory usage will also increase).

* After initialisation (see [[Initialization]] for info) generate the input file by issuing:
$ yambo -o c -V par -F yambo_IP.in
edit some the variables by setting
Chimod= "IP" # [X] IP/Hartree/ALDA/LRC/BSfxc
% QpntsRXd
1 | 1 | # [Xd] Transferred momenta
%
These changes set as ''independent particle'' (IP) the response function to be calculated, and asks for the dielectric function at q=1 (that is always gamma)
* Set also the following openmp related variables to zero (or simply delete them):
X_Threads = 0
DIP_Threads = 0
This is needed to control the number of OpenMP threads vai the OMP_NUM_THREADS environment variable. To avoid OpenMP parallelism, set
export OMP_NUM_THREADS=1
* Now you are ready to run. By suing the default parallelism (over 8 MPI tasks) we have to issue:
$ mpirun -np 8 yambo -F yambo_IP.in -J IP_mpi8
* by inspecting the log files (one per MPI task in the <code>./LOG</code> folder), we see that the parallelism over conduction states has been used.
<---> P0001: CPU structure provided for the Response_G_space_Zero_Momentum ENVIRONMENT is incomplete. Switching to defaults
<---> P0001: [LA] SERIAL linear algebra
<---> P0001: [PARALLEL Response_G_space_Zero_Momentum for K(ibz) on 1 CPU] Loaded/Total (Percentual):14/14(100%)
<---> P0001: [PARALLEL Response_G_space_Zero_Momentum for CON bands on 8 CPU] Loaded/Total (Percentual):12/92(13%)
<---> P0001: [PARALLEL Response_G_space_Zero_Momentum for VAL bands on 1 CPU] Loaded/Total (Percentual):8/8(100%)
* Alternatively, edit the input file and set the parallelism fine-tuning variables:
X_q_0_CPU= " 1 4 2" # [PARALLEL] CPUs for each role
X_q_0_ROLEs= "k c v" # [PARALLEL] CPUs roles (k,c,v)
Run as before
$ mpirun -np 8 yambo -F yambo_IP.in -J IP_mpi8_tuned
* Fine tuning is useful when running over a large number of MPI tasks. Care must be taken when setting the parameters: In this case, for instance, we need to make sure that conduction and valence states are multiples of 4 and 2 respectively. Such situations can be handled by yambo, but especially for valence states which are usually less than conduction states, can lead to load unbalance and not perfect filling of the cores.

'''RPA linear response'''

Here, after the calculation of the independent particle linear response, a matrix inversion is performed to obtain the RPA response.
* After initialization (see [[Initialization]] for info) generate the input file by issuing:
$ yambo -o c -V par -F yambo_RPA.in
edit some of the variables by setting
Chimod= "Hartree" # [X] IP/Hartree/ALDA/LRC/BSfxc
NGsBlkXd= 6 Ry # [Xd] Response block size
% QpntsRXd
1 | 1 | # [Xd] Transferred momenta
%
*Run and inspect the log files: After the calculation of 'Xo', the code computes 'X', performing some dense linear algebra operations, which can
be made parallel, using scaLapack, by setting, eg
X_q_0_nCPU_LinAlG_INV = 8 # [PARALLEL] CPUs for Linear Algebra
Note that the largest square number smaller than 8, in this case, will be used to form the scaLapack grid (2x2, here).
* Parallelism fine tuning works as for the IP response.

In case multiple or all q points need to be computed (as in GW calculations), the parallelism variables to be used, are:
X_all_q_ROLEs= "g q k c v" # [PARALLEL] CPUs roles (g,q,k,c,v)
X_all_q_CPU= "1 2 1 4 1" # [PARALLEL] CPUs for each role
X_all_q_nCPU_LinAlg_INV= 8 # [PARALLEL] CPUs for Linear Algebra
adding one extra MPI level of parallelism related to the distribution over q points.

Finally the different possible parallelism strategies for the dielectric constant are:

g parallelism over G-vectors
q parallelism over transferred momenta (q in Eq. above)
c/v parallelism over conduction/valence bands
k parallelism over k-points

Notice that parellelization on c,v and k reduces the amount of memory in the calculation.

==GW in parallel==
In a complete GW run, several runlevels (dipoles, RPA linear response for all q, exchange self-energy, and correlation self-energy) are run in a row to eventually compute the GW quasi-particle (QP) corrections.
How to run [[Using_Yambo_in_parallel#RPA response in parallel|linear response]] and the [[Using_Yambo_in_parallel#HF run in parallel|exchange self-energy]] in parallel has already been discussed above.
Here we focus on the parallelisation of the correlation self-energy.

The correlation part of the self-energy in a plane wave representation reads:
[[File:Sigma_c.png|none|x50px|caption]]

According to this equation, for each nk matrix element to be computed (qp corrections), a sum over q vectors in the Brillouin zone and a sum over (b) bands (m in Eq.) have to be performed, together with sums over G,G' reciprocal space variables. This gives rise to 3 levels of MPI parallelism (qp, q, b), which can be combined with OpenMP to take care of spatial degrees of freedom.
As for the exchange self-energy, the MPI parallelism levels that can be controlled are given by:

q parallelism over transferred momenta (q in Eq. above)
qp parallelism over qp corrections to be computed (nk in Eq.)
b parallelism over (occupied) density matrix (or Green's function) bands (m in Eq.)

Additionally, the variable <code>SE_Threads</code> can be set to fine-tune the OpenMP parallelism (leave it set to zero to control it via the <code>OMP_NUM_THREADS</code> environment variable)

To generate the input file, type
yambo -g n -p p -F gw.in

To run in parallel with default parallelism do:
export OMP_NUM_THREADS=1 #(or an integer larger than 1 to use OpenMP parallelism)
mpirun -np 8 yambo -F gw.in -J run_mpi8_omp1

Taking the case of hBN, in order to exploit this parallelism over 8 MPI tasks, set e.g.:
SE_CPU= " 1 2 4" # [PARALLEL] CPUs for each role
SE_ROLEs= "q qp b" # [PARALLEL] CPUs roles (q,qp,b)
Then run as
$ mpirun -np 8 yambo -F gw.in -J run_mpi8_omp1_tuned
Note that the product of the numbers in SE_CPU needs to be equal to the total number of MPI tasks, otherwise yambo will switch back to default parallelism (a warning is provided in the log).

Having a look at the report file, <code>r-run_mpi8_omp1_HF_and_locXC</code> here, one finds:
[01] CPU structure, Files & I/O Directories
===========================================

* CPU-Threads :8(CPU)-1(threads)-1(threads@SE)
* CPU-Threads :SE(environment)- 1 2 4(CPUs)-q qp b(ROLEs)
* MPI CPU : 8
* THREADS (max): 1
* THREADS TOT(max): 8

Now we can inspect the files created in the <code>./LOG</code> directory, e.g. <code>./LOG/l-run_mpi8_omp1_HF_and_locXC_CPU_1</code>, where we find:
<---> P0001: [01] CPU structure, Files & I/O Directories
<---> P0001: CPU-Threads:8(CPU)-1(threads)-1(threads@SE)
<---> P0001: CPU-Threads:SE(environment)- 1 2 4(CPUs)-q qp b(ROLEs)
...
<---> P0001: [PARALLEL Self_Energy for QPs on 2 CPU] Loaded/Total (Percentual):70/140(50%)
<---> P0001: [PARALLEL Self_Energy for Q(ibz) on 1 CPU] Loaded/Total (Percentual):14/14(100%)
<---> P0001: [PARALLEL Self_Energy for G bands on 4 CPU] Loaded/Total (Percentual):3/10(30%)
<---> P0001: [PARALLEL distribution for Wave-Function states] Loaded/Total(Percentual):84/140(60%)
providing the details of memory and computation distributions for the different levels. This report is from processor 1 (as highlighted about <code>_CPU_1</code> suffix). Similar pieces of information are provided for all CPUs. If different CPUs show very different distribution levels, it is likely that load unbalance occurs (e.g., try with 6 MPI tasks parallel over bands).

For Yambo version <= 4.1.2, Yambo may not be able to find a proper default parallel structure (try e.g. the above example asking for 20 MPI tasks, while you only have 8 bands to parallelise over). In These cases the calculation crashes and an error message is provided in the report file:
[ERROR]Impossible to define an appropriate parallel structure

In these cases it is then mandatory to specify a proper parallel structure. This has been mostly overcome by Yambo v. 4.2 on.

==BSE in parallel==

== Links ==
* [[Tutorials|Back to tutorials menu]]

[[Category:Modules]]

Using Yambo in parallel

2020-12-15T10:56:48Z

Claudio: /* RPA response in parallel */

This module presents examples of how to run Yambo in a parallel environment.
== Prerequisites ==
'''Previous modules'''
* Initialization for [[Bulk_material:_h-BN|bulk hBN]].

'''You will need''':
* The <code>SAVE</code> databases for bulk hBN
* The <code>yambo</code> executable

==Yambo Parallelism in a nutshell==
Yambo implements a hybrid [https://en.wikipedia.org/wiki/Message_Passing_Interface MPI]+[https://en.wikipedia.org/wiki/OpenMP OpenMP] parallel scheme, suited to run
on large partitions of HPC machines. For instance, runs over several tens of thousands of cores on the Marconi KNL partition (CINECA, IT) have been achieved, with a computational power ~ 3 PFl/s, as well as large scale runs on accelerated machines such as Piz-Daint at CSCS (CH), featuring NVIDIA GPUs.
* '''MPI''' is particularly suited to distribute both memory and computation, and has a very efficient implementation in Yambo, which needs very few communications though may be prone to load unbalance (see [[GW_parallel_strategies| GW parallel strategies]]).
* '''OpenMP''' instead works within a shared memory paradigm, meaning that multiple threads perform computation in parallel on the same data in memory (no memory replica, at least in principle).
* Concerning '''Yambo''', tend to use MPI parallelism as much as possible (i.e. as much as memory allows), then resort to OpenMP parallelism in order not to increase memory usage any further while exploiting more cores and computing power.
* '''GPU''' support is extremely efficient in Yambo, meaning that when you are running on GPU accelerated machines it is always a good idea to exploit the GPUs. In general, one needs to set 1 MPI task for each available GPU card, also including OpenMP threads to fully exploit the capabilities of the host. While a very relevant speed up can be achieved, device memory (eg 12, 16, 32 GB on currently available devices) may become a problem and needs to be controlled (eg increasing the number of required nodes and further distributing data across them).
* The number of '''MPI tasks''' and '''OpenMP threads''' per task can be controlled in a standard way, e.g. as
$ export OMP_NUM_THREADS=4
$ mpirun -np 12 yambo -F yambo.in -J label
resulting in a run exploiting up to 48 threads (best fit on 48 physical cores, though hyper-threading, i.e. more threads than cores, can be exploited to feed computing units at best)
* TIP: In order to control the number of OpenMP threads via the OMP_NUM_THREADS environment variable, make sure that the thread-related variables in the yambo input file (e.g. X_Threads, DIP_Threads, SE_Threads) are set to zero or not set. When set, these variables will overwrite the value given to OMP_NUM_THREADS.
* A fine tuning of the parallel structure of Yambo (both MPI and OpenMP) can be obtained by operating on specific input variables (run level dependent), which can be activated, during input generation, via the flag <code> -V par</code> (verbosity high on parallel variables).
* Yambo can take advantage of parallel dense linear algebra (e.g. via [[https://en.wikipedia.org/wiki/ScaLAPACK ScaLAPACK]], SLK in the following). Control is provided by input variables
(see e.g. [[Using_Yambo_in_parallel#RPA response in parallel|RPA response in parallel]])
* When running in parallel, one report file is written, while multiple log files are dumped (one per MPI task, by default), and stored in a newly created <code>./LOG</code> folder. When running with thousands of MPI tasks, the number of log files can be reduced by setting, in the input file, something like:
NLogCPUs = 4 # [PARALLEL] Live-timing CPU`s (0 for all)

In the following we give direct examples of parallel setup for some among the most standard Yambo kernels.

==HF run in parallel==
Full theory and instructions about how to run HF (or, better, exchange self-energy) calculations are given in the [[Hartree Fock]] module.

Concerning parallelism, the quantities to be computed are:

[[File:Sx.png|none|x50px|caption]]
Basically, for every orbital ''nk'' we want to compute the exchange contribution to the qp correction. In order to to this, we need to perform a sum over q vectors and a sum over occupied bands (to build the density matrix).

* Generate the input file asking for parallel verbosity:
$ yambo -x -V par -F hf.in
* By default, OpenMP acts on spatial degrees of freedom (both direct and reciprocal space) and takes care of FFTs. Do not forget to set the <code>OMP_NUM_THREADS</code> variable (to 1 to avoid OpenMP parallelism)
$ export OMP_NUM_THREADS=1 or
$ export OMP_NUM_THREADS= <integer_larger_than_one>
* By default, the MPI parallelism will distribute both computation and memory over the bands in the inner sum (b). Without editing the input file, simply run:
$ mpirun -np 4 yambo -F hf.in -J <run_label>
* Alternatively, MPI parallelism can work over three different levels <code>q,qp,b</code> at the same time:
q parallelism over transferred momenta (q in Eq. above)
qp parallelism over qp corrections to be computed (nk in Eq.)
b parallelism over (occupied) density matrix (or Green's function) bands (m in Eq.)

Taking the case of hBN, in order to exploit this parallelism over 8 MPI tasks, set e.g.:
SE_CPU= " 1 2 4" # [PARALLEL] CPUs for each role
SE_ROLEs= "q qp b" # [PARALLEL] CPUs roles (q,qp,b)
Then run as
$ mpirun -np 8 yambo -F hf.in -J run_mpi8_omp1
Note that the product of the numbers in SE_CPU needs to be equal to the total number of MPI tasks, otherwise yambo will switch back to default parallelism (a warning is provided in the log).

Having a look at the report file, <code>r-run_mpi8_omp1_HF_and_locXC</code> here, one finds:
[01] CPU structure, Files & I/O Directories
===========================================

* CPU-Threads :8(CPU)-1(threads)-1(threads@SE)
* CPU-Threads :SE(environment)- 1 2 4(CPUs)-q qp b(ROLEs)
* MPI CPU : 8
* THREADS (max): 1
* THREADS TOT(max): 8

Now we can inspect the files created in the <code>./LOG</code> directory, e.g. <code>./LOG/l-run_mpi8_omp1_HF_and_locXC_CPU_1</code>, where we find:
<---> P0001: [01] CPU structure, Files & I/O Directories
<---> P0001: CPU-Threads:8(CPU)-1(threads)-1(threads@SE)
<---> P0001: CPU-Threads:SE(environment)- 1 2 4(CPUs)-q qp b(ROLEs)
...
<---> P0001: [PARALLEL Self_Energy for QPs on 2 CPU] Loaded/Total (Percentual):70/140(50%)
<---> P0001: [PARALLEL Self_Energy for Q(ibz) on 1 CPU] Loaded/Total (Percentual):14/14(100%)
<---> P0001: [PARALLEL Self_Energy for G bands on 4 CPU] Loaded/Total (Percentual):3/10(30%)
<---> P0001: [PARALLEL distribution for Wave-Function states] Loaded/Total(Percentual):84/140(60%)
providing the details of memory and computation distributions for the different levels. This report is from processor 1 (as highlighted about <code>_CPU_1</code> suffix). Similar pieces of information are provided for all CPUs. If different CPUs show very different distribution levels, it is likely that load unbalance occurs (e.g., try with 6 MPI tasks parallel over bands).

For Yambo version <= 4.1.2, Yambo may not be able to find a proper default parallel structure (try e.g. the above example asking for 20 MPI tasks, while you only have 8 bands to parallelise over). In These cases the calculation crashes and an error message is provided in the report file:
[ERROR]Impossible to define an appropriate parallel structure

In these cases it is then mandatory to specify a proper parallel structure. This has been mostly overcome by Yambo v. 4.2 on.

==RPA response in parallel==
Full theory and instructions about how to run independent particle (IP) or RPA linear response calculations are given e.g. in [[Optics at the independent particle level]] or [[Dynamic screening (PPA)]].

'''IP linear response'''

Concerning parallelism, let us focus at first on a q-resolved quantity like the IP optical response:
[[File:CH1.png|none|x60px|Yambo tutorial image]]

* Here, in order to obtain the dielectric function, either in the optical limit (q->0) or at finite q, one basically needs to sum over valence-conduction transitions (v,c) for each k point in the BZ. The calculation can be made easily parallel over these indexes.
* This is done at the '''MPI level''' (distributing both memory and computation), and also by '''OpenMP threads''', just distributing the computational load.
* In this very specific case, OpenMP also requires some extra memory workspace (i.e. by increasing the number of OMP threads, the memory usage will also increase).

* After initialisation (see [[Initialization]] for info) generate the input file by issuing:
$ yambo -o c -V par -F yambo_IP.in
edit some the variables by setting
Chimod= "IP" # [X] IP/Hartree/ALDA/LRC/BSfxc
% QpntsRXd
1 | 1 | # [Xd] Transferred momenta
%
These changes set as ''independent particle'' (IP) the response function to be calculated, and asks for the dielectric function at q=1 (that is always gamma)
* Set also the following openmp related variables to zero (or simply delete them):
X_Threads = 0
DIP_Threads = 0
This is needed to control the number of OpenMP threads vai the OMP_NUM_THREADS environment variable. To avoid OpenMP parallelism, set
export OMP_NUM_THREADS=1
* Now you are ready to run. By suing the default parallelism (over 8 MPI tasks) we have to issue:
$ mpirun -np 8 yambo -F yambo_IP.in -J IP_mpi8
* by inspecting the log files (one per MPI task in the <code>./LOG</code> folder), we see that the parallelism over conduction states has been used.
<---> P0001: CPU structure provided for the Response_G_space_Zero_Momentum ENVIRONMENT is incomplete. Switching to defaults
<---> P0001: [LA] SERIAL linear algebra
<---> P0001: [PARALLEL Response_G_space_Zero_Momentum for K(ibz) on 1 CPU] Loaded/Total (Percentual):14/14(100%)
<---> P0001: [PARALLEL Response_G_space_Zero_Momentum for CON bands on 8 CPU] Loaded/Total (Percentual):12/92(13%)
<---> P0001: [PARALLEL Response_G_space_Zero_Momentum for VAL bands on 1 CPU] Loaded/Total (Percentual):8/8(100%)
* Alternatively, edit the input file and set the parallelism fine-tuning variables:
X_q_0_CPU= " 1 4 2" # [PARALLEL] CPUs for each role
X_q_0_ROLEs= "k c v" # [PARALLEL] CPUs roles (k,c,v)
Run as before
$ mpirun -np 8 yambo -F yambo_IP.in -J IP_mpi8_tuned
* Fine tuning is useful when running over a large number of MPI tasks. Care must be taken when setting the parameters: In this case, for instance, we need to make sure that conduction and valence states are multiples of 4 and 2 respectively. Such situations can be handled by yambo, but especially for valence states which are usually less than conduction states, can lead to load unbalance and not perfect filling of the cores.

'''RPA linear response'''

Here, after the calculation of the independent particle linear response, a matrix inversion is performed to obtain the RPA response.
* After initialisation (see [[Initialization]] for info) generate the input file by issuing:
$ yambo -o c -V par -F yambo_RPA.in
edit some of the variables by setting
Chimod= "Hartree" # [X] IP/Hartree/ALDA/LRC/BSfxc
NGsBlkXd= 6 Ry # [Xd] Response block size
% QpntsRXd
1 | 1 | # [Xd] Transferred momenta
%
*Run and inspect the log files: After the calculation of 'Xo', the code computes 'X', performing some dense linear algebra operations, which can
be made parallel, using scaLapack, by setting, eg
X_q_0_nCPU_LinAlG_INV = 8 # [PARALLEL] CPUs for Linear Algebra
Note that the largest square number smaller than 8, in this case, will be used to form the scaLapack grid (2x2, here).
* Parallelism fine tuning works as for the IP response.

In case multiple or all q points need to be computed (as in GW calculations), the parallelism variables to be used, are:
X_all_q_ROLEs= "g q k c v" # [PARALLEL] CPUs roles (g,q,k,c,v)
X_all_q_CPU= "1 2 1 4 1" # [PARALLEL] CPUs for each role
X_all_q_nCPU_LinAlg_INV= 8 # [PARALLEL] CPUs for Linear Algebra
adding one extra MPI level of parallelism related to the distribution over q points.

Finally the different possible parallelism strategies for the dielectric constant are:

g parallelism over G-vectors
q parallelism over transferred momenta (q in Eq. above)
c/v parallelism over conduction/valence bands
k parallelism over k-points

Notice that parellization on c,v and k reduce the amount of memory in the calculation.

==GW in parallel==
In a complete GW run, several runlevels (dipoles, RPA linear response for all q, exchange self-energy, and correlation self-energy) are run in a row to eventually compute the GW quasi-particle (QP) corrections.
How to run [[Using_Yambo_in_parallel#RPA response in parallel|linear response]] and the [[Using_Yambo_in_parallel#HF run in parallel|exchange self-energy]] in parallel has already been discussed above.
Here we focus on the parallelisation of the correlation self-energy.

The correlation part of the self-energy in a plane wave representation reads:
[[File:Sigma_c.png|none|x50px|caption]]

According to this equation, for each nk matrix element to be computed (qp corrections), a sum over q vectors in the Brillouin zone and a sum over (b) bands (m in Eq.) have to be performed, together with sums over G,G' reciprocal space variables. This gives rise to 3 levels of MPI parallelism (qp, q, b), which can be combined with OpenMP to take care of spatial degrees of freedom.
As for the exchange self-energy, the MPI parallelism levels that can be controlled are given by:

q parallelism over transferred momenta (q in Eq. above)
qp parallelism over qp corrections to be computed (nk in Eq.)
b parallelism over (occupied) density matrix (or Green's function) bands (m in Eq.)

Additionally, the variable <code>SE_Threads</code> can be set to fine-tune the OpenMP parallelism (leave it set to zero to control it via the <code>OMP_NUM_THREADS</code> environment variable)

To generate the input file, type
yambo -g n -p p -F gw.in

To run in parallel with default parallelism do:
export OMP_NUM_THREADS=1 #(or an integer larger than 1 to use OpenMP parallelism)
mpirun -np 8 yambo -F gw.in -J run_mpi8_omp1

Taking the case of hBN, in order to exploit this parallelism over 8 MPI tasks, set e.g.:
SE_CPU= " 1 2 4" # [PARALLEL] CPUs for each role
SE_ROLEs= "q qp b" # [PARALLEL] CPUs roles (q,qp,b)
Then run as
$ mpirun -np 8 yambo -F gw.in -J run_mpi8_omp1_tuned
Note that the product of the numbers in SE_CPU needs to be equal to the total number of MPI tasks, otherwise yambo will switch back to default parallelism (a warning is provided in the log).

Having a look at the report file, <code>r-run_mpi8_omp1_HF_and_locXC</code> here, one finds:
[01] CPU structure, Files & I/O Directories
===========================================

* CPU-Threads :8(CPU)-1(threads)-1(threads@SE)
* CPU-Threads :SE(environment)- 1 2 4(CPUs)-q qp b(ROLEs)
* MPI CPU : 8
* THREADS (max): 1
* THREADS TOT(max): 8

Now we can inspect the files created in the <code>./LOG</code> directory, e.g. <code>./LOG/l-run_mpi8_omp1_HF_and_locXC_CPU_1</code>, where we find:
<---> P0001: [01] CPU structure, Files & I/O Directories
<---> P0001: CPU-Threads:8(CPU)-1(threads)-1(threads@SE)
<---> P0001: CPU-Threads:SE(environment)- 1 2 4(CPUs)-q qp b(ROLEs)
...
<---> P0001: [PARALLEL Self_Energy for QPs on 2 CPU] Loaded/Total (Percentual):70/140(50%)
<---> P0001: [PARALLEL Self_Energy for Q(ibz) on 1 CPU] Loaded/Total (Percentual):14/14(100%)
<---> P0001: [PARALLEL Self_Energy for G bands on 4 CPU] Loaded/Total (Percentual):3/10(30%)
<---> P0001: [PARALLEL distribution for Wave-Function states] Loaded/Total(Percentual):84/140(60%)
providing the details of memory and computation distributions for the different levels. This report is from processor 1 (as highlighted about <code>_CPU_1</code> suffix). Similar pieces of information are provided for all CPUs. If different CPUs show very different distribution levels, it is likely that load unbalance occurs (e.g., try with 6 MPI tasks parallel over bands).

For Yambo version <= 4.1.2, Yambo may not be able to find a proper default parallel structure (try e.g. the above example asking for 20 MPI tasks, while you only have 8 bands to parallelise over). In These cases the calculation crashes and an error message is provided in the report file:
[ERROR]Impossible to define an appropriate parallel structure

In these cases it is then mandatory to specify a proper parallel structure. This has been mostly overcome by Yambo v. 4.2 on.

==BSE in parallel==

== Links ==
* [[Tutorials|Back to tutorials menu]]

[[Category:Modules]]

Using Yambo in parallel

2020-12-15T10:56:03Z

Claudio: /* RPA response in parallel */

This module presents examples of how to run Yambo in a parallel environment.
== Prerequisites ==
'''Previous modules'''
* Initialization for [[Bulk_material:_h-BN|bulk hBN]].

'''You will need''':
* The <code>SAVE</code> databases for bulk hBN
* The <code>yambo</code> executable

==Yambo Parallelism in a nutshell==
Yambo implements a hybrid [https://en.wikipedia.org/wiki/Message_Passing_Interface MPI]+[https://en.wikipedia.org/wiki/OpenMP OpenMP] parallel scheme, suited to run
on large partitions of HPC machines. For instance, runs over several tens of thousands of cores on the Marconi KNL partition (CINECA, IT) have been achieved, with a computational power ~ 3 PFl/s, as well as large scale runs on accelerated machines such as Piz-Daint at CSCS (CH), featuring NVIDIA GPUs.
* '''MPI''' is particularly suited to distribute both memory and computation, and has a very efficient implementation in Yambo, which needs very few communications though may be prone to load unbalance (see [[GW_parallel_strategies| GW parallel strategies]]).
* '''OpenMP''' instead works within a shared memory paradigm, meaning that multiple threads perform computation in parallel on the same data in memory (no memory replica, at least in principle).
* Concerning '''Yambo''', tend to use MPI parallelism as much as possible (i.e. as much as memory allows), then resort to OpenMP parallelism in order not to increase memory usage any further while exploiting more cores and computing power.
* '''GPU''' support is extremely efficient in Yambo, meaning that when you are running on GPU accelerated machines it is always a good idea to exploit the GPUs. In general, one needs to set 1 MPI task for each available GPU card, also including OpenMP threads to fully exploit the capabilities of the host. While a very relevant speed up can be achieved, device memory (eg 12, 16, 32 GB on currently available devices) may become a problem and needs to be controlled (eg increasing the number of required nodes and further distributing data across them).
* The number of '''MPI tasks''' and '''OpenMP threads''' per task can be controlled in a standard way, e.g. as
$ export OMP_NUM_THREADS=4
$ mpirun -np 12 yambo -F yambo.in -J label
resulting in a run exploiting up to 48 threads (best fit on 48 physical cores, though hyper-threading, i.e. more threads than cores, can be exploited to feed computing units at best)
* TIP: In order to control the number of OpenMP threads via the OMP_NUM_THREADS environment variable, make sure that the thread-related variables in the yambo input file (e.g. X_Threads, DIP_Threads, SE_Threads) are set to zero or not set. When set, these variables will overwrite the value given to OMP_NUM_THREADS.
* A fine tuning of the parallel structure of Yambo (both MPI and OpenMP) can be obtained by operating on specific input variables (run level dependent), which can be activated, during input generation, via the flag <code> -V par</code> (verbosity high on parallel variables).
* Yambo can take advantage of parallel dense linear algebra (e.g. via [[https://en.wikipedia.org/wiki/ScaLAPACK ScaLAPACK]], SLK in the following). Control is provided by input variables
(see e.g. [[Using_Yambo_in_parallel#RPA response in parallel|RPA response in parallel]])
* When running in parallel, one report file is written, while multiple log files are dumped (one per MPI task, by default), and stored in a newly created <code>./LOG</code> folder. When running with thousands of MPI tasks, the number of log files can be reduced by setting, in the input file, something like:
NLogCPUs = 4 # [PARALLEL] Live-timing CPU`s (0 for all)

In the following we give direct examples of parallel setup for some among the most standard Yambo kernels.

==HF run in parallel==
Full theory and instructions about how to run HF (or, better, exchange self-energy) calculations are given in the [[Hartree Fock]] module.

Concerning parallelism, the quantities to be computed are:

[[File:Sx.png|none|x50px|caption]]
Basically, for every orbital ''nk'' we want to compute the exchange contribution to the qp correction. In order to to this, we need to perform a sum over q vectors and a sum over occupied bands (to build the density matrix).

* Generate the input file asking for parallel verbosity:
$ yambo -x -V par -F hf.in
* By default, OpenMP acts on spatial degrees of freedom (both direct and reciprocal space) and takes care of FFTs. Do not forget to set the <code>OMP_NUM_THREADS</code> variable (to 1 to avoid OpenMP parallelism)
$ export OMP_NUM_THREADS=1 or
$ export OMP_NUM_THREADS= <integer_larger_than_one>
* By default, the MPI parallelism will distribute both computation and memory over the bands in the inner sum (b). Without editing the input file, simply run:
$ mpirun -np 4 yambo -F hf.in -J <run_label>
* Alternatively, MPI parallelism can work over three different levels <code>q,qp,b</code> at the same time:
q parallelism over transferred momenta (q in Eq. above)
qp parallelism over qp corrections to be computed (nk in Eq.)
b parallelism over (occupied) density matrix (or Green's function) bands (m in Eq.)

Taking the case of hBN, in order to exploit this parallelism over 8 MPI tasks, set e.g.:
SE_CPU= " 1 2 4" # [PARALLEL] CPUs for each role
SE_ROLEs= "q qp b" # [PARALLEL] CPUs roles (q,qp,b)
Then run as
$ mpirun -np 8 yambo -F hf.in -J run_mpi8_omp1
Note that the product of the numbers in SE_CPU needs to be equal to the total number of MPI tasks, otherwise yambo will switch back to default parallelism (a warning is provided in the log).

Having a look at the report file, <code>r-run_mpi8_omp1_HF_and_locXC</code> here, one finds:
[01] CPU structure, Files & I/O Directories
===========================================

* CPU-Threads :8(CPU)-1(threads)-1(threads@SE)
* CPU-Threads :SE(environment)- 1 2 4(CPUs)-q qp b(ROLEs)
* MPI CPU : 8
* THREADS (max): 1
* THREADS TOT(max): 8

Now we can inspect the files created in the <code>./LOG</code> directory, e.g. <code>./LOG/l-run_mpi8_omp1_HF_and_locXC_CPU_1</code>, where we find:
<---> P0001: [01] CPU structure, Files & I/O Directories
<---> P0001: CPU-Threads:8(CPU)-1(threads)-1(threads@SE)
<---> P0001: CPU-Threads:SE(environment)- 1 2 4(CPUs)-q qp b(ROLEs)
...
<---> P0001: [PARALLEL Self_Energy for QPs on 2 CPU] Loaded/Total (Percentual):70/140(50%)
<---> P0001: [PARALLEL Self_Energy for Q(ibz) on 1 CPU] Loaded/Total (Percentual):14/14(100%)
<---> P0001: [PARALLEL Self_Energy for G bands on 4 CPU] Loaded/Total (Percentual):3/10(30%)
<---> P0001: [PARALLEL distribution for Wave-Function states] Loaded/Total(Percentual):84/140(60%)
providing the details of memory and computation distributions for the different levels. This report is from processor 1 (as highlighted about <code>_CPU_1</code> suffix). Similar pieces of information are provided for all CPUs. If different CPUs show very different distribution levels, it is likely that load unbalance occurs (e.g., try with 6 MPI tasks parallel over bands).

For Yambo version <= 4.1.2, Yambo may not be able to find a proper default parallel structure (try e.g. the above example asking for 20 MPI tasks, while you only have 8 bands to parallelise over). In These cases the calculation crashes and an error message is provided in the report file:
[ERROR]Impossible to define an appropriate parallel structure

In these cases it is then mandatory to specify a proper parallel structure. This has been mostly overcome by Yambo v. 4.2 on.

==RPA response in parallel==
Full theory and instructions about how to run independent particle (IP) or RPA linear response calculations are given e.g. in [[Optics at the independent particle level]] or [[Dynamic screening (PPA)]].

'''IP linear response'''

Concerning parallelism, let us focus at first on a q-resolved quantity like the IP optical response:
[[File:CH1.png|none|x60px|Yambo tutorial image]]

* Here, in order to obtain the dielectric function, either in the optical limit (q->0) or at finite q, one basically needs to sum over valence-conduction transitions (v,c) for each k point in the BZ. The calculation can be made easily parallel over these indexes.
* This is done at the '''MPI level''' (distributing both memory and computation), and also by '''OpenMP threads''', just distributing the computational load.
* In this very specific case, OpenMP also requires some extra memory workspace (i.e. by increasing the number of OMP threads, the memory usage will also increase).

* After initialisation (see [[Initialization]] for info) generate the input file by issuing:
$ yambo -o c -V par -F yambo_IP.in
edit some the variables by setting
Chimod= "IP" # [X] IP/Hartree/ALDA/LRC/BSfxc
% QpntsRXd
1 | 1 | # [Xd] Transferred momenta
%
These changes set as ''independent particle'' (IP) the response function to be calculated, and asks for the dielectric function at q=1 (that is always gamma)
* Set also the following openmp related variables to zero (or simply delete them):
X_Threads = 0
DIP_Threads = 0
This is needed to control the number of OpenMP threads vai the OMP_NUM_THREADS environment variable. To avoid OpenMP parallelism, set
export OMP_NUM_THREADS=1
* Now you are ready to run. By suing the default parallelism (over 8 MPI tasks) we have to issue:
$ mpirun -np 8 yambo -F yambo_IP.in -J IP_mpi8
* by inspecting the log files (one per MPI task in the <code>./LOG</code> folder), we see that the parallelism over conduction states has been used.
<---> P0001: CPU structure provided for the Response_G_space_Zero_Momentum ENVIRONMENT is incomplete. Switching to defaults
<---> P0001: [LA] SERIAL linear algebra
<---> P0001: [PARALLEL Response_G_space_Zero_Momentum for K(ibz) on 1 CPU] Loaded/Total (Percentual):14/14(100%)
<---> P0001: [PARALLEL Response_G_space_Zero_Momentum for CON bands on 8 CPU] Loaded/Total (Percentual):12/92(13%)
<---> P0001: [PARALLEL Response_G_space_Zero_Momentum for VAL bands on 1 CPU] Loaded/Total (Percentual):8/8(100%)
* Alternatively, edit the input file and set the parallelism fine-tuning variables:
X_q_0_CPU= " 1 4 2" # [PARALLEL] CPUs for each role
X_q_0_ROLEs= "k c v" # [PARALLEL] CPUs roles (k,c,v)
Run as before
$ mpirun -np 8 yambo -F yambo_IP.in -J IP_mpi8_tuned
* Fine tuning is useful when running over a large number of MPI tasks. Care must be taken when setting the parameters: In this case, for instance, we need to make sure that conduction and valence states are multiples of 4 and 2 respectively. Such situations can be handled by yambo, but especially for valence states which are usually less than conduction states, can lead to load unbalance and not perfect filling of the cores.

'''RPA linear response'''

Here, after the calculation of the independent particle linear response, a matrix inversion is performed to obtain the RPA response.
* After initialisation (see [[Initialization]] for info) generate the input file by issuing:
$ yambo -o c -V par -F yambo_RPA.in
edit some of the variables by setting
Chimod= "Hartree" # [X] IP/Hartree/ALDA/LRC/BSfxc
NGsBlkXd= 6 Ry # [Xd] Response block size
% QpntsRXd
1 | 1 | # [Xd] Transferred momenta
%
*Run and inspect the log files: After the calculation of 'Xo', the code computes 'X', performing some dense linear algebra operations, which can
be made parallel, using scaLapack, by setting, eg
X_q_0_nCPU_LinAlG_INV = 8 # [PARALLEL] CPUs for Linear Algebra
Note that the largest square number smaller than 8, in this case, will be used to form the scaLapack grid (2x2, here).
* Parallelism fine tuning works as for the IP response.

In case multiple or all q points need to be computed (as in GW calculations), the parallelism variables to be used, are:
X_all_q_ROLEs= "g q k c v" # [PARALLEL] CPUs roles (g,q,k,c,v)
X_all_q_CPU= "1 2 1 4 1" # [PARALLEL] CPUs for each role
X_all_q_nCPU_LinAlg_INV= 8 # [PARALLEL] CPUs for Linear Algebra
adding one extra MPI level of parallelism related to the distribution over q points.
Finally the different possible parallelism strategies for the dielectric constant are:

g parallelism over G-vectors
q parallelism over transferred momenta (q in Eq. above)
c/v parallelism over conduction/valence bands
k parallelism over k-points

Notice that parellization on c,v and k reduce the amount of memory in the calculation.

==GW in parallel==
In a complete GW run, several runlevels (dipoles, RPA linear response for all q, exchange self-energy, and correlation self-energy) are run in a row to eventually compute the GW quasi-particle (QP) corrections.
How to run [[Using_Yambo_in_parallel#RPA response in parallel|linear response]] and the [[Using_Yambo_in_parallel#HF run in parallel|exchange self-energy]] in parallel has already been discussed above.
Here we focus on the parallelisation of the correlation self-energy.

The correlation part of the self-energy in a plane wave representation reads:
[[File:Sigma_c.png|none|x50px|caption]]

According to this equation, for each nk matrix element to be computed (qp corrections), a sum over q vectors in the Brillouin zone and a sum over (b) bands (m in Eq.) have to be performed, together with sums over G,G' reciprocal space variables. This gives rise to 3 levels of MPI parallelism (qp, q, b), which can be combined with OpenMP to take care of spatial degrees of freedom.
As for the exchange self-energy, the MPI parallelism levels that can be controlled are given by:

q parallelism over transferred momenta (q in Eq. above)
qp parallelism over qp corrections to be computed (nk in Eq.)
b parallelism over (occupied) density matrix (or Green's function) bands (m in Eq.)

Additionally, the variable <code>SE_Threads</code> can be set to fine-tune the OpenMP parallelism (leave it set to zero to control it via the <code>OMP_NUM_THREADS</code> environment variable)

To generate the input file, type
yambo -g n -p p -F gw.in

To run in parallel with default parallelism do:
export OMP_NUM_THREADS=1 #(or an integer larger than 1 to use OpenMP parallelism)
mpirun -np 8 yambo -F gw.in -J run_mpi8_omp1

Taking the case of hBN, in order to exploit this parallelism over 8 MPI tasks, set e.g.:
SE_CPU= " 1 2 4" # [PARALLEL] CPUs for each role
SE_ROLEs= "q qp b" # [PARALLEL] CPUs roles (q,qp,b)
Then run as
$ mpirun -np 8 yambo -F gw.in -J run_mpi8_omp1_tuned
Note that the product of the numbers in SE_CPU needs to be equal to the total number of MPI tasks, otherwise yambo will switch back to default parallelism (a warning is provided in the log).

Having a look at the report file, <code>r-run_mpi8_omp1_HF_and_locXC</code> here, one finds:
[01] CPU structure, Files & I/O Directories
===========================================

* CPU-Threads :8(CPU)-1(threads)-1(threads@SE)
* CPU-Threads :SE(environment)- 1 2 4(CPUs)-q qp b(ROLEs)
* MPI CPU : 8
* THREADS (max): 1
* THREADS TOT(max): 8

Now we can inspect the files created in the <code>./LOG</code> directory, e.g. <code>./LOG/l-run_mpi8_omp1_HF_and_locXC_CPU_1</code>, where we find:
<---> P0001: [01] CPU structure, Files & I/O Directories
<---> P0001: CPU-Threads:8(CPU)-1(threads)-1(threads@SE)
<---> P0001: CPU-Threads:SE(environment)- 1 2 4(CPUs)-q qp b(ROLEs)
...
<---> P0001: [PARALLEL Self_Energy for QPs on 2 CPU] Loaded/Total (Percentual):70/140(50%)
<---> P0001: [PARALLEL Self_Energy for Q(ibz) on 1 CPU] Loaded/Total (Percentual):14/14(100%)
<---> P0001: [PARALLEL Self_Energy for G bands on 4 CPU] Loaded/Total (Percentual):3/10(30%)
<---> P0001: [PARALLEL distribution for Wave-Function states] Loaded/Total(Percentual):84/140(60%)
providing the details of memory and computation distributions for the different levels. This report is from processor 1 (as highlighted about <code>_CPU_1</code> suffix). Similar pieces of information are provided for all CPUs. If different CPUs show very different distribution levels, it is likely that load unbalance occurs (e.g., try with 6 MPI tasks parallel over bands).

For Yambo version <= 4.1.2, Yambo may not be able to find a proper default parallel structure (try e.g. the above example asking for 20 MPI tasks, while you only have 8 bands to parallelise over). In These cases the calculation crashes and an error message is provided in the report file:
[ERROR]Impossible to define an appropriate parallel structure

In these cases it is then mandatory to specify a proper parallel structure. This has been mostly overcome by Yambo v. 4.2 on.

==BSE in parallel==

== Links ==
* [[Tutorials|Back to tutorials menu]]

[[Category:Modules]]

Using Yambo in parallel

2020-12-15T10:53:03Z

Claudio: /* RPA response in parallel */

This module presents examples of how to run Yambo in a parallel environment.
== Prerequisites ==
'''Previous modules'''
* Initialization for [[Bulk_material:_h-BN|bulk hBN]].

'''You will need''':
* The <code>SAVE</code> databases for bulk hBN
* The <code>yambo</code> executable

==Yambo Parallelism in a nutshell==
Yambo implements a hybrid [https://en.wikipedia.org/wiki/Message_Passing_Interface MPI]+[https://en.wikipedia.org/wiki/OpenMP OpenMP] parallel scheme, suited to run
on large partitions of HPC machines. For instance, runs over several tens of thousands of cores on the Marconi KNL partition (CINECA, IT) have been achieved, with a computational power ~ 3 PFl/s, as well as large scale runs on accelerated machines such as Piz-Daint at CSCS (CH), featuring NVIDIA GPUs.
* '''MPI''' is particularly suited to distribute both memory and computation, and has a very efficient implementation in Yambo, which needs very few communications though may be prone to load unbalance (see [[GW_parallel_strategies| GW parallel strategies]]).
* '''OpenMP''' instead works within a shared memory paradigm, meaning that multiple threads perform computation in parallel on the same data in memory (no memory replica, at least in principle).
* Concerning '''Yambo''', tend to use MPI parallelism as much as possible (i.e. as much as memory allows), then resort to OpenMP parallelism in order not to increase memory usage any further while exploiting more cores and computing power.
* '''GPU''' support is extremely efficient in Yambo, meaning that when you are running on GPU accelerated machines it is always a good idea to exploit the GPUs. In general, one needs to set 1 MPI task for each available GPU card, also including OpenMP threads to fully exploit the capabilities of the host. While a very relevant speed up can be achieved, device memory (eg 12, 16, 32 GB on currently available devices) may become a problem and needs to be controlled (eg increasing the number of required nodes and further distributing data across them).
* The number of '''MPI tasks''' and '''OpenMP threads''' per task can be controlled in a standard way, e.g. as
$ export OMP_NUM_THREADS=4
$ mpirun -np 12 yambo -F yambo.in -J label
resulting in a run exploiting up to 48 threads (best fit on 48 physical cores, though hyper-threading, i.e. more threads than cores, can be exploited to feed computing units at best)
* TIP: In order to control the number of OpenMP threads via the OMP_NUM_THREADS environment variable, make sure that the thread-related variables in the yambo input file (e.g. X_Threads, DIP_Threads, SE_Threads) are set to zero or not set. When set, these variables will overwrite the value given to OMP_NUM_THREADS.
* A fine tuning of the parallel structure of Yambo (both MPI and OpenMP) can be obtained by operating on specific input variables (run level dependent), which can be activated, during input generation, via the flag <code> -V par</code> (verbosity high on parallel variables).
* Yambo can take advantage of parallel dense linear algebra (e.g. via [[https://en.wikipedia.org/wiki/ScaLAPACK ScaLAPACK]], SLK in the following). Control is provided by input variables
(see e.g. [[Using_Yambo_in_parallel#RPA response in parallel|RPA response in parallel]])
* When running in parallel, one report file is written, while multiple log files are dumped (one per MPI task, by default), and stored in a newly created <code>./LOG</code> folder. When running with thousands of MPI tasks, the number of log files can be reduced by setting, in the input file, something like:
NLogCPUs = 4 # [PARALLEL] Live-timing CPU`s (0 for all)

In the following we give direct examples of parallel setup for some among the most standard Yambo kernels.

==HF run in parallel==
Full theory and instructions about how to run HF (or, better, exchange self-energy) calculations are given in the [[Hartree Fock]] module.

Concerning parallelism, the quantities to be computed are:

[[File:Sx.png|none|x50px|caption]]
Basically, for every orbital ''nk'' we want to compute the exchange contribution to the qp correction. In order to to this, we need to perform a sum over q vectors and a sum over occupied bands (to build the density matrix).

* Generate the input file asking for parallel verbosity:
$ yambo -x -V par -F hf.in
* By default, OpenMP acts on spatial degrees of freedom (both direct and reciprocal space) and takes care of FFTs. Do not forget to set the <code>OMP_NUM_THREADS</code> variable (to 1 to avoid OpenMP parallelism)
$ export OMP_NUM_THREADS=1 or
$ export OMP_NUM_THREADS= <integer_larger_than_one>
* By default, the MPI parallelism will distribute both computation and memory over the bands in the inner sum (b). Without editing the input file, simply run:
$ mpirun -np 4 yambo -F hf.in -J <run_label>
* Alternatively, MPI parallelism can work over three different levels <code>q,qp,b</code> at the same time:
q parallelism over transferred momenta (q in Eq. above)
qp parallelism over qp corrections to be computed (nk in Eq.)
b parallelism over (occupied) density matrix (or Green's function) bands (m in Eq.)

Taking the case of hBN, in order to exploit this parallelism over 8 MPI tasks, set e.g.:
SE_CPU= " 1 2 4" # [PARALLEL] CPUs for each role
SE_ROLEs= "q qp b" # [PARALLEL] CPUs roles (q,qp,b)
Then run as
$ mpirun -np 8 yambo -F hf.in -J run_mpi8_omp1
Note that the product of the numbers in SE_CPU needs to be equal to the total number of MPI tasks, otherwise yambo will switch back to default parallelism (a warning is provided in the log).

Having a look at the report file, <code>r-run_mpi8_omp1_HF_and_locXC</code> here, one finds:
[01] CPU structure, Files & I/O Directories
===========================================

* CPU-Threads :8(CPU)-1(threads)-1(threads@SE)
* CPU-Threads :SE(environment)- 1 2 4(CPUs)-q qp b(ROLEs)
* MPI CPU : 8
* THREADS (max): 1
* THREADS TOT(max): 8

Now we can inspect the files created in the <code>./LOG</code> directory, e.g. <code>./LOG/l-run_mpi8_omp1_HF_and_locXC_CPU_1</code>, where we find:
<---> P0001: [01] CPU structure, Files & I/O Directories
<---> P0001: CPU-Threads:8(CPU)-1(threads)-1(threads@SE)
<---> P0001: CPU-Threads:SE(environment)- 1 2 4(CPUs)-q qp b(ROLEs)
...
<---> P0001: [PARALLEL Self_Energy for QPs on 2 CPU] Loaded/Total (Percentual):70/140(50%)
<---> P0001: [PARALLEL Self_Energy for Q(ibz) on 1 CPU] Loaded/Total (Percentual):14/14(100%)
<---> P0001: [PARALLEL Self_Energy for G bands on 4 CPU] Loaded/Total (Percentual):3/10(30%)
<---> P0001: [PARALLEL distribution for Wave-Function states] Loaded/Total(Percentual):84/140(60%)
providing the details of memory and computation distributions for the different levels. This report is from processor 1 (as highlighted about <code>_CPU_1</code> suffix). Similar pieces of information are provided for all CPUs. If different CPUs show very different distribution levels, it is likely that load unbalance occurs (e.g., try with 6 MPI tasks parallel over bands).

For Yambo version <= 4.1.2, Yambo may not be able to find a proper default parallel structure (try e.g. the above example asking for 20 MPI tasks, while you only have 8 bands to parallelise over). In These cases the calculation crashes and an error message is provided in the report file:
[ERROR]Impossible to define an appropriate parallel structure

In these cases it is then mandatory to specify a proper parallel structure. This has been mostly overcome by Yambo v. 4.2 on.

==RPA response in parallel==
Full theory and instructions about how to run independent particle (IP) or RPA linear response calculations are given e.g. in [[Optics at the independent particle level]] or [[Dynamic screening (PPA)]].

'''IP linear response'''

Concerning parallelism, let us focus at first on a q-resolved quantity like the IP optical response:
[[File:CH1.png|none|x60px|Yambo tutorial image]]

* Here, in order to obtain the dielectric function, either in the optical limit (q->0) or at finite q, one basically needs to sum over valence-conduction transitions (v,c) for each k point in the BZ. The calculation can be made easily parallel over these indexes.
* This is done at the '''MPI level''' (distributing both memory and computation), and also by '''OpenMP threads''', just distributing the computational load.
* In this very specific case, OpenMP also requires some extra memory workspace (i.e. by increasing the number of OMP threads, the memory usage will also increase).

* After initialisation (see [[Initialization]] for info) generate the input file by issuing:
$ yambo -o c -V par -F yambo_IP.in
edit some the variables by setting
Chimod= "IP" # [X] IP/Hartree/ALDA/LRC/BSfxc
% QpntsRXd
1 | 1 | # [Xd] Transferred momenta
%
These changes set as ''independent particle'' (IP) the response function to be calculated, and asks for the dielectric function at q=1 (that is always gamma)
* Set also the following openmp related variables to zero (or simply delete them):
X_Threads = 0
DIP_Threads = 0
This is needed to control the number of OpenMP threads vai the OMP_NUM_THREADS environment variable. To avoid OpenMP parallelism, set
export OMP_NUM_THREADS=1
* Now you are ready to run. By suing the default parallelism (over 8 MPI tasks) we have to issue:
$ mpirun -np 8 yambo -F yambo_IP.in -J IP_mpi8
* by inspecting the log files (one per MPI task in the <code>./LOG</code> folder), we see that the parallelism over conduction states has been used.
<---> P0001: CPU structure provided for the Response_G_space_Zero_Momentum ENVIRONMENT is incomplete. Switching to defaults
<---> P0001: [LA] SERIAL linear algebra
<---> P0001: [PARALLEL Response_G_space_Zero_Momentum for K(ibz) on 1 CPU] Loaded/Total (Percentual):14/14(100%)
<---> P0001: [PARALLEL Response_G_space_Zero_Momentum for CON bands on 8 CPU] Loaded/Total (Percentual):12/92(13%)
<---> P0001: [PARALLEL Response_G_space_Zero_Momentum for VAL bands on 1 CPU] Loaded/Total (Percentual):8/8(100%)
* Alternatively, edit the input file and set the parallelism fine-tuning variables:
X_q_0_CPU= " 1 4 2" # [PARALLEL] CPUs for each role
X_q_0_ROLEs= "k c v" # [PARALLEL] CPUs roles (k,c,v)
Run as before
$ mpirun -np 8 yambo -F yambo_IP.in -J IP_mpi8_tuned
* Fine tuning is useful when running over a large number of MPI tasks. Care must be taken when setting the parameters: In this case, for instance, we need to make sure that conduction and valence states are multiples of 4 and 2 respectively. Such situations can be handled by yambo, but especially for valence states which are usually less than conduction states, can lead to load unbalance and not perfect filling of the cores.

'''RPA linear response'''

Here, after the calculation of the independent particle linear response, a matrix inversion is performed to obtain the RPA response.
* After initialisation (see [[Initialization]] for info) generate the input file by issuing:
$ yambo -o c -V par -F yambo_RPA.in
edit some of the variables by setting
Chimod= "Hartree" # [X] IP/Hartree/ALDA/LRC/BSfxc
NGsBlkXd= 6 Ry # [Xd] Response block size
% QpntsRXd
1 | 1 | # [Xd] Transferred momenta
%
*Run and inspect the log files: After the calculation of 'Xo', the code computes 'X', performing some dense linear algebra operations, which can
be made parallel, using scaLapack, by setting, eg
X_q_0_nCPU_LinAlG_INV = 8 # [PARALLEL] CPUs for Linear Algebra
Note that the largest square number smaller than 8, in this case, will be used to form the scaLapack grid (2x2, here).
* Parallelism fine tuning works as for the IP response.

In case multiple or all q points need to be computed (as in GW calculations), the parallelism variables to be used, are:
X_all_q_ROLEs= "g q k c v" # [PARALLEL] CPUs roles (g,q,k,c,v)
X_all_q_CPU= "1 2 1 4 1" # [PARALLEL] CPUs for each role
X_all_q_nCPU_LinAlg_INV= 8 # [PARALLEL] CPUs for Linear Algebra
adding one extra MPI level of parallelism related to the distribution over q points.

==GW in parallel==
In a complete GW run, several runlevels (dipoles, RPA linear response for all q, exchange self-energy, and correlation self-energy) are run in a row to eventually compute the GW quasi-particle (QP) corrections.
How to run [[Using_Yambo_in_parallel#RPA response in parallel|linear response]] and the [[Using_Yambo_in_parallel#HF run in parallel|exchange self-energy]] in parallel has already been discussed above.
Here we focus on the parallelisation of the correlation self-energy.

The correlation part of the self-energy in a plane wave representation reads:
[[File:Sigma_c.png|none|x50px|caption]]

According to this equation, for each nk matrix element to be computed (qp corrections), a sum over q vectors in the Brillouin zone and a sum over (b) bands (m in Eq.) have to be performed, together with sums over G,G' reciprocal space variables. This gives rise to 3 levels of MPI parallelism (qp, q, b), which can be combined with OpenMP to take care of spatial degrees of freedom.
As for the exchange self-energy, the MPI parallelism levels that can be controlled are given by:

q parallelism over transferred momenta (q in Eq. above)
qp parallelism over qp corrections to be computed (nk in Eq.)
b parallelism over (occupied) density matrix (or Green's function) bands (m in Eq.)

Additionally, the variable <code>SE_Threads</code> can be set to fine-tune the OpenMP parallelism (leave it set to zero to control it via the <code>OMP_NUM_THREADS</code> environment variable)

To generate the input file, type
yambo -g n -p p -F gw.in

To run in parallel with default parallelism do:
export OMP_NUM_THREADS=1 #(or an integer larger than 1 to use OpenMP parallelism)
mpirun -np 8 yambo -F gw.in -J run_mpi8_omp1

Taking the case of hBN, in order to exploit this parallelism over 8 MPI tasks, set e.g.:
SE_CPU= " 1 2 4" # [PARALLEL] CPUs for each role
SE_ROLEs= "q qp b" # [PARALLEL] CPUs roles (q,qp,b)
Then run as
$ mpirun -np 8 yambo -F gw.in -J run_mpi8_omp1_tuned
Note that the product of the numbers in SE_CPU needs to be equal to the total number of MPI tasks, otherwise yambo will switch back to default parallelism (a warning is provided in the log).

Having a look at the report file, <code>r-run_mpi8_omp1_HF_and_locXC</code> here, one finds:
[01] CPU structure, Files & I/O Directories
===========================================

* CPU-Threads :8(CPU)-1(threads)-1(threads@SE)
* CPU-Threads :SE(environment)- 1 2 4(CPUs)-q qp b(ROLEs)
* MPI CPU : 8
* THREADS (max): 1
* THREADS TOT(max): 8

Now we can inspect the files created in the <code>./LOG</code> directory, e.g. <code>./LOG/l-run_mpi8_omp1_HF_and_locXC_CPU_1</code>, where we find:
<---> P0001: [01] CPU structure, Files & I/O Directories
<---> P0001: CPU-Threads:8(CPU)-1(threads)-1(threads@SE)
<---> P0001: CPU-Threads:SE(environment)- 1 2 4(CPUs)-q qp b(ROLEs)
...
<---> P0001: [PARALLEL Self_Energy for QPs on 2 CPU] Loaded/Total (Percentual):70/140(50%)
<---> P0001: [PARALLEL Self_Energy for Q(ibz) on 1 CPU] Loaded/Total (Percentual):14/14(100%)
<---> P0001: [PARALLEL Self_Energy for G bands on 4 CPU] Loaded/Total (Percentual):3/10(30%)
<---> P0001: [PARALLEL distribution for Wave-Function states] Loaded/Total(Percentual):84/140(60%)
providing the details of memory and computation distributions for the different levels. This report is from processor 1 (as highlighted about <code>_CPU_1</code> suffix). Similar pieces of information are provided for all CPUs. If different CPUs show very different distribution levels, it is likely that load unbalance occurs (e.g., try with 6 MPI tasks parallel over bands).

For Yambo version <= 4.1.2, Yambo may not be able to find a proper default parallel structure (try e.g. the above example asking for 20 MPI tasks, while you only have 8 bands to parallelise over). In These cases the calculation crashes and an error message is provided in the report file:
[ERROR]Impossible to define an appropriate parallel structure

In these cases it is then mandatory to specify a proper parallel structure. This has been mostly overcome by Yambo v. 4.2 on.

==BSE in parallel==

== Links ==
* [[Tutorials|Back to tutorials menu]]

[[Category:Modules]]

Using Yambo in parallel

2020-12-15T10:52:37Z

Claudio: /* RPA response in parallel */

This module presents examples of how to run Yambo in a parallel environment.
== Prerequisites ==
'''Previous modules'''
* Initialization for [[Bulk_material:_h-BN|bulk hBN]].

'''You will need''':
* The <code>SAVE</code> databases for bulk hBN
* The <code>yambo</code> executable

==Yambo Parallelism in a nutshell==
Yambo implements a hybrid [https://en.wikipedia.org/wiki/Message_Passing_Interface MPI]+[https://en.wikipedia.org/wiki/OpenMP OpenMP] parallel scheme, suited to run
on large partitions of HPC machines. For instance, runs over several tens of thousands of cores on the Marconi KNL partition (CINECA, IT) have been achieved, with a computational power ~ 3 PFl/s, as well as large scale runs on accelerated machines such as Piz-Daint at CSCS (CH), featuring NVIDIA GPUs.
* '''MPI''' is particularly suited to distribute both memory and computation, and has a very efficient implementation in Yambo, which needs very few communications though may be prone to load unbalance (see [[GW_parallel_strategies| GW parallel strategies]]).
* '''OpenMP''' instead works within a shared memory paradigm, meaning that multiple threads perform computation in parallel on the same data in memory (no memory replica, at least in principle).
* Concerning '''Yambo''', tend to use MPI parallelism as much as possible (i.e. as much as memory allows), then resort to OpenMP parallelism in order not to increase memory usage any further while exploiting more cores and computing power.
* '''GPU''' support is extremely efficient in Yambo, meaning that when you are running on GPU accelerated machines it is always a good idea to exploit the GPUs. In general, one needs to set 1 MPI task for each available GPU card, also including OpenMP threads to fully exploit the capabilities of the host. While a very relevant speed up can be achieved, device memory (eg 12, 16, 32 GB on currently available devices) may become a problem and needs to be controlled (eg increasing the number of required nodes and further distributing data across them).
* The number of '''MPI tasks''' and '''OpenMP threads''' per task can be controlled in a standard way, e.g. as
$ export OMP_NUM_THREADS=4
$ mpirun -np 12 yambo -F yambo.in -J label
resulting in a run exploiting up to 48 threads (best fit on 48 physical cores, though hyper-threading, i.e. more threads than cores, can be exploited to feed computing units at best)
* TIP: In order to control the number of OpenMP threads via the OMP_NUM_THREADS environment variable, make sure that the thread-related variables in the yambo input file (e.g. X_Threads, DIP_Threads, SE_Threads) are set to zero or not set. When set, these variables will overwrite the value given to OMP_NUM_THREADS.
* A fine tuning of the parallel structure of Yambo (both MPI and OpenMP) can be obtained by operating on specific input variables (run level dependent), which can be activated, during input generation, via the flag <code> -V par</code> (verbosity high on parallel variables).
* Yambo can take advantage of parallel dense linear algebra (e.g. via [[https://en.wikipedia.org/wiki/ScaLAPACK ScaLAPACK]], SLK in the following). Control is provided by input variables
(see e.g. [[Using_Yambo_in_parallel#RPA response in parallel|RPA response in parallel]])
* When running in parallel, one report file is written, while multiple log files are dumped (one per MPI task, by default), and stored in a newly created <code>./LOG</code> folder. When running with thousands of MPI tasks, the number of log files can be reduced by setting, in the input file, something like:
NLogCPUs = 4 # [PARALLEL] Live-timing CPU`s (0 for all)

In the following we give direct examples of parallel setup for some among the most standard Yambo kernels.

==HF run in parallel==
Full theory and instructions about how to run HF (or, better, exchange self-energy) calculations are given in the [[Hartree Fock]] module.

Concerning parallelism, the quantities to be computed are:

[[File:Sx.png|none|x50px|caption]]
Basically, for every orbital ''nk'' we want to compute the exchange contribution to the qp correction. In order to to this, we need to perform a sum over q vectors and a sum over occupied bands (to build the density matrix).

* Generate the input file asking for parallel verbosity:
$ yambo -x -V par -F hf.in
* By default, OpenMP acts on spatial degrees of freedom (both direct and reciprocal space) and takes care of FFTs. Do not forget to set the <code>OMP_NUM_THREADS</code> variable (to 1 to avoid OpenMP parallelism)
$ export OMP_NUM_THREADS=1 or
$ export OMP_NUM_THREADS= <integer_larger_than_one>
* By default, the MPI parallelism will distribute both computation and memory over the bands in the inner sum (b). Without editing the input file, simply run:
$ mpirun -np 4 yambo -F hf.in -J <run_label>
* Alternatively, MPI parallelism can work over three different levels <code>q,qp,b</code> at the same time:
q parallelism over transferred momenta (q in Eq. above)
qp parallelism over qp corrections to be computed (nk in Eq.)
b parallelism over (occupied) density matrix (or Green's function) bands (m in Eq.)

Taking the case of hBN, in order to exploit this parallelism over 8 MPI tasks, set e.g.:
SE_CPU= " 1 2 4" # [PARALLEL] CPUs for each role
SE_ROLEs= "q qp b" # [PARALLEL] CPUs roles (q,qp,b)
Then run as
$ mpirun -np 8 yambo -F hf.in -J run_mpi8_omp1
Note that the product of the numbers in SE_CPU needs to be equal to the total number of MPI tasks, otherwise yambo will switch back to default parallelism (a warning is provided in the log).

Having a look at the report file, <code>r-run_mpi8_omp1_HF_and_locXC</code> here, one finds:
[01] CPU structure, Files & I/O Directories
===========================================

* CPU-Threads :8(CPU)-1(threads)-1(threads@SE)
* CPU-Threads :SE(environment)- 1 2 4(CPUs)-q qp b(ROLEs)
* MPI CPU : 8
* THREADS (max): 1
* THREADS TOT(max): 8

Now we can inspect the files created in the <code>./LOG</code> directory, e.g. <code>./LOG/l-run_mpi8_omp1_HF_and_locXC_CPU_1</code>, where we find:
<---> P0001: [01] CPU structure, Files & I/O Directories
<---> P0001: CPU-Threads:8(CPU)-1(threads)-1(threads@SE)
<---> P0001: CPU-Threads:SE(environment)- 1 2 4(CPUs)-q qp b(ROLEs)
...
<---> P0001: [PARALLEL Self_Energy for QPs on 2 CPU] Loaded/Total (Percentual):70/140(50%)
<---> P0001: [PARALLEL Self_Energy for Q(ibz) on 1 CPU] Loaded/Total (Percentual):14/14(100%)
<---> P0001: [PARALLEL Self_Energy for G bands on 4 CPU] Loaded/Total (Percentual):3/10(30%)
<---> P0001: [PARALLEL distribution for Wave-Function states] Loaded/Total(Percentual):84/140(60%)
providing the details of memory and computation distributions for the different levels. This report is from processor 1 (as highlighted about <code>_CPU_1</code> suffix). Similar pieces of information are provided for all CPUs. If different CPUs show very different distribution levels, it is likely that load unbalance occurs (e.g., try with 6 MPI tasks parallel over bands).

For Yambo version <= 4.1.2, Yambo may not be able to find a proper default parallel structure (try e.g. the above example asking for 20 MPI tasks, while you only have 8 bands to parallelise over). In These cases the calculation crashes and an error message is provided in the report file:
[ERROR]Impossible to define an appropriate parallel structure

In these cases it is then mandatory to specify a proper parallel structure. This has been mostly overcome by Yambo v. 4.2 on.

==RPA response in parallel==
Full theory and instructions about how to run independent particle (IP) or RPA linear response calculations are given e.g. in [[Optics at the independent particle level]] or [[Dynamic screening (PPA)]].

'''IP linear response'''

Concerning parallelism, let us focus at first on a q-resolved quantity like the IP optical response:
[[File:CH1.png|none|x60px|Yambo tutorial image]]

* Here, in order to obtain the dielectric function, either in the optical limit (q->0) or at finite q, one basically needs to sum over valence-conduction transitions (v,c) for each k point in the BZ. The calculation can be made easily parallel over these indexes.
* This is done at the '''MPI level''' (distributing both memory and computation), and also by '''OpenMP threads''', just distributing the computational load.
* In this very specific case, OpenMP also requires some extra memory workspace (i.e. by increasing the number of OMP threads, the memory usage will also increase).

* After initialisation (see [[Initialization]] for info) generate the input file by issuing:
$ yambo -o c -V par -F yambo_IP.in
edit some the variables by setting
Chimod= "IP" # [X] IP/Hartree/ALDA/LRC/BSfxc
% QpntsRXd
1 | 1 | # [Xd] Transferred momenta
%
These changes set as ''independent particle'' (IP) the response function to be calculated, and asks for the dielectric function at q=1 (that is always gamma)
* Set also the following openmp related variables to zero (or simply delete them):
X_Threads = 0
DIP_Threads = 0
This is needed to control the number of OpenMP threads vai the OMP_NUM_THREADS environment variable. To avoid OpenMP parallelism, set
export OMP_NUM_THREADS=1
* Now you are ready to run. By suing the default parallelism (over 8 MPI tasks) we have to issue:
$ mpirun -np 8 yambo -F yambo_IP.in -J IP_mpi8
* by inspecting the log files (one per MPI task in the <code>./LOG</code> folder), we see that the parallelism over conduction states has been used.
<---> P0001: CPU structure provided for the Response_G_space_Zero_Momentum ENVIRONMENT is incomplete. Switching to defaults
<---> P0001: [LA] SERIAL linear algebra
<---> P0001: [PARALLEL Response_G_space_Zero_Momentum for K(ibz) on 1 CPU] Loaded/Total (Percentual):14/14(100%)
<---> P0001: [PARALLEL Response_G_space_Zero_Momentum for CON bands on 8 CPU] Loaded/Total (Percentual):12/92(13%)
<---> P0001: [PARALLEL Response_G_space_Zero_Momentum for VAL bands on 1 CPU] Loaded/Total (Percentual):8/8(100%)
* Alternatively, edit the input file and set the parallelism fine-tuning variables:
X_q_0_CPU= " 1 4 2" # [PARALLEL] CPUs for each role
X_q_0_ROLEs= "k c v" # [PARALLEL] CPUs roles (k,c,v)
Run as before
$ mpirun -np 8 yambo -F yambo_IP.in -J IP_mpi8_tuned
* Fine tuning is useful when running over a large number of MPI tasks. Care must be taken when setting the parameters: In this case, for instance, we need to make sure that conduction and valence states are multiples of 4 and 2 respectively. Such situations can be handled by yambo, but especially for valence states which are usually less than conduction states, can lead to load unbalance and not perfect filling of the cores.

'''RPA linear response'''

Here, after the calculation of the independent particle linear response, a matrix inversion is performed to obtain the RPA response.
* After initialisation (see [[Initialization]] for info) generate the input file by issuing:
$ yambo -o c -V par -F yambo_RPA.in
edit some of the variables by setting
Chimod= "Hartree" # [X] IP/Hartree/ALDA/LRC/BSfxc
NGsBlkXd= 6 Ry # [Xd] Response block size
% QpntsRXd
1 | 1 | # [Xd] Transferred momenta
%
*Run and inspect the log files: After the calculation of 'Xo', the code computes 'X', performing some dense linear algebra operations, which can
be made parallel, using scaLapack, by setting, eg
X_q_0_nCPU_LinAlG_INV = 8 # [PARALLEL] CPUs for Linear Algebra
Note that the largest square number smaller than 8, in this case, will be used to form the scaLapack grid (2x2, here).
* Parallelism fine tuning works as for the IP response.

In case multiple or all q points need to be computed (as in GW calculations), the parallelism variables to be used, are:
X_all_q_ROLEs= "g q k c v" # [PARALLEL] CPUs roles (q,k,c,v)
X_all_q_CPU= "1 2 1 4 1" # [PARALLEL] CPUs for each role
X_all_q_nCPU_LinAlg_INV= 8 # [PARALLEL] CPUs for Linear Algebra
adding one extra MPI level of parallelism related to the distribution over q points.

==GW in parallel==
In a complete GW run, several runlevels (dipoles, RPA linear response for all q, exchange self-energy, and correlation self-energy) are run in a row to eventually compute the GW quasi-particle (QP) corrections.
How to run [[Using_Yambo_in_parallel#RPA response in parallel|linear response]] and the [[Using_Yambo_in_parallel#HF run in parallel|exchange self-energy]] in parallel has already been discussed above.
Here we focus on the parallelisation of the correlation self-energy.

The correlation part of the self-energy in a plane wave representation reads:
[[File:Sigma_c.png|none|x50px|caption]]

According to this equation, for each nk matrix element to be computed (qp corrections), a sum over q vectors in the Brillouin zone and a sum over (b) bands (m in Eq.) have to be performed, together with sums over G,G' reciprocal space variables. This gives rise to 3 levels of MPI parallelism (qp, q, b), which can be combined with OpenMP to take care of spatial degrees of freedom.
As for the exchange self-energy, the MPI parallelism levels that can be controlled are given by:

q parallelism over transferred momenta (q in Eq. above)
qp parallelism over qp corrections to be computed (nk in Eq.)
b parallelism over (occupied) density matrix (or Green's function) bands (m in Eq.)

Additionally, the variable <code>SE_Threads</code> can be set to fine-tune the OpenMP parallelism (leave it set to zero to control it via the <code>OMP_NUM_THREADS</code> environment variable)

To generate the input file, type
yambo -g n -p p -F gw.in

To run in parallel with default parallelism do:
export OMP_NUM_THREADS=1 #(or an integer larger than 1 to use OpenMP parallelism)
mpirun -np 8 yambo -F gw.in -J run_mpi8_omp1

Taking the case of hBN, in order to exploit this parallelism over 8 MPI tasks, set e.g.:
SE_CPU= " 1 2 4" # [PARALLEL] CPUs for each role
SE_ROLEs= "q qp b" # [PARALLEL] CPUs roles (q,qp,b)
Then run as
$ mpirun -np 8 yambo -F gw.in -J run_mpi8_omp1_tuned
Note that the product of the numbers in SE_CPU needs to be equal to the total number of MPI tasks, otherwise yambo will switch back to default parallelism (a warning is provided in the log).

Having a look at the report file, <code>r-run_mpi8_omp1_HF_and_locXC</code> here, one finds:
[01] CPU structure, Files & I/O Directories
===========================================

* CPU-Threads :8(CPU)-1(threads)-1(threads@SE)
* CPU-Threads :SE(environment)- 1 2 4(CPUs)-q qp b(ROLEs)
* MPI CPU : 8
* THREADS (max): 1
* THREADS TOT(max): 8

Now we can inspect the files created in the <code>./LOG</code> directory, e.g. <code>./LOG/l-run_mpi8_omp1_HF_and_locXC_CPU_1</code>, where we find:
<---> P0001: [01] CPU structure, Files & I/O Directories
<---> P0001: CPU-Threads:8(CPU)-1(threads)-1(threads@SE)
<---> P0001: CPU-Threads:SE(environment)- 1 2 4(CPUs)-q qp b(ROLEs)
...
<---> P0001: [PARALLEL Self_Energy for QPs on 2 CPU] Loaded/Total (Percentual):70/140(50%)
<---> P0001: [PARALLEL Self_Energy for Q(ibz) on 1 CPU] Loaded/Total (Percentual):14/14(100%)
<---> P0001: [PARALLEL Self_Energy for G bands on 4 CPU] Loaded/Total (Percentual):3/10(30%)
<---> P0001: [PARALLEL distribution for Wave-Function states] Loaded/Total(Percentual):84/140(60%)
providing the details of memory and computation distributions for the different levels. This report is from processor 1 (as highlighted about <code>_CPU_1</code> suffix). Similar pieces of information are provided for all CPUs. If different CPUs show very different distribution levels, it is likely that load unbalance occurs (e.g., try with 6 MPI tasks parallel over bands).

For Yambo version <= 4.1.2, Yambo may not be able to find a proper default parallel structure (try e.g. the above example asking for 20 MPI tasks, while you only have 8 bands to parallelise over). In These cases the calculation crashes and an error message is provided in the report file:
[ERROR]Impossible to define an appropriate parallel structure

In these cases it is then mandatory to specify a proper parallel structure. This has been mostly overcome by Yambo v. 4.2 on.

==BSE in parallel==

== Links ==
* [[Tutorials|Back to tutorials menu]]

[[Category:Modules]]

Selected Readings

2020-12-07T10:57:18Z

Claudio: /* Theoretical Spectroscopy */

== General Theory ==

* [http://nanodft09.iyte.edu.tr/pdf/MG-Lectures.pdf Theoretical spectroscopy], M. Gatti
* [http://etsf.polytechnique.fr/sites/default/files/users/francesco/els.pdf Energy Loss Spectroscopy], F. Sottile

= Many-body Theory =

* [http://nano-bio.ehu.es/lecturescagliari.php PhD lectures: MBPT and Yambo], L. Chiodo
* [http://www.physics.rutgers.edu/~coleman/mbody/pdf/bk.pdf The evolving monogram on Many Body Physics], Piers Coleman
* [http://www.sissa.it/cm/phd/lecture_notes/Many-Body.pdf Many Body], Michele Fabrizio
* [http://www.physics.ucla.edu/~nayak/many_body.pdf Quantum Condensed Matter Physics], Chetan Nayak
* [http://freescience.info/Physics.php?id=26 FreeScience.info--> Many Body]

= The GW method =

* [http://www.tddft.org/bmg/files/seminarios/24830.pdf Introduction to GW and Bethe-Salpeter - beyond density functional theory], S. Botti
* [http://www.physics.ohio-state.edu/~wilkins/vita/gw_review.ps Quasiparticle calculations in solids], Aulbur WG, Jonsson L, Wilkins JW
* [http://xxx.lanl.gov/abs/cond-mat/9712013 The GW methods], F. Aryasetiawan and O. Gunnarsson
* [http://www.fzj.helmholtz.de/nic-series/volume31/friedrich.pdf Many-Body Perturbation Theory: The GW Approximation], Christoph Friedrich and Arno Schindlmayr
* [http://www.amazon.com/Electron-Correlation-Solid-State-Norman/dp/1860942008 Electron Correlation in the Solid State] (not free), Norman H. March
* [http://repository.kulib.kyoto-u.ac.jp/dspace/bitstream/2433/96909/1/KJ00004711290.pdf Correlation effects in solids from first principles], Aryasetiawan Ferdi
* [https://www.frontiersin.org/articles/10.3389/fchem.2019.00377/full The GW Compendium: A Practical Guide to Theoretical Photoemission Spectroscopy], Dorothea Golze, Marc Dvorak and Patrick Rinke
* [http://arxiv.org/abs/1109.3972 Hedin Equations, GW, GW+DMFT, and All That], K. Held, C. Taranto, G. Rohringer, A. Toschi

= Density Functional Theory =

* [http://dft.uci.edu/materials/bookABCDFT/gamma/g1.pdf The ABC of DFT], Kieron Burke
* [http://chem.ps.uci.edu/~kieron/dft/pubs/PK98.ps Density Functionals for non relativistic Coulomb Systems], J. Perdew and S. Kurth
* [http://arxiv.org/abs/cond-mat/0211443 A bird's-eye view of density-functional theory], Klaus Capelle
* [http://www.fisica.uniud.it/~giannozz/Corsi/pisa05.pdf Density Functional Theory for Electronic Structure Calculations], Paolo Giannozzi
* [http://arxiv.org/abs/cond-mat/0012092 Phonons and related properties of extended systems from density-functional perturbation theory], S. Baroni, S. de Gironcoli, A. Dal Corso, P. Giannozzi
* [http://theochem.chem.rug.nl/publications/PDF/ft425.pdf Density functional approach to the many-body problem], Robert van Leeuwen

= TDDFT =

* [http://research.physics.illinois.edu/ElectronicStructure/598SCM-F04/Reining-ref-papers-for-lectures/Reining-RMP.pdf Electronic Excitations: Density-Functional VS Many-body Green's], G. Onida, L. Reining, A. Rubio
* [http://www.physik.fu-berlin.de/~ag-gross/articles/pdf/BG98.pdf A guided tour of time-dependent density functional theory], K. Burke and E.K.U. Gross
* [http://www.physik.fu-berlin.de/~ag-gross/articles/pdf/MG03.pdf Time-dependent Density Functional Theory], Miguel A. L. Marques and E. K. U. Gross
* [http://www.physik.fu-berlin.de/~ag-gross/articles/pdf/GDP96.pdf Density functional theory of time-dependent phenomena], E.K.U. Gross , J.F. Dobson , and M. Petersilka
* [http://dcm.ujf-grenoble.fr/PERSONNEL/CT/casida/research/chong.ps Time-dependent density-functional response theory for molecules], Mark Casida
* [http://www.fhi-berlin.mpg.de/th/publications/RPP-70-357-2007.pdf Time-dependent density-functional theory for extended systems], S. Botti et al.

= Non-equilibrium Green's function =

* [http://theochem.chem.rug.nl/research/vanleeuwen/literature/NGF.pdf An Introduction to Nonequilibrium Green Functions], Robert van Leeuwen
* [http://www.physics.arizona.edu/~stafford/Courses/560A/nonequilibrium.pdf An Introduction to Nonequilibrium Many-Body Theory], Joseph Maciejko
* [http://theochem.chem.rug.nl/publications/PDF/ft497.pdf The Keldysh Formalism Applied to Time-Dependent Current-Density-Functional Theory], Robert van Leeuwen

= Theoretical Spectroscopy =

* [http://www.amazon.com/Electrodynamics-Solids-Optical-Properties-Electrons/dp/0521597269 Electrodynamics of Solids: Optical Properties of Electrons in Matter], Martin Dressel , George Gruner
* [http://nd.edu/~mkuno/Class_downloads/Chem648_quantum_text.pdf Quantum Mechanics and Spectroscopy: another book], M. Kuno
* [http://nd.edu/~mkuno/Class_downloads/Chem90652_spect_text.pdf Molecular spectroscopy], M. Kuno
* [http://folk.uio.no/yurig/lund97.ps.gz Non-Stationary Electric and Optical Properties of Bulk Conductin], Yuri Galperin
* [http://physik.uni-graz.at/~uxh/Publications/nano.pdf Optical properties of semiconductor nanostructures: Decoherence versus Quantum Control], Ulrich Hohenester
* [http://www.gps.caltech.edu/~gab/ch21b/Lecture_notes.html Spectroscopy], Geoffrey A. Blake
* [http://bcsbec.df.unicam.it/files/LaRNC11_N12(1988).pdf Application of the Green’s functions method to the study of the optical properties of semiconductors], G. Strinati
* [https://iopscience.iop.org/article/10.1238/Physica.Topical.109a00141 Effects of the Electron–Hole Interaction on the Optical Properties of Materials: the Bethe–Salpeter Equation], G. Bussi
* [http://freescience.info/Physics.php?id=441 FreeScience.info--> Spectroscopy]

= Computer Programming =

* [http://www.star.le.ac.uk/~cgp/f90course/f90.html Fortran90 for Fortran77 Programmers], Clive Page
* [http://www.personal.psu.edu/jhm/f90/lectures/quickref.html Fortran 90 Lectures], John Mahaffy
* [http://tldp.org/LDP/Bash-Beginners-Guide/Bash-Beginners-Guide.pdf Bash Guide for Beginners], Machtelt Garrels
* [http://www.cs.cf.ac.uk/Dave/C/CE.html Programming in C UNIX System Calls and Subroutines using C], A. D. Marshall
* [http://publications.gbdirect.co.uk/c_book/ The C Book], Mike Banahan, Declan Brady and Mark Doran

Selected Readings

2020-12-07T10:56:48Z

Claudio: /* Theoretical Spectroscopy */

== General Theory ==

* [http://nanodft09.iyte.edu.tr/pdf/MG-Lectures.pdf Theoretical spectroscopy], M. Gatti
* [http://etsf.polytechnique.fr/sites/default/files/users/francesco/els.pdf Energy Loss Spectroscopy], F. Sottile

= Many-body Theory =

* [http://nano-bio.ehu.es/lecturescagliari.php PhD lectures: MBPT and Yambo], L. Chiodo
* [http://www.physics.rutgers.edu/~coleman/mbody/pdf/bk.pdf The evolving monogram on Many Body Physics], Piers Coleman
* [http://www.sissa.it/cm/phd/lecture_notes/Many-Body.pdf Many Body], Michele Fabrizio
* [http://www.physics.ucla.edu/~nayak/many_body.pdf Quantum Condensed Matter Physics], Chetan Nayak
* [http://freescience.info/Physics.php?id=26 FreeScience.info--> Many Body]

= The GW method =

* [http://www.tddft.org/bmg/files/seminarios/24830.pdf Introduction to GW and Bethe-Salpeter - beyond density functional theory], S. Botti
* [http://www.physics.ohio-state.edu/~wilkins/vita/gw_review.ps Quasiparticle calculations in solids], Aulbur WG, Jonsson L, Wilkins JW
* [http://xxx.lanl.gov/abs/cond-mat/9712013 The GW methods], F. Aryasetiawan and O. Gunnarsson
* [http://www.fzj.helmholtz.de/nic-series/volume31/friedrich.pdf Many-Body Perturbation Theory: The GW Approximation], Christoph Friedrich and Arno Schindlmayr
* [http://www.amazon.com/Electron-Correlation-Solid-State-Norman/dp/1860942008 Electron Correlation in the Solid State] (not free), Norman H. March
* [http://repository.kulib.kyoto-u.ac.jp/dspace/bitstream/2433/96909/1/KJ00004711290.pdf Correlation effects in solids from first principles], Aryasetiawan Ferdi
* [https://www.frontiersin.org/articles/10.3389/fchem.2019.00377/full The GW Compendium: A Practical Guide to Theoretical Photoemission Spectroscopy], Dorothea Golze, Marc Dvorak and Patrick Rinke
* [http://arxiv.org/abs/1109.3972 Hedin Equations, GW, GW+DMFT, and All That], K. Held, C. Taranto, G. Rohringer, A. Toschi

= Density Functional Theory =

* [http://dft.uci.edu/materials/bookABCDFT/gamma/g1.pdf The ABC of DFT], Kieron Burke
* [http://chem.ps.uci.edu/~kieron/dft/pubs/PK98.ps Density Functionals for non relativistic Coulomb Systems], J. Perdew and S. Kurth
* [http://arxiv.org/abs/cond-mat/0211443 A bird's-eye view of density-functional theory], Klaus Capelle
* [http://www.fisica.uniud.it/~giannozz/Corsi/pisa05.pdf Density Functional Theory for Electronic Structure Calculations], Paolo Giannozzi
* [http://arxiv.org/abs/cond-mat/0012092 Phonons and related properties of extended systems from density-functional perturbation theory], S. Baroni, S. de Gironcoli, A. Dal Corso, P. Giannozzi
* [http://theochem.chem.rug.nl/publications/PDF/ft425.pdf Density functional approach to the many-body problem], Robert van Leeuwen

= TDDFT =

* [http://research.physics.illinois.edu/ElectronicStructure/598SCM-F04/Reining-ref-papers-for-lectures/Reining-RMP.pdf Electronic Excitations: Density-Functional VS Many-body Green's], G. Onida, L. Reining, A. Rubio
* [http://www.physik.fu-berlin.de/~ag-gross/articles/pdf/BG98.pdf A guided tour of time-dependent density functional theory], K. Burke and E.K.U. Gross
* [http://www.physik.fu-berlin.de/~ag-gross/articles/pdf/MG03.pdf Time-dependent Density Functional Theory], Miguel A. L. Marques and E. K. U. Gross
* [http://www.physik.fu-berlin.de/~ag-gross/articles/pdf/GDP96.pdf Density functional theory of time-dependent phenomena], E.K.U. Gross , J.F. Dobson , and M. Petersilka
* [http://dcm.ujf-grenoble.fr/PERSONNEL/CT/casida/research/chong.ps Time-dependent density-functional response theory for molecules], Mark Casida
* [http://www.fhi-berlin.mpg.de/th/publications/RPP-70-357-2007.pdf Time-dependent density-functional theory for extended systems], S. Botti et al.

= Non-equilibrium Green's function =

* [http://theochem.chem.rug.nl/research/vanleeuwen/literature/NGF.pdf An Introduction to Nonequilibrium Green Functions], Robert van Leeuwen
* [http://www.physics.arizona.edu/~stafford/Courses/560A/nonequilibrium.pdf An Introduction to Nonequilibrium Many-Body Theory], Joseph Maciejko
* [http://theochem.chem.rug.nl/publications/PDF/ft497.pdf The Keldysh Formalism Applied to Time-Dependent Current-Density-Functional Theory], Robert van Leeuwen

= Theoretical Spectroscopy =

* [http://www.amazon.com/Electrodynamics-Solids-Optical-Properties-Electrons/dp/0521597269 Electrodynamics of Solids: Optical Properties of Electrons in Matter], Martin Dressel , George Gruner
* [http://nd.edu/~mkuno/Class_downloads/Chem648_quantum_text.pdf Quantum Mechanics and Spectroscopy: another book], M. Kuno
* [http://nd.edu/~mkuno/Class_downloads/Chem90652_spect_text.pdf Molecular spectroscopy], M. Kuno
* [http://folk.uio.no/yurig/lund97.ps.gz Non-Stationary Electric and Optical Properties of Bulk Conductin], Yuri Galperin
* [http://physik.uni-graz.at/~uxh/Publications/nano.pdf Optical properties of semiconductor nanostructures: Decoherence versus Quantum Control], Ulrich Hohenester
* [http://www.gps.caltech.edu/~gab/ch21b/Lecture_notes.html Spectroscopy], Geoffrey A. Blake
* [http://bcsbec.df.unicam.it/files/LaRNC11_N12(1988).pdf Application of the Green’s functions method to the study of the optical properties of semiconductors], G. Strinati
* [https://iopscience.iop.org/article/10.1238/Physica.Topical.109a00141 https://iopscience.iop.org/article/10.1238/Physica.Topical.109a00141], G. Bussi
* [http://freescience.info/Physics.php?id=441 FreeScience.info--> Spectroscopy]

= Computer Programming =

* [http://www.star.le.ac.uk/~cgp/f90course/f90.html Fortran90 for Fortran77 Programmers], Clive Page
* [http://www.personal.psu.edu/jhm/f90/lectures/quickref.html Fortran 90 Lectures], John Mahaffy
* [http://tldp.org/LDP/Bash-Beginners-Guide/Bash-Beginners-Guide.pdf Bash Guide for Beginners], Machtelt Garrels
* [http://www.cs.cf.ac.uk/Dave/C/CE.html Programming in C UNIX System Calls and Subroutines using C], A. D. Marshall
* [http://publications.gbdirect.co.uk/c_book/ The C Book], Mike Banahan, Declan Brady and Mark Doran

Selected Readings

2020-12-07T10:54:26Z

Claudio: /* The GW method */

== General Theory ==

* [http://nanodft09.iyte.edu.tr/pdf/MG-Lectures.pdf Theoretical spectroscopy], M. Gatti
* [http://etsf.polytechnique.fr/sites/default/files/users/francesco/els.pdf Energy Loss Spectroscopy], F. Sottile

= Many-body Theory =

* [http://nano-bio.ehu.es/lecturescagliari.php PhD lectures: MBPT and Yambo], L. Chiodo
* [http://www.physics.rutgers.edu/~coleman/mbody/pdf/bk.pdf The evolving monogram on Many Body Physics], Piers Coleman
* [http://www.sissa.it/cm/phd/lecture_notes/Many-Body.pdf Many Body], Michele Fabrizio
* [http://www.physics.ucla.edu/~nayak/many_body.pdf Quantum Condensed Matter Physics], Chetan Nayak
* [http://freescience.info/Physics.php?id=26 FreeScience.info--> Many Body]

= The GW method =

* [http://www.tddft.org/bmg/files/seminarios/24830.pdf Introduction to GW and Bethe-Salpeter - beyond density functional theory], S. Botti
* [http://www.physics.ohio-state.edu/~wilkins/vita/gw_review.ps Quasiparticle calculations in solids], Aulbur WG, Jonsson L, Wilkins JW
* [http://xxx.lanl.gov/abs/cond-mat/9712013 The GW methods], F. Aryasetiawan and O. Gunnarsson
* [http://www.fzj.helmholtz.de/nic-series/volume31/friedrich.pdf Many-Body Perturbation Theory: The GW Approximation], Christoph Friedrich and Arno Schindlmayr
* [http://www.amazon.com/Electron-Correlation-Solid-State-Norman/dp/1860942008 Electron Correlation in the Solid State] (not free), Norman H. March
* [http://repository.kulib.kyoto-u.ac.jp/dspace/bitstream/2433/96909/1/KJ00004711290.pdf Correlation effects in solids from first principles], Aryasetiawan Ferdi
* [https://www.frontiersin.org/articles/10.3389/fchem.2019.00377/full The GW Compendium: A Practical Guide to Theoretical Photoemission Spectroscopy], Dorothea Golze, Marc Dvorak and Patrick Rinke
* [http://arxiv.org/abs/1109.3972 Hedin Equations, GW, GW+DMFT, and All That], K. Held, C. Taranto, G. Rohringer, A. Toschi

= Density Functional Theory =

* [http://dft.uci.edu/materials/bookABCDFT/gamma/g1.pdf The ABC of DFT], Kieron Burke
* [http://chem.ps.uci.edu/~kieron/dft/pubs/PK98.ps Density Functionals for non relativistic Coulomb Systems], J. Perdew and S. Kurth
* [http://arxiv.org/abs/cond-mat/0211443 A bird's-eye view of density-functional theory], Klaus Capelle
* [http://www.fisica.uniud.it/~giannozz/Corsi/pisa05.pdf Density Functional Theory for Electronic Structure Calculations], Paolo Giannozzi
* [http://arxiv.org/abs/cond-mat/0012092 Phonons and related properties of extended systems from density-functional perturbation theory], S. Baroni, S. de Gironcoli, A. Dal Corso, P. Giannozzi
* [http://theochem.chem.rug.nl/publications/PDF/ft425.pdf Density functional approach to the many-body problem], Robert van Leeuwen

= TDDFT =

* [http://research.physics.illinois.edu/ElectronicStructure/598SCM-F04/Reining-ref-papers-for-lectures/Reining-RMP.pdf Electronic Excitations: Density-Functional VS Many-body Green's], G. Onida, L. Reining, A. Rubio
* [http://www.physik.fu-berlin.de/~ag-gross/articles/pdf/BG98.pdf A guided tour of time-dependent density functional theory], K. Burke and E.K.U. Gross
* [http://www.physik.fu-berlin.de/~ag-gross/articles/pdf/MG03.pdf Time-dependent Density Functional Theory], Miguel A. L. Marques and E. K. U. Gross
* [http://www.physik.fu-berlin.de/~ag-gross/articles/pdf/GDP96.pdf Density functional theory of time-dependent phenomena], E.K.U. Gross , J.F. Dobson , and M. Petersilka
* [http://dcm.ujf-grenoble.fr/PERSONNEL/CT/casida/research/chong.ps Time-dependent density-functional response theory for molecules], Mark Casida
* [http://www.fhi-berlin.mpg.de/th/publications/RPP-70-357-2007.pdf Time-dependent density-functional theory for extended systems], S. Botti et al.

= Non-equilibrium Green's function =

* [http://theochem.chem.rug.nl/research/vanleeuwen/literature/NGF.pdf An Introduction to Nonequilibrium Green Functions], Robert van Leeuwen
* [http://www.physics.arizona.edu/~stafford/Courses/560A/nonequilibrium.pdf An Introduction to Nonequilibrium Many-Body Theory], Joseph Maciejko
* [http://theochem.chem.rug.nl/publications/PDF/ft497.pdf The Keldysh Formalism Applied to Time-Dependent Current-Density-Functional Theory], Robert van Leeuwen

= Theoretical Spectroscopy =

* [http://www.amazon.com/Electrodynamics-Solids-Optical-Properties-Electrons/dp/0521597269 Electrodynamics of Solids: Optical Properties of Electrons in Matter], Martin Dressel , George Gruner
* [http://nd.edu/~mkuno/Class_downloads/Chem648_quantum_text.pdf Quantum Mechanics and Spectroscopy: another book], M. Kuno
* [http://nd.edu/~mkuno/Class_downloads/Chem90652_spect_text.pdf Molecular spectroscopy], M. Kuno
* [http://folk.uio.no/yurig/lund97.ps.gz Non-Stationary Electric and Optical Properties of Bulk Conductin], Yuri Galperin
* [http://physik.uni-graz.at/~uxh/Publications/nano.pdf Optical properties of semiconductor nanostructures: Decoherence versus Quantum Control], Ulrich Hohenester
* [http://www.gps.caltech.edu/~gab/ch21b/Lecture_notes.html Spectroscopy], Geoffrey A. Blake
* [http://bcsbec.df.unicam.it/files/LaRNC11_N12(1988).pdf Application of the Green’s functions method to the study of the optical properties of semiconductors], G. Strinati
* [http://freescience.info/Physics.php?id=441 FreeScience.info--> Spectroscopy]

= Computer Programming =

* [http://www.star.le.ac.uk/~cgp/f90course/f90.html Fortran90 for Fortran77 Programmers], Clive Page
* [http://www.personal.psu.edu/jhm/f90/lectures/quickref.html Fortran 90 Lectures], John Mahaffy
* [http://tldp.org/LDP/Bash-Beginners-Guide/Bash-Beginners-Guide.pdf Bash Guide for Beginners], Machtelt Garrels
* [http://www.cs.cf.ac.uk/Dave/C/CE.html Programming in C UNIX System Calls and Subroutines using C], A. D. Marshall
* [http://publications.gbdirect.co.uk/c_book/ The C Book], Mike Banahan, Declan Brady and Mark Doran

Test-suite

2020-12-04T10:27:30Z

Claudio:

== Web-Interface ==

The updated list of test-suite runs can be found on the old Yambo web-page.

Tests' list is splitted in [http://www.yambo-code.org/robots/index.php branches].
For each branch many robots are shown.
Check the [http://www.yambo-code.org/robots/bug-fixes/polluce.php bug-fixes] branch as an example.

This list is automatically updated by the test-suite driver.pl when the -report option is used.

== Installation ==
The test suite is available on GitHub via git

%git clone https://github.com/yambo-code/yambo-tests.git yambo-tests

you may need to provide your GitHub username and password.

After the checkout the first thing to do is the configuration

%cd test-suite
%./configure --with-yambo=/home/marini/Yambo/yambo/master/

If the configuration works you should see something similar to the following message:

%./configure --with-yambo=/home/marini/Yambo/yambo/master/
%checking build system type... x86_64-unknown-linux-gnu
%checking host system type... x86_64-unknown-linux-gnu
%checking the anomaly.mlib.ism.cnr.it ROBOT... created
%checking for nccopy... no
%checking for ncftp... ncftp
%checking for ncftpls... ncftpls
%checking for ncftpput... ncftpput
%checking for awk... awk
%checking for txt2html... txt2html
%checking the Yambo source... /home/marini/Yambo/yambo/master/
%configure: creating ./config.status
%config.status: creating config/MODULES.pl
%config.status: creating config/TOOLS.pl

=== Robot informations ===

By typing

%./driver.pl -i

you will see some basic info about your machine. This command is useful to see the available flows, configurations and so on. An example is

Running on host: anomaly.mlib.ism.cnr.it
By user : marini
Version : 5.0
Available CPU's: 8
Available confs: default.sh
Available flows: failed_master.pl validate.pl default.pl failed_SLK.pl failed_devel-qp-dbs.pl minimal.pl

=== Database download ===
Now it is time to download all databases. This can be easily done using the -d option

%./driver.pl -d all

=== Compilation ===
By default the configure copies a basic compilation script in ROBOTS/<YOUR ROBOT>/CONFIGURATIONS/default.sh. This uses internally compiled libraries so it should work easily. In order to test it launch

%./driver.pl -compile

=== Internal Test ===
Use the autotest to verify your compiled source:

%./driver.pl -autotest

If everything works you should see as log the following message

%==================================================================================
%= Starting Yambo test-suite
%==================================================================================
% - Check requirements : ...ncftp...ncftpls...ncftpput...txt2html
% - Test selection : from input
% ncdump : /opt/gcc4/netcdf-4.0.1/bin/ncdump
% - Executable checks : (yambo OK ) (ypp FAIL )(a2y FAIL )(p2y FAIL )
% Running tests : hBN/GW-OPTICS 01_init 02_HF
% Projects : nopj
% Verbosity : low
% Precision : 0.01
% Hostname : anomaly.mlib.ism.cnr.it
% revision : 14505
% build : MPI+SLK
% bin dir : bin
% shortname :
% source : master_-precompiled
% Parallel Loop : SERIAL
%=--------------------------------------------------------------------------------=
% > [1 /1 ] hBN/GW-OPTICS[serial] '''5 passes'''
%=--------------------------------------------------------------------------------=

The '''5 passes''' are important as they represent the number of passed tests.

== For the impatiens: quick cron run and final reporting ==
If you do not want to bother with all details of the testing script and want just to install the suite read this section and stop.

In order to properly setup your machine for night test-suite runs you have to:

#Choose the branch(s) to test
For this purpose use
%./driver.pl -edit branches
#create a crontab entry
See [https://corenominal.org/2016/05/12/howto-setup-a-crontab-file/ here] for detailled informations on cron. My personal crontab file looks like

%# m h dom mon dow command
% 30 18 * * Thu ~/bin/scripts/yambo_validation.tcsh validate >> /home/marini/Yambo/sources/svn/yambo-tests/test-suite/LOG 2>&1

with

%>cat bin/scripts/yambo_validation.tcsh
%#!/usr/bin/tcsh
%cd /home/marini/Yambo/sources/svn/yambo-tests/test-suite
%./driver.pl -flow $argv[1] -report

That's all you need.

== Available tests ==
The list of tests can be done using the -l option:

%./driver.pl -l

Note that you can add a TEST to -l to list the specific inputs of that test. For example

%>./driver.pl -l GaAs001-c4x4/YAMBO
%
%Available input files for GaAs001-c4x4/YAMBO are: 01_init 02_RAS_full 03_RAS_full 04_RAS_front 05_RAS_dimer

== Reports & Logs ==
The autotest and any other run of the test-suite produces three files. Each file is labelled with the date of the run.

In order to see the meaning and the in formations written in the files let's do a quick run of a Dummy test created in order to reproduce some of the possible error conditions.

Let's first clean the suite

%./driver.pl -c

and use the -force to run also tests tagged as BROKEN (like the Dummy one). First thing to do is to download the Dummy database adding the -force option.

%./driver.pl -d Dummy -force

Then we can run the Dummy test using

%./driver.pl -tests Dummy -force

The result will now be

%=--------------------------------------------------------------------------------=
% > [1 /1 ] Dummy[serial] 11 passes 5 fails
%=--------------------------------------------------------------------------------=

The 5 fails cover most of the potential errors detected by the test-suite. Details can be now found in the report/log files

=== REPORT file ===
This file contains very condensed information about the run. There is the duration time plus some detail of the reasons behind the 5 fails.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% Yambo test suite global REPORT
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%==================================================================================
%Running tests :Dummy
%Projects :nopj
%Date - Time :Fri-19-May - 11-46
%Build :master - MPI+SLK - rev.14505
%Parallel Conf :[serial] - none
%=--------------------------------------------------------------------------------=
%FAIL: 5 & NO RUN: 0 & SKIPS: 0 % WHITELIST: 1 % OKs: 10
%FAIL details: 1 wrong output % 1 no reference % 1 no output % 2 no DB
%=--------------------------------------------------------------------------------=
%% Section Duration : 0:0:3 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% TOTAL Duration : 0:0:3 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

In the dummy case indeed the suite should detect:
# 1 wrong output
# 1 output missing the REFERENCE
# 1 missing output (not generated by the run)
# 2 missing databases.

More details can be found in the LOG and and in the ERROR.

''The REPORT file is the one used to send final logs to the mailing list.''

=== ERROR file ===
This is a useful file with detailed information about the errors only.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% Yambo test suite ERRORs log
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%==================================================================================
%Running tests :Dummy
%Projects :nopj
%Date - Time :Fri-19-May - 11-46
%Build :master - MPI+SLK - rev.14505
%Parallel Conf :[serial] - none
%=--------------------------------------------------------------------------------=
%Dummy/02_hf-serial-master/o-02_hf.hf : VALUE(# 17)@COL# 6 is -5.4691 [REF] vs -4.4691 [OUT] corresponding to 6.1013 [% RELATIVE TO MAX]
%Dummy/02_hf-serial-master : NO REFERENCE/o-02_hf.ndb.em1s_fragment_1 in OUTPUT
%Dummy/04_em1s-serial-master : NO o-04_em1s.ndb.em1s_fragment_1 in REFERENCE
%% Section Duration : 0:0:3 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% TOTAL Duration : 0:0:3 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

== Running ==
Before entering in the details of the different running methods let's first describe the Parallel Options

=== Parallel Options ===
% (parallel options)
% -np <N> Fixed number of CPU used
% -np_min <N> Minimum number of CPU used
% -np_max <N> Maximum number of CPU used
% -nt <T> # of OMP threads
% -nl <L> # of CPU used for linear algebra
% -def_par Use the default parallelization scheme
% -rand_par Use randomly generated parallel structures

Examples:

%./driver.pl -tests Dummy -force -np 2

produces all possible combinations of 2 cpu's for the Dummy tests. Each run is labelled in such a way to be unique. The Dummy folder will look like

%%l tests/Dummy/
%01_init-Nmpi2-1-master/ 02_hf-Nmpi2-3-master/ 03_optics-Nmpi2-3-master/ 04_em1s-Nmpi2-3-master/ INPUTS/ yambo.in
%02_hf 03_optics 04_em1s 04_em1s-Nmpi2-4-master/ LOG/
%02_hf-Nmpi2-1-master/ 03_optics-Nmpi2-1-master/ 04_em1s-Nmpi2-1-master/ BROKEN REFERENCE/
%02_hf-Nmpi2-2-master/ 03_optics-Nmpi2-2-master/ 04_em1s-Nmpi2-2-master/ Dummy.tar.gz SAVE/

Note that each run is labelled by the number of MPI cpus ('''Nmpi2''') and by the increasing counter of potential combinations of the two cpu's ('''-1-master,-2-master,...''').

Other potential combinations are

* MPI, default parallelization (no cycle)

%./driver.pl -tests Dummy -force -np 2 -def_par

* MPI, random parallelization (no cycle, good for testing)

%./driver.pl -tests Dummy -force -np 2 -rand_par

* MPI, using 2 and 4 cpu's, no cycle on combinations, using random parallelization

%./driver.pl -tests Dummy -force -np_min 2 -np_max 4 -rand_par

* OpenMP (if compiled with OpenMP)

%./driver.pl -tests Dummy -force -nt 2

* MPI+SLK

%./driver.pl -tests Dummy -force -np 4 -nl 4 -def_par

== Tests selection ==
The test-suite can be run in three different ways

# Using a theme
# Passing individual sets of tests
# Using flows

Moreover tests can be selected using projects.

Flows are discussed in the [[Test-suite|Flows]].

=== Theme ===
A theme is a just a series of tests. Themes are stored in the THEMES/ folder and are used simply using

%./driver.pl -theme test

''test'' is a text file in the THEMES folder.

=== Individual Tests ===
This is the way we used to run the Dummy test. Just use

%./driver.pl -tests Dummy

to select a combination of specific inputs and tests you can use more complex tests options:

%./driver.pl -tests "Dummy 01_init 02_hf; Si_bulk/GW-OPTICS 00_init 02Cohsex"

=== Projects & Keys ===
Project are listed with the test lists and are accessed with the lowercase options: elph,sc,rt,nl...

So in order to run '''all''' tests belonging to the '''sc''' project just type

%./driver.pl -tests all -keys sc

Actually the -keys option is more powerful as, in the future, should also select all inputs with specific observables (like gw, optics and so on).

The list of project are accessed by simply the first column in the list obtained by using the -l option. In the following are in bold.

%%./driver.pl -l
%Available test materials/systems:
%[YAMBO] Al111
% C6H3Cl3
% PA_chain[H]
% SiH4
% Al_bulk/GW-OPTICS
% H2/OPTICS
% H_chain/2.05
% H_chain/2.5
% hBN/GW-OPTICS
% LiF/GW-OPTICS
% Si_bulk/GW-OPTICS
% Si_surface/OPTICS
% Si_wire/OPTICS
% MoS2/pwscf/OPTICS
% MoS2/abinit/OPTICS/With-SOC
% MoS2/abinit/OPTICS/Without-SOC-sp1
% MoS2/abinit/OPTICS/Without-SOC-sp2
%['''QED'''] Si_bulk/QED
%['''NL'''] hBN/NL
%['''RT'''] AlAs[H]
% H2/RT
% hBN/RT
% Si_bulk/RT
% WSe2/RT[H]
% MoS2/pwscf/RT
%['''SC'''] H2/SC
% hBN/SC
% Si_bulk/SC
%['''MAGNETIC'''] Si_bulk/MAGNETIC
%['''ELPH'''] Diamond/ELPH1[H]
% Si_bulk/ELPH/BSE
% Si_bulk/ELPH/ELPH_base
% Si_bulk/ELPH/ELPH_for_BSE
% Si_bulk/ELPH/QP_CTL
%['''KERR'''] Cobalt
% Nickel
% Iron/pwscf
% Iron/abinit/With-SOC
% Iron/abinit/Without-SOC
%[BROKEN] Dummy
% GaAs001-c4x4/YAMBO
% hBN/PL[PL]
% Si001-c4x2/YAMBO
% WS2/PL[PL]

Note that to access any of these projects you must use the lowercase option. For example
*SC → -keys sc
*RT → -keys rt
*SC+RT → -keys 'sc rt'

=== HARD tests ===
Some of the tests are long. In the tests list they are labelled with a '''[H]'''. In order to run them the key ''hard'' must be used. For example

%./driver.pl -tests all -keys 'sc rt hard'

runs all SC+RT tests including the heavy ones.

== FLOWS ==
All properties of a single launch of the test-suite and also a more complex test-suite launch looping on several parallel, tests, branches, combinations can be controlled via the FLOW feature.

A FLOW is a perl file (like validate.pl) containing combinations of descriptors.

All FLOW files are in the '''ROBOTS/<YOUR ROBOT>/FLOWS'''.

A FLOW is run using

%./driver.pl -flow validate

A general flow descriptor is
% {
% ACTIVE => "yes", # can be yes or no
% MPI_CPU => "NP",
% SLK_CPU => "NM",
% PAR_MODE => "TEXT", # (TEXT can be default, random, loop)
% THREADS => "NT",
% BRANCH => "/home/marini/Yambo/sources/git/yambo/branches/SLK", # (SAVED)
% THEME => "G_parallelization", # (SAVED)
% CONFIG => "gfortran_slk.sh", # (SAVED)
% TESTS => "hBN/GW-OPTICS", # (SAVED)
% KEYS => "nopj elph hard bse rpa", # (SAVED)
%}

The fields labelled with a '''(SAVE)''' are not changed if this descriptor is included in a more complex FLOW. In order to explain this feature let's just have a look at the default validate FLOW provided by default:

%#!/usr/bin/perl
%#
%@flow = (
%{
% ACTIVE => "yes",
% CONFIG => "default.sh",
% KEYS => "nopj elph sc hard",
%},
%{
% MPI_CPU => $SYSTEM_NP,
% PAR_MODE => "default",
%},
%{
% MPI_CPU => $SYSTEM_NP,
% PAR_MODE => "random",
%},
%{
% MPI_CPU => $SYSTEM_NP_half,
% PAR_MODE => "loop",
%},
%{
% THREADS => $SYSTEM_NP_half,
%},
%{
% MPI_CPU => $SYSTEM_NP,
% SLK_CPU => $SYSTEM_NP_half,
% PAR_MODE => "default",
%},
%{
% MPI_CPU => $SYSTEM_NP_half,
% THREADS => $SYSTEM_NP_half,
% SLK_CPU => $SYSTEM_SLK,
% PAR_MODE => "default",
%},
%);

When this flow is launched the driver.pl will run all tests of the ''"nopj elph sc hard"'' projects using: a serial run, all system CPU's with default parallelization, with random parallelization, cycling among all possible combinations and so so...

Note that also the -autotest is just a simple calculation flow.

== Robots ==
In version 5.0 the concept of Robots was introduced. In practice each time you run the driver.pl test-suite in any form (compilation, flow, manual tests and so on) the perl script will create a ROBOT.

In practice this means that all operations will be labelled with a <ROBOT> string. Single tests, executables will be copied to a dedicated ROBOT folder and also the LOG and REPORT files will be labelled by the specific ROBOT they belong to.

The benefits of this ROBOT structure is that multiple ROBOTS can be run simultaneously on the same test-suite!

Try yourself by simply running two instances of driver.pl.

'''WARNING: when you run more than 1 robot at the same time be sure to give time to the driver.pl to open all log files'''.

In addition if you are compiling the same source leave the robot the time to compile it before running a second robot on the same source.

=== Robot specific operations ===

You can clean/kill only the robot ID by using

%./driver.pl -c -robot ID
%./driver.pl -kill -robot ID

You can also launch the driver.pl with a specific robot ID

%./driver.pl -flow validate -robot ID

=== Robot branches ===

When several robots are run at the same time it is often necessary to specify for each robot a branch to do. This can be easily done via the branch file. This is an example of robot dependent branch file (obtained via the ./driver.pl -e branches) command

/home/marini/yambo/master master R1
/home/marini/yambo/master master R2
/home/marini/yambo/gpl master R3
/home/marini/yambo/gpl master R4
/home/marini/yambo/gpl master R5
/home/marini/yambo/gpl master R6
/home/marini/yambo/branches/devel-rt-stable devel-rt-stable R7
/home/marini/yambo/branches/devel-rt-stable devel-rt-stable R8

This file commands the driver.pl to run the master when the robot ID (-robot ID) is 1 or 2, the gpl for robots from 3 to 6 and so on.

== Adding New Tests ==

Adding a new test is easy.

Let's use a simple example.

Imagine I want to add the test hBN/PIPPO for which I have the SAVE and a list of input files. I copy everything in TESTS/MAIN/hBN creating a new directory, PIPPO

hBN>ls
GW-OPTICS hBN.tar.gz NL PIPPO PL RT SC

In PIPPO I have only the INPUTS and SAVE folders

PIPPO>ls -R
.:
INPUTS SAVE

./INPUTS:

01_init 02_HF

./SAVE:
ns.db1 ns.kb_pp ns.kb_pp_fragment_1 ns.kb_pp_fragment_2 ns.kb_pp_fragment_3 ns.kb_pp_fragment_4 ns.wf ns.wf_fragments_1_1
ns.wf_fragments_2_1 ns.wf_fragments_3_1 ns.wf_fragments_4_1

At this point I simply run

./driver.pl -update hBN/PIPPO

The driver will run the inputs, create the REFERENCE folder, the .tar.gz of the new test which is uploaded on the ftp server.

Remember to add -compile if your source is not compiled.

At the end of the calculation the git status command should give

yambo-tests>git status
On branch master
Your branch is up-to-date with 'origin/master'.
Changes to be committed:
(use "git reset HEAD <file>..." to unstage)
new file: TESTS/MAIN/hBN/PIPPO/INPUTS/01_init
new file: TESTS/MAIN/hBN/PIPPO/INPUTS/02_HF
new file: TESTS/MAIN/hBN/PIPPO/REFERENCE/l-02_HF_HF_and_locXC
new file: TESTS/MAIN/hBN/PIPPO/REFERENCE/o-02_HF.hf
new file: TESTS/MAIN/hBN/PIPPO/REFERENCE/o-02_HF.ndb.HF_and_locXC
new file: TESTS/MAIN/hBN/PIPPO/REFERENCE/r-02_HF_HF_and_locXC
new file: TESTS/MAIN/hBN/PIPPO/SAVE/.empty

It's now enough that you push and the new test will be ready!

Test-suite-simple

2020-12-04T10:26:28Z

Claudio: /* Troubleshooting */

== Intro for dummies ==

Download and configure (warning the last step will download ~1GB)
%git clone https://github.com/yambo-code/yambo-tests.git yambo-tests
%cd yambo-tests
%./configure --with-yambo=/home/marini/Yambo/yambo/master/
%./driver.pl -d all
Run the test suite and wait for it to finish (warning yambo, ypp, p2y, a2y, yambo_rt and ypp_rt need to be already compiled)
%./driver.pl -tests Si_bulk -keys rt
Check for available options
%./driver.pl -H

== Add a new input inside a test ==

%cd TESTS/MAIN/Si_bulk/RT

create input file
%cp my_test.in INPUTS/XX_testname
%git add INPUTS/XX_testname
and add output reference files
%cp *my_tests* REFERENCE
%git add REFERENCE/*my_test*

After that if you go back to the main folder and run
%./driver.pl -tests Si_bulk -keys rt
the new test will be executed.
If everything works fine you can commit:
%git commit

For a more extended description see [[Test-suite|Test-suite]]

== Troubleshooting ==

* If you link external libraries please be sure to copy ''ncdump'' and ''nccopy'' in the Yambo bin folder

* do not forget to create the BRANCHES file in ROBOTS/hostname/usernames/BRANCHES with the folder and the name of your branch like
/home/attacc/SOFTWARE/yambo-bugfixes bugfixes

* In order to make test-suite works properly you need to add ssh-key in GitHub and clone the code using SSH and not HTTPS

* Be sure that the following packages are installed on your pc: ncftp, ncftpls, ncftput, wget, git, awk, txt2html, rsync

* If you want to test a branch and then upload the result on the web, it is important to use -branch branch_name when you perform the test otherwise the script will put the results of all branches in the same report and the upload will not work properly

* If you use a script in the crontab do not forget to add the path of all libraries in the script and to load the MKL variables.

How to obtain the quasi-particle band structure of a bulk material: h-BN

2020-11-19T13:53:16Z

Claudio: /* Step 7: Taking into account the material anisotropy (only available in Yambo 4.6) */

In this tutorial you will learn how to:
* Calculate quasi-particle corrections in the Hartree-Fock approximation
* Calculate quasi-particle corrections in the GW approximation
* Choose the input parameters for a meaningful converged calculation
* Plot a band structure including quasi-particle corrections
We will use bulk hBN as an example system. Before starting, you need to obtain the appropriate tarball. See instructions on the [[Tutorials|main tutorials page]]. 
We strongly recommend that you first complete the [[First steps: a walk through from DFT to optical properties]] tutorial.



The aim of the present tutorial is to obtain quasiparticle correction to energy levels using many-body perturbation theory (MBPT). 
The general non-linear quasiparticle equation reads:
[[File:Eqp_1.png|none|x26px|caption]]
As a first step we want to evaluate the self energy Σ entering in the quasiparticle equation. In the GW approach the self-energy can be separated into two components: a static term called the exchange self-energy (Σx), and a dynamical term (energy dependent) called the correlation self-energy (Σc):
[[File:Sigma.png|none|x25px|caption]]
We will treat these two terms separately and demonstrate how to set the most important variables for calculating each term.
In practice we will compute the quasi-particle corrections to the one particle Kohn-Sham eigenvalues obtained through a DFT calculation.

The steps are the following:

==Step 1: The Exchange Self Energy or HF quasi-particle correction==

We start by evaluating the exchange Self-Energy and the corresponding Quasiparticle energies (Hartree-Fock energies).
Follow the module on '''[[Hartree Fock]]''' and then return to this tutorial ''How to obtain the quasiparticle band structure of a bulk material: h-BN''.

==Step 2: The Correlation Self-Energy and Quasiparticle Energies==
Once we have calculated the exchange part, we next turn our attention to the more demanding dynamical part. The correlation part of the self-energy in a plane wave representation reads:
[[File:Sigma_c.png|none|x50px|caption]]
In the expression for the correlation self energy, we have (1) a summation over bands, (2) an integral over the Brillouin Zone, and (3) a sum over the G vectors. In contrast with the case of Σx, the summation over bands extends over ''all'' bands (including the unoccupied ones), and so convergence tests are needed. Another important difference is that the Coulomb interaction is now screened so a fundamental ingredient is the evaluation of the dynamical dielectric matrix. The expression for the dielectric matrix, calculated at the RPA level and including local field effects, has been already treated in the [[Local fields|Local fields]] tutorial.

In the following, we will see two ways to take into account the dynamical effects. First, we will see how to set the proper parameters to obtain a model dielectric function based on a widely used approximation, which models the energy dependence of each component of the dielectric matrix with a single pole function.
Secondly, we will see how to perform calculations by evaluating the dielectric matrix on a regular grid of frequencies.

Once the correlation part of the self-energy is calculated, we will check the convergence of the different parameters with respect to some final quantity, such as the gap.

After computing the frequency dependent self-energy, we will discover that in order to solve the quasiparticle equation we will need to know its value ''at the value of the quasiparticle itself''. In the following, unless explicitly stated, we will solve the non-linear quasi-particle equation at first order, by expanding the self-energy around the Kohn-Sham eigenvalue. In this way the quasiparticle equation reads:

[[File:Eqp_2.png|none|x26px|caption]]

where the normalization factor Z is defined as:

[[File:z_fac.png|none|x40px|caption]]

===The Plasmon Pole approximation===
As stated above, the basic idea of the plasmon-pole approximation is to approximate the frequency dependence of the dielectric matrix with a single pole function of the form:
[[File:ppa.png|none|x26px|caption]]
The two parameters RGG' and ΩGG' are obtained by a fit (for each component), after having calculated the RPA dielectric matrix at two given frequencies.
Yambo calculates the dielectric matrix in the static limit ( ω=0) and at a user defined frequency called the plasmon-pole frequency (ω=iωp).
Such an approximation has the big computational advantage of calculating the dielectric matrix for only two frequencies and leads to an analytical expression for the frequency integral of the correlation self-energy.
==== Input file generation ====
Let's start by building up the input file for a GW/PPA calculation, including the calculation of the exchange self-energy. From <code>yambo -H</code> you should understand that the correct option is <code>yambo -x -p p -g n</code>:

$ cd YAMBO_TUTORIALS/hBN/YAMBO
$ yambo -x -p p -g n -F gw_ppa.in

Let's modify the input file in the following way:

HF_and_locXC # [R XX] Hartree-Fock Self-energy and Vxc
ppa # [R Xp] Plasmon Pole Approximation
gw0 # [R GW] GoWo Quasiparticle energy levels
em1d # [R Xd] Dynamical Inverse Dielectric Matrix
[[Variables#EXXRLvcs|EXXRLvcs]] = 40 Ry # [XX] Exchange RL components
[[Variables#VXCRLvcs|VXCRLvcs]] = 3187 RL # [XC] XCpotential RL components
Chimod= "Hartree" # [X] IP/Hartree/ALDA/LRC/BSfxc
% BndsRnXp
1 | 10 | # [Xp] Polarization function bands
%
[[Variables#NGsBlkXp|NGsBlkXp]]= 1000 mRy # [Xp] Response block size
% LongDrXp
1.000000 | 1.000000 | 1.000000 | # [Xp] [cc] Electric Field
%
[[Variables#PPAPntXp|PPAPntXp]] = 27.21138 eV # [Xp] PPA imaginary energy
%[[Variables#GbndRnge|GbndRnge]]
1 | 40 | # [GW] G[W] bands range
%
GDamping= 0.10000 eV # [GW] G[W] damping
dScStep= 0.10000 eV # [GW] Energy step to evaluate Z factors
DysSolver= "n" # [GW] Dyson Equation solver ("n","s","g")
%[[Variables#QPkrange|QPkrange]] # [GW] QP generalized Kpoint/Band indices
7| 7| 8| 9|
%

Brief explanation of some settings:
* Similar to the Hartree Fock study, we will concentrate on the convergence of the '''direct''' gap of the system. Hence we select the last occupied (8) and first unoccupied (9) bands for k-point number 7 in the <code>[[Variables#QPkrange|QPkrange]]</code> variable.
* We also keep <code>[[Variables#EXXRLvcs|EXXRLvcs]]</code> at its converged value of 40 Ry as obtained in the '''[[Hartree Fock]]''' tutorial.
* For the moment we keep fixed the plasmon pole energy <code>[[Variables#PPAPntXp|PPAPntXp]]</code> at its default value (=1 Hartree).
* We keep fixed the direction of the electric field for the evaluation of the dielectric matrix to a non-specific value: <code>[[Variables#LongDrXp|LongDrXp]]</code>=(1,1,1).
* Later we will study convergence with respect to <code>[[Variables#GbndRnge|GbndRnge]]</code>, <code>[[Variables#NGsBlkXp|NGsBlkXp]]</code>, and <code>[[Variables#BndsRnXp|BndsRnXp]]</code>; for now just set them to the values indicated.

==== Understanding the output ====
Let's look at the typical Yambo output. Run Yambo with an appropriate <code>-J</code> flag:

$ yambo -F gw_ppa.in -J 10b_1Ry

In the standard output you can recognise the different steps of the calculations: calculation of the screening matrix (evaluation of the non interacting and interacting response), calculation of the exchange self-energy, and finally the calculation of the correlation self-energy and quasiparticle energies. Moreover information on memory usage and execution time are reported:
...
<---> [05] Dynamic Dielectric Matrix (PPA)
...
<08s> Xo@q[3] |########################################| [100%] 03s(E) 03s(X)
<08s> X@q[3] |########################################| [100%] --(E) --(X)
...
<43s> [06] Bare local and non-local Exchange-Correlation
<43s> EXS |########################################| [100%] --(E) --(X)
...
<43s> [07] Dyson equation: Newton solver
<43s> [07.01] G0W0 (W PPA)
...
<45s> G0W0 (W PPA) |########################################| [100%] --(E) --(X)
...
<45s> [07.02] QP properties and I/O
<45s> [08] Game Over & Game summary

Let's have a look at the report and output. The output file ''o-10b_1Ry.qp'' contains (for each band and k-point that we indicated in the input file) the values of the bare KS eigenvalue, its GW correction and the correlation part of the self energy:
#
# K-point Band Eo E-Eo Sc|Eo
#
7.000000 8.000000 -0.411876 -0.567723 2.322443
7.000000 9.000000 3.877976 2.413773 -2.232241

In the header you can see the details of the calculations, for instance it reports that <code>[[Variables#NGsBlkXp|NGsBlkXp]]</code>=1 Ry corresponds to 5 Gvectors:

# X G`s [used]: 5

Other information can be found in the report file ''r-10b_1Ry_em1d_ppa_HF_and_locXC_gw0'', such as the renormalization factor defined above, the value of the ''exchange'' self-energy (non-local XC) and of the DFT exchange-correlation potential (local XC):

[07.02] QP properties and I/O
=============================
Legend (energies in eV):
- B : Band - Eo : bare energy
- E : QP energy - Z : Renormalization factor
- So : Sc(Eo) - S : Sc(E)
- dSp: Sc derivative precision
- lXC: Starting Local XC (DFT)
-nlXC: Starting non-Local XC (HF)
QP [eV] @ K [7] (iku): 0.000000 -0.500000 0.000000
B=8 Eo= -0.41 E= -0.98 E-Eo= -0.56 Re(Z)=0.81 Im(Z)=-.2368E-2 nlXC=-19.13 lXC=-16.11 So= 2.322
B=9 Eo= 3.88 E= 6.29 E-Eo= 2.41 Re(Z)=0.83 Im(Z)=-.2016E-2 nlXC=-5.536 lXC=-10.67 So=-2.232

Extended information can be also found in the output activating in the input the <code>[[Variables#ExtendOut|ExtendOut]]</code> flag. This is an optional flag that can be activated by adding the <code>-V qp</code> verbosity option when building the input file. The plasmon pole screening, exchange self-energy and the quasiparticle energies are also saved in databases so that they can be reused in further runs:

$ ls ./10b_1Ry
ndb.pp ndb.pp_fragment_1 ... ndb.HF_and_locXC ndb.QP

===Convergence tests for a quasi particle calculation===

Now we can check the convergence of the different variables entering in the expression of the correlation part of the self energy. 
First, we focus on the parameter governing the ''screening matrix'' you have already seen in the [[RPA/IP]] section. In contrast to the calculation of the [[RPA/IP]] dielectric function, where you considered either the optical limit or a finite q response (EELS), here the dielectric matrix will be calculated for ''all'' q-points determined by the choice of k-point sampling.

The parameters that need to be converged can be understood by looking at expression of the dielectric matrix:
[[File:Yambo-CH5.png|none|x30px|Yambo tutorial image]]
where ''χGG''' is given by
[[File:Dyson_rpa.png|none|x40px|Yambo tutorial image]]
and χ0GG' is given by
[[File:ChiO.png|none|x45px|Yambo tutorial image]]
* <code>[[Variables#NGsBlkXp|NGsBlkXp]]</code> : The dimension of the microscopic inverse matrix, related to [[Local fields]]
* <code>[[Variables#BndsRnXp|BndsRnXp]]</code> : The sum on bands (c,v) in the independent particle χ0GG'

====Converging Screening Parameters====
Here we will check the convergence of the gap starting from the variables controlling the screening reported above: the bands employed to build the RPA response function <code>[[Variables#BndsRnXp|BndsRnXp]]</code> and the number of blocks (G,G') of the dielectric matrix ε-1G,G' <code>[[Variables#NGsBlkXp|NGsBlkXp]]</code>.
In the next section we will study convergence with respect to the sum over states summation (sum over ''m'' in the Σc expression); here let's fix <code>[[Variables#GbndRnge|GbndRnge]]</code> to a reasonable value (40 Ry).

Let's build a series of input files differing by the values of bands and block sizes in χ0GG' considering <code>[[Variables#BndsRnXp|BndsRnXp]]</code> in the range 10-50 (upper limit) and <code>[[Variables#NGsBlkXp|NGsBlkXp]]</code> in the range 1 to 5 Ry. To do this by hand, file by file, open the ''gw_ppa.in'' file in an editor and change to:
[[Variables#NGsBlkXp|NGsBlkXp]] = '''2 Ry'''
while leaving the rest untouched. Repeat for 3 Ry, 4 Ry etc. Next, for each <code>[[Variables#NGsBlkXp|NGsBlkXp]]</code> change to:
% [[Variables#BndsRnXp|BndsRnXp]]
1 | 20 | # [Xp] Polarization function bands
%
and repeat for 30, 40 and so on. Give a '''different name''' to each file: ''gw_ppa_Xb_YRy.in'' with X=10,20,30,40 and Y=1,2,3,4,5 Ry.

This is obviously quite tedious. However, you can automate both the input construction and code execution using bash or python scripts (indeed later you will learn how to use the the yambo-python [http://www.yambo-code.org/wiki/index.php?title=GW_tutorial._Convergence_and_approximations_(BN)]tool for this task). For now, you can use the simple [[bash_scripts|generate_inputs_1.sh]] bash script to generate the required input files (after copying the script you need to type <code>$ chmod +x name_of_the_script.sh </code>).

Finally launch the calculations:

$ yambo -F gw_ppa_10b_1Ry.in -J 10b_1Ry
$ yambo -F gw_ppa_10b_2Ry.in -J 10b_2Ry
...
$ yambo -F gw_ppa_40b_5Ry.in -J 40b_5Ry

Once the jobs are terminated we can collect the quasiparticle energies for fixed <code>[[Variables#BndsRnXp|BndsRnXp]]</code> in different files named e.g. ''10b.dat, 20b.dat'' etc. for plotting, by putting in separate columns: the energy cutoff; the size of the G blocks; the quasiparticle energy of the valence band; and that of the conduction band.
To do this e.g. for the ''10b.dat'' file you can type:
$ cat o-10b* | grep "8.000" | awk '{print $3+$4}'
to parse the valence band quasiparticle energies and
$ cat o-10b* | grep "9.000" | awk '{print $3+$4}'
for the conduction band; and put all the data in the ''10b.dat'' files. As there are many files to process you can use the [[bash_scripts|parse_qps.sh]] script to create the ''10b.dat'' file and edit the script changing the number of <code>[[Variables#BndsRnXp|BndsRnXp]]</code> for the other output files.

Once we have collected all the quasiparticle values we can plot the gap, or the valence and conduction band energies separately, as a function of the block size or energy cutoff:
$ gnuplot
gnuplot> p "10b.dat" u 1:3 w lp t " Valence BndsRnXp=10", "20b.dat" u 1:3 w lp t "Valence BndsRnXp=20",..
gnuplot> p "10b.dat" u 1:4 w lp t " Conduction BndsRnXp=10", "20b.dat" u 1:4 w lp t "Conduction BndsRnXp=20",..
gnuplot> p "10b.dat" u 1:($4-$3) w lp t " Gap BndsRnXp=10", "20b.dat" u 1:($4-$3) w lp t "gap BndsRnXp=20",..
or both using e.g. the [[gnuplot_scripts|ppa_gap.gnu]] gnuplot script:

<gallery mode=nolines widths=500px heights=500px perrow=1 caption="Quasiparticle energies with respect screening parameters">
File:ppa2.png|Valence band energy wrt <code>[[Variables#BndsRnXp|BndsRnXp]]</code> and <code>[[Variables#NGsBlkXp|NGsBlkXp]]</code>.
File:ppa3.png|Conduction band energy wrt <code>[[Variables#BndsRnXp|BndsRnXp]]</code> and <code>[[Variables#NGsBlkXp|NGsBlkXp]]</code>.
</gallery>

[[File:ppa1.png|center|600px|caption]]

Looking at the plot we can see that:
* The two parameters are not totally independent (see e.g. the valence quasiparticle convergence) and this is the reason why we converged them simultaneously
* The gap (energy difference) converge faster than single quasiparticle state
* The convergence criteria depends on the degree of accuracy we look for, but considering the approximations behind the calculations (plasmon-pole etc.), it is not always a good idea to enforce too strict a criteria.
* Even if not totally converged we can consider that the upper limit of <code>[[Variables#BndsRnXp|BndsRnXp]]</code>=30, and <code>[[Variables#NGsBlkXp|NGsBlkXp]]</code>=3Ry are reasonable parameters.

Finally notice that in the last versions of Yambo 4.5 etc. there is a terminator for the dielectric constant that accelerates convergence on the number of bands,
you can active it with the <code>-V resp</code> verbosity and setting <code>XTermKind= "BG"</code>. You can compare the converge of the dielectric constant with and without terminator,
similar to what happens for the self-energy, see next section.

====Converging the sum over states in the correlation self-energy====
From now on we will keep fixed these parameters and will perform a convergence study on the sum over state summation in the correlation self-energy (Σc) <code>[[Variables#GbndRnge|GbndRnge]]</code>.

In order to use the screening previously calculated we can copy the plasmon pole parameters saved in the <code>30b_3Ry</code> directory in the <code>SAVE</code> directory. In this way the screening will be read by Yambo and not calculated again:

$ cp ./30b_3Ry/ndb.pp* ./SAVE/.

(Note: you may have to delete these files before running the BSE tutorials)

In order to use the databases we have to be sure to have the same plasmon-pole parameters in our input files.
Edit ''gw_ppa_30b_3Ry.in'' and modify <code>[[Variables#GbndRnge|GbndRnge]]</code> to order to have a number of bands in the range from 10 to 80 inside different files named ''gw_ppa_Gbnd10.in'', ''gw_ppa_Gbnd20.in'' etc. You can also run the the [[bash_scripts|generate_inputs_2.sh]] bash script to generate the required input files.

Next, launch yambo for each input:

$ yambo -F gw_ppa_Gbnd10.in -J Gbnd10
$ yambo -F gw_ppa_Gbnd20.in -J Gbnd20
...

and as done before we can inspect the obtained quasiparticle energies:

$ grep 8.00 o-Gbnd* | awk '{print $4+$5}'
for the valence bands, and
$ grep 9.00 o-Gbnd* | awk '{print $4+$5}'
for the conduction band.

Collect the results in a text file ''Gbnd_conv.dat'' containing: the number of Gbnd, the valence energy, and the conduction energy.
Now, as done before we can plot the valence and conduction quasiparticle levels separately as well as the gap, as a function of the number of bands used in the summation:

$ gnuplot
gnuplot> p "Gbnd_conv.dat" u 1:2 w lp lt 7 t "Valence"
gnuplot> p "Gbnd_conv.dat" u 1:3 w lp lt 7 t "Conduction"
gnuplot> p "Gbnd_conv.dat" u 1:($3-$2) w lp lt 7 t "Gap"

<gallery mode=nolines widths=500px heights=500px perrow=2 caption="Quasiparticle energies with respect sum over states in correlation self-energy">
File:Gbnd_val.png|Valence band energy wrt <code>[[Variables#GbndRange|GbndRange]]</code>.
File:Gbnd_cond.png|Conduction band energy wrt <code>[[Variables#GbndRange|GbndRange]]</code>
</gallery>

[[File:Gbnd_gap.png|center|600px|caption]]

Inspecting the plot we can see that:
* The convergence with respect to <code>[[Variables#GbndRange|GbndRange]]</code> is rather slow and many bands are needed to get converged results.
* As observed above the gap (energy difference) converges faster than the single quasiparticle state energies.

====Accelerating the sum over states convergence in the correlation self-energy====
In general the convergence with respect the sum over states can be very cumbersome. Here we show how it can be mitigated by using
a technique developed by F. Bruneval and X. Gonze <ref name="BG"> F. Bruneval and X. Gonze, Physical Review B 78, 085125 (2008 )</ref>. The basic idea relies in replacing the eigenenergies of the states that are not treated explicitly by a common energy, and take into account all the states, which are not explicitly included in the calculation through the closure relation.
To apply this technique in Yambo we need to activate the optional terminator variable [[Variables#GTermKind|GTermKind]]. We can activate it by adding the quasiparticle verbosity to the command line when generating the input file:

$ yambo -p p -g n -F gw_ppa_Gbnd10.in -V qp

and you can edit the input file by setting:

[[Variables#GTermKind|GTermKind]]= "BG"

or simply you can add by hand this line in all the other ''gw_ppa_GbndX.in'' input files.
Now we can repeat the same calculations

$ yambo -F gw_ppa_Gbnd10.in -J Gbnd10_term
$ yambo -F gw_ppa_Gbnd20.in -J Gbnd20_term
...

and collect the new results:

$ grep 8.000 *term.qp | awk '{print $4+$5}'
$ grep 9.000 *term.qp | awk '{print $4+$5}'

in a new file called ''Gbnd_conv_terminator.dat''. Now we can plot the same quantities as before by looking at the effect of having introduced the terminator.

gnuplot
gnuplot> p "Gbnd_conv.dat" u 1:2 w lp t "Valence", "Gbnd_conv_terminator.dat" u 1:2 w lp t "Valence with terminator"
gnuplot> p "Gbnd_conv.dat" u 1:3 w lp t "Conduction", "Gbnd_conv_terminator.dat" u 1:3 w lp t "Conduction with terminator"
gnuplot> p "Gbnd_conv.dat" u 1:($3-$2) w lp t "Gap", "Gbnd_conv_terminator.dat" u 1:($3-$2) w lp t "Gap with terminator"

<gallery mode=nolines widths=500px heights=500px perrow=2 caption="Effect of the terminator in convergence of QP energies with respect sum over states">
File:val_t.png|Valence band energy wrt <code>[[Variables#GbndRange|GbndRange]]</code> with and without the terminator technique <ref name="BG" />
File:cond_t.png|Conduction band energy wrt <code>[[Variables#GbndRange|GbndRange]]</code> with and without the terminator technique<ref name="BG" />
</gallery>

[[File:gap_t.png|center|600px|caption]]

We can see that:
* The convergence with respect to <code>[[Variables#GbndRange|GbndRange]]</code> is accelerated in particular for the single quasiparticle states.
* From the plot above we can see that <code>[[Variables#GbndRange|GbndRange]]</code>=40 is sufficient to have a converged gap

===Beyond the plasmon pole approximation: a full frequency approach - real axis integration===
All the calculations performed up to now were based on the plasmon pole approximation (PPA). Now we remove this approximation by evaluating numerically the frequency integral in the expression of the correlation self-energy (Σc). To this aim we need to evaluate the screening for a number of frequencies in the interval depending on the electron-hole energy difference (energy difference between empty and occupied states) entering in the sum over states.
Let's build the input file for a full frequency calculation by simply typing:

$ yambo -F gw_ff.in -g n

and we can set the variable studied up to now at their converged value:

%[[Variables#BndsRnXd|BndsRnXd]]
1 | 30 |
%
[[Variables#NGsBlkXd|NGsBlkXd]]=3 Ry
%[[Variables#GbndRange|GbndRange]]
1 | 40 |
%
[[Variables#EXXRLvcs|EXXRLvcs]]=40 Ry
% [[Variables#LongDrXd|LongDrXd]]
1.000000 | 1.000000 | 1.000000 | # [Xd] [cc] Electric Field
%
%QPkrange # # [GW] QP generalized Kpoint/Band indices
7|7|8|9|
%

and next vary in different files (name them ''gw_ff10.in'' etc.) the number of frequencies we evaluate for the screened coulomb potential. This is done by setting the values of [[Variables#ETStpsXd|ETStpsXd]]=10 , 50 , 100, 150, 200, 250.
You can also run the the [[bash_scripts|generate_inputs_3.sh]] bash script to generate the required input files.

Next launch yambo:
$ yambo -F gw_ff10.in -J ff10
$ yambo -F gw_ff50.in -J ff50
...

Clearly as we are evaluating the screening for a large number of frequencies these calculations will be heavier than the case above where the calculation of the screening was done for only two frequencies (zero and plasmon-pole).
As before, collect the valence and conduction bands as a function of the number of frequencies in a file called ''gw_ff.dat'' and plot the behaviour of the conduction and valence bands and the gap.

$ gnuplot
gnuplot> p "gw_ff.dat" u 1:2 w lp t "Valence"
gnuplot> p "gw_ff.dat" u 1:3 w lp t "Conduction"
gnuplot> p "gw_ff.dat" u 1:($3-$2) w lp t "Gap"

<gallery mode=nolines widths=500px heights=500px perrow=2 caption="Real axis integration, convergences with respect the used number of frequencies">
File:ff_v.png|Valence band energy wrt <code>[[Variables#ETStpsXd|ETStpsXd]]</code>
File:ff_c.png|Conduction band energy wrt <code>[[Variables#ETStpsXd|ETStpsXd]]</code>
</gallery>

[[File:ff_g.png|center|600px|caption]]

We can see that:

* Oscillations are still present, indicating that even more frequencies have to be considered. In general, a real-axis calculation is very demanding.
* The final result of the gap obtained up to now does not differ too much from the one obtained at the plasmon-pole level (~50 meV)

===Secant Solver===

The real axis integration permits also to go beyond the linear expansion to solve the quasi particle equation.
The QP equation is a non-linear equation whose solution must be found using a suitable numerical algorithm.
[[File:Eqp_sec.png|none|x22px|caption]]
The mostly used, based on the linearization of the self-energy operator is the Newton method that is the one we have used up to now.
Yambo can also perform a search of the QP energies using a non-linear iterative method based on the [https://en.wikipedia.org/wiki/Secant_method Secant iterative Method].

In numerical analysis, the secant method is a root-finding algorithm that uses a succession of roots of secant lines to better approximate a root of a function ''f''. The secant method can be thought of as a finite difference approximation of Newton's method.
The equation that defines the secant method is:

[[File:secant_eq.png|none|x35px|caption]]

The first two iterations of the secant method are shown in the following picture. The red curve shows the function f and the blue lines are the secants.

[[File:Secant_method.png|center|250px|caption]]

To see if there is any non-linear effect in the solution of the Dyson equation we compare the result of the calculation using the Newton solver as done before with the present case.
In order to use the secant method you need to edit one of the the previous ''gw_ffN.in'' files e.g. ''gw_ff100.in'' and substitute:

DysSolver= "g"
to
DysSolver= "s"

Repeat the calculations in the same way as before:

$ yambo -F gw_ff100.in -J ff100

Note than now the screening will ''not'' be calculated again as it has been stored in the ''ffN'' directories as can be seen in the report file:

[05] Dynamical Dielectric Matrix
================================
[RD./ff10//ndb.em1d]----
...
[RD./ff10//ndb.em1d_fragment_1]--------------
...

Comparing the output files, e.g. for the case with 100 freqs:

''o-ff100.qp'' '''Newton Solver:'''
# K-point Band Eo E-Eo Sc|Eo
#
7.00000 8.00000 -0.41188 -0.08708 2.91254
7.00000 9.00000 3.877976 1.421968 -3.417357

''o-ff100.qp_01'' '''Secant Solver:'''
#
# K-point Band Eo E-Eo Sc|Eo
#
7.00000 8.00000 -0.41188 -0.08715 2.93518
7.00000 9.00000 3.877976 1.401408 -3.731649

From the comparison, we see that the effect is of the order of 20 meV, of the same order of magnitude of the accuracy of the GW calculations.

==Step 3: Interpolating Band Structures==
Up to now we have checked convergence for the gap. Now we want to calculate the quasiparticle corrections across the Brillouin zone in order to visualize the entire band structure along a path connecting high symmetry points.

To do that we start by calculating the QP correction in the plasmon-pole approximation for all the k points of our sampling and for a number of bands around the gap. You can use a previous input file or generate a new one: <code> yambo -F gw_ppa_all_Bz.in -x -p p -g n </code> and set the parameters found in the previous tests:

EXXRLvcs= 40 Ry
% BndsRnXp
1 | 30 | # [Xp] Polarization function bands
%
NGsBlkXp= 3 Ry # [Xp] Response block size
% LongDrXp
1.000000 | 1.000000 | 1.000000 | # [Xp] [cc] Electric Field
%
PPAPntXp= 27.21138 eV # [Xp] PPA imaginary energy
% GbndRnge
1 | 40 | # [GW] G[W] bands range
%

and we calculate it for all the available kpoints by setting:
%QPkrange # [GW] QP generalized Kpoint/Band indices
1| 14| 6|11|
%

Note that as we have already calculated the screening with these parameters you can save time and use that database either by running in the previous directory by using <code> -J 30b_3Ry </code> or if you prefer to put the new databases in the new all_Bz directory you can create a new directory and copy there the screening databases:

$ mkdir all_Bz
$ cp ./30b_3Ry/ndb.pp* ./all_Bz/

and launch the calculation:

$ yambo -F gw_ppa_all_Bz.in -J all_Bz

Now we can inspect the output and see that it contains the correction for all the k points for the bands we asked:

# K-point Band Eo E-Eo Sc|Eo
#
1.000000 6.000000 -1.299712 -0.219100 3.788044
1.000000 7.000000 -1.296430 -0.241496 3.788092
1.000000 8.000000 -1.296420 -0.243115 3.785947
1.000000 9.000000 4.832399 0.952386 -3.679259
1.00000 10.00000 10.76416 2.09915 -4.38743
1.00000 11.00000 11.36167 2.48053 -3.91021
....
By plotting some of the 'o-all_Bz.qp" columns it is possible to discuss some physical properties of the hBN QPs. Using columns 3 and (3+4), ie plotting the GW energies with respect to the LDA energies we can deduce the band gap renormalization and the stretching of the conduction/valence bands:

$ gnuplot
gnuplot> p "o-all_Bz.qp" u 3:($3+$4) w p t "Eqp vs Elda"

[[File:EqpvE0.png|center|350px|caption]]

Essentially we can see that the effect of the GW self-energy is the opening of the gap and a linear stretching of the conduction/valence bands that can be estimated by performing a linear fit of the positive and negative energies (the zero is set at top of the valence band).

In order to calculate the band structure, however, we need to interpolate the values we have calculated above on a given path. In Yambo the interpolation is done by the executable <code>ypp</code> (Yambo Post Processing).
By typing:
$ ypp -H
you will recognize that in order to interpolate the bands we need to build a ypp input file using
$ ypp -s b

we can generate the input for the band interpolation:

$ypp -s b -F ypp_bands.in

and edit the ''ypp_bands.in'' file:

electrons # [R] Electrons (and holes)
bnds # [R] Bands
INTERP_mode= "NN" # Interpolation mode (NN=nearest point, BOLTZ=boltztrap aproach)
OutputAlat= 4.716000 # [a.u.] Lattice constant used for "alat" ouput format
cooIn= "rlu" # Points coordinates (in) cc/rlu/iku/alat
cooOut= "rlu"
% BANDS_bands
1 | 100 | # Number of bands
%
% INTERP_Grid
-1 |-1 |-1 | # Interpolation BZ Grid
%
INTERP_Shell_Fac= 20.00000 # The bigger it is a higher number of shells is used
CIRCUIT_E_DB_path= "none" # SAVE obtained from the QE `bands` run (alternative to %BANDS_kpts)
BANDS_path= "" # BANDS path points labels (G,M,K,L...)
BANDS_steps= 10
#BANDS_built_in # Print the bands of the generating points of the circuit using the nearest internal point
%BANDS_kpts
%

We modify the following lines:
BANDS_steps=30
% BANDS_bands
6 | 11 | # Number of bands
%
%BANDS_kpts # K points of the bands circuit
0.33300 |-.66667 |0.00000 |
0.00000 |0.00000 |0.00000 |
0.50000 |-.50000 |0.00000 |
0.33300 |-.66667 |0.00000 |
0.33300 |-.66667 |0.50000 |
0.00000 |0.00000 |0.50000 |
0.50000 |-.50000 |0.50000 |
%

which means we assign 30 points in each segment, we ask to interpolate 3 occupied and 3 empty bands and we assign the following path passing from the high symmetry points: K Γ M K H A L.
Launching:
$ ypp -F ypp_bands.in
will produce the output file ''o.bands_interpolated'' containing:

#
# |k| b6 b7 b8 b9 b10 b11 kx ky kz
#
#
0.00000 -7.22092 -0.13402 -0.13395 4.67691 4.67694 10.08905 0.33300 -0.66667 0.00000
0.03725 -7.18857 -0.17190 -0.12684 4.66126 4.71050 10.12529 0.32190 -0.64445 0.00000
...

and we can plot the bands using gnuplot:
$ gnuplot
gnuplot> p "o.bands_interpolated" u 0:2 w l, "o.bands_interpolated" u 0:3 w l, ...

[[File:bands_lda.png|center|350px|caption]]

and you can recognize the index of the high symmetry point by inspecting the last three columns.
Note that up to now we have interpolated the LDA band structure. In order to plot the GW band structure, we need to tell <code>ypp</code> in the input file where the ''ndb.QP'' database is found. This is achieved by adding in the ''ypp_bands.in'' file the line:

GfnQPdb= "E < ./all_Bz/ndb.QP"

and relaunch

$ ypp -F ypp_bands.in

Now the file ''o.bands_interpolated_01'' contains the GW interpolated band structure. We can plot the LDA and GW band structure together by using the gnuplot script [[gnuplot_scripts|bands.gnu]].

<gallery mode=nolines widths=500px heights=500px perrow=2 caption="Band strcuture of bulk hBN">
File:hBN_bands.png| LDA and GW bands structure
File:hBN_bands_lit.png| LDA and GW bands structure from Ref. <ref name="Arnaud" />
</gallery>

*As expected the effect of the GW correction is to open the gap.
*Comparing the obtained band structure with the one found in the literature by Arnaud and coworkers <ref name="Arnaud"> B. Arnaud, S. Lebegue,P. Rabiller, and M. Alouani Phys, Rev. Lett. 96, 026402 (2006)</ref> we found a very nice qualitative agreement.
*Quantitatively we found a smaller gap: about 5.2 eV (indirect gap), 5.7 eV (direct gap) while in Ref.<ref name="Arnaud" /> is found 5.95 eV for the indirect gap and a minimum direct band gap of 6.47 eV. Other values are also reported in the literature depending on the used pseudopotentials, starting functional and type of self-consistency (see below).
*The present tutorial has been done with a small k point grid which is an important parameter to be checked, so convergence with respect the k point sampling has to be validated.

==Step 4: Summary of the convergence parameters==
We have calculated the band structure of hBN starting from a DFT calculation, here we summarize the main variable we have checked to achieve convergence:

* <code>[[Variables#EXXRLvcs|EXXRLvcs]]</code> # [XX] Exchange RL components
Number of G-vectors in the exchange. This number should be checked carefully. Generally a large number is needed as the QP energies show a slow convergence. The calcualtion of the exchange part is rather fast.

*<code>[[Variables#BndsRnXp|BndsRnXp]]</code> #[Xp] Polarization function bands
Number of bands in the independent response function form which the dielectric matrix is calculated. Also this paramater has to be checked carefully,together with NGsBlkXp as the two variables are interconnected

*<code>[[Variables#NGsBlkXp|NGsBlkXp]]</code> # [Xp] Response block size
Number of G-vectors block in the dielectric constant. Also this paramater has to be checked carefully, to be checked together with BndsRnXp. A large number of bands and block can make the calculation very demanding.

*<code>[[Variables#LongDrXp|LongDrXp]] </code> # [Xp] [cc] Electric Field
Direction of the electric field for the calculation of the q=0 component of the dielectric constant e(q,w). In a bulk can be set to (1,1,1), attention must be paid for non 3D systems.

*<code>[[Variables#PPAPntXp|PPAPntXp]] </code> # [Xp] Plasmon pole imaginary energy: this is the second frequency used to fit the Godby-Needs plasmon-pole model (PPM). If results depend consistently by changing this frequency, the PPM is not adequate for your calculation and it is need to gp beyond that, e.g. Real-axis.

*<code>[[Variables#GbndRnge|GbndRnge]] </code> # [GW] G[W] bands range
Number of bands used to expand the Green's function. This number is usually larger than the number of bands used to calculated the dielectricconstant. Single quasiparticle energies converge slowly with respect GbndRnge, energy difference behave better. You can use terminator technique to mitigate the slow dependence.

*<code>[[Variables#GDamping|GDamping]] </code> # [GW] G[W] damping
Small damping in the Green's function definition, the delta
parameter. The final result shouuld not depend on that, usually set at 0.1 eV

*<code>[[Variables#dScStep|dScStep]] </code> # [GW]
Energy step to evaluate Z factors

*<code>[[Variables#DysSolver|DysSolver]] </code> # [GW] Dyson Equation solver ("n","s","g")
Parameters related to the solution of the Dyson equation, "n" Newton linearization, 's' non linear secant method

*<code>[[Variables#GTermKind|GTermKind]] </code> [GW] GW terminator
Terminator for the self-energy<ref name="BG" /> . We have seen how this spped up the convergence with respect empty bands.

*<code>[[Variables#%QPkrange |QPkrange ]] </code> # [GW] QP generalized Kpoint/Band indices
K-points and band range where you want to calculate the GW correction. The syntax is
first kpoint | last kpoint | first band | last band

==Step 5: Eigenvalue only self-consistent evGW0 and evGW (only available in Yambo 4.6) ==
Here we want to see how we can compute an eigenvalue only evGW0 or evGW correction in Yambo. In the new version of Yambo there are two flags for these kind of self-consistency:

<code>[[Variables#GWoIter|GWoIter]]</code> number of GW0 iterations

<code>[[Variables#GWoIter|GWIter]]</code> number of GW iterations

you can set one of them to 10 for example, the code will stop when convergence is reached, usually in less than 5 iterations.
For example if you consider the input file below:

HF_and_locXC # [R XX] Hartree-Fock Self-energy and Vxc
ppa # [R Xp] Plasmon Pole Approximation
gw0 # [R GW] GoWo Quasiparticle energy levels
em1d # [R Xd] Dynamical Inverse Dielectric Matrix
EXXRLvcs = 40.000 mRy # [XX] Exchange RL components
VXCRLvcs = 3187 RL # [XC] XCpotential RL components
Chimod= "Hartree" # [X] IP/Hartree/ALDA/LRC/BSfxc
% BndsRnXp
1 | 10 | # [Xp] Polarization function bands
%
NGsBlkXp= 1000 mRy # [Xp] Response block size
% LongDrXp
1.000000 | 1.000000 | 1.000000 | # [Xp] [cc] Electric Field
%
PPAPntXp = 27.21138 eV # [Xp] PPA imaginary energy
%GbndRnge
1 | 40 | # [GW] G[W] bands range
%
GDamping= 0.10000 eV # [GW] G[W] damping
dScStep= 0.10000 eV # [GW] Energy step to evaluate Z factors
DysSolver= "n" # [GW] Dyson Equation solver ("n","s","g")
GWoIter=0 # [GW] GWo self-consistent (evGWo) iterations on eigenvalues
GWIter =0 # [GW] GW self-consistent (evGW) iterations on eigenvalues
%QPkrange # [GW] QP generalized Kpoint/Band indices
1| 14| 7| 10|
%
if you set both GWIter and GWoIter to zero you get a gap correction of 4.15 eV.
If you perform self-consistency on G (GWoIter/=)
the gap will be 4.713 eV and finally if you perform
self-consistency in both G and W (GWIter /=0) the gap will be 5.506 eV.

Notice that these values are absolutelly not converged because we used very few
bands and a small block size.

It's important to note that the final result of the self-consistent GW may
depend from the number of bands you decide to correct, because they are used
to reconstruct G and W. For the non-corrected bands Yambo applied a rigid shift
of their energy based on the closed corrected band.

==Step 6: A better integration of the q=0 point ==

The integration of the q=0 of the Coulomb potential is problematic because the 1/q diverges.
Usually in Yambo this integration is performed analytically in a small sphere around q=0.

[[File:Circle box.gif|center|frame]]

however in this way the code lost part of the integral out of the circle. This usually
is not problematic because for a large number of q and k point the missing term goes to zero.
However in system that requires few k-points or even only the gamma one, it is possible
to perform a better integration of this term by adding the flag -r to generate the input

HF_and_locXC # [R XX] Hartree-Fock Self-energy and Vxc
ppa # [R Xp] Plasmon Pole Approximation
gw0 # [R GW] GoWo Quasiparticle energy levels
rim_cut # [R] Coulomb potential
em1d # [R Xd] Dynamical Inverse Dielectric Matrix
RandQpts= 3000000 # [RIM] Number of random q-points in the BZ
RandGvec= 1 RL # [RIM] Coulomb interaction RS components
#QpgFull # [F RIM] Coulomb interaction: Full matrix
EXXRLvcs = 40.000 mRy # [XX] Exchange RL components
VXCRLvcs = 3187 RL # [XC] XCpotential RL components
Chimod= "Hartree" # [X] IP/Hartree/ALDA/LRC/BSfxc
% BndsRnXp
1 | 10 | # [Xp] Polarization function bands
%
NGsBlkXp= 1000 mRy # [Xp] Response block size
% LongDrXp
1.000000 | 1.000000 | 1.000000 | # [Xp] [cc] Electric Field
%
PPAPntXp = 27.21138 eV # [Xp] PPA imaginary energy
%GbndRnge
1 | 40 | # [GW] G[W] bands range
%
GDamping= 0.10000 eV # [GW] G[W] damping
dScStep= 0.10000 eV # [GW] Energy step to evaluate Z factors
DysSolver= "n" # [GW] Dyson Equation solver ("n","s","g")
%QPkrange # [GW] QP generalized Kpoint/Band indices
7| 7| 8| 9|
%

in this input <code>[[Variables#RandGvec|RandGvec]]</code> is the component of the Coulomb potential we want integrate numerically,
in this case only the first one G=G'=0, and <code>[[Variables#RandQpts|RandQpts]]</code> is the number of random points
used to perform the integral by Monte Carlo.

If you turn one this integration you will get a slightly different band gap,
but in the limit of large k points the final results will be the same of the standard method.

However this correction is important for systems that converge with few k-points or with gamma only.

==Step 7: Taking into account the material anisotropy (only available in Yambo 4.6) ==

Hexagonal Boron Nitride is an anisotropic material so there is the question in which direction
one shold calculate the dielectric constant the enters in the GW.
If you run again this tutorial changing the direction of the q=0 point in GW calculation,
the variable <code>[[Variables#LongDrXp|LongDrXp]]</code>, you will realize that the there gap correction changes.
In Yambo there is a way to take into account this anisitropy of the dielectri tensor.

First of all you need to calculate the dielectric constant in the three cartesian directions with the command <code> yambo -o c -k hartree</code>

optics # [R] Linear Response optical properties
kernel # [R] Kernel
chi # [R][CHI] Dyson equation for Chi.
dipoles # [R] Oscillator strenghts (or dipoles)
Chimod= "HARTREE" # [X] IP/Hartree/ALDA/LRC/PF/BSfxc
NGsBlkXd= 3000 mRy # [Xd] Response block size
% QpntsRXd
1 | 1 | # [Xd] Transferred momenta
%
% BndsRnXd
1 | 100 | # [Xd] Polarization function bands
%
% EnRngeXd
0.00000 | 10.00000 | eV # [Xd] Energy range
%
% DmRngeXd
0.10000 | 0.10000 | eV # [Xd] Damping range
%
ETStpsXd= 1 # [Xd] Total Energy steps
% LongDrXd
1.000000 | 0.000000 | 0.000000 | # [Xd] [cc] Electric Field
%

From the result in the output file <code> o.eps_q1_inv_rpa_dyson</code> you can calculate the zero component of inverse dielectric matrix, in this case 1.0/5.044076 = 0.198252.

Repeat this calculation with the field in the other two directions y and z. The y-direction is equal to x, while in z direction the zero component of the inverse dielectric matrix is 1.0/2.872451 = 0.348134.

Now generate a new input file for the GW, with the command <code> yambo -g n -p p -r -V RL</code>

HF_and_locXC # [R XX] Hartree-Fock Self-energy and Vxc
ppa # [R Xp] Plasmon Pole Approximation
gw0 # [R GW] GoWo Quasiparticle energy levels
rim_cut # [R] Coulomb potential
em1d # [R Xd] Dynamical Inverse Dielectric Matrix
RandQpts=3000000 # [RIM] Number of random q-points in the BZ
RandGvec= 1 RL # [RIM] Coulomb interaction RS components
#QpgFull # [F RIM] Coulomb interaction: Full matrix
% Em1Anys
 0.198252 | 0.198252 | 0.348134 | # [RIM] X Y Z Static Inverse dielectric matrix
%
IDEm1Ref= 1
EXXRLvcs = 40.000 mRy # [XX] Exchange RL components
VXCRLvcs = 3187 RL # [XC] XCpotential RL components
Chimod= "Hartree" # [X] IP/Hartree/ALDA/LRC/BSfxc
% BndsRnXp
1 | 10 | # [Xp] Polarization function bands
%
NGsBlkXp= 1000 mRy # [Xp] Response block size
% LongDrXp
1.000000 | 0.000000 | 0.000000 | # [Xp] [cc] Electric Field
%
PPAPntXp = 27.21138 eV # [Xp] PPA imaginary energy
%GbndRnge
1 | 40 | # [GW] G[W] bands range
%
GDamping= 0.10000 eV # [GW] G[W] damping
dScStep= 0.10000 eV # [GW] Energy step to evaluate Z factors
DysSolver= "n" # [GW] Dyson Equation solver ("n","s","g")
%QPkrange # [GW] QP generalized Kpoint/Band indices
7| 7| 8| 9|
%

run the calculations and you will find a correction of the gap intermediate between the one with the field in x and z directions.

==Step 8: Exercise: Convergence with respect K points==
As an exercise now you can check the convergence with respect the K point sampling:
# perform a new non-scf calculation with a bigger k point grid: 9x9x3 and 12x12x4 ...
# convert wave functions and electronic structure to Yambo databases in a different directory as explained in the [[Bulk material: h-BN|DFT and p2y module]],
# [[initialization |Initialize]] the Yambo databases,
# Redo the steps explained in this section (exchange self energy, plasmon pole GW, band structure interpolation)
# The PPA-GW calculation using 12x12x4 grid depending on your machine can take several minutes in serial mode. You can think to perform the exercise after having learned some basic on the parallelization strategy.

 
{| style="width:100%" border="1"
|style="width:15%; text-align:left"|Prev: [[Tutorials|Tutorials Home]]
|style="width:50%; text-align:center"|Now: [[Tutorials|Tutorials Home]] --> [[How_to_obtain_the_quasi-particle_band_structure_of_a_bulk_material:_h-BN|GW]]
|style="width:35%; text-align:right"|Next: If you did everything, choose another tutorial in the menu
|-
|}

==References==

How to obtain the quasi-particle band structure of a bulk material: h-BN

2020-11-19T13:44:22Z

Claudio: /* Step 7: Taking into account the material anisotropy (only available in Yambo 4.6) */

In this tutorial you will learn how to:
* Calculate quasi-particle corrections in the Hartree-Fock approximation
* Calculate quasi-particle corrections in the GW approximation
* Choose the input parameters for a meaningful converged calculation
* Plot a band structure including quasi-particle corrections
We will use bulk hBN as an example system. Before starting, you need to obtain the appropriate tarball. See instructions on the [[Tutorials|main tutorials page]]. 
We strongly recommend that you first complete the [[First steps: a walk through from DFT to optical properties]] tutorial.



The aim of the present tutorial is to obtain quasiparticle correction to energy levels using many-body perturbation theory (MBPT). 
The general non-linear quasiparticle equation reads:
[[File:Eqp_1.png|none|x26px|caption]]
As a first step we want to evaluate the self energy Σ entering in the quasiparticle equation. In the GW approach the self-energy can be separated into two components: a static term called the exchange self-energy (Σx), and a dynamical term (energy dependent) called the correlation self-energy (Σc):
[[File:Sigma.png|none|x25px|caption]]
We will treat these two terms separately and demonstrate how to set the most important variables for calculating each term.
In practice we will compute the quasi-particle corrections to the one particle Kohn-Sham eigenvalues obtained through a DFT calculation.

The steps are the following:

==Step 1: The Exchange Self Energy or HF quasi-particle correction==

We start by evaluating the exchange Self-Energy and the corresponding Quasiparticle energies (Hartree-Fock energies).
Follow the module on '''[[Hartree Fock]]''' and then return to this tutorial ''How to obtain the quasiparticle band structure of a bulk material: h-BN''.

==Step 2: The Correlation Self-Energy and Quasiparticle Energies==
Once we have calculated the exchange part, we next turn our attention to the more demanding dynamical part. The correlation part of the self-energy in a plane wave representation reads:
[[File:Sigma_c.png|none|x50px|caption]]
In the expression for the correlation self energy, we have (1) a summation over bands, (2) an integral over the Brillouin Zone, and (3) a sum over the G vectors. In contrast with the case of Σx, the summation over bands extends over ''all'' bands (including the unoccupied ones), and so convergence tests are needed. Another important difference is that the Coulomb interaction is now screened so a fundamental ingredient is the evaluation of the dynamical dielectric matrix. The expression for the dielectric matrix, calculated at the RPA level and including local field effects, has been already treated in the [[Local fields|Local fields]] tutorial.

In the following, we will see two ways to take into account the dynamical effects. First, we will see how to set the proper parameters to obtain a model dielectric function based on a widely used approximation, which models the energy dependence of each component of the dielectric matrix with a single pole function.
Secondly, we will see how to perform calculations by evaluating the dielectric matrix on a regular grid of frequencies.

Once the correlation part of the self-energy is calculated, we will check the convergence of the different parameters with respect to some final quantity, such as the gap.

After computing the frequency dependent self-energy, we will discover that in order to solve the quasiparticle equation we will need to know its value ''at the value of the quasiparticle itself''. In the following, unless explicitly stated, we will solve the non-linear quasi-particle equation at first order, by expanding the self-energy around the Kohn-Sham eigenvalue. In this way the quasiparticle equation reads:

[[File:Eqp_2.png|none|x26px|caption]]

where the normalization factor Z is defined as:

[[File:z_fac.png|none|x40px|caption]]

===The Plasmon Pole approximation===
As stated above, the basic idea of the plasmon-pole approximation is to approximate the frequency dependence of the dielectric matrix with a single pole function of the form:
[[File:ppa.png|none|x26px|caption]]
The two parameters RGG' and ΩGG' are obtained by a fit (for each component), after having calculated the RPA dielectric matrix at two given frequencies.
Yambo calculates the dielectric matrix in the static limit ( ω=0) and at a user defined frequency called the plasmon-pole frequency (ω=iωp).
Such an approximation has the big computational advantage of calculating the dielectric matrix for only two frequencies and leads to an analytical expression for the frequency integral of the correlation self-energy.
==== Input file generation ====
Let's start by building up the input file for a GW/PPA calculation, including the calculation of the exchange self-energy. From <code>yambo -H</code> you should understand that the correct option is <code>yambo -x -p p -g n</code>:

$ cd YAMBO_TUTORIALS/hBN/YAMBO
$ yambo -x -p p -g n -F gw_ppa.in

Let's modify the input file in the following way:

HF_and_locXC # [R XX] Hartree-Fock Self-energy and Vxc
ppa # [R Xp] Plasmon Pole Approximation
gw0 # [R GW] GoWo Quasiparticle energy levels
em1d # [R Xd] Dynamical Inverse Dielectric Matrix
[[Variables#EXXRLvcs|EXXRLvcs]] = 40 Ry # [XX] Exchange RL components
[[Variables#VXCRLvcs|VXCRLvcs]] = 3187 RL # [XC] XCpotential RL components
Chimod= "Hartree" # [X] IP/Hartree/ALDA/LRC/BSfxc
% BndsRnXp
1 | 10 | # [Xp] Polarization function bands
%
[[Variables#NGsBlkXp|NGsBlkXp]]= 1000 mRy # [Xp] Response block size
% LongDrXp
1.000000 | 1.000000 | 1.000000 | # [Xp] [cc] Electric Field
%
[[Variables#PPAPntXp|PPAPntXp]] = 27.21138 eV # [Xp] PPA imaginary energy
%[[Variables#GbndRnge|GbndRnge]]
1 | 40 | # [GW] G[W] bands range
%
GDamping= 0.10000 eV # [GW] G[W] damping
dScStep= 0.10000 eV # [GW] Energy step to evaluate Z factors
DysSolver= "n" # [GW] Dyson Equation solver ("n","s","g")
%[[Variables#QPkrange|QPkrange]] # [GW] QP generalized Kpoint/Band indices
7| 7| 8| 9|
%

Brief explanation of some settings:
* Similar to the Hartree Fock study, we will concentrate on the convergence of the '''direct''' gap of the system. Hence we select the last occupied (8) and first unoccupied (9) bands for k-point number 7 in the <code>[[Variables#QPkrange|QPkrange]]</code> variable.
* We also keep <code>[[Variables#EXXRLvcs|EXXRLvcs]]</code> at its converged value of 40 Ry as obtained in the '''[[Hartree Fock]]''' tutorial.
* For the moment we keep fixed the plasmon pole energy <code>[[Variables#PPAPntXp|PPAPntXp]]</code> at its default value (=1 Hartree).
* We keep fixed the direction of the electric field for the evaluation of the dielectric matrix to a non-specific value: <code>[[Variables#LongDrXp|LongDrXp]]</code>=(1,1,1).
* Later we will study convergence with respect to <code>[[Variables#GbndRnge|GbndRnge]]</code>, <code>[[Variables#NGsBlkXp|NGsBlkXp]]</code>, and <code>[[Variables#BndsRnXp|BndsRnXp]]</code>; for now just set them to the values indicated.

==== Understanding the output ====
Let's look at the typical Yambo output. Run Yambo with an appropriate <code>-J</code> flag:

$ yambo -F gw_ppa.in -J 10b_1Ry

In the standard output you can recognise the different steps of the calculations: calculation of the screening matrix (evaluation of the non interacting and interacting response), calculation of the exchange self-energy, and finally the calculation of the correlation self-energy and quasiparticle energies. Moreover information on memory usage and execution time are reported:
...
<---> [05] Dynamic Dielectric Matrix (PPA)
...
<08s> Xo@q[3] |########################################| [100%] 03s(E) 03s(X)
<08s> X@q[3] |########################################| [100%] --(E) --(X)
...
<43s> [06] Bare local and non-local Exchange-Correlation
<43s> EXS |########################################| [100%] --(E) --(X)
...
<43s> [07] Dyson equation: Newton solver
<43s> [07.01] G0W0 (W PPA)
...
<45s> G0W0 (W PPA) |########################################| [100%] --(E) --(X)
...
<45s> [07.02] QP properties and I/O
<45s> [08] Game Over & Game summary

Let's have a look at the report and output. The output file ''o-10b_1Ry.qp'' contains (for each band and k-point that we indicated in the input file) the values of the bare KS eigenvalue, its GW correction and the correlation part of the self energy:
#
# K-point Band Eo E-Eo Sc|Eo
#
7.000000 8.000000 -0.411876 -0.567723 2.322443
7.000000 9.000000 3.877976 2.413773 -2.232241

In the header you can see the details of the calculations, for instance it reports that <code>[[Variables#NGsBlkXp|NGsBlkXp]]</code>=1 Ry corresponds to 5 Gvectors:

# X G`s [used]: 5

Other information can be found in the report file ''r-10b_1Ry_em1d_ppa_HF_and_locXC_gw0'', such as the renormalization factor defined above, the value of the ''exchange'' self-energy (non-local XC) and of the DFT exchange-correlation potential (local XC):

[07.02] QP properties and I/O
=============================
Legend (energies in eV):
- B : Band - Eo : bare energy
- E : QP energy - Z : Renormalization factor
- So : Sc(Eo) - S : Sc(E)
- dSp: Sc derivative precision
- lXC: Starting Local XC (DFT)
-nlXC: Starting non-Local XC (HF)
QP [eV] @ K [7] (iku): 0.000000 -0.500000 0.000000
B=8 Eo= -0.41 E= -0.98 E-Eo= -0.56 Re(Z)=0.81 Im(Z)=-.2368E-2 nlXC=-19.13 lXC=-16.11 So= 2.322
B=9 Eo= 3.88 E= 6.29 E-Eo= 2.41 Re(Z)=0.83 Im(Z)=-.2016E-2 nlXC=-5.536 lXC=-10.67 So=-2.232

Extended information can be also found in the output activating in the input the <code>[[Variables#ExtendOut|ExtendOut]]</code> flag. This is an optional flag that can be activated by adding the <code>-V qp</code> verbosity option when building the input file. The plasmon pole screening, exchange self-energy and the quasiparticle energies are also saved in databases so that they can be reused in further runs:

$ ls ./10b_1Ry
ndb.pp ndb.pp_fragment_1 ... ndb.HF_and_locXC ndb.QP

===Convergence tests for a quasi particle calculation===

Now we can check the convergence of the different variables entering in the expression of the correlation part of the self energy. 
First, we focus on the parameter governing the ''screening matrix'' you have already seen in the [[RPA/IP]] section. In contrast to the calculation of the [[RPA/IP]] dielectric function, where you considered either the optical limit or a finite q response (EELS), here the dielectric matrix will be calculated for ''all'' q-points determined by the choice of k-point sampling.

The parameters that need to be converged can be understood by looking at expression of the dielectric matrix:
[[File:Yambo-CH5.png|none|x30px|Yambo tutorial image]]
where ''χGG''' is given by
[[File:Dyson_rpa.png|none|x40px|Yambo tutorial image]]
and χ0GG' is given by
[[File:ChiO.png|none|x45px|Yambo tutorial image]]
* <code>[[Variables#NGsBlkXp|NGsBlkXp]]</code> : The dimension of the microscopic inverse matrix, related to [[Local fields]]
* <code>[[Variables#BndsRnXp|BndsRnXp]]</code> : The sum on bands (c,v) in the independent particle χ0GG'

====Converging Screening Parameters====
Here we will check the convergence of the gap starting from the variables controlling the screening reported above: the bands employed to build the RPA response function <code>[[Variables#BndsRnXp|BndsRnXp]]</code> and the number of blocks (G,G') of the dielectric matrix ε-1G,G' <code>[[Variables#NGsBlkXp|NGsBlkXp]]</code>.
In the next section we will study convergence with respect to the sum over states summation (sum over ''m'' in the Σc expression); here let's fix <code>[[Variables#GbndRnge|GbndRnge]]</code> to a reasonable value (40 Ry).

Let's build a series of input files differing by the values of bands and block sizes in χ0GG' considering <code>[[Variables#BndsRnXp|BndsRnXp]]</code> in the range 10-50 (upper limit) and <code>[[Variables#NGsBlkXp|NGsBlkXp]]</code> in the range 1 to 5 Ry. To do this by hand, file by file, open the ''gw_ppa.in'' file in an editor and change to:
[[Variables#NGsBlkXp|NGsBlkXp]] = '''2 Ry'''
while leaving the rest untouched. Repeat for 3 Ry, 4 Ry etc. Next, for each <code>[[Variables#NGsBlkXp|NGsBlkXp]]</code> change to:
% [[Variables#BndsRnXp|BndsRnXp]]
1 | 20 | # [Xp] Polarization function bands
%
and repeat for 30, 40 and so on. Give a '''different name''' to each file: ''gw_ppa_Xb_YRy.in'' with X=10,20,30,40 and Y=1,2,3,4,5 Ry.

This is obviously quite tedious. However, you can automate both the input construction and code execution using bash or python scripts (indeed later you will learn how to use the the yambo-python [http://www.yambo-code.org/wiki/index.php?title=GW_tutorial._Convergence_and_approximations_(BN)]tool for this task). For now, you can use the simple [[bash_scripts|generate_inputs_1.sh]] bash script to generate the required input files (after copying the script you need to type <code>$ chmod +x name_of_the_script.sh </code>).

Finally launch the calculations:

$ yambo -F gw_ppa_10b_1Ry.in -J 10b_1Ry
$ yambo -F gw_ppa_10b_2Ry.in -J 10b_2Ry
...
$ yambo -F gw_ppa_40b_5Ry.in -J 40b_5Ry

Once the jobs are terminated we can collect the quasiparticle energies for fixed <code>[[Variables#BndsRnXp|BndsRnXp]]</code> in different files named e.g. ''10b.dat, 20b.dat'' etc. for plotting, by putting in separate columns: the energy cutoff; the size of the G blocks; the quasiparticle energy of the valence band; and that of the conduction band.
To do this e.g. for the ''10b.dat'' file you can type:
$ cat o-10b* | grep "8.000" | awk '{print $3+$4}'
to parse the valence band quasiparticle energies and
$ cat o-10b* | grep "9.000" | awk '{print $3+$4}'
for the conduction band; and put all the data in the ''10b.dat'' files. As there are many files to process you can use the [[bash_scripts|parse_qps.sh]] script to create the ''10b.dat'' file and edit the script changing the number of <code>[[Variables#BndsRnXp|BndsRnXp]]</code> for the other output files.

Once we have collected all the quasiparticle values we can plot the gap, or the valence and conduction band energies separately, as a function of the block size or energy cutoff:
$ gnuplot
gnuplot> p "10b.dat" u 1:3 w lp t " Valence BndsRnXp=10", "20b.dat" u 1:3 w lp t "Valence BndsRnXp=20",..
gnuplot> p "10b.dat" u 1:4 w lp t " Conduction BndsRnXp=10", "20b.dat" u 1:4 w lp t "Conduction BndsRnXp=20",..
gnuplot> p "10b.dat" u 1:($4-$3) w lp t " Gap BndsRnXp=10", "20b.dat" u 1:($4-$3) w lp t "gap BndsRnXp=20",..
or both using e.g. the [[gnuplot_scripts|ppa_gap.gnu]] gnuplot script:

<gallery mode=nolines widths=500px heights=500px perrow=1 caption="Quasiparticle energies with respect screening parameters">
File:ppa2.png|Valence band energy wrt <code>[[Variables#BndsRnXp|BndsRnXp]]</code> and <code>[[Variables#NGsBlkXp|NGsBlkXp]]</code>.
File:ppa3.png|Conduction band energy wrt <code>[[Variables#BndsRnXp|BndsRnXp]]</code> and <code>[[Variables#NGsBlkXp|NGsBlkXp]]</code>.
</gallery>

[[File:ppa1.png|center|600px|caption]]

Looking at the plot we can see that:
* The two parameters are not totally independent (see e.g. the valence quasiparticle convergence) and this is the reason why we converged them simultaneously
* The gap (energy difference) converge faster than single quasiparticle state
* The convergence criteria depends on the degree of accuracy we look for, but considering the approximations behind the calculations (plasmon-pole etc.), it is not always a good idea to enforce too strict a criteria.
* Even if not totally converged we can consider that the upper limit of <code>[[Variables#BndsRnXp|BndsRnXp]]</code>=30, and <code>[[Variables#NGsBlkXp|NGsBlkXp]]</code>=3Ry are reasonable parameters.

Finally notice that in the last versions of Yambo 4.5 etc. there is a terminator for the dielectric constant that accelerates convergence on the number of bands,
you can active it with the <code>-V resp</code> verbosity and setting <code>XTermKind= "BG"</code>. You can compare the converge of the dielectric constant with and without terminator,
similar to what happens for the self-energy, see next section.

====Converging the sum over states in the correlation self-energy====
From now on we will keep fixed these parameters and will perform a convergence study on the sum over state summation in the correlation self-energy (Σc) <code>[[Variables#GbndRnge|GbndRnge]]</code>.

In order to use the screening previously calculated we can copy the plasmon pole parameters saved in the <code>30b_3Ry</code> directory in the <code>SAVE</code> directory. In this way the screening will be read by Yambo and not calculated again:

$ cp ./30b_3Ry/ndb.pp* ./SAVE/.

(Note: you may have to delete these files before running the BSE tutorials)

In order to use the databases we have to be sure to have the same plasmon-pole parameters in our input files.
Edit ''gw_ppa_30b_3Ry.in'' and modify <code>[[Variables#GbndRnge|GbndRnge]]</code> to order to have a number of bands in the range from 10 to 80 inside different files named ''gw_ppa_Gbnd10.in'', ''gw_ppa_Gbnd20.in'' etc. You can also run the the [[bash_scripts|generate_inputs_2.sh]] bash script to generate the required input files.

Next, launch yambo for each input:

$ yambo -F gw_ppa_Gbnd10.in -J Gbnd10
$ yambo -F gw_ppa_Gbnd20.in -J Gbnd20
...

and as done before we can inspect the obtained quasiparticle energies:

$ grep 8.00 o-Gbnd* | awk '{print $4+$5}'
for the valence bands, and
$ grep 9.00 o-Gbnd* | awk '{print $4+$5}'
for the conduction band.

Collect the results in a text file ''Gbnd_conv.dat'' containing: the number of Gbnd, the valence energy, and the conduction energy.
Now, as done before we can plot the valence and conduction quasiparticle levels separately as well as the gap, as a function of the number of bands used in the summation:

$ gnuplot
gnuplot> p "Gbnd_conv.dat" u 1:2 w lp lt 7 t "Valence"
gnuplot> p "Gbnd_conv.dat" u 1:3 w lp lt 7 t "Conduction"
gnuplot> p "Gbnd_conv.dat" u 1:($3-$2) w lp lt 7 t "Gap"

<gallery mode=nolines widths=500px heights=500px perrow=2 caption="Quasiparticle energies with respect sum over states in correlation self-energy">
File:Gbnd_val.png|Valence band energy wrt <code>[[Variables#GbndRange|GbndRange]]</code>.
File:Gbnd_cond.png|Conduction band energy wrt <code>[[Variables#GbndRange|GbndRange]]</code>
</gallery>

[[File:Gbnd_gap.png|center|600px|caption]]

Inspecting the plot we can see that:
* The convergence with respect to <code>[[Variables#GbndRange|GbndRange]]</code> is rather slow and many bands are needed to get converged results.
* As observed above the gap (energy difference) converges faster than the single quasiparticle state energies.

====Accelerating the sum over states convergence in the correlation self-energy====
In general the convergence with respect the sum over states can be very cumbersome. Here we show how it can be mitigated by using
a technique developed by F. Bruneval and X. Gonze <ref name="BG"> F. Bruneval and X. Gonze, Physical Review B 78, 085125 (2008 )</ref>. The basic idea relies in replacing the eigenenergies of the states that are not treated explicitly by a common energy, and take into account all the states, which are not explicitly included in the calculation through the closure relation.
To apply this technique in Yambo we need to activate the optional terminator variable [[Variables#GTermKind|GTermKind]]. We can activate it by adding the quasiparticle verbosity to the command line when generating the input file:

$ yambo -p p -g n -F gw_ppa_Gbnd10.in -V qp

and you can edit the input file by setting:

[[Variables#GTermKind|GTermKind]]= "BG"

or simply you can add by hand this line in all the other ''gw_ppa_GbndX.in'' input files.
Now we can repeat the same calculations

$ yambo -F gw_ppa_Gbnd10.in -J Gbnd10_term
$ yambo -F gw_ppa_Gbnd20.in -J Gbnd20_term
...

and collect the new results:

$ grep 8.000 *term.qp | awk '{print $4+$5}'
$ grep 9.000 *term.qp | awk '{print $4+$5}'

in a new file called ''Gbnd_conv_terminator.dat''. Now we can plot the same quantities as before by looking at the effect of having introduced the terminator.

gnuplot
gnuplot> p "Gbnd_conv.dat" u 1:2 w lp t "Valence", "Gbnd_conv_terminator.dat" u 1:2 w lp t "Valence with terminator"
gnuplot> p "Gbnd_conv.dat" u 1:3 w lp t "Conduction", "Gbnd_conv_terminator.dat" u 1:3 w lp t "Conduction with terminator"
gnuplot> p "Gbnd_conv.dat" u 1:($3-$2) w lp t "Gap", "Gbnd_conv_terminator.dat" u 1:($3-$2) w lp t "Gap with terminator"

<gallery mode=nolines widths=500px heights=500px perrow=2 caption="Effect of the terminator in convergence of QP energies with respect sum over states">
File:val_t.png|Valence band energy wrt <code>[[Variables#GbndRange|GbndRange]]</code> with and without the terminator technique <ref name="BG" />
File:cond_t.png|Conduction band energy wrt <code>[[Variables#GbndRange|GbndRange]]</code> with and without the terminator technique<ref name="BG" />
</gallery>

[[File:gap_t.png|center|600px|caption]]

We can see that:
* The convergence with respect to <code>[[Variables#GbndRange|GbndRange]]</code> is accelerated in particular for the single quasiparticle states.
* From the plot above we can see that <code>[[Variables#GbndRange|GbndRange]]</code>=40 is sufficient to have a converged gap

===Beyond the plasmon pole approximation: a full frequency approach - real axis integration===
All the calculations performed up to now were based on the plasmon pole approximation (PPA). Now we remove this approximation by evaluating numerically the frequency integral in the expression of the correlation self-energy (Σc). To this aim we need to evaluate the screening for a number of frequencies in the interval depending on the electron-hole energy difference (energy difference between empty and occupied states) entering in the sum over states.
Let's build the input file for a full frequency calculation by simply typing:

$ yambo -F gw_ff.in -g n

and we can set the variable studied up to now at their converged value:

%[[Variables#BndsRnXd|BndsRnXd]]
1 | 30 |
%
[[Variables#NGsBlkXd|NGsBlkXd]]=3 Ry
%[[Variables#GbndRange|GbndRange]]
1 | 40 |
%
[[Variables#EXXRLvcs|EXXRLvcs]]=40 Ry
% [[Variables#LongDrXd|LongDrXd]]
1.000000 | 1.000000 | 1.000000 | # [Xd] [cc] Electric Field
%
%QPkrange # # [GW] QP generalized Kpoint/Band indices
7|7|8|9|
%

and next vary in different files (name them ''gw_ff10.in'' etc.) the number of frequencies we evaluate for the screened coulomb potential. This is done by setting the values of [[Variables#ETStpsXd|ETStpsXd]]=10 , 50 , 100, 150, 200, 250.
You can also run the the [[bash_scripts|generate_inputs_3.sh]] bash script to generate the required input files.

Next launch yambo:
$ yambo -F gw_ff10.in -J ff10
$ yambo -F gw_ff50.in -J ff50
...

Clearly as we are evaluating the screening for a large number of frequencies these calculations will be heavier than the case above where the calculation of the screening was done for only two frequencies (zero and plasmon-pole).
As before, collect the valence and conduction bands as a function of the number of frequencies in a file called ''gw_ff.dat'' and plot the behaviour of the conduction and valence bands and the gap.

$ gnuplot
gnuplot> p "gw_ff.dat" u 1:2 w lp t "Valence"
gnuplot> p "gw_ff.dat" u 1:3 w lp t "Conduction"
gnuplot> p "gw_ff.dat" u 1:($3-$2) w lp t "Gap"

<gallery mode=nolines widths=500px heights=500px perrow=2 caption="Real axis integration, convergences with respect the used number of frequencies">
File:ff_v.png|Valence band energy wrt <code>[[Variables#ETStpsXd|ETStpsXd]]</code>
File:ff_c.png|Conduction band energy wrt <code>[[Variables#ETStpsXd|ETStpsXd]]</code>
</gallery>

[[File:ff_g.png|center|600px|caption]]

We can see that:

* Oscillations are still present, indicating that even more frequencies have to be considered. In general, a real-axis calculation is very demanding.
* The final result of the gap obtained up to now does not differ too much from the one obtained at the plasmon-pole level (~50 meV)

===Secant Solver===

The real axis integration permits also to go beyond the linear expansion to solve the quasi particle equation.
The QP equation is a non-linear equation whose solution must be found using a suitable numerical algorithm.
[[File:Eqp_sec.png|none|x22px|caption]]
The mostly used, based on the linearization of the self-energy operator is the Newton method that is the one we have used up to now.
Yambo can also perform a search of the QP energies using a non-linear iterative method based on the [https://en.wikipedia.org/wiki/Secant_method Secant iterative Method].

In numerical analysis, the secant method is a root-finding algorithm that uses a succession of roots of secant lines to better approximate a root of a function ''f''. The secant method can be thought of as a finite difference approximation of Newton's method.
The equation that defines the secant method is:

[[File:secant_eq.png|none|x35px|caption]]

The first two iterations of the secant method are shown in the following picture. The red curve shows the function f and the blue lines are the secants.

[[File:Secant_method.png|center|250px|caption]]

To see if there is any non-linear effect in the solution of the Dyson equation we compare the result of the calculation using the Newton solver as done before with the present case.
In order to use the secant method you need to edit one of the the previous ''gw_ffN.in'' files e.g. ''gw_ff100.in'' and substitute:

DysSolver= "g"
to
DysSolver= "s"

Repeat the calculations in the same way as before:

$ yambo -F gw_ff100.in -J ff100

Note than now the screening will ''not'' be calculated again as it has been stored in the ''ffN'' directories as can be seen in the report file:

[05] Dynamical Dielectric Matrix
================================
[RD./ff10//ndb.em1d]----
...
[RD./ff10//ndb.em1d_fragment_1]--------------
...

Comparing the output files, e.g. for the case with 100 freqs:

''o-ff100.qp'' '''Newton Solver:'''
# K-point Band Eo E-Eo Sc|Eo
#
7.00000 8.00000 -0.41188 -0.08708 2.91254
7.00000 9.00000 3.877976 1.421968 -3.417357

''o-ff100.qp_01'' '''Secant Solver:'''
#
# K-point Band Eo E-Eo Sc|Eo
#
7.00000 8.00000 -0.41188 -0.08715 2.93518
7.00000 9.00000 3.877976 1.401408 -3.731649

From the comparison, we see that the effect is of the order of 20 meV, of the same order of magnitude of the accuracy of the GW calculations.

==Step 3: Interpolating Band Structures==
Up to now we have checked convergence for the gap. Now we want to calculate the quasiparticle corrections across the Brillouin zone in order to visualize the entire band structure along a path connecting high symmetry points.

To do that we start by calculating the QP correction in the plasmon-pole approximation for all the k points of our sampling and for a number of bands around the gap. You can use a previous input file or generate a new one: <code> yambo -F gw_ppa_all_Bz.in -x -p p -g n </code> and set the parameters found in the previous tests:

EXXRLvcs= 40 Ry
% BndsRnXp
1 | 30 | # [Xp] Polarization function bands
%
NGsBlkXp= 3 Ry # [Xp] Response block size
% LongDrXp
1.000000 | 1.000000 | 1.000000 | # [Xp] [cc] Electric Field
%
PPAPntXp= 27.21138 eV # [Xp] PPA imaginary energy
% GbndRnge
1 | 40 | # [GW] G[W] bands range
%

and we calculate it for all the available kpoints by setting:
%QPkrange # [GW] QP generalized Kpoint/Band indices
1| 14| 6|11|
%

Note that as we have already calculated the screening with these parameters you can save time and use that database either by running in the previous directory by using <code> -J 30b_3Ry </code> or if you prefer to put the new databases in the new all_Bz directory you can create a new directory and copy there the screening databases:

$ mkdir all_Bz
$ cp ./30b_3Ry/ndb.pp* ./all_Bz/

and launch the calculation:

$ yambo -F gw_ppa_all_Bz.in -J all_Bz

Now we can inspect the output and see that it contains the correction for all the k points for the bands we asked:

# K-point Band Eo E-Eo Sc|Eo
#
1.000000 6.000000 -1.299712 -0.219100 3.788044
1.000000 7.000000 -1.296430 -0.241496 3.788092
1.000000 8.000000 -1.296420 -0.243115 3.785947
1.000000 9.000000 4.832399 0.952386 -3.679259
1.00000 10.00000 10.76416 2.09915 -4.38743
1.00000 11.00000 11.36167 2.48053 -3.91021
....
By plotting some of the 'o-all_Bz.qp" columns it is possible to discuss some physical properties of the hBN QPs. Using columns 3 and (3+4), ie plotting the GW energies with respect to the LDA energies we can deduce the band gap renormalization and the stretching of the conduction/valence bands:

$ gnuplot
gnuplot> p "o-all_Bz.qp" u 3:($3+$4) w p t "Eqp vs Elda"

[[File:EqpvE0.png|center|350px|caption]]

Essentially we can see that the effect of the GW self-energy is the opening of the gap and a linear stretching of the conduction/valence bands that can be estimated by performing a linear fit of the positive and negative energies (the zero is set at top of the valence band).

In order to calculate the band structure, however, we need to interpolate the values we have calculated above on a given path. In Yambo the interpolation is done by the executable <code>ypp</code> (Yambo Post Processing).
By typing:
$ ypp -H
you will recognize that in order to interpolate the bands we need to build a ypp input file using
$ ypp -s b

we can generate the input for the band interpolation:

$ypp -s b -F ypp_bands.in

and edit the ''ypp_bands.in'' file:

electrons # [R] Electrons (and holes)
bnds # [R] Bands
INTERP_mode= "NN" # Interpolation mode (NN=nearest point, BOLTZ=boltztrap aproach)
OutputAlat= 4.716000 # [a.u.] Lattice constant used for "alat" ouput format
cooIn= "rlu" # Points coordinates (in) cc/rlu/iku/alat
cooOut= "rlu"
% BANDS_bands
1 | 100 | # Number of bands
%
% INTERP_Grid
-1 |-1 |-1 | # Interpolation BZ Grid
%
INTERP_Shell_Fac= 20.00000 # The bigger it is a higher number of shells is used
CIRCUIT_E_DB_path= "none" # SAVE obtained from the QE `bands` run (alternative to %BANDS_kpts)
BANDS_path= "" # BANDS path points labels (G,M,K,L...)
BANDS_steps= 10
#BANDS_built_in # Print the bands of the generating points of the circuit using the nearest internal point
%BANDS_kpts
%

We modify the following lines:
BANDS_steps=30
% BANDS_bands
6 | 11 | # Number of bands
%
%BANDS_kpts # K points of the bands circuit
0.33300 |-.66667 |0.00000 |
0.00000 |0.00000 |0.00000 |
0.50000 |-.50000 |0.00000 |
0.33300 |-.66667 |0.00000 |
0.33300 |-.66667 |0.50000 |
0.00000 |0.00000 |0.50000 |
0.50000 |-.50000 |0.50000 |
%

which means we assign 30 points in each segment, we ask to interpolate 3 occupied and 3 empty bands and we assign the following path passing from the high symmetry points: K Γ M K H A L.
Launching:
$ ypp -F ypp_bands.in
will produce the output file ''o.bands_interpolated'' containing:

#
# |k| b6 b7 b8 b9 b10 b11 kx ky kz
#
#
0.00000 -7.22092 -0.13402 -0.13395 4.67691 4.67694 10.08905 0.33300 -0.66667 0.00000
0.03725 -7.18857 -0.17190 -0.12684 4.66126 4.71050 10.12529 0.32190 -0.64445 0.00000
...

and we can plot the bands using gnuplot:
$ gnuplot
gnuplot> p "o.bands_interpolated" u 0:2 w l, "o.bands_interpolated" u 0:3 w l, ...

[[File:bands_lda.png|center|350px|caption]]

and you can recognize the index of the high symmetry point by inspecting the last three columns.
Note that up to now we have interpolated the LDA band structure. In order to plot the GW band structure, we need to tell <code>ypp</code> in the input file where the ''ndb.QP'' database is found. This is achieved by adding in the ''ypp_bands.in'' file the line:

GfnQPdb= "E < ./all_Bz/ndb.QP"

and relaunch

$ ypp -F ypp_bands.in

Now the file ''o.bands_interpolated_01'' contains the GW interpolated band structure. We can plot the LDA and GW band structure together by using the gnuplot script [[gnuplot_scripts|bands.gnu]].

<gallery mode=nolines widths=500px heights=500px perrow=2 caption="Band strcuture of bulk hBN">
File:hBN_bands.png| LDA and GW bands structure
File:hBN_bands_lit.png| LDA and GW bands structure from Ref. <ref name="Arnaud" />
</gallery>

*As expected the effect of the GW correction is to open the gap.
*Comparing the obtained band structure with the one found in the literature by Arnaud and coworkers <ref name="Arnaud"> B. Arnaud, S. Lebegue,P. Rabiller, and M. Alouani Phys, Rev. Lett. 96, 026402 (2006)</ref> we found a very nice qualitative agreement.
*Quantitatively we found a smaller gap: about 5.2 eV (indirect gap), 5.7 eV (direct gap) while in Ref.<ref name="Arnaud" /> is found 5.95 eV for the indirect gap and a minimum direct band gap of 6.47 eV. Other values are also reported in the literature depending on the used pseudopotentials, starting functional and type of self-consistency (see below).
*The present tutorial has been done with a small k point grid which is an important parameter to be checked, so convergence with respect the k point sampling has to be validated.

==Step 4: Summary of the convergence parameters==
We have calculated the band structure of hBN starting from a DFT calculation, here we summarize the main variable we have checked to achieve convergence:

* <code>[[Variables#EXXRLvcs|EXXRLvcs]]</code> # [XX] Exchange RL components
Number of G-vectors in the exchange. This number should be checked carefully. Generally a large number is needed as the QP energies show a slow convergence. The calcualtion of the exchange part is rather fast.

*<code>[[Variables#BndsRnXp|BndsRnXp]]</code> #[Xp] Polarization function bands
Number of bands in the independent response function form which the dielectric matrix is calculated. Also this paramater has to be checked carefully,together with NGsBlkXp as the two variables are interconnected

*<code>[[Variables#NGsBlkXp|NGsBlkXp]]</code> # [Xp] Response block size
Number of G-vectors block in the dielectric constant. Also this paramater has to be checked carefully, to be checked together with BndsRnXp. A large number of bands and block can make the calculation very demanding.

*<code>[[Variables#LongDrXp|LongDrXp]] </code> # [Xp] [cc] Electric Field
Direction of the electric field for the calculation of the q=0 component of the dielectric constant e(q,w). In a bulk can be set to (1,1,1), attention must be paid for non 3D systems.

*<code>[[Variables#PPAPntXp|PPAPntXp]] </code> # [Xp] Plasmon pole imaginary energy: this is the second frequency used to fit the Godby-Needs plasmon-pole model (PPM). If results depend consistently by changing this frequency, the PPM is not adequate for your calculation and it is need to gp beyond that, e.g. Real-axis.

*<code>[[Variables#GbndRnge|GbndRnge]] </code> # [GW] G[W] bands range
Number of bands used to expand the Green's function. This number is usually larger than the number of bands used to calculated the dielectricconstant. Single quasiparticle energies converge slowly with respect GbndRnge, energy difference behave better. You can use terminator technique to mitigate the slow dependence.

*<code>[[Variables#GDamping|GDamping]] </code> # [GW] G[W] damping
Small damping in the Green's function definition, the delta
parameter. The final result shouuld not depend on that, usually set at 0.1 eV

*<code>[[Variables#dScStep|dScStep]] </code> # [GW]
Energy step to evaluate Z factors

*<code>[[Variables#DysSolver|DysSolver]] </code> # [GW] Dyson Equation solver ("n","s","g")
Parameters related to the solution of the Dyson equation, "n" Newton linearization, 's' non linear secant method

*<code>[[Variables#GTermKind|GTermKind]] </code> [GW] GW terminator
Terminator for the self-energy<ref name="BG" /> . We have seen how this spped up the convergence with respect empty bands.

*<code>[[Variables#%QPkrange |QPkrange ]] </code> # [GW] QP generalized Kpoint/Band indices
K-points and band range where you want to calculate the GW correction. The syntax is
first kpoint | last kpoint | first band | last band

==Step 5: Eigenvalue only self-consistent evGW0 and evGW (only available in Yambo 4.6) ==
Here we want to see how we can compute an eigenvalue only evGW0 or evGW correction in Yambo. In the new version of Yambo there are two flags for these kind of self-consistency:

<code>[[Variables#GWoIter|GWoIter]]</code> number of GW0 iterations

<code>[[Variables#GWoIter|GWIter]]</code> number of GW iterations

you can set one of them to 10 for example, the code will stop when convergence is reached, usually in less than 5 iterations.
For example if you consider the input file below:

HF_and_locXC # [R XX] Hartree-Fock Self-energy and Vxc
ppa # [R Xp] Plasmon Pole Approximation
gw0 # [R GW] GoWo Quasiparticle energy levels
em1d # [R Xd] Dynamical Inverse Dielectric Matrix
EXXRLvcs = 40.000 mRy # [XX] Exchange RL components
VXCRLvcs = 3187 RL # [XC] XCpotential RL components
Chimod= "Hartree" # [X] IP/Hartree/ALDA/LRC/BSfxc
% BndsRnXp
1 | 10 | # [Xp] Polarization function bands
%
NGsBlkXp= 1000 mRy # [Xp] Response block size
% LongDrXp
1.000000 | 1.000000 | 1.000000 | # [Xp] [cc] Electric Field
%
PPAPntXp = 27.21138 eV # [Xp] PPA imaginary energy
%GbndRnge
1 | 40 | # [GW] G[W] bands range
%
GDamping= 0.10000 eV # [GW] G[W] damping
dScStep= 0.10000 eV # [GW] Energy step to evaluate Z factors
DysSolver= "n" # [GW] Dyson Equation solver ("n","s","g")
GWoIter=0 # [GW] GWo self-consistent (evGWo) iterations on eigenvalues
GWIter =0 # [GW] GW self-consistent (evGW) iterations on eigenvalues
%QPkrange # [GW] QP generalized Kpoint/Band indices
1| 14| 7| 10|
%
if you set both GWIter and GWoIter to zero you get a gap correction of 4.15 eV.
If you perform self-consistency on G (GWoIter/=)
the gap will be 4.713 eV and finally if you perform
self-consistency in both G and W (GWIter /=0) the gap will be 5.506 eV.

Notice that these values are absolutelly not converged because we used very few
bands and a small block size.

It's important to note that the final result of the self-consistent GW may
depend from the number of bands you decide to correct, because they are used
to reconstruct G and W. For the non-corrected bands Yambo applied a rigid shift
of their energy based on the closed corrected band.

==Step 6: A better integration of the q=0 point ==

The integration of the q=0 of the Coulomb potential is problematic because the 1/q diverges.
Usually in Yambo this integration is performed analytically in a small sphere around q=0.

[[File:Circle box.gif|center|frame]]

however in this way the code lost part of the integral out of the circle. This usually
is not problematic because for a large number of q and k point the missing term goes to zero.
However in system that requires few k-points or even only the gamma one, it is possible
to perform a better integration of this term by adding the flag -r to generate the input

HF_and_locXC # [R XX] Hartree-Fock Self-energy and Vxc
ppa # [R Xp] Plasmon Pole Approximation
gw0 # [R GW] GoWo Quasiparticle energy levels
rim_cut # [R] Coulomb potential
em1d # [R Xd] Dynamical Inverse Dielectric Matrix
RandQpts= 3000000 # [RIM] Number of random q-points in the BZ
RandGvec= 1 RL # [RIM] Coulomb interaction RS components
#QpgFull # [F RIM] Coulomb interaction: Full matrix
EXXRLvcs = 40.000 mRy # [XX] Exchange RL components
VXCRLvcs = 3187 RL # [XC] XCpotential RL components
Chimod= "Hartree" # [X] IP/Hartree/ALDA/LRC/BSfxc
% BndsRnXp
1 | 10 | # [Xp] Polarization function bands
%
NGsBlkXp= 1000 mRy # [Xp] Response block size
% LongDrXp
1.000000 | 1.000000 | 1.000000 | # [Xp] [cc] Electric Field
%
PPAPntXp = 27.21138 eV # [Xp] PPA imaginary energy
%GbndRnge
1 | 40 | # [GW] G[W] bands range
%
GDamping= 0.10000 eV # [GW] G[W] damping
dScStep= 0.10000 eV # [GW] Energy step to evaluate Z factors
DysSolver= "n" # [GW] Dyson Equation solver ("n","s","g")
%QPkrange # [GW] QP generalized Kpoint/Band indices
7| 7| 8| 9|
%

in this input <code>[[Variables#RandGvec|RandGvec]]</code> is the component of the Coulomb potential we want integrate numerically,
in this case only the first one G=G'=0, and <code>[[Variables#RandQpts|RandQpts]]</code> is the number of random points
used to perform the integral by Monte Carlo.

If you turn one this integration you will get a slightly different band gap,
but in the limit of large k points the final results will be the same of the standard method.

However this correction is important for systems that converge with few k-points or with gamma only.

==Step 7: Taking into account the material anisotropy (only available in Yambo 4.6) ==

Hexagonal Boron Nitride is an anisotropic material so there is the question in which direction
one shold calculate the dielectric constant the enters in the GW.
If you run again this tutorial changing the direction of the q=0 point in GW calculation,
the variable <code>[[Variables#LongDrXp|LongDrXp]]</code>, you will realize that the there gap correction changes.
In Yambo there is a way to take into account this anisitropy of the dielectri tensor.

First of all you need to calculate the dielectric constant in the three cartesian directions with the command <code> yambo -o c -k hartree</code>

optics # [R] Linear Response optical properties
kernel # [R] Kernel
chi # [R][CHI] Dyson equation for Chi.
dipoles # [R] Oscillator strenghts (or dipoles)
Chimod= "HARTREE" # [X] IP/Hartree/ALDA/LRC/PF/BSfxc
NGsBlkXd= 3000 mRy # [Xd] Response block size
% QpntsRXd
1 | 1 | # [Xd] Transferred momenta
%
% BndsRnXd
1 | 100 | # [Xd] Polarization function bands
%
% EnRngeXd
0.00000 | 10.00000 | eV # [Xd] Energy range
%
% DmRngeXd
0.10000 | 0.10000 | eV # [Xd] Damping range
%
ETStpsXd= 1 # [Xd] Total Energy steps
% LongDrXd
1.000000 | 0.000000 | 0.000000 | # [Xd] [cc] Electric Field
%

In the output file <code> o.eps_q1_inv_rpa_dyson</code> you will find the real-part of the zero component of inverse dielectric matrix, in this case 1.0/5.044076 = 0.198252.

Repeat this calculation with the field in the other two directions y and z. The y-direction is equal to x, while in z direction the zero component of the inverse dielectric matrix is 1.0/2.872451 = 0.348134.

Now generate a new input file for the GW, with the command <code> yambo -g n -p p -r -V RL</code>

HF_and_locXC # [R XX] Hartree-Fock Self-energy and Vxc
ppa # [R Xp] Plasmon Pole Approximation
gw0 # [R GW] GoWo Quasiparticle energy levels
rim_cut # [R] Coulomb potential
em1d # [R Xd] Dynamical Inverse Dielectric Matrix
RandQpts=3000000 # [RIM] Number of random q-points in the BZ
RandGvec= 1 RL # [RIM] Coulomb interaction RS components
#QpgFull # [F RIM] Coulomb interaction: Full matrix
% Em1Anys
 0.198252 | 0.198252 | 0.348134 | # [RIM] X Y Z Static Inverse dielectric matrix
%
IDEm1Ref= 1
EXXRLvcs = 40.000 mRy # [XX] Exchange RL components
VXCRLvcs = 3187 RL # [XC] XCpotential RL components
Chimod= "Hartree" # [X] IP/Hartree/ALDA/LRC/BSfxc
% BndsRnXp
1 | 10 | # [Xp] Polarization function bands
%
NGsBlkXp= 1000 mRy # [Xp] Response block size
% LongDrXp
1.000000 | 0.000000 | 0.000000 | # [Xp] [cc] Electric Field
%
PPAPntXp = 27.21138 eV # [Xp] PPA imaginary energy
%GbndRnge
1 | 40 | # [GW] G[W] bands range
%
GDamping= 0.10000 eV # [GW] G[W] damping
dScStep= 0.10000 eV # [GW] Energy step to evaluate Z factors
DysSolver= "n" # [GW] Dyson Equation solver ("n","s","g")
%QPkrange # [GW] QP generalized Kpoint/Band indices
7| 7| 8| 9|
%

run the calculations and you will find a correction of the gap intermediate between the one with the field in x and z directions.

==Step 8: Exercise: Convergence with respect K points==
As an exercise now you can check the convergence with respect the K point sampling:
# perform a new non-scf calculation with a bigger k point grid: 9x9x3 and 12x12x4 ...
# convert wave functions and electronic structure to Yambo databases in a different directory as explained in the [[Bulk material: h-BN|DFT and p2y module]],
# [[initialization |Initialize]] the Yambo databases,
# Redo the steps explained in this section (exchange self energy, plasmon pole GW, band structure interpolation)
# The PPA-GW calculation using 12x12x4 grid depending on your machine can take several minutes in serial mode. You can think to perform the exercise after having learned some basic on the parallelization strategy.

 
{| style="width:100%" border="1"
|style="width:15%; text-align:left"|Prev: [[Tutorials|Tutorials Home]]
|style="width:50%; text-align:center"|Now: [[Tutorials|Tutorials Home]] --> [[How_to_obtain_the_quasi-particle_band_structure_of_a_bulk_material:_h-BN|GW]]
|style="width:35%; text-align:right"|Next: If you did everything, choose another tutorial in the menu
|-
|}

==References==

How to obtain the quasi-particle band structure of a bulk material: h-BN

2020-11-19T12:44:58Z

Claudio: /* Step 7: Taking into account the material anisotropy (only available in Yambo 4.6) */

In this tutorial you will learn how to:
* Calculate quasi-particle corrections in the Hartree-Fock approximation
* Calculate quasi-particle corrections in the GW approximation
* Choose the input parameters for a meaningful converged calculation
* Plot a band structure including quasi-particle corrections
We will use bulk hBN as an example system. Before starting, you need to obtain the appropriate tarball. See instructions on the [[Tutorials|main tutorials page]]. 
We strongly recommend that you first complete the [[First steps: a walk through from DFT to optical properties]] tutorial.



The aim of the present tutorial is to obtain quasiparticle correction to energy levels using many-body perturbation theory (MBPT). 
The general non-linear quasiparticle equation reads:
[[File:Eqp_1.png|none|x26px|caption]]
As a first step we want to evaluate the self energy Σ entering in the quasiparticle equation. In the GW approach the self-energy can be separated into two components: a static term called the exchange self-energy (Σx), and a dynamical term (energy dependent) called the correlation self-energy (Σc):
[[File:Sigma.png|none|x25px|caption]]
We will treat these two terms separately and demonstrate how to set the most important variables for calculating each term.
In practice we will compute the quasi-particle corrections to the one particle Kohn-Sham eigenvalues obtained through a DFT calculation.

The steps are the following:

==Step 1: The Exchange Self Energy or HF quasi-particle correction==

We start by evaluating the exchange Self-Energy and the corresponding Quasiparticle energies (Hartree-Fock energies).
Follow the module on '''[[Hartree Fock]]''' and then return to this tutorial ''How to obtain the quasiparticle band structure of a bulk material: h-BN''.

==Step 2: The Correlation Self-Energy and Quasiparticle Energies==
Once we have calculated the exchange part, we next turn our attention to the more demanding dynamical part. The correlation part of the self-energy in a plane wave representation reads:
[[File:Sigma_c.png|none|x50px|caption]]
In the expression for the correlation self energy, we have (1) a summation over bands, (2) an integral over the Brillouin Zone, and (3) a sum over the G vectors. In contrast with the case of Σx, the summation over bands extends over ''all'' bands (including the unoccupied ones), and so convergence tests are needed. Another important difference is that the Coulomb interaction is now screened so a fundamental ingredient is the evaluation of the dynamical dielectric matrix. The expression for the dielectric matrix, calculated at the RPA level and including local field effects, has been already treated in the [[Local fields|Local fields]] tutorial.

In the following, we will see two ways to take into account the dynamical effects. First, we will see how to set the proper parameters to obtain a model dielectric function based on a widely used approximation, which models the energy dependence of each component of the dielectric matrix with a single pole function.
Secondly, we will see how to perform calculations by evaluating the dielectric matrix on a regular grid of frequencies.

Once the correlation part of the self-energy is calculated, we will check the convergence of the different parameters with respect to some final quantity, such as the gap.

After computing the frequency dependent self-energy, we will discover that in order to solve the quasiparticle equation we will need to know its value ''at the value of the quasiparticle itself''. In the following, unless explicitly stated, we will solve the non-linear quasi-particle equation at first order, by expanding the self-energy around the Kohn-Sham eigenvalue. In this way the quasiparticle equation reads:

[[File:Eqp_2.png|none|x26px|caption]]

where the normalization factor Z is defined as:

[[File:z_fac.png|none|x40px|caption]]

===The Plasmon Pole approximation===
As stated above, the basic idea of the plasmon-pole approximation is to approximate the frequency dependence of the dielectric matrix with a single pole function of the form:
[[File:ppa.png|none|x26px|caption]]
The two parameters RGG' and ΩGG' are obtained by a fit (for each component), after having calculated the RPA dielectric matrix at two given frequencies.
Yambo calculates the dielectric matrix in the static limit ( ω=0) and at a user defined frequency called the plasmon-pole frequency (ω=iωp).
Such an approximation has the big computational advantage of calculating the dielectric matrix for only two frequencies and leads to an analytical expression for the frequency integral of the correlation self-energy.
==== Input file generation ====
Let's start by building up the input file for a GW/PPA calculation, including the calculation of the exchange self-energy. From <code>yambo -H</code> you should understand that the correct option is <code>yambo -x -p p -g n</code>:

$ cd YAMBO_TUTORIALS/hBN/YAMBO
$ yambo -x -p p -g n -F gw_ppa.in

Let's modify the input file in the following way:

HF_and_locXC # [R XX] Hartree-Fock Self-energy and Vxc
ppa # [R Xp] Plasmon Pole Approximation
gw0 # [R GW] GoWo Quasiparticle energy levels
em1d # [R Xd] Dynamical Inverse Dielectric Matrix
[[Variables#EXXRLvcs|EXXRLvcs]] = 40 Ry # [XX] Exchange RL components
[[Variables#VXCRLvcs|VXCRLvcs]] = 3187 RL # [XC] XCpotential RL components
Chimod= "Hartree" # [X] IP/Hartree/ALDA/LRC/BSfxc
% BndsRnXp
1 | 10 | # [Xp] Polarization function bands
%
[[Variables#NGsBlkXp|NGsBlkXp]]= 1000 mRy # [Xp] Response block size
% LongDrXp
1.000000 | 1.000000 | 1.000000 | # [Xp] [cc] Electric Field
%
[[Variables#PPAPntXp|PPAPntXp]] = 27.21138 eV # [Xp] PPA imaginary energy
%[[Variables#GbndRnge|GbndRnge]]
1 | 40 | # [GW] G[W] bands range
%
GDamping= 0.10000 eV # [GW] G[W] damping
dScStep= 0.10000 eV # [GW] Energy step to evaluate Z factors
DysSolver= "n" # [GW] Dyson Equation solver ("n","s","g")
%[[Variables#QPkrange|QPkrange]] # [GW] QP generalized Kpoint/Band indices
7| 7| 8| 9|
%

Brief explanation of some settings:
* Similar to the Hartree Fock study, we will concentrate on the convergence of the '''direct''' gap of the system. Hence we select the last occupied (8) and first unoccupied (9) bands for k-point number 7 in the <code>[[Variables#QPkrange|QPkrange]]</code> variable.
* We also keep <code>[[Variables#EXXRLvcs|EXXRLvcs]]</code> at its converged value of 40 Ry as obtained in the '''[[Hartree Fock]]''' tutorial.
* For the moment we keep fixed the plasmon pole energy <code>[[Variables#PPAPntXp|PPAPntXp]]</code> at its default value (=1 Hartree).
* We keep fixed the direction of the electric field for the evaluation of the dielectric matrix to a non-specific value: <code>[[Variables#LongDrXp|LongDrXp]]</code>=(1,1,1).
* Later we will study convergence with respect to <code>[[Variables#GbndRnge|GbndRnge]]</code>, <code>[[Variables#NGsBlkXp|NGsBlkXp]]</code>, and <code>[[Variables#BndsRnXp|BndsRnXp]]</code>; for now just set them to the values indicated.

==== Understanding the output ====
Let's look at the typical Yambo output. Run Yambo with an appropriate <code>-J</code> flag:

$ yambo -F gw_ppa.in -J 10b_1Ry

In the standard output you can recognise the different steps of the calculations: calculation of the screening matrix (evaluation of the non interacting and interacting response), calculation of the exchange self-energy, and finally the calculation of the correlation self-energy and quasiparticle energies. Moreover information on memory usage and execution time are reported:
...
<---> [05] Dynamic Dielectric Matrix (PPA)
...
<08s> Xo@q[3] |########################################| [100%] 03s(E) 03s(X)
<08s> X@q[3] |########################################| [100%] --(E) --(X)
...
<43s> [06] Bare local and non-local Exchange-Correlation
<43s> EXS |########################################| [100%] --(E) --(X)
...
<43s> [07] Dyson equation: Newton solver
<43s> [07.01] G0W0 (W PPA)
...
<45s> G0W0 (W PPA) |########################################| [100%] --(E) --(X)
...
<45s> [07.02] QP properties and I/O
<45s> [08] Game Over & Game summary

Let's have a look at the report and output. The output file ''o-10b_1Ry.qp'' contains (for each band and k-point that we indicated in the input file) the values of the bare KS eigenvalue, its GW correction and the correlation part of the self energy:
#
# K-point Band Eo E-Eo Sc|Eo
#
7.000000 8.000000 -0.411876 -0.567723 2.322443
7.000000 9.000000 3.877976 2.413773 -2.232241

In the header you can see the details of the calculations, for instance it reports that <code>[[Variables#NGsBlkXp|NGsBlkXp]]</code>=1 Ry corresponds to 5 Gvectors:

# X G`s [used]: 5

Other information can be found in the report file ''r-10b_1Ry_em1d_ppa_HF_and_locXC_gw0'', such as the renormalization factor defined above, the value of the ''exchange'' self-energy (non-local XC) and of the DFT exchange-correlation potential (local XC):

[07.02] QP properties and I/O
=============================
Legend (energies in eV):
- B : Band - Eo : bare energy
- E : QP energy - Z : Renormalization factor
- So : Sc(Eo) - S : Sc(E)
- dSp: Sc derivative precision
- lXC: Starting Local XC (DFT)
-nlXC: Starting non-Local XC (HF)
QP [eV] @ K [7] (iku): 0.000000 -0.500000 0.000000
B=8 Eo= -0.41 E= -0.98 E-Eo= -0.56 Re(Z)=0.81 Im(Z)=-.2368E-2 nlXC=-19.13 lXC=-16.11 So= 2.322
B=9 Eo= 3.88 E= 6.29 E-Eo= 2.41 Re(Z)=0.83 Im(Z)=-.2016E-2 nlXC=-5.536 lXC=-10.67 So=-2.232

Extended information can be also found in the output activating in the input the <code>[[Variables#ExtendOut|ExtendOut]]</code> flag. This is an optional flag that can be activated by adding the <code>-V qp</code> verbosity option when building the input file. The plasmon pole screening, exchange self-energy and the quasiparticle energies are also saved in databases so that they can be reused in further runs:

$ ls ./10b_1Ry
ndb.pp ndb.pp_fragment_1 ... ndb.HF_and_locXC ndb.QP

===Convergence tests for a quasi particle calculation===

Now we can check the convergence of the different variables entering in the expression of the correlation part of the self energy. 
First, we focus on the parameter governing the ''screening matrix'' you have already seen in the [[RPA/IP]] section. In contrast to the calculation of the [[RPA/IP]] dielectric function, where you considered either the optical limit or a finite q response (EELS), here the dielectric matrix will be calculated for ''all'' q-points determined by the choice of k-point sampling.

The parameters that need to be converged can be understood by looking at expression of the dielectric matrix:
[[File:Yambo-CH5.png|none|x30px|Yambo tutorial image]]
where ''χGG''' is given by
[[File:Dyson_rpa.png|none|x40px|Yambo tutorial image]]
and χ0GG' is given by
[[File:ChiO.png|none|x45px|Yambo tutorial image]]
* <code>[[Variables#NGsBlkXp|NGsBlkXp]]</code> : The dimension of the microscopic inverse matrix, related to [[Local fields]]
* <code>[[Variables#BndsRnXp|BndsRnXp]]</code> : The sum on bands (c,v) in the independent particle χ0GG'

====Converging Screening Parameters====
Here we will check the convergence of the gap starting from the variables controlling the screening reported above: the bands employed to build the RPA response function <code>[[Variables#BndsRnXp|BndsRnXp]]</code> and the number of blocks (G,G') of the dielectric matrix ε-1G,G' <code>[[Variables#NGsBlkXp|NGsBlkXp]]</code>.
In the next section we will study convergence with respect to the sum over states summation (sum over ''m'' in the Σc expression); here let's fix <code>[[Variables#GbndRnge|GbndRnge]]</code> to a reasonable value (40 Ry).

Let's build a series of input files differing by the values of bands and block sizes in χ0GG' considering <code>[[Variables#BndsRnXp|BndsRnXp]]</code> in the range 10-50 (upper limit) and <code>[[Variables#NGsBlkXp|NGsBlkXp]]</code> in the range 1 to 5 Ry. To do this by hand, file by file, open the ''gw_ppa.in'' file in an editor and change to:
[[Variables#NGsBlkXp|NGsBlkXp]] = '''2 Ry'''
while leaving the rest untouched. Repeat for 3 Ry, 4 Ry etc. Next, for each <code>[[Variables#NGsBlkXp|NGsBlkXp]]</code> change to:
% [[Variables#BndsRnXp|BndsRnXp]]
1 | 20 | # [Xp] Polarization function bands
%
and repeat for 30, 40 and so on. Give a '''different name''' to each file: ''gw_ppa_Xb_YRy.in'' with X=10,20,30,40 and Y=1,2,3,4,5 Ry.

This is obviously quite tedious. However, you can automate both the input construction and code execution using bash or python scripts (indeed later you will learn how to use the the yambo-python [http://www.yambo-code.org/wiki/index.php?title=GW_tutorial._Convergence_and_approximations_(BN)]tool for this task). For now, you can use the simple [[bash_scripts|generate_inputs_1.sh]] bash script to generate the required input files (after copying the script you need to type <code>$ chmod +x name_of_the_script.sh </code>).

Finally launch the calculations:

$ yambo -F gw_ppa_10b_1Ry.in -J 10b_1Ry
$ yambo -F gw_ppa_10b_2Ry.in -J 10b_2Ry
...
$ yambo -F gw_ppa_40b_5Ry.in -J 40b_5Ry

Once the jobs are terminated we can collect the quasiparticle energies for fixed <code>[[Variables#BndsRnXp|BndsRnXp]]</code> in different files named e.g. ''10b.dat, 20b.dat'' etc. for plotting, by putting in separate columns: the energy cutoff; the size of the G blocks; the quasiparticle energy of the valence band; and that of the conduction band.
To do this e.g. for the ''10b.dat'' file you can type:
$ cat o-10b* | grep "8.000" | awk '{print $3+$4}'
to parse the valence band quasiparticle energies and
$ cat o-10b* | grep "9.000" | awk '{print $3+$4}'
for the conduction band; and put all the data in the ''10b.dat'' files. As there are many files to process you can use the [[bash_scripts|parse_qps.sh]] script to create the ''10b.dat'' file and edit the script changing the number of <code>[[Variables#BndsRnXp|BndsRnXp]]</code> for the other output files.

Once we have collected all the quasiparticle values we can plot the gap, or the valence and conduction band energies separately, as a function of the block size or energy cutoff:
$ gnuplot
gnuplot> p "10b.dat" u 1:3 w lp t " Valence BndsRnXp=10", "20b.dat" u 1:3 w lp t "Valence BndsRnXp=20",..
gnuplot> p "10b.dat" u 1:4 w lp t " Conduction BndsRnXp=10", "20b.dat" u 1:4 w lp t "Conduction BndsRnXp=20",..
gnuplot> p "10b.dat" u 1:($4-$3) w lp t " Gap BndsRnXp=10", "20b.dat" u 1:($4-$3) w lp t "gap BndsRnXp=20",..
or both using e.g. the [[gnuplot_scripts|ppa_gap.gnu]] gnuplot script:

<gallery mode=nolines widths=500px heights=500px perrow=1 caption="Quasiparticle energies with respect screening parameters">
File:ppa2.png|Valence band energy wrt <code>[[Variables#BndsRnXp|BndsRnXp]]</code> and <code>[[Variables#NGsBlkXp|NGsBlkXp]]</code>.
File:ppa3.png|Conduction band energy wrt <code>[[Variables#BndsRnXp|BndsRnXp]]</code> and <code>[[Variables#NGsBlkXp|NGsBlkXp]]</code>.
</gallery>

[[File:ppa1.png|center|600px|caption]]

Looking at the plot we can see that:
* The two parameters are not totally independent (see e.g. the valence quasiparticle convergence) and this is the reason why we converged them simultaneously
* The gap (energy difference) converge faster than single quasiparticle state
* The convergence criteria depends on the degree of accuracy we look for, but considering the approximations behind the calculations (plasmon-pole etc.), it is not always a good idea to enforce too strict a criteria.
* Even if not totally converged we can consider that the upper limit of <code>[[Variables#BndsRnXp|BndsRnXp]]</code>=30, and <code>[[Variables#NGsBlkXp|NGsBlkXp]]</code>=3Ry are reasonable parameters.

Finally notice that in the last versions of Yambo 4.5 etc. there is a terminator for the dielectric constant that accelerates convergence on the number of bands,
you can active it with the <code>-V resp</code> verbosity and setting <code>XTermKind= "BG"</code>. You can compare the converge of the dielectric constant with and without terminator,
similar to what happens for the self-energy, see next section.

====Converging the sum over states in the correlation self-energy====
From now on we will keep fixed these parameters and will perform a convergence study on the sum over state summation in the correlation self-energy (Σc) <code>[[Variables#GbndRnge|GbndRnge]]</code>.

In order to use the screening previously calculated we can copy the plasmon pole parameters saved in the <code>30b_3Ry</code> directory in the <code>SAVE</code> directory. In this way the screening will be read by Yambo and not calculated again:

$ cp ./30b_3Ry/ndb.pp* ./SAVE/.

(Note: you may have to delete these files before running the BSE tutorials)

In order to use the databases we have to be sure to have the same plasmon-pole parameters in our input files.
Edit ''gw_ppa_30b_3Ry.in'' and modify <code>[[Variables#GbndRnge|GbndRnge]]</code> to order to have a number of bands in the range from 10 to 80 inside different files named ''gw_ppa_Gbnd10.in'', ''gw_ppa_Gbnd20.in'' etc. You can also run the the [[bash_scripts|generate_inputs_2.sh]] bash script to generate the required input files.

Next, launch yambo for each input:

$ yambo -F gw_ppa_Gbnd10.in -J Gbnd10
$ yambo -F gw_ppa_Gbnd20.in -J Gbnd20
...

and as done before we can inspect the obtained quasiparticle energies:

$ grep 8.00 o-Gbnd* | awk '{print $4+$5}'
for the valence bands, and
$ grep 9.00 o-Gbnd* | awk '{print $4+$5}'
for the conduction band.

Collect the results in a text file ''Gbnd_conv.dat'' containing: the number of Gbnd, the valence energy, and the conduction energy.
Now, as done before we can plot the valence and conduction quasiparticle levels separately as well as the gap, as a function of the number of bands used in the summation:

$ gnuplot
gnuplot> p "Gbnd_conv.dat" u 1:2 w lp lt 7 t "Valence"
gnuplot> p "Gbnd_conv.dat" u 1:3 w lp lt 7 t "Conduction"
gnuplot> p "Gbnd_conv.dat" u 1:($3-$2) w lp lt 7 t "Gap"

<gallery mode=nolines widths=500px heights=500px perrow=2 caption="Quasiparticle energies with respect sum over states in correlation self-energy">
File:Gbnd_val.png|Valence band energy wrt <code>[[Variables#GbndRange|GbndRange]]</code>.
File:Gbnd_cond.png|Conduction band energy wrt <code>[[Variables#GbndRange|GbndRange]]</code>
</gallery>

[[File:Gbnd_gap.png|center|600px|caption]]

Inspecting the plot we can see that:
* The convergence with respect to <code>[[Variables#GbndRange|GbndRange]]</code> is rather slow and many bands are needed to get converged results.
* As observed above the gap (energy difference) converges faster than the single quasiparticle state energies.

====Accelerating the sum over states convergence in the correlation self-energy====
In general the convergence with respect the sum over states can be very cumbersome. Here we show how it can be mitigated by using
a technique developed by F. Bruneval and X. Gonze <ref name="BG"> F. Bruneval and X. Gonze, Physical Review B 78, 085125 (2008 )</ref>. The basic idea relies in replacing the eigenenergies of the states that are not treated explicitly by a common energy, and take into account all the states, which are not explicitly included in the calculation through the closure relation.
To apply this technique in Yambo we need to activate the optional terminator variable [[Variables#GTermKind|GTermKind]]. We can activate it by adding the quasiparticle verbosity to the command line when generating the input file:

$ yambo -p p -g n -F gw_ppa_Gbnd10.in -V qp

and you can edit the input file by setting:

[[Variables#GTermKind|GTermKind]]= "BG"

or simply you can add by hand this line in all the other ''gw_ppa_GbndX.in'' input files.
Now we can repeat the same calculations

$ yambo -F gw_ppa_Gbnd10.in -J Gbnd10_term
$ yambo -F gw_ppa_Gbnd20.in -J Gbnd20_term
...

and collect the new results:

$ grep 8.000 *term.qp | awk '{print $4+$5}'
$ grep 9.000 *term.qp | awk '{print $4+$5}'

in a new file called ''Gbnd_conv_terminator.dat''. Now we can plot the same quantities as before by looking at the effect of having introduced the terminator.

gnuplot
gnuplot> p "Gbnd_conv.dat" u 1:2 w lp t "Valence", "Gbnd_conv_terminator.dat" u 1:2 w lp t "Valence with terminator"
gnuplot> p "Gbnd_conv.dat" u 1:3 w lp t "Conduction", "Gbnd_conv_terminator.dat" u 1:3 w lp t "Conduction with terminator"
gnuplot> p "Gbnd_conv.dat" u 1:($3-$2) w lp t "Gap", "Gbnd_conv_terminator.dat" u 1:($3-$2) w lp t "Gap with terminator"

<gallery mode=nolines widths=500px heights=500px perrow=2 caption="Effect of the terminator in convergence of QP energies with respect sum over states">
File:val_t.png|Valence band energy wrt <code>[[Variables#GbndRange|GbndRange]]</code> with and without the terminator technique <ref name="BG" />
File:cond_t.png|Conduction band energy wrt <code>[[Variables#GbndRange|GbndRange]]</code> with and without the terminator technique<ref name="BG" />
</gallery>

[[File:gap_t.png|center|600px|caption]]

We can see that:
* The convergence with respect to <code>[[Variables#GbndRange|GbndRange]]</code> is accelerated in particular for the single quasiparticle states.
* From the plot above we can see that <code>[[Variables#GbndRange|GbndRange]]</code>=40 is sufficient to have a converged gap

===Beyond the plasmon pole approximation: a full frequency approach - real axis integration===
All the calculations performed up to now were based on the plasmon pole approximation (PPA). Now we remove this approximation by evaluating numerically the frequency integral in the expression of the correlation self-energy (Σc). To this aim we need to evaluate the screening for a number of frequencies in the interval depending on the electron-hole energy difference (energy difference between empty and occupied states) entering in the sum over states.
Let's build the input file for a full frequency calculation by simply typing:

$ yambo -F gw_ff.in -g n

and we can set the variable studied up to now at their converged value:

%[[Variables#BndsRnXd|BndsRnXd]]
1 | 30 |
%
[[Variables#NGsBlkXd|NGsBlkXd]]=3 Ry
%[[Variables#GbndRange|GbndRange]]
1 | 40 |
%
[[Variables#EXXRLvcs|EXXRLvcs]]=40 Ry
% [[Variables#LongDrXd|LongDrXd]]
1.000000 | 1.000000 | 1.000000 | # [Xd] [cc] Electric Field
%
%QPkrange # # [GW] QP generalized Kpoint/Band indices
7|7|8|9|
%

and next vary in different files (name them ''gw_ff10.in'' etc.) the number of frequencies we evaluate for the screened coulomb potential. This is done by setting the values of [[Variables#ETStpsXd|ETStpsXd]]=10 , 50 , 100, 150, 200, 250.
You can also run the the [[bash_scripts|generate_inputs_3.sh]] bash script to generate the required input files.

Next launch yambo:
$ yambo -F gw_ff10.in -J ff10
$ yambo -F gw_ff50.in -J ff50
...

Clearly as we are evaluating the screening for a large number of frequencies these calculations will be heavier than the case above where the calculation of the screening was done for only two frequencies (zero and plasmon-pole).
As before, collect the valence and conduction bands as a function of the number of frequencies in a file called ''gw_ff.dat'' and plot the behaviour of the conduction and valence bands and the gap.

$ gnuplot
gnuplot> p "gw_ff.dat" u 1:2 w lp t "Valence"
gnuplot> p "gw_ff.dat" u 1:3 w lp t "Conduction"
gnuplot> p "gw_ff.dat" u 1:($3-$2) w lp t "Gap"

<gallery mode=nolines widths=500px heights=500px perrow=2 caption="Real axis integration, convergences with respect the used number of frequencies">
File:ff_v.png|Valence band energy wrt <code>[[Variables#ETStpsXd|ETStpsXd]]</code>
File:ff_c.png|Conduction band energy wrt <code>[[Variables#ETStpsXd|ETStpsXd]]</code>
</gallery>

[[File:ff_g.png|center|600px|caption]]

We can see that:

* Oscillations are still present, indicating that even more frequencies have to be considered. In general, a real-axis calculation is very demanding.
* The final result of the gap obtained up to now does not differ too much from the one obtained at the plasmon-pole level (~50 meV)

===Secant Solver===

The real axis integration permits also to go beyond the linear expansion to solve the quasi particle equation.
The QP equation is a non-linear equation whose solution must be found using a suitable numerical algorithm.
[[File:Eqp_sec.png|none|x22px|caption]]
The mostly used, based on the linearization of the self-energy operator is the Newton method that is the one we have used up to now.
Yambo can also perform a search of the QP energies using a non-linear iterative method based on the [https://en.wikipedia.org/wiki/Secant_method Secant iterative Method].

In numerical analysis, the secant method is a root-finding algorithm that uses a succession of roots of secant lines to better approximate a root of a function ''f''. The secant method can be thought of as a finite difference approximation of Newton's method.
The equation that defines the secant method is:

[[File:secant_eq.png|none|x35px|caption]]

The first two iterations of the secant method are shown in the following picture. The red curve shows the function f and the blue lines are the secants.

[[File:Secant_method.png|center|250px|caption]]

To see if there is any non-linear effect in the solution of the Dyson equation we compare the result of the calculation using the Newton solver as done before with the present case.
In order to use the secant method you need to edit one of the the previous ''gw_ffN.in'' files e.g. ''gw_ff100.in'' and substitute:

DysSolver= "g"
to
DysSolver= "s"

Repeat the calculations in the same way as before:

$ yambo -F gw_ff100.in -J ff100

Note than now the screening will ''not'' be calculated again as it has been stored in the ''ffN'' directories as can be seen in the report file:

[05] Dynamical Dielectric Matrix
================================
[RD./ff10//ndb.em1d]----
...
[RD./ff10//ndb.em1d_fragment_1]--------------
...

Comparing the output files, e.g. for the case with 100 freqs:

''o-ff100.qp'' '''Newton Solver:'''
# K-point Band Eo E-Eo Sc|Eo
#
7.00000 8.00000 -0.41188 -0.08708 2.91254
7.00000 9.00000 3.877976 1.421968 -3.417357

''o-ff100.qp_01'' '''Secant Solver:'''
#
# K-point Band Eo E-Eo Sc|Eo
#
7.00000 8.00000 -0.41188 -0.08715 2.93518
7.00000 9.00000 3.877976 1.401408 -3.731649

From the comparison, we see that the effect is of the order of 20 meV, of the same order of magnitude of the accuracy of the GW calculations.

==Step 3: Interpolating Band Structures==
Up to now we have checked convergence for the gap. Now we want to calculate the quasiparticle corrections across the Brillouin zone in order to visualize the entire band structure along a path connecting high symmetry points.

To do that we start by calculating the QP correction in the plasmon-pole approximation for all the k points of our sampling and for a number of bands around the gap. You can use a previous input file or generate a new one: <code> yambo -F gw_ppa_all_Bz.in -x -p p -g n </code> and set the parameters found in the previous tests:

EXXRLvcs= 40 Ry
% BndsRnXp
1 | 30 | # [Xp] Polarization function bands
%
NGsBlkXp= 3 Ry # [Xp] Response block size
% LongDrXp
1.000000 | 1.000000 | 1.000000 | # [Xp] [cc] Electric Field
%
PPAPntXp= 27.21138 eV # [Xp] PPA imaginary energy
% GbndRnge
1 | 40 | # [GW] G[W] bands range
%

and we calculate it for all the available kpoints by setting:
%QPkrange # [GW] QP generalized Kpoint/Band indices
1| 14| 6|11|
%

Note that as we have already calculated the screening with these parameters you can save time and use that database either by running in the previous directory by using <code> -J 30b_3Ry </code> or if you prefer to put the new databases in the new all_Bz directory you can create a new directory and copy there the screening databases:

$ mkdir all_Bz
$ cp ./30b_3Ry/ndb.pp* ./all_Bz/

and launch the calculation:

$ yambo -F gw_ppa_all_Bz.in -J all_Bz

Now we can inspect the output and see that it contains the correction for all the k points for the bands we asked:

# K-point Band Eo E-Eo Sc|Eo
#
1.000000 6.000000 -1.299712 -0.219100 3.788044
1.000000 7.000000 -1.296430 -0.241496 3.788092
1.000000 8.000000 -1.296420 -0.243115 3.785947
1.000000 9.000000 4.832399 0.952386 -3.679259
1.00000 10.00000 10.76416 2.09915 -4.38743
1.00000 11.00000 11.36167 2.48053 -3.91021
....
By plotting some of the 'o-all_Bz.qp" columns it is possible to discuss some physical properties of the hBN QPs. Using columns 3 and (3+4), ie plotting the GW energies with respect to the LDA energies we can deduce the band gap renormalization and the stretching of the conduction/valence bands:

$ gnuplot
gnuplot> p "o-all_Bz.qp" u 3:($3+$4) w p t "Eqp vs Elda"

[[File:EqpvE0.png|center|350px|caption]]

Essentially we can see that the effect of the GW self-energy is the opening of the gap and a linear stretching of the conduction/valence bands that can be estimated by performing a linear fit of the positive and negative energies (the zero is set at top of the valence band).

In order to calculate the band structure, however, we need to interpolate the values we have calculated above on a given path. In Yambo the interpolation is done by the executable <code>ypp</code> (Yambo Post Processing).
By typing:
$ ypp -H
you will recognize that in order to interpolate the bands we need to build a ypp input file using
$ ypp -s b

we can generate the input for the band interpolation:

$ypp -s b -F ypp_bands.in

and edit the ''ypp_bands.in'' file:

electrons # [R] Electrons (and holes)
bnds # [R] Bands
INTERP_mode= "NN" # Interpolation mode (NN=nearest point, BOLTZ=boltztrap aproach)
OutputAlat= 4.716000 # [a.u.] Lattice constant used for "alat" ouput format
cooIn= "rlu" # Points coordinates (in) cc/rlu/iku/alat
cooOut= "rlu"
% BANDS_bands
1 | 100 | # Number of bands
%
% INTERP_Grid
-1 |-1 |-1 | # Interpolation BZ Grid
%
INTERP_Shell_Fac= 20.00000 # The bigger it is a higher number of shells is used
CIRCUIT_E_DB_path= "none" # SAVE obtained from the QE `bands` run (alternative to %BANDS_kpts)
BANDS_path= "" # BANDS path points labels (G,M,K,L...)
BANDS_steps= 10
#BANDS_built_in # Print the bands of the generating points of the circuit using the nearest internal point
%BANDS_kpts
%

We modify the following lines:
BANDS_steps=30
% BANDS_bands
6 | 11 | # Number of bands
%
%BANDS_kpts # K points of the bands circuit
0.33300 |-.66667 |0.00000 |
0.00000 |0.00000 |0.00000 |
0.50000 |-.50000 |0.00000 |
0.33300 |-.66667 |0.00000 |
0.33300 |-.66667 |0.50000 |
0.00000 |0.00000 |0.50000 |
0.50000 |-.50000 |0.50000 |
%

which means we assign 30 points in each segment, we ask to interpolate 3 occupied and 3 empty bands and we assign the following path passing from the high symmetry points: K Γ M K H A L.
Launching:
$ ypp -F ypp_bands.in
will produce the output file ''o.bands_interpolated'' containing:

#
# |k| b6 b7 b8 b9 b10 b11 kx ky kz
#
#
0.00000 -7.22092 -0.13402 -0.13395 4.67691 4.67694 10.08905 0.33300 -0.66667 0.00000
0.03725 -7.18857 -0.17190 -0.12684 4.66126 4.71050 10.12529 0.32190 -0.64445 0.00000
...

and we can plot the bands using gnuplot:
$ gnuplot
gnuplot> p "o.bands_interpolated" u 0:2 w l, "o.bands_interpolated" u 0:3 w l, ...

[[File:bands_lda.png|center|350px|caption]]

and you can recognize the index of the high symmetry point by inspecting the last three columns.
Note that up to now we have interpolated the LDA band structure. In order to plot the GW band structure, we need to tell <code>ypp</code> in the input file where the ''ndb.QP'' database is found. This is achieved by adding in the ''ypp_bands.in'' file the line:

GfnQPdb= "E < ./all_Bz/ndb.QP"

and relaunch

$ ypp -F ypp_bands.in

Now the file ''o.bands_interpolated_01'' contains the GW interpolated band structure. We can plot the LDA and GW band structure together by using the gnuplot script [[gnuplot_scripts|bands.gnu]].

<gallery mode=nolines widths=500px heights=500px perrow=2 caption="Band strcuture of bulk hBN">
File:hBN_bands.png| LDA and GW bands structure
File:hBN_bands_lit.png| LDA and GW bands structure from Ref. <ref name="Arnaud" />
</gallery>

*As expected the effect of the GW correction is to open the gap.
*Comparing the obtained band structure with the one found in the literature by Arnaud and coworkers <ref name="Arnaud"> B. Arnaud, S. Lebegue,P. Rabiller, and M. Alouani Phys, Rev. Lett. 96, 026402 (2006)</ref> we found a very nice qualitative agreement.
*Quantitatively we found a smaller gap: about 5.2 eV (indirect gap), 5.7 eV (direct gap) while in Ref.<ref name="Arnaud" /> is found 5.95 eV for the indirect gap and a minimum direct band gap of 6.47 eV. Other values are also reported in the literature depending on the used pseudopotentials, starting functional and type of self-consistency (see below).
*The present tutorial has been done with a small k point grid which is an important parameter to be checked, so convergence with respect the k point sampling has to be validated.

==Step 4: Summary of the convergence parameters==
We have calculated the band structure of hBN starting from a DFT calculation, here we summarize the main variable we have checked to achieve convergence:

* <code>[[Variables#EXXRLvcs|EXXRLvcs]]</code> # [XX] Exchange RL components
Number of G-vectors in the exchange. This number should be checked carefully. Generally a large number is needed as the QP energies show a slow convergence. The calcualtion of the exchange part is rather fast.

*<code>[[Variables#BndsRnXp|BndsRnXp]]</code> #[Xp] Polarization function bands
Number of bands in the independent response function form which the dielectric matrix is calculated. Also this paramater has to be checked carefully,together with NGsBlkXp as the two variables are interconnected

*<code>[[Variables#NGsBlkXp|NGsBlkXp]]</code> # [Xp] Response block size
Number of G-vectors block in the dielectric constant. Also this paramater has to be checked carefully, to be checked together with BndsRnXp. A large number of bands and block can make the calculation very demanding.

*<code>[[Variables#LongDrXp|LongDrXp]] </code> # [Xp] [cc] Electric Field
Direction of the electric field for the calculation of the q=0 component of the dielectric constant e(q,w). In a bulk can be set to (1,1,1), attention must be paid for non 3D systems.

*<code>[[Variables#PPAPntXp|PPAPntXp]] </code> # [Xp] Plasmon pole imaginary energy: this is the second frequency used to fit the Godby-Needs plasmon-pole model (PPM). If results depend consistently by changing this frequency, the PPM is not adequate for your calculation and it is need to gp beyond that, e.g. Real-axis.

*<code>[[Variables#GbndRnge|GbndRnge]] </code> # [GW] G[W] bands range
Number of bands used to expand the Green's function. This number is usually larger than the number of bands used to calculated the dielectricconstant. Single quasiparticle energies converge slowly with respect GbndRnge, energy difference behave better. You can use terminator technique to mitigate the slow dependence.

*<code>[[Variables#GDamping|GDamping]] </code> # [GW] G[W] damping
Small damping in the Green's function definition, the delta
parameter. The final result shouuld not depend on that, usually set at 0.1 eV

*<code>[[Variables#dScStep|dScStep]] </code> # [GW]
Energy step to evaluate Z factors

*<code>[[Variables#DysSolver|DysSolver]] </code> # [GW] Dyson Equation solver ("n","s","g")
Parameters related to the solution of the Dyson equation, "n" Newton linearization, 's' non linear secant method

*<code>[[Variables#GTermKind|GTermKind]] </code> [GW] GW terminator
Terminator for the self-energy<ref name="BG" /> . We have seen how this spped up the convergence with respect empty bands.

*<code>[[Variables#%QPkrange |QPkrange ]] </code> # [GW] QP generalized Kpoint/Band indices
K-points and band range where you want to calculate the GW correction. The syntax is
first kpoint | last kpoint | first band | last band

==Step 5: Eigenvalue only self-consistent evGW0 and evGW (only available in Yambo 4.6) ==
Here we want to see how we can compute an eigenvalue only evGW0 or evGW correction in Yambo. In the new version of Yambo there are two flags for these kind of self-consistency:

<code>[[Variables#GWoIter|GWoIter]]</code> number of GW0 iterations

<code>[[Variables#GWoIter|GWIter]]</code> number of GW iterations

you can set one of them to 10 for example, the code will stop when convergence is reached, usually in less than 5 iterations.
For example if you consider the input file below:

HF_and_locXC # [R XX] Hartree-Fock Self-energy and Vxc
ppa # [R Xp] Plasmon Pole Approximation
gw0 # [R GW] GoWo Quasiparticle energy levels
em1d # [R Xd] Dynamical Inverse Dielectric Matrix
EXXRLvcs = 40.000 mRy # [XX] Exchange RL components
VXCRLvcs = 3187 RL # [XC] XCpotential RL components
Chimod= "Hartree" # [X] IP/Hartree/ALDA/LRC/BSfxc
% BndsRnXp
1 | 10 | # [Xp] Polarization function bands
%
NGsBlkXp= 1000 mRy # [Xp] Response block size
% LongDrXp
1.000000 | 1.000000 | 1.000000 | # [Xp] [cc] Electric Field
%
PPAPntXp = 27.21138 eV # [Xp] PPA imaginary energy
%GbndRnge
1 | 40 | # [GW] G[W] bands range
%
GDamping= 0.10000 eV # [GW] G[W] damping
dScStep= 0.10000 eV # [GW] Energy step to evaluate Z factors
DysSolver= "n" # [GW] Dyson Equation solver ("n","s","g")
GWoIter=0 # [GW] GWo self-consistent (evGWo) iterations on eigenvalues
GWIter =0 # [GW] GW self-consistent (evGW) iterations on eigenvalues
%QPkrange # [GW] QP generalized Kpoint/Band indices
1| 14| 7| 10|
%
if you set both GWIter and GWoIter to zero you get a gap correction of 4.15 eV.
If you perform self-consistency on G (GWoIter/=)
the gap will be 4.713 eV and finally if you perform
self-consistency in both G and W (GWIter /=0) the gap will be 5.506 eV.

Notice that these values are absolutelly not converged because we used very few
bands and a small block size.

It's important to note that the final result of the self-consistent GW may
depend from the number of bands you decide to correct, because they are used
to reconstruct G and W. For the non-corrected bands Yambo applied a rigid shift
of their energy based on the closed corrected band.

==Step 6: A better integration of the q=0 point ==

The integration of the q=0 of the Coulomb potential is problematic because the 1/q diverges.
Usually in Yambo this integration is performed analytically in a small sphere around q=0.

[[File:Circle box.gif|center|frame]]

however in this way the code lost part of the integral out of the circle. This usually
is not problematic because for a large number of q and k point the missing term goes to zero.
However in system that requires few k-points or even only the gamma one, it is possible
to perform a better integration of this term by adding the flag -r to generate the input

HF_and_locXC # [R XX] Hartree-Fock Self-energy and Vxc
ppa # [R Xp] Plasmon Pole Approximation
gw0 # [R GW] GoWo Quasiparticle energy levels
rim_cut # [R] Coulomb potential
em1d # [R Xd] Dynamical Inverse Dielectric Matrix
RandQpts= 3000000 # [RIM] Number of random q-points in the BZ
RandGvec= 1 RL # [RIM] Coulomb interaction RS components
#QpgFull # [F RIM] Coulomb interaction: Full matrix
EXXRLvcs = 40.000 mRy # [XX] Exchange RL components
VXCRLvcs = 3187 RL # [XC] XCpotential RL components
Chimod= "Hartree" # [X] IP/Hartree/ALDA/LRC/BSfxc
% BndsRnXp
1 | 10 | # [Xp] Polarization function bands
%
NGsBlkXp= 1000 mRy # [Xp] Response block size
% LongDrXp
1.000000 | 1.000000 | 1.000000 | # [Xp] [cc] Electric Field
%
PPAPntXp = 27.21138 eV # [Xp] PPA imaginary energy
%GbndRnge
1 | 40 | # [GW] G[W] bands range
%
GDamping= 0.10000 eV # [GW] G[W] damping
dScStep= 0.10000 eV # [GW] Energy step to evaluate Z factors
DysSolver= "n" # [GW] Dyson Equation solver ("n","s","g")
%QPkrange # [GW] QP generalized Kpoint/Band indices
7| 7| 8| 9|
%

in this input <code>[[Variables#RandGvec|RandGvec]]</code> is the component of the Coulomb potential we want integrate numerically,
in this case only the first one G=G'=0, and <code>[[Variables#RandQpts|RandQpts]]</code> is the number of random points
used to perform the integral by Monte Carlo.

If you turn one this integration you will get a slightly different band gap,
but in the limit of large k points the final results will be the same of the standard method.

However this correction is important for systems that converge with few k-points or with gamma only.

==Step 7: Taking into account the material anisotropy (only available in Yambo 4.6) ==

Hexagonal Boron Nitride is an anisotropic material so there is the question in which direction
one shold calculate the dielectric constant the enters in the GW.
If you run again this tutorial changing the direction of the q=0 point in GW calculation,
the variable <code>[[Variables#LongDrXp|LongDrXp]]</code>, you will realize that the there gap correction changes.
In Yambo there is a way to take into account this anisitropy of the dielectri tensor.

First of all you need to calculate the dielectric constant in the three cartesian directions with the command <code> yambo -o c -k hartree</code>

optics # [R] Linear Response optical properties
kernel # [R] Kernel
chi # [R][CHI] Dyson equation for Chi.
dipoles # [R] Oscillator strenghts (or dipoles)
Chimod= "HARTREE" # [X] IP/Hartree/ALDA/LRC/PF/BSfxc
NGsBlkXd= 3000 mRy # [Xd] Response block size
% QpntsRXd
1 | 1 | # [Xd] Transferred momenta
%
% BndsRnXd
1 | 100 | # [Xd] Polarization function bands
%
% EnRngeXd
0.00000 | 10.00000 | eV # [Xd] Energy range
%
% DmRngeXd
0.10000 | 0.10000 | eV # [Xd] Damping range
%
ETStpsXd= 1 # [Xd] Total Energy steps
% LongDrXd
1.000000 | 0.000000 | 0.000000 | # [Xd] [cc] Electric Field
%

In the output file <code> o.eps_q1_inv_rpa_dyson</code> you will find the real-part of the zero component of inverse dielectric matrix, in this case 5.044076.

Repeat this calculation with the field in the other two directions y and z. The y-direction is equal to x, while in z direction the zero component of the inverse dielectric matrix is 2.872451.

Now generate a new input file for the GW, with the command <code> yambo -g n -p p -r -V RL</code>

HF_and_locXC # [R XX] Hartree-Fock Self-energy and Vxc
ppa # [R Xp] Plasmon Pole Approximation
gw0 # [R GW] GoWo Quasiparticle energy levels
rim_cut # [R] Coulomb potential
em1d # [R Xd] Dynamical Inverse Dielectric Matrix
RandQpts=3000000 # [RIM] Number of random q-points in the BZ
RandGvec= 1 RL # [RIM] Coulomb interaction RS components
#QpgFull # [F RIM] Coulomb interaction: Full matrix
% Em1Anys
5.044076 | 5.044076 | 2.872451 | # [RIM] X Y Z Static Inverse dielectric matrix
%
IDEm1Ref= 1
EXXRLvcs = 40.000 mRy # [XX] Exchange RL components
VXCRLvcs = 3187 RL # [XC] XCpotential RL components
Chimod= "Hartree" # [X] IP/Hartree/ALDA/LRC/BSfxc
% BndsRnXp
1 | 10 | # [Xp] Polarization function bands
%
NGsBlkXp= 1000 mRy # [Xp] Response block size
% LongDrXp
1.000000 | 0.000000 | 0.000000 | # [Xp] [cc] Electric Field
%
PPAPntXp = 27.21138 eV # [Xp] PPA imaginary energy
%GbndRnge
1 | 40 | # [GW] G[W] bands range
%
GDamping= 0.10000 eV # [GW] G[W] damping
dScStep= 0.10000 eV # [GW] Energy step to evaluate Z factors
DysSolver= "n" # [GW] Dyson Equation solver ("n","s","g")
%QPkrange # [GW] QP generalized Kpoint/Band indices
7| 7| 8| 9|
%

run the calculations and you will find a correction of the gap intermediate between the one with the field in x and z directions.

==Step 8: Exercise: Convergence with respect K points==
As an exercise now you can check the convergence with respect the K point sampling:
# perform a new non-scf calculation with a bigger k point grid: 9x9x3 and 12x12x4 ...
# convert wave functions and electronic structure to Yambo databases in a different directory as explained in the [[Bulk material: h-BN|DFT and p2y module]],
# [[initialization |Initialize]] the Yambo databases,
# Redo the steps explained in this section (exchange self energy, plasmon pole GW, band structure interpolation)
# The PPA-GW calculation using 12x12x4 grid depending on your machine can take several minutes in serial mode. You can think to perform the exercise after having learned some basic on the parallelization strategy.

 
{| style="width:100%" border="1"
|style="width:15%; text-align:left"|Prev: [[Tutorials|Tutorials Home]]
|style="width:50%; text-align:center"|Now: [[Tutorials|Tutorials Home]] --> [[How_to_obtain_the_quasi-particle_band_structure_of_a_bulk_material:_h-BN|GW]]
|style="width:35%; text-align:right"|Next: If you did everything, choose another tutorial in the menu
|-
|}

==References==

How to obtain the quasi-particle band structure of a bulk material: h-BN

2020-11-19T12:43:15Z

Claudio: /* Step 7: Taking into account the material anisotropy (only available in Yambo 4.6) */

In this tutorial you will learn how to:
* Calculate quasi-particle corrections in the Hartree-Fock approximation
* Calculate quasi-particle corrections in the GW approximation
* Choose the input parameters for a meaningful converged calculation
* Plot a band structure including quasi-particle corrections
We will use bulk hBN as an example system. Before starting, you need to obtain the appropriate tarball. See instructions on the [[Tutorials|main tutorials page]]. 
We strongly recommend that you first complete the [[First steps: a walk through from DFT to optical properties]] tutorial.



The aim of the present tutorial is to obtain quasiparticle correction to energy levels using many-body perturbation theory (MBPT). 
The general non-linear quasiparticle equation reads:
[[File:Eqp_1.png|none|x26px|caption]]
As a first step we want to evaluate the self energy Σ entering in the quasiparticle equation. In the GW approach the self-energy can be separated into two components: a static term called the exchange self-energy (Σx), and a dynamical term (energy dependent) called the correlation self-energy (Σc):
[[File:Sigma.png|none|x25px|caption]]
We will treat these two terms separately and demonstrate how to set the most important variables for calculating each term.
In practice we will compute the quasi-particle corrections to the one particle Kohn-Sham eigenvalues obtained through a DFT calculation.

The steps are the following:

==Step 1: The Exchange Self Energy or HF quasi-particle correction==

We start by evaluating the exchange Self-Energy and the corresponding Quasiparticle energies (Hartree-Fock energies).
Follow the module on '''[[Hartree Fock]]''' and then return to this tutorial ''How to obtain the quasiparticle band structure of a bulk material: h-BN''.

==Step 2: The Correlation Self-Energy and Quasiparticle Energies==
Once we have calculated the exchange part, we next turn our attention to the more demanding dynamical part. The correlation part of the self-energy in a plane wave representation reads:
[[File:Sigma_c.png|none|x50px|caption]]
In the expression for the correlation self energy, we have (1) a summation over bands, (2) an integral over the Brillouin Zone, and (3) a sum over the G vectors. In contrast with the case of Σx, the summation over bands extends over ''all'' bands (including the unoccupied ones), and so convergence tests are needed. Another important difference is that the Coulomb interaction is now screened so a fundamental ingredient is the evaluation of the dynamical dielectric matrix. The expression for the dielectric matrix, calculated at the RPA level and including local field effects, has been already treated in the [[Local fields|Local fields]] tutorial.

In the following, we will see two ways to take into account the dynamical effects. First, we will see how to set the proper parameters to obtain a model dielectric function based on a widely used approximation, which models the energy dependence of each component of the dielectric matrix with a single pole function.
Secondly, we will see how to perform calculations by evaluating the dielectric matrix on a regular grid of frequencies.

Once the correlation part of the self-energy is calculated, we will check the convergence of the different parameters with respect to some final quantity, such as the gap.

After computing the frequency dependent self-energy, we will discover that in order to solve the quasiparticle equation we will need to know its value ''at the value of the quasiparticle itself''. In the following, unless explicitly stated, we will solve the non-linear quasi-particle equation at first order, by expanding the self-energy around the Kohn-Sham eigenvalue. In this way the quasiparticle equation reads:

[[File:Eqp_2.png|none|x26px|caption]]

where the normalization factor Z is defined as:

[[File:z_fac.png|none|x40px|caption]]

===The Plasmon Pole approximation===
As stated above, the basic idea of the plasmon-pole approximation is to approximate the frequency dependence of the dielectric matrix with a single pole function of the form:
[[File:ppa.png|none|x26px|caption]]
The two parameters RGG' and ΩGG' are obtained by a fit (for each component), after having calculated the RPA dielectric matrix at two given frequencies.
Yambo calculates the dielectric matrix in the static limit ( ω=0) and at a user defined frequency called the plasmon-pole frequency (ω=iωp).
Such an approximation has the big computational advantage of calculating the dielectric matrix for only two frequencies and leads to an analytical expression for the frequency integral of the correlation self-energy.
==== Input file generation ====
Let's start by building up the input file for a GW/PPA calculation, including the calculation of the exchange self-energy. From <code>yambo -H</code> you should understand that the correct option is <code>yambo -x -p p -g n</code>:

$ cd YAMBO_TUTORIALS/hBN/YAMBO
$ yambo -x -p p -g n -F gw_ppa.in

Let's modify the input file in the following way:

HF_and_locXC # [R XX] Hartree-Fock Self-energy and Vxc
ppa # [R Xp] Plasmon Pole Approximation
gw0 # [R GW] GoWo Quasiparticle energy levels
em1d # [R Xd] Dynamical Inverse Dielectric Matrix
[[Variables#EXXRLvcs|EXXRLvcs]] = 40 Ry # [XX] Exchange RL components
[[Variables#VXCRLvcs|VXCRLvcs]] = 3187 RL # [XC] XCpotential RL components
Chimod= "Hartree" # [X] IP/Hartree/ALDA/LRC/BSfxc
% BndsRnXp
1 | 10 | # [Xp] Polarization function bands
%
[[Variables#NGsBlkXp|NGsBlkXp]]= 1000 mRy # [Xp] Response block size
% LongDrXp
1.000000 | 1.000000 | 1.000000 | # [Xp] [cc] Electric Field
%
[[Variables#PPAPntXp|PPAPntXp]] = 27.21138 eV # [Xp] PPA imaginary energy
%[[Variables#GbndRnge|GbndRnge]]
1 | 40 | # [GW] G[W] bands range
%
GDamping= 0.10000 eV # [GW] G[W] damping
dScStep= 0.10000 eV # [GW] Energy step to evaluate Z factors
DysSolver= "n" # [GW] Dyson Equation solver ("n","s","g")
%[[Variables#QPkrange|QPkrange]] # [GW] QP generalized Kpoint/Band indices
7| 7| 8| 9|
%

Brief explanation of some settings:
* Similar to the Hartree Fock study, we will concentrate on the convergence of the '''direct''' gap of the system. Hence we select the last occupied (8) and first unoccupied (9) bands for k-point number 7 in the <code>[[Variables#QPkrange|QPkrange]]</code> variable.
* We also keep <code>[[Variables#EXXRLvcs|EXXRLvcs]]</code> at its converged value of 40 Ry as obtained in the '''[[Hartree Fock]]''' tutorial.
* For the moment we keep fixed the plasmon pole energy <code>[[Variables#PPAPntXp|PPAPntXp]]</code> at its default value (=1 Hartree).
* We keep fixed the direction of the electric field for the evaluation of the dielectric matrix to a non-specific value: <code>[[Variables#LongDrXp|LongDrXp]]</code>=(1,1,1).
* Later we will study convergence with respect to <code>[[Variables#GbndRnge|GbndRnge]]</code>, <code>[[Variables#NGsBlkXp|NGsBlkXp]]</code>, and <code>[[Variables#BndsRnXp|BndsRnXp]]</code>; for now just set them to the values indicated.

==== Understanding the output ====
Let's look at the typical Yambo output. Run Yambo with an appropriate <code>-J</code> flag:

$ yambo -F gw_ppa.in -J 10b_1Ry

In the standard output you can recognise the different steps of the calculations: calculation of the screening matrix (evaluation of the non interacting and interacting response), calculation of the exchange self-energy, and finally the calculation of the correlation self-energy and quasiparticle energies. Moreover information on memory usage and execution time are reported:
...
<---> [05] Dynamic Dielectric Matrix (PPA)
...
<08s> Xo@q[3] |########################################| [100%] 03s(E) 03s(X)
<08s> X@q[3] |########################################| [100%] --(E) --(X)
...
<43s> [06] Bare local and non-local Exchange-Correlation
<43s> EXS |########################################| [100%] --(E) --(X)
...
<43s> [07] Dyson equation: Newton solver
<43s> [07.01] G0W0 (W PPA)
...
<45s> G0W0 (W PPA) |########################################| [100%] --(E) --(X)
...
<45s> [07.02] QP properties and I/O
<45s> [08] Game Over & Game summary

Let's have a look at the report and output. The output file ''o-10b_1Ry.qp'' contains (for each band and k-point that we indicated in the input file) the values of the bare KS eigenvalue, its GW correction and the correlation part of the self energy:
#
# K-point Band Eo E-Eo Sc|Eo
#
7.000000 8.000000 -0.411876 -0.567723 2.322443
7.000000 9.000000 3.877976 2.413773 -2.232241

In the header you can see the details of the calculations, for instance it reports that <code>[[Variables#NGsBlkXp|NGsBlkXp]]</code>=1 Ry corresponds to 5 Gvectors:

# X G`s [used]: 5

Other information can be found in the report file ''r-10b_1Ry_em1d_ppa_HF_and_locXC_gw0'', such as the renormalization factor defined above, the value of the ''exchange'' self-energy (non-local XC) and of the DFT exchange-correlation potential (local XC):

[07.02] QP properties and I/O
=============================
Legend (energies in eV):
- B : Band - Eo : bare energy
- E : QP energy - Z : Renormalization factor
- So : Sc(Eo) - S : Sc(E)
- dSp: Sc derivative precision
- lXC: Starting Local XC (DFT)
-nlXC: Starting non-Local XC (HF)
QP [eV] @ K [7] (iku): 0.000000 -0.500000 0.000000
B=8 Eo= -0.41 E= -0.98 E-Eo= -0.56 Re(Z)=0.81 Im(Z)=-.2368E-2 nlXC=-19.13 lXC=-16.11 So= 2.322
B=9 Eo= 3.88 E= 6.29 E-Eo= 2.41 Re(Z)=0.83 Im(Z)=-.2016E-2 nlXC=-5.536 lXC=-10.67 So=-2.232

Extended information can be also found in the output activating in the input the <code>[[Variables#ExtendOut|ExtendOut]]</code> flag. This is an optional flag that can be activated by adding the <code>-V qp</code> verbosity option when building the input file. The plasmon pole screening, exchange self-energy and the quasiparticle energies are also saved in databases so that they can be reused in further runs:

$ ls ./10b_1Ry
ndb.pp ndb.pp_fragment_1 ... ndb.HF_and_locXC ndb.QP

===Convergence tests for a quasi particle calculation===

Now we can check the convergence of the different variables entering in the expression of the correlation part of the self energy. 
First, we focus on the parameter governing the ''screening matrix'' you have already seen in the [[RPA/IP]] section. In contrast to the calculation of the [[RPA/IP]] dielectric function, where you considered either the optical limit or a finite q response (EELS), here the dielectric matrix will be calculated for ''all'' q-points determined by the choice of k-point sampling.

The parameters that need to be converged can be understood by looking at expression of the dielectric matrix:
[[File:Yambo-CH5.png|none|x30px|Yambo tutorial image]]
where ''χGG''' is given by
[[File:Dyson_rpa.png|none|x40px|Yambo tutorial image]]
and χ0GG' is given by
[[File:ChiO.png|none|x45px|Yambo tutorial image]]
* <code>[[Variables#NGsBlkXp|NGsBlkXp]]</code> : The dimension of the microscopic inverse matrix, related to [[Local fields]]
* <code>[[Variables#BndsRnXp|BndsRnXp]]</code> : The sum on bands (c,v) in the independent particle χ0GG'

====Converging Screening Parameters====
Here we will check the convergence of the gap starting from the variables controlling the screening reported above: the bands employed to build the RPA response function <code>[[Variables#BndsRnXp|BndsRnXp]]</code> and the number of blocks (G,G') of the dielectric matrix ε-1G,G' <code>[[Variables#NGsBlkXp|NGsBlkXp]]</code>.
In the next section we will study convergence with respect to the sum over states summation (sum over ''m'' in the Σc expression); here let's fix <code>[[Variables#GbndRnge|GbndRnge]]</code> to a reasonable value (40 Ry).

Let's build a series of input files differing by the values of bands and block sizes in χ0GG' considering <code>[[Variables#BndsRnXp|BndsRnXp]]</code> in the range 10-50 (upper limit) and <code>[[Variables#NGsBlkXp|NGsBlkXp]]</code> in the range 1 to 5 Ry. To do this by hand, file by file, open the ''gw_ppa.in'' file in an editor and change to:
[[Variables#NGsBlkXp|NGsBlkXp]] = '''2 Ry'''
while leaving the rest untouched. Repeat for 3 Ry, 4 Ry etc. Next, for each <code>[[Variables#NGsBlkXp|NGsBlkXp]]</code> change to:
% [[Variables#BndsRnXp|BndsRnXp]]
1 | 20 | # [Xp] Polarization function bands
%
and repeat for 30, 40 and so on. Give a '''different name''' to each file: ''gw_ppa_Xb_YRy.in'' with X=10,20,30,40 and Y=1,2,3,4,5 Ry.

This is obviously quite tedious. However, you can automate both the input construction and code execution using bash or python scripts (indeed later you will learn how to use the the yambo-python [http://www.yambo-code.org/wiki/index.php?title=GW_tutorial._Convergence_and_approximations_(BN)]tool for this task). For now, you can use the simple [[bash_scripts|generate_inputs_1.sh]] bash script to generate the required input files (after copying the script you need to type <code>$ chmod +x name_of_the_script.sh </code>).

Finally launch the calculations:

$ yambo -F gw_ppa_10b_1Ry.in -J 10b_1Ry
$ yambo -F gw_ppa_10b_2Ry.in -J 10b_2Ry
...
$ yambo -F gw_ppa_40b_5Ry.in -J 40b_5Ry

Once the jobs are terminated we can collect the quasiparticle energies for fixed <code>[[Variables#BndsRnXp|BndsRnXp]]</code> in different files named e.g. ''10b.dat, 20b.dat'' etc. for plotting, by putting in separate columns: the energy cutoff; the size of the G blocks; the quasiparticle energy of the valence band; and that of the conduction band.
To do this e.g. for the ''10b.dat'' file you can type:
$ cat o-10b* | grep "8.000" | awk '{print $3+$4}'
to parse the valence band quasiparticle energies and
$ cat o-10b* | grep "9.000" | awk '{print $3+$4}'
for the conduction band; and put all the data in the ''10b.dat'' files. As there are many files to process you can use the [[bash_scripts|parse_qps.sh]] script to create the ''10b.dat'' file and edit the script changing the number of <code>[[Variables#BndsRnXp|BndsRnXp]]</code> for the other output files.

Once we have collected all the quasiparticle values we can plot the gap, or the valence and conduction band energies separately, as a function of the block size or energy cutoff:
$ gnuplot
gnuplot> p "10b.dat" u 1:3 w lp t " Valence BndsRnXp=10", "20b.dat" u 1:3 w lp t "Valence BndsRnXp=20",..
gnuplot> p "10b.dat" u 1:4 w lp t " Conduction BndsRnXp=10", "20b.dat" u 1:4 w lp t "Conduction BndsRnXp=20",..
gnuplot> p "10b.dat" u 1:($4-$3) w lp t " Gap BndsRnXp=10", "20b.dat" u 1:($4-$3) w lp t "gap BndsRnXp=20",..
or both using e.g. the [[gnuplot_scripts|ppa_gap.gnu]] gnuplot script:

<gallery mode=nolines widths=500px heights=500px perrow=1 caption="Quasiparticle energies with respect screening parameters">
File:ppa2.png|Valence band energy wrt <code>[[Variables#BndsRnXp|BndsRnXp]]</code> and <code>[[Variables#NGsBlkXp|NGsBlkXp]]</code>.
File:ppa3.png|Conduction band energy wrt <code>[[Variables#BndsRnXp|BndsRnXp]]</code> and <code>[[Variables#NGsBlkXp|NGsBlkXp]]</code>.
</gallery>

[[File:ppa1.png|center|600px|caption]]

Looking at the plot we can see that:
* The two parameters are not totally independent (see e.g. the valence quasiparticle convergence) and this is the reason why we converged them simultaneously
* The gap (energy difference) converge faster than single quasiparticle state
* The convergence criteria depends on the degree of accuracy we look for, but considering the approximations behind the calculations (plasmon-pole etc.), it is not always a good idea to enforce too strict a criteria.
* Even if not totally converged we can consider that the upper limit of <code>[[Variables#BndsRnXp|BndsRnXp]]</code>=30, and <code>[[Variables#NGsBlkXp|NGsBlkXp]]</code>=3Ry are reasonable parameters.

Finally notice that in the last versions of Yambo 4.5 etc. there is a terminator for the dielectric constant that accelerates convergence on the number of bands,
you can active it with the <code>-V resp</code> verbosity and setting <code>XTermKind= "BG"</code>. You can compare the converge of the dielectric constant with and without terminator,
similar to what happens for the self-energy, see next section.

====Converging the sum over states in the correlation self-energy====
From now on we will keep fixed these parameters and will perform a convergence study on the sum over state summation in the correlation self-energy (Σc) <code>[[Variables#GbndRnge|GbndRnge]]</code>.

In order to use the screening previously calculated we can copy the plasmon pole parameters saved in the <code>30b_3Ry</code> directory in the <code>SAVE</code> directory. In this way the screening will be read by Yambo and not calculated again:

$ cp ./30b_3Ry/ndb.pp* ./SAVE/.

(Note: you may have to delete these files before running the BSE tutorials)

In order to use the databases we have to be sure to have the same plasmon-pole parameters in our input files.
Edit ''gw_ppa_30b_3Ry.in'' and modify <code>[[Variables#GbndRnge|GbndRnge]]</code> to order to have a number of bands in the range from 10 to 80 inside different files named ''gw_ppa_Gbnd10.in'', ''gw_ppa_Gbnd20.in'' etc. You can also run the the [[bash_scripts|generate_inputs_2.sh]] bash script to generate the required input files.

Next, launch yambo for each input:

$ yambo -F gw_ppa_Gbnd10.in -J Gbnd10
$ yambo -F gw_ppa_Gbnd20.in -J Gbnd20
...

and as done before we can inspect the obtained quasiparticle energies:

$ grep 8.00 o-Gbnd* | awk '{print $4+$5}'
for the valence bands, and
$ grep 9.00 o-Gbnd* | awk '{print $4+$5}'
for the conduction band.

Collect the results in a text file ''Gbnd_conv.dat'' containing: the number of Gbnd, the valence energy, and the conduction energy.
Now, as done before we can plot the valence and conduction quasiparticle levels separately as well as the gap, as a function of the number of bands used in the summation:

$ gnuplot
gnuplot> p "Gbnd_conv.dat" u 1:2 w lp lt 7 t "Valence"
gnuplot> p "Gbnd_conv.dat" u 1:3 w lp lt 7 t "Conduction"
gnuplot> p "Gbnd_conv.dat" u 1:($3-$2) w lp lt 7 t "Gap"

<gallery mode=nolines widths=500px heights=500px perrow=2 caption="Quasiparticle energies with respect sum over states in correlation self-energy">
File:Gbnd_val.png|Valence band energy wrt <code>[[Variables#GbndRange|GbndRange]]</code>.
File:Gbnd_cond.png|Conduction band energy wrt <code>[[Variables#GbndRange|GbndRange]]</code>
</gallery>

[[File:Gbnd_gap.png|center|600px|caption]]

Inspecting the plot we can see that:
* The convergence with respect to <code>[[Variables#GbndRange|GbndRange]]</code> is rather slow and many bands are needed to get converged results.
* As observed above the gap (energy difference) converges faster than the single quasiparticle state energies.

====Accelerating the sum over states convergence in the correlation self-energy====
In general the convergence with respect the sum over states can be very cumbersome. Here we show how it can be mitigated by using
a technique developed by F. Bruneval and X. Gonze <ref name="BG"> F. Bruneval and X. Gonze, Physical Review B 78, 085125 (2008 )</ref>. The basic idea relies in replacing the eigenenergies of the states that are not treated explicitly by a common energy, and take into account all the states, which are not explicitly included in the calculation through the closure relation.
To apply this technique in Yambo we need to activate the optional terminator variable [[Variables#GTermKind|GTermKind]]. We can activate it by adding the quasiparticle verbosity to the command line when generating the input file:

$ yambo -p p -g n -F gw_ppa_Gbnd10.in -V qp

and you can edit the input file by setting:

[[Variables#GTermKind|GTermKind]]= "BG"

or simply you can add by hand this line in all the other ''gw_ppa_GbndX.in'' input files.
Now we can repeat the same calculations

$ yambo -F gw_ppa_Gbnd10.in -J Gbnd10_term
$ yambo -F gw_ppa_Gbnd20.in -J Gbnd20_term
...

and collect the new results:

$ grep 8.000 *term.qp | awk '{print $4+$5}'
$ grep 9.000 *term.qp | awk '{print $4+$5}'

in a new file called ''Gbnd_conv_terminator.dat''. Now we can plot the same quantities as before by looking at the effect of having introduced the terminator.

gnuplot
gnuplot> p "Gbnd_conv.dat" u 1:2 w lp t "Valence", "Gbnd_conv_terminator.dat" u 1:2 w lp t "Valence with terminator"
gnuplot> p "Gbnd_conv.dat" u 1:3 w lp t "Conduction", "Gbnd_conv_terminator.dat" u 1:3 w lp t "Conduction with terminator"
gnuplot> p "Gbnd_conv.dat" u 1:($3-$2) w lp t "Gap", "Gbnd_conv_terminator.dat" u 1:($3-$2) w lp t "Gap with terminator"

<gallery mode=nolines widths=500px heights=500px perrow=2 caption="Effect of the terminator in convergence of QP energies with respect sum over states">
File:val_t.png|Valence band energy wrt <code>[[Variables#GbndRange|GbndRange]]</code> with and without the terminator technique <ref name="BG" />
File:cond_t.png|Conduction band energy wrt <code>[[Variables#GbndRange|GbndRange]]</code> with and without the terminator technique<ref name="BG" />
</gallery>

[[File:gap_t.png|center|600px|caption]]

We can see that:
* The convergence with respect to <code>[[Variables#GbndRange|GbndRange]]</code> is accelerated in particular for the single quasiparticle states.
* From the plot above we can see that <code>[[Variables#GbndRange|GbndRange]]</code>=40 is sufficient to have a converged gap

===Beyond the plasmon pole approximation: a full frequency approach - real axis integration===
All the calculations performed up to now were based on the plasmon pole approximation (PPA). Now we remove this approximation by evaluating numerically the frequency integral in the expression of the correlation self-energy (Σc). To this aim we need to evaluate the screening for a number of frequencies in the interval depending on the electron-hole energy difference (energy difference between empty and occupied states) entering in the sum over states.
Let's build the input file for a full frequency calculation by simply typing:

$ yambo -F gw_ff.in -g n

and we can set the variable studied up to now at their converged value:

%[[Variables#BndsRnXd|BndsRnXd]]
1 | 30 |
%
[[Variables#NGsBlkXd|NGsBlkXd]]=3 Ry
%[[Variables#GbndRange|GbndRange]]
1 | 40 |
%
[[Variables#EXXRLvcs|EXXRLvcs]]=40 Ry
% [[Variables#LongDrXd|LongDrXd]]
1.000000 | 1.000000 | 1.000000 | # [Xd] [cc] Electric Field
%
%QPkrange # # [GW] QP generalized Kpoint/Band indices
7|7|8|9|
%

and next vary in different files (name them ''gw_ff10.in'' etc.) the number of frequencies we evaluate for the screened coulomb potential. This is done by setting the values of [[Variables#ETStpsXd|ETStpsXd]]=10 , 50 , 100, 150, 200, 250.
You can also run the the [[bash_scripts|generate_inputs_3.sh]] bash script to generate the required input files.

Next launch yambo:
$ yambo -F gw_ff10.in -J ff10
$ yambo -F gw_ff50.in -J ff50
...

Clearly as we are evaluating the screening for a large number of frequencies these calculations will be heavier than the case above where the calculation of the screening was done for only two frequencies (zero and plasmon-pole).
As before, collect the valence and conduction bands as a function of the number of frequencies in a file called ''gw_ff.dat'' and plot the behaviour of the conduction and valence bands and the gap.

$ gnuplot
gnuplot> p "gw_ff.dat" u 1:2 w lp t "Valence"
gnuplot> p "gw_ff.dat" u 1:3 w lp t "Conduction"
gnuplot> p "gw_ff.dat" u 1:($3-$2) w lp t "Gap"

<gallery mode=nolines widths=500px heights=500px perrow=2 caption="Real axis integration, convergences with respect the used number of frequencies">
File:ff_v.png|Valence band energy wrt <code>[[Variables#ETStpsXd|ETStpsXd]]</code>
File:ff_c.png|Conduction band energy wrt <code>[[Variables#ETStpsXd|ETStpsXd]]</code>
</gallery>

[[File:ff_g.png|center|600px|caption]]

We can see that:

* Oscillations are still present, indicating that even more frequencies have to be considered. In general, a real-axis calculation is very demanding.
* The final result of the gap obtained up to now does not differ too much from the one obtained at the plasmon-pole level (~50 meV)

===Secant Solver===

The real axis integration permits also to go beyond the linear expansion to solve the quasi particle equation.
The QP equation is a non-linear equation whose solution must be found using a suitable numerical algorithm.
[[File:Eqp_sec.png|none|x22px|caption]]
The mostly used, based on the linearization of the self-energy operator is the Newton method that is the one we have used up to now.
Yambo can also perform a search of the QP energies using a non-linear iterative method based on the [https://en.wikipedia.org/wiki/Secant_method Secant iterative Method].

In numerical analysis, the secant method is a root-finding algorithm that uses a succession of roots of secant lines to better approximate a root of a function ''f''. The secant method can be thought of as a finite difference approximation of Newton's method.
The equation that defines the secant method is:

[[File:secant_eq.png|none|x35px|caption]]

The first two iterations of the secant method are shown in the following picture. The red curve shows the function f and the blue lines are the secants.

[[File:Secant_method.png|center|250px|caption]]

To see if there is any non-linear effect in the solution of the Dyson equation we compare the result of the calculation using the Newton solver as done before with the present case.
In order to use the secant method you need to edit one of the the previous ''gw_ffN.in'' files e.g. ''gw_ff100.in'' and substitute:

DysSolver= "g"
to
DysSolver= "s"

Repeat the calculations in the same way as before:

$ yambo -F gw_ff100.in -J ff100

Note than now the screening will ''not'' be calculated again as it has been stored in the ''ffN'' directories as can be seen in the report file:

[05] Dynamical Dielectric Matrix
================================
[RD./ff10//ndb.em1d]----
...
[RD./ff10//ndb.em1d_fragment_1]--------------
...

Comparing the output files, e.g. for the case with 100 freqs:

''o-ff100.qp'' '''Newton Solver:'''
# K-point Band Eo E-Eo Sc|Eo
#
7.00000 8.00000 -0.41188 -0.08708 2.91254
7.00000 9.00000 3.877976 1.421968 -3.417357

''o-ff100.qp_01'' '''Secant Solver:'''
#
# K-point Band Eo E-Eo Sc|Eo
#
7.00000 8.00000 -0.41188 -0.08715 2.93518
7.00000 9.00000 3.877976 1.401408 -3.731649

From the comparison, we see that the effect is of the order of 20 meV, of the same order of magnitude of the accuracy of the GW calculations.

==Step 3: Interpolating Band Structures==
Up to now we have checked convergence for the gap. Now we want to calculate the quasiparticle corrections across the Brillouin zone in order to visualize the entire band structure along a path connecting high symmetry points.

To do that we start by calculating the QP correction in the plasmon-pole approximation for all the k points of our sampling and for a number of bands around the gap. You can use a previous input file or generate a new one: <code> yambo -F gw_ppa_all_Bz.in -x -p p -g n </code> and set the parameters found in the previous tests:

EXXRLvcs= 40 Ry
% BndsRnXp
1 | 30 | # [Xp] Polarization function bands
%
NGsBlkXp= 3 Ry # [Xp] Response block size
% LongDrXp
1.000000 | 1.000000 | 1.000000 | # [Xp] [cc] Electric Field
%
PPAPntXp= 27.21138 eV # [Xp] PPA imaginary energy
% GbndRnge
1 | 40 | # [GW] G[W] bands range
%

and we calculate it for all the available kpoints by setting:
%QPkrange # [GW] QP generalized Kpoint/Band indices
1| 14| 6|11|
%

Note that as we have already calculated the screening with these parameters you can save time and use that database either by running in the previous directory by using <code> -J 30b_3Ry </code> or if you prefer to put the new databases in the new all_Bz directory you can create a new directory and copy there the screening databases:

$ mkdir all_Bz
$ cp ./30b_3Ry/ndb.pp* ./all_Bz/

and launch the calculation:

$ yambo -F gw_ppa_all_Bz.in -J all_Bz

Now we can inspect the output and see that it contains the correction for all the k points for the bands we asked:

# K-point Band Eo E-Eo Sc|Eo
#
1.000000 6.000000 -1.299712 -0.219100 3.788044
1.000000 7.000000 -1.296430 -0.241496 3.788092
1.000000 8.000000 -1.296420 -0.243115 3.785947
1.000000 9.000000 4.832399 0.952386 -3.679259
1.00000 10.00000 10.76416 2.09915 -4.38743
1.00000 11.00000 11.36167 2.48053 -3.91021
....
By plotting some of the 'o-all_Bz.qp" columns it is possible to discuss some physical properties of the hBN QPs. Using columns 3 and (3+4), ie plotting the GW energies with respect to the LDA energies we can deduce the band gap renormalization and the stretching of the conduction/valence bands:

$ gnuplot
gnuplot> p "o-all_Bz.qp" u 3:($3+$4) w p t "Eqp vs Elda"

[[File:EqpvE0.png|center|350px|caption]]

Essentially we can see that the effect of the GW self-energy is the opening of the gap and a linear stretching of the conduction/valence bands that can be estimated by performing a linear fit of the positive and negative energies (the zero is set at top of the valence band).

In order to calculate the band structure, however, we need to interpolate the values we have calculated above on a given path. In Yambo the interpolation is done by the executable <code>ypp</code> (Yambo Post Processing).
By typing:
$ ypp -H
you will recognize that in order to interpolate the bands we need to build a ypp input file using
$ ypp -s b

we can generate the input for the band interpolation:

$ypp -s b -F ypp_bands.in

and edit the ''ypp_bands.in'' file:

electrons # [R] Electrons (and holes)
bnds # [R] Bands
INTERP_mode= "NN" # Interpolation mode (NN=nearest point, BOLTZ=boltztrap aproach)
OutputAlat= 4.716000 # [a.u.] Lattice constant used for "alat" ouput format
cooIn= "rlu" # Points coordinates (in) cc/rlu/iku/alat
cooOut= "rlu"
% BANDS_bands
1 | 100 | # Number of bands
%
% INTERP_Grid
-1 |-1 |-1 | # Interpolation BZ Grid
%
INTERP_Shell_Fac= 20.00000 # The bigger it is a higher number of shells is used
CIRCUIT_E_DB_path= "none" # SAVE obtained from the QE `bands` run (alternative to %BANDS_kpts)
BANDS_path= "" # BANDS path points labels (G,M,K,L...)
BANDS_steps= 10
#BANDS_built_in # Print the bands of the generating points of the circuit using the nearest internal point
%BANDS_kpts
%

We modify the following lines:
BANDS_steps=30
% BANDS_bands
6 | 11 | # Number of bands
%
%BANDS_kpts # K points of the bands circuit
0.33300 |-.66667 |0.00000 |
0.00000 |0.00000 |0.00000 |
0.50000 |-.50000 |0.00000 |
0.33300 |-.66667 |0.00000 |
0.33300 |-.66667 |0.50000 |
0.00000 |0.00000 |0.50000 |
0.50000 |-.50000 |0.50000 |
%

which means we assign 30 points in each segment, we ask to interpolate 3 occupied and 3 empty bands and we assign the following path passing from the high symmetry points: K Γ M K H A L.
Launching:
$ ypp -F ypp_bands.in
will produce the output file ''o.bands_interpolated'' containing:

#
# |k| b6 b7 b8 b9 b10 b11 kx ky kz
#
#
0.00000 -7.22092 -0.13402 -0.13395 4.67691 4.67694 10.08905 0.33300 -0.66667 0.00000
0.03725 -7.18857 -0.17190 -0.12684 4.66126 4.71050 10.12529 0.32190 -0.64445 0.00000
...

and we can plot the bands using gnuplot:
$ gnuplot
gnuplot> p "o.bands_interpolated" u 0:2 w l, "o.bands_interpolated" u 0:3 w l, ...

[[File:bands_lda.png|center|350px|caption]]

and you can recognize the index of the high symmetry point by inspecting the last three columns.
Note that up to now we have interpolated the LDA band structure. In order to plot the GW band structure, we need to tell <code>ypp</code> in the input file where the ''ndb.QP'' database is found. This is achieved by adding in the ''ypp_bands.in'' file the line:

GfnQPdb= "E < ./all_Bz/ndb.QP"

and relaunch

$ ypp -F ypp_bands.in

Now the file ''o.bands_interpolated_01'' contains the GW interpolated band structure. We can plot the LDA and GW band structure together by using the gnuplot script [[gnuplot_scripts|bands.gnu]].

<gallery mode=nolines widths=500px heights=500px perrow=2 caption="Band strcuture of bulk hBN">
File:hBN_bands.png| LDA and GW bands structure
File:hBN_bands_lit.png| LDA and GW bands structure from Ref. <ref name="Arnaud" />
</gallery>

*As expected the effect of the GW correction is to open the gap.
*Comparing the obtained band structure with the one found in the literature by Arnaud and coworkers <ref name="Arnaud"> B. Arnaud, S. Lebegue,P. Rabiller, and M. Alouani Phys, Rev. Lett. 96, 026402 (2006)</ref> we found a very nice qualitative agreement.
*Quantitatively we found a smaller gap: about 5.2 eV (indirect gap), 5.7 eV (direct gap) while in Ref.<ref name="Arnaud" /> is found 5.95 eV for the indirect gap and a minimum direct band gap of 6.47 eV. Other values are also reported in the literature depending on the used pseudopotentials, starting functional and type of self-consistency (see below).
*The present tutorial has been done with a small k point grid which is an important parameter to be checked, so convergence with respect the k point sampling has to be validated.

==Step 4: Summary of the convergence parameters==
We have calculated the band structure of hBN starting from a DFT calculation, here we summarize the main variable we have checked to achieve convergence:

* <code>[[Variables#EXXRLvcs|EXXRLvcs]]</code> # [XX] Exchange RL components
Number of G-vectors in the exchange. This number should be checked carefully. Generally a large number is needed as the QP energies show a slow convergence. The calcualtion of the exchange part is rather fast.

*<code>[[Variables#BndsRnXp|BndsRnXp]]</code> #[Xp] Polarization function bands
Number of bands in the independent response function form which the dielectric matrix is calculated. Also this paramater has to be checked carefully,together with NGsBlkXp as the two variables are interconnected

*<code>[[Variables#NGsBlkXp|NGsBlkXp]]</code> # [Xp] Response block size
Number of G-vectors block in the dielectric constant. Also this paramater has to be checked carefully, to be checked together with BndsRnXp. A large number of bands and block can make the calculation very demanding.

*<code>[[Variables#LongDrXp|LongDrXp]] </code> # [Xp] [cc] Electric Field
Direction of the electric field for the calculation of the q=0 component of the dielectric constant e(q,w). In a bulk can be set to (1,1,1), attention must be paid for non 3D systems.

*<code>[[Variables#PPAPntXp|PPAPntXp]] </code> # [Xp] Plasmon pole imaginary energy: this is the second frequency used to fit the Godby-Needs plasmon-pole model (PPM). If results depend consistently by changing this frequency, the PPM is not adequate for your calculation and it is need to gp beyond that, e.g. Real-axis.

*<code>[[Variables#GbndRnge|GbndRnge]] </code> # [GW] G[W] bands range
Number of bands used to expand the Green's function. This number is usually larger than the number of bands used to calculated the dielectricconstant. Single quasiparticle energies converge slowly with respect GbndRnge, energy difference behave better. You can use terminator technique to mitigate the slow dependence.

*<code>[[Variables#GDamping|GDamping]] </code> # [GW] G[W] damping
Small damping in the Green's function definition, the delta
parameter. The final result shouuld not depend on that, usually set at 0.1 eV

*<code>[[Variables#dScStep|dScStep]] </code> # [GW]
Energy step to evaluate Z factors

*<code>[[Variables#DysSolver|DysSolver]] </code> # [GW] Dyson Equation solver ("n","s","g")
Parameters related to the solution of the Dyson equation, "n" Newton linearization, 's' non linear secant method

*<code>[[Variables#GTermKind|GTermKind]] </code> [GW] GW terminator
Terminator for the self-energy<ref name="BG" /> . We have seen how this spped up the convergence with respect empty bands.

*<code>[[Variables#%QPkrange |QPkrange ]] </code> # [GW] QP generalized Kpoint/Band indices
K-points and band range where you want to calculate the GW correction. The syntax is
first kpoint | last kpoint | first band | last band

==Step 5: Eigenvalue only self-consistent evGW0 and evGW (only available in Yambo 4.6) ==
Here we want to see how we can compute an eigenvalue only evGW0 or evGW correction in Yambo. In the new version of Yambo there are two flags for these kind of self-consistency:

<code>[[Variables#GWoIter|GWoIter]]</code> number of GW0 iterations

<code>[[Variables#GWoIter|GWIter]]</code> number of GW iterations

you can set one of them to 10 for example, the code will stop when convergence is reached, usually in less than 5 iterations.
For example if you consider the input file below:

HF_and_locXC # [R XX] Hartree-Fock Self-energy and Vxc
ppa # [R Xp] Plasmon Pole Approximation
gw0 # [R GW] GoWo Quasiparticle energy levels
em1d # [R Xd] Dynamical Inverse Dielectric Matrix
EXXRLvcs = 40.000 mRy # [XX] Exchange RL components
VXCRLvcs = 3187 RL # [XC] XCpotential RL components
Chimod= "Hartree" # [X] IP/Hartree/ALDA/LRC/BSfxc
% BndsRnXp
1 | 10 | # [Xp] Polarization function bands
%
NGsBlkXp= 1000 mRy # [Xp] Response block size
% LongDrXp
1.000000 | 1.000000 | 1.000000 | # [Xp] [cc] Electric Field
%
PPAPntXp = 27.21138 eV # [Xp] PPA imaginary energy
%GbndRnge
1 | 40 | # [GW] G[W] bands range
%
GDamping= 0.10000 eV # [GW] G[W] damping
dScStep= 0.10000 eV # [GW] Energy step to evaluate Z factors
DysSolver= "n" # [GW] Dyson Equation solver ("n","s","g")
GWoIter=0 # [GW] GWo self-consistent (evGWo) iterations on eigenvalues
GWIter =0 # [GW] GW self-consistent (evGW) iterations on eigenvalues
%QPkrange # [GW] QP generalized Kpoint/Band indices
1| 14| 7| 10|
%
if you set both GWIter and GWoIter to zero you get a gap correction of 4.15 eV.
If you perform self-consistency on G (GWoIter/=)
the gap will be 4.713 eV and finally if you perform
self-consistency in both G and W (GWIter /=0) the gap will be 5.506 eV.

Notice that these values are absolutelly not converged because we used very few
bands and a small block size.

It's important to note that the final result of the self-consistent GW may
depend from the number of bands you decide to correct, because they are used
to reconstruct G and W. For the non-corrected bands Yambo applied a rigid shift
of their energy based on the closed corrected band.

==Step 6: A better integration of the q=0 point ==

The integration of the q=0 of the Coulomb potential is problematic because the 1/q diverges.
Usually in Yambo this integration is performed analytically in a small sphere around q=0.

[[File:Circle box.gif|center|frame]]

however in this way the code lost part of the integral out of the circle. This usually
is not problematic because for a large number of q and k point the missing term goes to zero.
However in system that requires few k-points or even only the gamma one, it is possible
to perform a better integration of this term by adding the flag -r to generate the input

HF_and_locXC # [R XX] Hartree-Fock Self-energy and Vxc
ppa # [R Xp] Plasmon Pole Approximation
gw0 # [R GW] GoWo Quasiparticle energy levels
rim_cut # [R] Coulomb potential
em1d # [R Xd] Dynamical Inverse Dielectric Matrix
RandQpts= 3000000 # [RIM] Number of random q-points in the BZ
RandGvec= 1 RL # [RIM] Coulomb interaction RS components
#QpgFull # [F RIM] Coulomb interaction: Full matrix
EXXRLvcs = 40.000 mRy # [XX] Exchange RL components
VXCRLvcs = 3187 RL # [XC] XCpotential RL components
Chimod= "Hartree" # [X] IP/Hartree/ALDA/LRC/BSfxc
% BndsRnXp
1 | 10 | # [Xp] Polarization function bands
%
NGsBlkXp= 1000 mRy # [Xp] Response block size
% LongDrXp
1.000000 | 1.000000 | 1.000000 | # [Xp] [cc] Electric Field
%
PPAPntXp = 27.21138 eV # [Xp] PPA imaginary energy
%GbndRnge
1 | 40 | # [GW] G[W] bands range
%
GDamping= 0.10000 eV # [GW] G[W] damping
dScStep= 0.10000 eV # [GW] Energy step to evaluate Z factors
DysSolver= "n" # [GW] Dyson Equation solver ("n","s","g")
%QPkrange # [GW] QP generalized Kpoint/Band indices
7| 7| 8| 9|
%

in this input <code>[[Variables#RandGvec|RandGvec]]</code> is the component of the Coulomb potential we want integrate numerically,
in this case only the first one G=G'=0, and <code>[[Variables#RandQpts|RandQpts]]</code> is the number of random points
used to perform the integral by Monte Carlo.

If you turn one this integration you will get a slightly different band gap,
but in the limit of large k points the final results will be the same of the standard method.

However this correction is important for systems that converge with few k-points or with gamma only.

==Step 7: Taking into account the material anisotropy (only available in Yambo 4.6) ==

Hexagonal Boron Nitride is an anisotropic material so there is the question in which direction
one shold calculate the dielectric constant the enters in the GW.
If you run again this tutorial changing the direction of the q=0 point in GW calculation,
the variable <code>[[Variables#LongDrXp|LongDrXp]]</code>, you will realize that the there gap correction changes.
In Yambo there is a way to take into account this anisitropy of the dielectri tensor.

First of all you need to calculate the dielectric constant in the three cartesian directions with the command <code> yambo -o c -k hartree</code>

optics # [R] Linear Response optical properties
kernel # [R] Kernel
chi # [R][CHI] Dyson equation for Chi.
dipoles # [R] Oscillator strenghts (or dipoles)
Chimod= "HARTREE" # [X] IP/Hartree/ALDA/LRC/PF/BSfxc
NGsBlkXd= 3000 mRy # [Xd] Response block size
% QpntsRXd
1 | 1 | # [Xd] Transferred momenta
%
% BndsRnXd
1 | 100 | # [Xd] Polarization function bands
%
% EnRngeXd
0.00000 | 10.00000 | eV # [Xd] Energy range
%
% DmRngeXd
0.10000 | 0.10000 | eV # [Xd] Damping range
%
ETStpsXd= 1 # [Xd] Total Energy steps
% LongDrXd
1.000000 | 0.000000 | 0.000000 | # [Xd] [cc] Electric Field
%

In the output file <code> o.eps_q1_inv_rpa_dyson</code> you will find the real-part of the inverse dielectric matrix, in this case 5.044076.

Repeat this calculation with the field in the other two directions y and z. The y-direction will be equal to x, while in z the dielectric constant will be 2.872451.

Now generate a new input file for the GW, with the command <code> yambo -g n -p p -r -V RL</code>

HF_and_locXC # [R XX] Hartree-Fock Self-energy and Vxc
ppa # [R Xp] Plasmon Pole Approximation
gw0 # [R GW] GoWo Quasiparticle energy levels
rim_cut # [R] Coulomb potential
em1d # [R Xd] Dynamical Inverse Dielectric Matrix
RandQpts=3000000 # [RIM] Number of random q-points in the BZ
RandGvec= 1 RL # [RIM] Coulomb interaction RS components
#QpgFull # [F RIM] Coulomb interaction: Full matrix
% Em1Anys
5.044076 | 5.044076 | 2.872451 | # [RIM] X Y Z Static Inverse dielectric matrix
%
IDEm1Ref= 1
EXXRLvcs = 40.000 mRy # [XX] Exchange RL components
VXCRLvcs = 3187 RL # [XC] XCpotential RL components
Chimod= "Hartree" # [X] IP/Hartree/ALDA/LRC/BSfxc
% BndsRnXp
1 | 10 | # [Xp] Polarization function bands
%
NGsBlkXp= 1000 mRy # [Xp] Response block size
% LongDrXp
1.000000 | 0.000000 | 0.000000 | # [Xp] [cc] Electric Field
%
PPAPntXp = 27.21138 eV # [Xp] PPA imaginary energy
%GbndRnge
1 | 40 | # [GW] G[W] bands range
%
GDamping= 0.10000 eV # [GW] G[W] damping
dScStep= 0.10000 eV # [GW] Energy step to evaluate Z factors
DysSolver= "n" # [GW] Dyson Equation solver ("n","s","g")
%QPkrange # [GW] QP generalized Kpoint/Band indices
7| 7| 8| 9|
%

run the calculations and you will find a correction of the gap intermediate between the one with the field in x and z directions.

==Step 8: Exercise: Convergence with respect K points==
As an exercise now you can check the convergence with respect the K point sampling:
# perform a new non-scf calculation with a bigger k point grid: 9x9x3 and 12x12x4 ...
# convert wave functions and electronic structure to Yambo databases in a different directory as explained in the [[Bulk material: h-BN|DFT and p2y module]],
# [[initialization |Initialize]] the Yambo databases,
# Redo the steps explained in this section (exchange self energy, plasmon pole GW, band structure interpolation)
# The PPA-GW calculation using 12x12x4 grid depending on your machine can take several minutes in serial mode. You can think to perform the exercise after having learned some basic on the parallelization strategy.

 
{| style="width:100%" border="1"
|style="width:15%; text-align:left"|Prev: [[Tutorials|Tutorials Home]]
|style="width:50%; text-align:center"|Now: [[Tutorials|Tutorials Home]] --> [[How_to_obtain_the_quasi-particle_band_structure_of_a_bulk_material:_h-BN|GW]]
|style="width:35%; text-align:right"|Next: If you did everything, choose another tutorial in the menu
|-
|}

==References==