The Yambo Project - User contributions [en]

Hartree Fock

2022-04-03T17:14:34Z

Maurizia:

== Prerequisites ==
[[File:Yambo-handbook-v4.1.2-p-9.png|thumb|Cheatsheet on HF|150px]]

* You must first complete the "How to use Yambo" modules (''[[Input_file_generation_and_command_line_options|input file generation and command_line_options]], [[Initialization]]'')

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

== Background ==
The exchange part contribution of the self-energy for a generic state (nk) in reciprocal space reads:
[[File:Sx.png|none|x50px|caption]]
It is important to note that in this way we are adding the HF contribution in a perturbative way to previously calculated DFT energies:

[[File:Ehf.png|x20px|caption]]

and hence they will differ from a standard self-consistent HF calculation.

== Input file generation ==

Let's start by building up an input file for a HF calculation. From <code>yambo -h</code> you should understand that the correct option is <code>yambo -x</code>:

$ cd YAMBO_TUTORIALS/hBN/YAMBO
$ yambo ''(Initialization)''
$ yambo -x -F hf.in

Looking inside the input file you will find:

[[Variables#EXXRLvcs|EXXRLvcs]] = 3187 RL # [XX] Exchange RL components
[[Variables#VXCRLvcs|VXCRLvcs]] = 3187 RL # [XC] XCpotential RL components
%[[Variables#QPkrange|QPkrange]] # [GW] QP generalized Kpoint/Band indices
1| 14| 1|100|
%

The variable [[Variables#EXXRLvcs|EXXRLvcs]] governs the number of G vectors to be summed in the expression of the exchange self-energy reported above.
The variable [[Variables#VXCRLvcs|VXCRLvcs]] set the number of G vectors used in the evaluation of the density for the <Vxc> matrix element. A large number is needed in order to have a precise cancellation with the ground state calculation, in particular when GGA potentials are used. A good practice is to leave it at the maximum number (default). In case it would be needed to reduce (e.g. for memory reason), the accuracy can be checked by comparing the E_xc value printed in Yambo report and QE output file.
The [[Variables#QPkrange|QPkrange]] name list it is a generalized index needed to select the first and last kpoints and bands we want to calculate the QP correction.
In general, we are interested in the gap of the system or in the band structure across the Fermi Energy. Let's start by editing the ''hf.in'' file by selecting the last occupied and first unoccupied bands These are the bands 8 and 9 as reported in the r_setup file.
So we change the [[Variables#QPkrange|QPkrange]] variable in:

%[[Variables#QPkrange|QPkrange]] # [GW] QP generalized Kpoint/Band indices
1| 14| 8| 9|
%

and run calculations to converge the expression above. In the expression of the Exchange Self Energy, we have a summation over bands, an integral over the Brillouin Zone and a Sum over the G vectors. Looking at the occupation factor we realize that occupied states only enters in the expression, so we do not need to worry about the bands as Yambo will include all the occupied bands by default. In order to check convergence of the G vectors in the summation in the Σx expression, we will perform different calculation varying the kinetic energy cutoff governing the number of G vectors entering in the sum. Let's start by setting in ''hf.in'':

[[Variables#EXXRLvcs|EXXRLvcs]]= 10 Ry

== Calculation and analysis of output ==
Let's now run yambo:

$ yambo -F hf.in -J 3D

The result can be found int the output ''o-3D.hf'' file and in the ''r-3D_HF_and_locXC'' file. Looking inside the output file we have:

# K-point Band Eo Ehf DFT HF
#
1.00000 8.00000 -1.29642 -4.79324 -18.03344 -21.53026
1.00000 9.00000 4.83239 9.755507 -9.592554 -4.669446
2.00000 8.00000 -1.33551 -4.80994 -18.07476 -21.54919
2.00000 9.00000 7.56742 13.43122 -11.55012 -5.68633
........

Looking at the definition of the HF energy, the third column is the DFT energy (KS eigenvalue), Ehf is the HF energy, and column 4 and 5 report the different contribution to be subtracted Vx (DFT) and added Σx (HF) to the unperturbed DFT eigenvalue. From these data we can calculate the HF gap: you can recognize that the direct gap is found at k-point number 7, being 4.29 eV at DFT level and 11.95 eV in HF approximation. This information can be also easily found in the
report file ''r-3D_HF_and_locXC'' searching for Direct Gaps:

Before the HF computation:

[X] Direct Gap : 4.289853 [eV]
[X] Direct Gap localized at k-point : 7
[X] Indirect Gap : 3.877976 [eV]
[X] Indirect Gap between k-points : 14 7

... after the HF computation:

[05.01] HF occupations report
=============================

[Hartree-Fock] Direct Gap : 11.94549 [eV]
[Hartree-Fock] Direct Gap localized at k-point : 7
[Hartree-Fock] Indirect Gap : 11.28767 [eV]
[Hartree-Fock] Indirect Gap between k-points : 14 7

or simply by typing:

$ grep "irect Gap" r-3D_HF_and_locXC

and the gap value before and after the HF correction is shown:
[X] Direct Gap : 4.289853 [eV]
[X] Direct Gap localized at k-point : 7
[Hartree-Fock] Direct Gap : 11.94549 [eV]
[Hartree-Fock] Direct Gap localized at k-point : 7
[Hartree-Fock] Indirect Gap : 11.28767 [eV]
[Hartree-Fock] Indirect Gap between kpts : 14 7

In the report file, the first value indicates the maximum (direct) gap while the second one is the minimum (indirect) energy gap between the same bands.

In the following, in order to converge the direct gap, we will focus the K point where the direct band is found. Inspecting the ''r_setup'' file, or any other report file it can be recognized that the direct minimum gap is found at the K-point number 7 (M point): this can be seen by searching the DFT "Direct Gap" and looking at the eigenvalues reported for each k point. Note that the zero energy is fixed at the top of the valence band, K point number 14 (H point).
So we can restrict the convergence calculations to the occupied and empty bands at point M, by modifying the input file as:

%[[Variables#QPkrange|QPkrange]] # [GW] QP generalized Kpoint/Band indices
7| 7| 8| 9|
%

Even if for this case the calculations are not at all expensive, reducing the calculations to few bands when performing convergence test allows to save memory and time.

Now we can run different calculations changing the value of [[Variables#EXXRLvcs|EXXRLvcs]], let's say to 10,20,30 and 40 Ry.
Build four different input files differing only for the [[Variables#EXXRLvcs|EXXRLvcs]] values and naming them hf_10Ry.in, hf_20Ry.in, etc.

$ cp hf.in hf_10Ry.in
$ yambo -F hf_10Ry.in -J 3D
$ cp hf.in hf_20Ry.in ''and edit file, changing EXXRLvcs to 20 Ry''
$ yambo -F hf_20Ry.in -J 3D
.....

Once the calculations are terminated, collect the results found in the output, for instance, putting in a file named hf.dat the following data:
Cutoff Energy, Number of G vector in the Sum, HF energy for the occupied state (Ehf for the state 8), HF energy for the unoccupied state (Ehf for the state 9).
You can use the ''grep'' command to extract these data from the output e.g by typing.

grep "^ *7 *8" o-3D.hf_*
and
grep "^ *7 *9" o-3D.hf_*

and looking at the column corresponding to Ehf value (column 4).
For the number of G vectors corresponding to the cutoff energy cutoff in input search ''Exchange RL vectors'' in the report files. Note that it is not possible anymore to extract directly the HF gap from the report file as we did above, as in this case, we did not include all the BZ in the calculation.
Now it possible to plot the energy gap in function of the energy cutoff or number of Gvectors:

$ gnuplot
gnuplot> plot "hf.dat" u 1:($4-$3) w lp t "HF gap vs Energy cutoff"
gnuplot> plot "hf.dat" u 2:($4-$3) w lp t "HF gap vs Number of G vector"

or you can plot the gap in function of both quantities using the [[gnuplot_scripts|hf.gnu]] gnuplot script:

[[File:Hf_plot1.png|none|600px|caption]]

and you can see that at 40Ry the energy gap is very close to convergence. Plotting the occupied and unoccupied bands separately you can recognize that for this system the unoccupied band does converge much faster.

The last important convergence test deals with the accuracy of the integral over the Brillouin zone in the expression of the Exchange Self-Energy, which translates into K point convergence.
In order to test the K point sampling, you should:
# perform a new non-scf calculation with a bigger k point grid,
# 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.

For now, however, you can skip this convergence test and continue the main tutorial (click back on your browser).

[[Category:Modules]]

Hartree Fock

2022-04-03T17:09:46Z

Maurizia:

== Prerequisites ==
[[File:Yambo-handbook-v4.1.2-p-9.png|thumb|Cheatsheet on HF|150px]]

* You must first complete the "How to use Yambo" modules (''[[Input_file_generation_and_command_line_options|input file generation and command_line_options]], [[Initialization]]'')

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

== Background ==
The exchange part contribution of the self-energy for a generic state (nk) in reciprocal space reads:
[[File:Sx.png|none|x50px|caption]]
It is important to note that in this way we are adding the HF contribution in a perturbative way to previously calculated DFT energies:

[[File:Ehf.png|x20px|caption]]

and hence they will differ from a standard self-consistent HF calculation.

== Input file generation ==

Let's start by building up an input file for a HF calculation. From <code>yambo -h</code> you should understand that the correct option is <code>yambo -x</code>:

$ cd YAMBO_TUTORIALS/hBN/YAMBO
$ yambo ''(Initialization)''
$ yambo -x -F hf.in

Looking inside the input file you will find:

[[Variables#EXXRLvcs|EXXRLvcs]] = 3187 RL # [XX] Exchange RL components
[[Variables#VXCRLvcs|VXCRLvcs]] = 3187 RL # [XC] XCpotential RL components
%[[Variables#QPkrange|QPkrange]] # [GW] QP generalized Kpoint/Band indices
1| 14| 1|100|
%

The variable [[Variables#EXXRLvcs|EXXRLvcs]] governs the number of G vectors to be summed in the expression of the exchange self-energy reported above.
The variable [[Variables#VXCRLvcs|VXCRLvcs]] set the number of G vectors used in the evaluation of the density for the <Vxc> matrix element. A large number is needed in order to have a precise cancellation with the ground state calculation, in particular when GGA potentials are used. A good practice is to leave it at the maximum number (default). In case it would be needed to reduce (e.g. for memory reason), the accuracy can be checked by comparing the E_xc value printed in Yambo report and QE output file.
The [[Variables#QPkrange|QPkrange]] name list it is a generalized index needed to select the first and last kpoints and bands we want to calculate the QP correction.
In general, we are interested in the gap of the system or in the band structure across the Fermi Energy. Let's start by editing the ''hf.in'' file by selecting the last occupied and first unoccupied bands These are the bands 8 and 9 as reported in the r_setup file.
So we change the [[Variables#QPkrange|QPkrange]] variable in:

%[[Variables#QPkrange|QPkrange]] # [GW] QP generalized Kpoint/Band indices
1| 14| 8| 9|
%

and run calculations to converge the expression above. In the expression of the Exchange Self Energy, we have a summation over bands, an integral over the Brillouin Zone and a Sum over the G vectors. Looking at the occupation factor we realize that occupied states only enters in the expression, so we do not need to worry about the bands as Yambo will include all the occupied bands by default. In order to check convergence of the G vectors in the summation in the Σx expression, we will perform different calculation varying the kinetic energy cutoff governing the number of G vectors entering in the sum. Let's start by setting in ''hf.in'':

[[Variables#EXXRLvcs|EXXRLvcs]]= 10 Ry

== Calculation and analysis of output ==
Let's now run yambo:

$ yambo -F hf.in -J 3D

The result can be found int the output ''o-3D.hf'' file and in the ''r-3D_HF_and_locXC'' file. Looking inside the output file we have:

# K-point Band Eo Ehf DFT HF
#
1.00000 8.00000 -1.29642 -4.79324 -18.03344 -21.53026
1.00000 9.00000 4.83239 9.755507 -9.592554 -4.669446
2.00000 8.00000 -1.33551 -4.80994 -18.07476 -21.54919
2.00000 9.00000 7.56742 13.43122 -11.55012 -5.68633
........

Looking at the definition of the HF energy, the third column is the DFT energy (KS eigenvalue), Ehf is the HF energy, and column 4 and 5 report the different contribution to be subtracted Vx (DFT) and added Σx (HF) to the unperturbed DFT eigenvalue. From these data we can calculate the HF gap: you can recognize that the direct gap is found at k-point number 7, being 4.29 eV at DFT level and 11.95 eV in HF approximation. This information can be also easily found in the
report file ''r-3D_HF_and_locXC'' searching for Direct Gaps:

Before the HF computation:

[X] Direct Gap : 4.289853 [eV]
[X] Direct Gap localized at k-point : 7
[X] Indirect Gap : 3.877976 [eV]
[X] Indirect Gap between k-points : 14 7

... after the HF computation:

[05.01] HF occupations report
=============================

[Hartree-Fock] Direct Gap : 11.94549 [eV]
[Hartree-Fock] Direct Gap localized at k-point : 7
[Hartree-Fock] Indirect Gap : 11.28767 [eV]
[Hartree-Fock] Indirect Gap between k-points : 14 7

or simply by typing:

$ grep "irect Gap" r-3D_HF_and_locXC

and the gap value before and after the HF correction is shown:
[X] Direct Gap : 4.289853 [eV]
[X] Direct Gap localized at k-point : 7
[Hartree-Fock] Direct Gap : 11.94549 [eV]
[Hartree-Fock] Direct Gap localized at k-point : 7
[Hartree-Fock] Indirect Gap : 11.28767 [eV]
[Hartree-Fock] Indirect Gap between kpts : 14 7

In the report file, the first value indicates the maximum (direct) gap while the second one is the minimum (indirect) energy gap between the same bands.

In the following, in order to converge the direct gap, we will focus the K point where the direct band is found. Inspecting the ''r_setup'' file, or any other report file it can be recognized that the direct minimum gap is found at the K-point number 7 (M point): this can be seen by searching the DFT "Direct Gap" and looking at the eigenvalues reported for each k point. Note that the zero energy is fixed at the top of the valence band, K point number 14 (H point).
So we can restrict the convergence calculations to the occupied and empty bands at point M, by modifying the input file as:

%[[Variables#QPkrange|QPkrange]] # [GW] QP generalized Kpoint/Band indices
7| 7| 8| 9|
%

Even if for this case the calculations are not at all expensive, reducing the calculations to few bands when performing convergence test allows to save memory and time.

Now we can run different calculations changing the value of [[Variables#EXXRLvcs|EXXRLvcs]], let's say to 10,20,30 and 40 Ry.
Build four different input files differing only for the [[Variables#EXXRLvcs|EXXRLvcs]] values and naming them hf_10Ry.in, hf_20Ry.in, etc.

$ cp hf.in hf_10Ry.in
$ yambo -F hf_10Ry.in -J 3D
$ cp hf.in hf_20Ry.in ''and edit file, changing EXXRLvcs to 20Ry''
$ yambo -F hf_20Ry.in -J 3D
.....

Once the calculations are terminated, collect the results found in the output, for instance, putting in a file named hf.dat the following data:
Cutoff Energy, Number of G vector in the Sum, HF energy for the occupied state (Ehf for the state 8), HF energy for the unoccupied state (Ehf for the state 9).
You can use the ''grep'' command to extract these data from the output e.g by typing.

grep "^ *7 *8" o-3D.hf_*
and
grep "^ *7 *9" o-3D.hf_*

and looking at the column corresponding to Ehf value (column 4).
For the number of G vectors corresponding to the cutoff energy cutoff in input search ''Exchange RL vectors'' in the report files. Note that it is not possible anymore to extract directly the HF gap from the report file as we did above, as in this case, we did not include all the BZ in the calculation.
Now it possible to plot the energy gap in function of the energy cutoff or number of Gvectors:

$ gnuplot
gnuplot> plot "hf.dat" u 1:($4-$3) w lp t "HF gap vs Energy cutoff"
gnuplot> plot "hf.dat" u 2:($4-$3) w lp t "HF gap vs Number of G vector"

or you can plot the gap in function of both quantities using the [[gnuplot_scripts|hf.gnu]] gnuplot script:

[[File:Hf_plot1.png|none|600px|caption]]

and you can see that at 40Ry the energy gap is very close to convergence. Plotting the occupied and unoccupied bands separately you can recognize that for this system the unoccupied band does converge much faster.

The last important convergence test deals with the accuracy of the integral over the Brillouin zone in the expression of the Exchange Self-Energy, which translates into K point convergence.
In order to test the K point sampling, you should:
# perform a new non-scf calculation with a bigger k point grid,
# 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.

For now, however, you can skip this convergence test and continue the main tutorial (click back on your browser).

[[Category:Modules]]

GW hBN Yambo Virtual 2021 version

2022-04-03T16:36:35Z

Maurizia: /* Step 1: The Exchange Self Energy or HF quasi-particle correction */

This is a modified version of the tutorial prepared for the Yambo 2021 virtual school.
In case you are interested you can find the extended version of the tutorial here: [[How to obtain the quasi-particle band structure of a bulk material: h-BN]]

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.

One can also skip this step and go directly to the input file generation for GW (browse below), which already includes the calculation of the exchange self-energy
(simply, this is not discussed in detail as done in the '''[[Hartree Fock]]''' module).

==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 take into account the dynamical effects by setting 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.
It is also possible to perform calculations by evaluating the dielectric matrix on a regular grid of frequencies: for this, you may have a look at the [[Real Axis and Lifetimes]] tutorial.

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 -hf -gw0 p -dyson n</code> (or in short <code>yambo -x -p p -g n</code>):

$ cd YAMBO_TUTORIALS/hBN/YAMBO
$ yambo -hf -gw0 p -dyson n -F gw_ppa.in

Here the input file is redirected by the <code>-F</code> option to <code>gw_ppa.in</code> (the default name is <code>yambo.in</code>).
Depending on the version of <code>yambo</code>, you may need to open the file for editing.

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|'''
%

A brief explanation of some settings:
* Similar to the Hartree Fock study, we will focus 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 [eV] E-Eo [eV] Sc|Eo [eV]
#
7 8 -0.411876 -0.567816 2.322433
7 9 3.877976 2.413679 -2.232244
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: Local XC (Slater exchange(X)+Perdew & Zunger(C))
-nlXC: non-Local XC (Hartree-Fock)

QP [eV] @ K [7] (iku): 0.000000 -0.500000 0.000000
B=8 Eo= -0.41 E= -0.93 E-Eo= -0.52 Re(Z)=0.81 Im(Z)=-0.248518E-2 nlXC= -19.1293 lXC= -16.1072 So= 2.37503
B=9 Eo= 3.88 E= 6.23 E-Eo= 2.35 Re(Z)=0.83 Im(Z)=-0.215043E-2 nlXC= -5.53648 lXC= -10.6698 So= -2.28481

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-points 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 (if interested you can see and learn how to use python scripts using 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 "^ *7 *8" | awk '{print $3+$4}'
to parse the valence band quasiparticle energies and
$ cat o-10b* | grep "^ *7 *9" | 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 2:3 w lp t "Valence BndsRnXp=10", "20b.dat" u 2:3 w lp t "Valence BndsRnXp=20",.. <place here all other datasets>
gnuplot> p "10b.dat" u 2:4 w lp t "Conduction BndsRnXp=10", "20b.dat" u 2:4 w lp t "Conduction BndsRnXp=20",..
gnuplot> p "10b.dat" u 2:($4-$3) w lp t " Gap BndsRnXp=10", "20b.dat" u 2:($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.

====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 <code>gw_ppa_30b_3Ry.in</code> 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 <code>gw_ppa_Gbnd10.in</code>, <code>gw_ppa_Gbnd20.in</code>, 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 "^ *7 *8" o-Gbnd* | awk '{print $4+$5}'
for the valence bands, and
$ grep "^ *7 *9" o-Gbnd* | awk '{print $4+$5}'
for the conduction band.

Collect the results in a text file <code>Gbnd_conv.dat</code> containing: the number of <code>Gbnd</code>, 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.

==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= "none" # 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:
INTERP_mode= "BOLTZ" # Interpolation mode (NN=nearest point, BOLTZ=boltztrap aproach)
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 use the best interpolation method for band structures, 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 structure 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 ==

 
'''For self-consistent GW please follow this tutorial: [http://www.yambo-code.org/wiki/index.php?title=Self-consistent_GW_on_eigenvalues_only Self-consistent GW on eigenvalues only]'''
 

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 absolutely 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 anbed 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.

==Links==
* Back to [[ICTP 2022#Tutorials]]
* Back to [[CECAM VIRTUAL 2021#Tutorials]]



==References==

GW hBN Yambo Virtual 2021 version

2021-04-07T14:24:26Z

Maurizia: /* Step 3: Interpolating Band Structures */

This is a modified version of the tutorial prepared for the Yambo 2021 virtual school.
In case you are interested you can find the extended version of the tutorial here: [[How to obtain the quasi-particle band structure of a bulk material: h-BN]]

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''.

One can also skip this step and go directly to the input file generation for GW (browse below), which already includes the calculation of the exchange self-energy
(simply, this is not discussed in detail as done in the '''[[Hartree Fock]]''' module).

==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 take into account the dynamical effects by setting 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.
It is also possible to perform calculations by evaluating the dielectric matrix on a regular grid of frequencies: for this, you may have a look at the [[Real Axis and Lifetimes]] tutorial.

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

Here the input file is redirected by the <code>-F</code> option to <code>gw_ppa.in</code> (the default name is <code>yambo.in</code>).
Depending on the version of <code>yambo</code>, you may need to open the file for editing.

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 focus 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 [eV] E-Eo [eV] Sc|Eo [eV]
#
7 8 -0.411876 -0.521152 2.375027
7 9 3.877976 2.351568 -2.284813
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: Local XC (Slater exchange(X)+Perdew & Zunger(C))
-nlXC: non-Local XC (Hartree-Fock)

QP [eV] @ K [7] (iku): 0.000000 -0.500000 0.000000
B=8 Eo= -0.41 E= -0.93 E-Eo= -0.52 Re(Z)=0.81 Im(Z)=-0.248518E-2 nlXC= -19.1293 lXC= -16.1072 So= 2.37503
B=9 Eo= 3.88 E= 6.23 E-Eo= 2.35 Re(Z)=0.83 Im(Z)=-0.215043E-2 nlXC= -5.53648 lXC= -10.6698 So= -2.28481

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-points 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 (if interested you can see and learn how to use python scripts using 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 "^ *7 *8" | awk '{print $3+$4}'
to parse the valence band quasiparticle energies and
$ cat o-10b* | grep "^ *7 *9" | 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 2:3 w lp t "Valence BndsRnXp=10", "20b.dat" u 2:3 w lp t "Valence BndsRnXp=20",.. <place here all other datasets>
gnuplot> p "10b.dat" u 2:4 w lp t "Conduction BndsRnXp=10", "20b.dat" u 2:4 w lp t "Conduction BndsRnXp=20",..
gnuplot> p "10b.dat" u 2:($4-$3) w lp t " Gap BndsRnXp=10", "20b.dat" u 2:($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.

====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 <code>gw_ppa_30b_3Ry.in</code> 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 <code>gw_ppa_Gbnd10.in</code>, <code>gw_ppa_Gbnd20.in</code>, 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 "^ *7 *8" o-Gbnd* | awk '{print $4+$5}'
for the valence bands, and
$ grep "^ *7 *9" o-Gbnd* | awk '{print $4+$5}'
for the conduction band.

Collect the results in a text file <code>Gbnd_conv.dat</code> containing: the number of <code>Gbnd</code>, 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.

==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= "none" # 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:
INTERP_mode= "BOLTZ" # Interpolation mode (NN=nearest point, BOLTZ=boltztrap aproach)
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 use the best interpolation method for band structures, 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 structure 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 ==

 
'''For self-consistent GW please follow this tutorial: [http://www.yambo-code.org/wiki/index.php?title=Self-consistent_GW_on_eigenvalues_only Self-consistent GW on eigenvalues only]'''
 

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 absolutely 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 anbed 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: Back to [[CECAM VIRTUAL 2021|CECAM 2021 page]]
|-
|}

==References==

GW hBN Yambo Virtual 2021 version

2021-04-07T13:41:37Z

Maurizia: /* Step 3: Interpolating Band Structures */

This is a modified version of the tutorial prepared for the Yambo 2021 virtual school.
In case you are interested you can find the extended version of the tutorial here: [[How to obtain the quasi-particle band structure of a bulk material: h-BN]]

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''.

One can also skip this step and go directly to the input file generation for GW (browse below), which already includes the calculation of the exchange self-energy
(simply, this is not discussed in detail as done in the '''[[Hartree Fock]]''' module).

==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

Here the input file is redirected by the <code>-F</code> option to <code>gw_ppa.in</code> (the default name is <code>yambo.in</code>).
Depending on the version of <code>yambo</code>, you may need to open the file for editing.

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 focus 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 [eV] E-Eo [eV] Sc|Eo [eV]
#
7 8 -0.411876 -0.521152 2.375027
7 9 3.877976 2.351568 -2.284813
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: Local XC (Slater exchange(X)+Perdew & Zunger(C))
-nlXC: non-Local XC (Hartree-Fock)

QP [eV] @ K [7] (iku): 0.000000 -0.500000 0.000000
B=8 Eo= -0.41 E= -0.93 E-Eo= -0.52 Re(Z)=0.81 Im(Z)=-0.248518E-2 nlXC= -19.1293 lXC= -16.1072 So= 2.37503
B=9 Eo= 3.88 E= 6.23 E-Eo= 2.35 Re(Z)=0.83 Im(Z)=-0.215043E-2 nlXC= -5.53648 lXC= -10.6698 So= -2.28481

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-points 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 (if interested you can see and learn how to use python scripts using 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 "^ *7 *8" | awk '{print $3+$4}'
to parse the valence band quasiparticle energies and
$ cat o-10b* | grep "^ *7 *9" | 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 2:3 w lp t "Valence BndsRnXp=10", "20b.dat" u 2:3 w lp t "Valence BndsRnXp=20",.. <place here all other datasets>
gnuplot> p "10b.dat" u 2:4 w lp t "Conduction BndsRnXp=10", "20b.dat" u 2:4 w lp t "Conduction BndsRnXp=20",..
gnuplot> p "10b.dat" u 2:($4-$3) w lp t " Gap BndsRnXp=10", "20b.dat" u 2:($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.

====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 <code>gw_ppa_30b_3Ry.in</code> 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 <code>gw_ppa_Gbnd10.in</code>, <code>gw_ppa_Gbnd20.in</code>, 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 "^ *7 *8" o-Gbnd* | awk '{print $4+$5}'
for the valence bands, and
$ grep "^ *7 *9" o-Gbnd* | awk '{print $4+$5}'
for the conduction band.

Collect the results in a text file <code>Gbnd_conv.dat</code> containing: the number of <code>Gbnd</code>, 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.

==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= "none" # 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:
INTERP_mode= "BOLTZ" # Interpolation mode (NN=nearest point, BOLTZ=boltztrap aproach)
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 use the best interpolation method for band structures, 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 ==

 
'''For self-consistent GW please follow this tutorial: [http://www.yambo-code.org/wiki/index.php?title=Self-consistent_GW_on_eigenvalues_only Self-consistent GW on eigenvalues only]'''
 

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 absolutely 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 anbed 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==

GW hBN Yambo Virtual 2021 version

2021-04-06T12:44:30Z

Maurizia: /* Converging Screening Parameters */

This is a modified version of the tutorial prepared for the Yambo 2021 virtual school.
In case you are interested you can find the extended version of the tutorial here: [[How to obtain the quasi-particle band structure of a bulk material: h-BN]]

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 focus 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-points 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 (if interested you can see and learn how to use python scripts using 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 "7 8" | awk '{print $3+$4}'
to parse the valence band quasiparticle energies and
$ cat o-10b* | grep "7 9" | 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.

====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.

==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 ==

 
'''For self-consistent GW please look this new tutorial: [http://www.yambo-code.org/wiki/index.php?title=Self-consistent_GW_on_eigenvalues_only Self-consistent GW on eigenvalues only]'''
 

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 absolutely 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 anbed 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==

GW hBN Yambo Virtual 2021 version

2021-04-06T12:43:49Z

Maurizia: /* Converging Screening Parameters */

This is a modified version of the tutorial prepared for the Yambo 2021 virtual school.
In case you are interested you can find the extended version of the tutorial here: [[How to obtain the quasi-particle band structure of a bulk material: h-BN]]

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 focus 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-points 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 (if interested you can see and learn how to use python scripts using 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 "7 8" | awk '{print $3+$4}'
to parse the valence band quasiparticle energies and
$ cat o-10b* | grep "7 9" | 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.

====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.

==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 ==

 
'''For self-consistent GW please look this new tutorial: [http://www.yambo-code.org/wiki/index.php?title=Self-consistent_GW_on_eigenvalues_only Self-consistent GW on eigenvalues only]'''
 

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 absolutely 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 anbed 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==

GW hBN Yambo Virtual 2021 version

2021-04-06T12:42:52Z

Maurizia: /* Converging Screening Parameters */

This is a modified version of the tutorial prepared for the Yambo 2021 virtual school.
In case you are interested you can find the extended version of the tutorial here: [[How to obtain the quasi-particle band structure of a bulk material: h-BN]]

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 focus 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-points 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 (if interested you can see and learn how to use python scripts using 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 "7 8" | awk '{print $3+$4}'
! $ cat o-10b* | grep "8.000" | awk '{print $3+$4}'
to parse the valence band quasiparticle energies and
$ cat o-10b* | grep "7 9" | awk '{print $3+$4}'
! $ 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.

====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.

==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 ==

 
'''For self-consistent GW please look this new tutorial: [http://www.yambo-code.org/wiki/index.php?title=Self-consistent_GW_on_eigenvalues_only Self-consistent GW on eigenvalues only]'''
 

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 absolutely 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 anbed 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==

GW hBN Yambo Virtual 2021 version

2021-04-06T09:24:27Z

Maurizia: /* Converging Screening Parameters */

This is a modified version of the tutorial prepared for the Yambo 2021 virtual school.
In case you are interested you can find the extended version of the tutorial here: [[How to obtain the quasi-particle band structure of a bulk material: h-BN]]

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 focus 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-points 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 (if interested you can see and learn how to use python scripts using 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.

====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.

==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 ==

 
'''For self-consistent GW please look this new tutorial: [http://www.yambo-code.org/wiki/index.php?title=Self-consistent_GW_on_eigenvalues_only Self-consistent GW on eigenvalues only]'''
 

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 absolutely 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 anbed 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==

GW hBN Yambo Virtual 2021 version

2021-04-06T09:22:03Z

Maurizia: /* Convergence tests for a quasi particle calculation */

This is a modified version of the tutorial prepared for the Yambo 2021 virtual school.
In case you are interested you can find the extended version of the tutorial here: [[How to obtain the quasi-particle band structure of a bulk material: h-BN]]

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 focus 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-points 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.

====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.

==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 ==

 
'''For self-consistent GW please look this new tutorial: [http://www.yambo-code.org/wiki/index.php?title=Self-consistent_GW_on_eigenvalues_only Self-consistent GW on eigenvalues only]'''
 

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 absolutely 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 anbed 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==

First steps: walk through from DFT(standalone)

2021-04-06T08:32:30Z

Maurizia: /* Download the Files */

In this tutorial you will learn how to calculate optical spectra using Yambo, starting from a DFT calculation and ending with a look at local field effects in the optical response.

== System characteristics ==
We will use a 3D system (bulk hBN) and a 2D system (hBN sheet).

[[File:HBN-bulk-3x3-annotated.png|x200px|Atomic structure of bulk hBN]]
[[File:HBN2.png|x200px|Atomic structure of 2D hBN]]

'''Hexagonal boron nitride - hBN''':
* HCP lattice, ABAB stacking
* Four atoms per cell, B and N (16 electrons)
* Lattice constants: ''a'' = 4.716 [a.u.], ''c/a'' = 2.582
* Plane wave cutoff 40 Ry (~1500 RL vectors in wavefunctions)
* SCF run: shifted ''6x6x2'' grid (12 k-points) with 8 bands
* Non-SCF run: gamma-centred ''6x6x2'' (14 k-points) grid with 100 bands

=== Prerequisites ===
'''You will need''':
* PWSCF input files and pseudopotentials for hBN bulk
* <code>pw.x</code> executable, version 5.0 or later
* <code>p2y</code> and <code>yambo</code> executables
* <code>gnuplot</code> for plotting spectra

==Download the Files==

Download and unpack the followint files:
[http://www.yambo-code.org/educational/tutorials/files/hBN.tar.gz hBN.tar.gz] [15 MB],
[http://www.yambo-code.org/educational/tutorials/files/hBN-2D.tar.gz hBN-2D.tar.gz] [8,6 MB]

In the next days you could also use this file which you may like to download now
[http://www.yambo-code.org/educational/tutorials/files/hBN-convergence-kpoints.tar.gz hBN-convergence-kpoints.tar.gz] [254 MB]

After downloading the tar.gz files just unpack them in the '''YAMBO_TUTORIALS''' folder. For example
$ mkdir YAMBO_TUTORIALS
$ mv hBN.tar.gz YAMBO_TUTORIALS
$ cd YAMBO_TUTORIALS
$ tar -xvfz hBN.tar.gz
$ ls YAMBO_TUTORIALS
hBN
$ cd hBN
$ ls
$ PWSCF YAMBO

(Advanced users can download and install all tutorial files using git. See the main [[Tutorials#Files|Tutorial Files]] page.)

Now you can go directly in '''YAMBO''' folder where you can find the '''SAVE''' folder which is needed to start and go directly to '''[Initialization of Yambo databases]''' below, which is always the first step you have to perform for any simulation using the Yambo code.

Or if you wish you can learn also how to start from the DFT simulations doing a scf and nscf calculation, entering in '''PWSCF''' folder. In this way you will see how you can create the '''SAVE''' folder starting from *.save directory produced by pw.x.

==DFT calculation of bulk hBN and conversion to Yambo==

In this module you will learn how to generate the Yambo ''SAVE'' folder for bulk hBN starting from a PWscf calculation.

=== DFT calculations ===
$ cd YAMBO_TUTORIALS/hBN/PWSCF
$ ls
Inputs Pseudos PostProcessing References
hBN_scf.in hBN_nscf.in hBN_scf_plot_bands.in hBN_nscf_plot_bands.in

First run the SCF calculation to generate the ground-state charge density, occupations, Fermi level, and so on:
$ pw.x < hBN_scf.in > hBN_scf.out
Inspection of the output shows that the valence band maximum lies at 5.06eV.

Next run a non-SCF calculation to generate a set of Kohn-Sham eigenvalues and eigenvectors for both occupied and unoccupied states (100 bands):
$ pw.x < hBN_nscf.in > hBN_nscf.out ''(serial run, ~1 min) OR''
$ mpirun -np 2 pw.x < hBN_nscf.in > hBN_nscf.out ''(parallel run, 40s)''
Here we use a ''6x6x2'' grid giving 14 k-points, but denser grids should be used for checking convergence of Yambo runs.

Note the presence of the following flags in the input file:
wf_collect=.true.
force_symmorphic=.true.
diago_thr_init=5.0e-6,
diago_full_acc=.true.
which are needed for generating the Yambo databases accurately. Full explanations of these variables are given on the [http://www.quantum-espresso.org/wp-content/uploads/Doc/INPUT_PW.html quantum-ESPRESSO input variables page].

After these two runs, you should have a ''hBN.save'' directory:
$ ls hBN.save
data-file.xml charge-density.dat gvectors.dat B.pz-vbc.UPF N.pz-vbc.UPF
K00001 K00002 .... K00035 K00036
-->

=== Conversion to Yambo format ===
Once you have performed a nscf simulation with pw.x the PWscf ''bBN.save'' should not be empty and you can then convert it to the Yambo format using the <code>p2y</code> executable (pwscf to yambo), found in the yambo ''bin'' directory.
Enter ''hBN.save'' and launch <code>p2y</code>:

$ cd hBN.save
$ p2y
...
<---> DBs path set to .
<---> Index file set to data-file.xml
<---> Header/K-points/Energies... done
...
<---> == DB1 (Gvecs and more) ...
<---> ... Database done
<---> == DB2 (wavefunctions) ... done ==
<---> == DB3 (PseudoPotential) ... done ==
<---> == P2Y completed ==

This output repeats some information about the system and generates a ''SAVE'' directory:
$ ls SAVE
ns.db1 ns.wf ns.kb_pp_pwscf
ns.wf_fragments_1_1 ...
ns.kb_pp_pwscf_fragment_1 ...
These files, with an ''n'' prefix, indicate that they are in netCDF format, and thus not human readable. However, they are perfectly transferable across different architectures. You can check that the databases contain the information you expect by launching Yambo using the <code>-D</code> option:

$ yambo -D
[RD./SAVE//ns.db1]------------------------------------------
Bands : 100
K-points : 14
G-vectors [RL space]: 8029
Components [wavefunctions]: 1016
...
[RD./SAVE//ns.wf]-------------------------------------------
Fragmentation :yes
...
[RD./SAVE//ns.kb_pp_pwscf]----------------------------------
Fragmentation :yes
- S/N 006626 -------------------------- v.04.01.02 r.00000 -

In practice we suggest to move the ''SAVE'' folder into a new clean folder.

In this tutorial however, we ask instead that you continue using a ''SAVE'' folder that we prepared previously:
$ cd ../../YAMBO
$ ls
SAVE

==Initialization of Yambo databases==
Use the ''SAVE'' folders that are already provided, rather than any ones you may have generated previously.

Every Yambo run '''must''' start with this step. Go to the folder ''containing'' the hBN-bulk <code>SAVE</code> directory:
$ cd YAMBO_TUTORIALS/hBN/YAMBO
$ ls
SAVE

'''TIP''': do not run yambo from ''inside'' the <code>SAVE</code> folder!
'''This is the wrong way .. '''
$ cd SAVE
$ yambo
yambo: cannot access CORE database (SAVE/*db1 and/or SAVE/*wf)
In fact, if you ever see such message:
it usually means you are trying to launch Yambo '''from the wrong place'''.
$ cd ..

Now you are in the proper place and
$ ls
SAVE
you can simply launch the code
$ yambo
This will run the initialization (setup) ''runlevel''.

===Run-time output===
This is typically written to standard output (on screen) and tracks the progress of the run in real time:
<---> [01] MPI/OPENMP structure, Files & I/O Directories
<---> [02] CORE Variables Setup
<---> [02.01] Unit cells
<---> [02.02] Symmetries
<---> [02.03] Reciprocal space
<---> Shells finder |########################################| [100%] --(E) --(X)
<---> [02.04] K-grid lattice
<---> Grid dimensions : 6 6 2
<---> [02.05] Energies & Occupations
<---> [03] Transferred momenta grid and indexing
<---> BZ -> IBZ reduction |########################################| [100%] --(E) --(X)
<---> [03.01] X indexes
<---> X [eval] |########################################| [100%] --(E) --(X)
<---> X[REDUX] |########################################| [100%] --(E) --(X)
<---> [03.01.01] Sigma indexes
<---> Sigma [eval] |########################################| [100%] --(E) --(X)
<---> Sigma[REDUX] |########################################| [100%] --(E) --(X)
<---> [04] Timing Overview
<---> [05] Memory Overview
<---> [06] Game Over & Game summary
Specific runlevels are indicated with numeric labels like [02.02]. 
The hashes (#) indicate progress of the run in Wall Clock time, indicating the elapsed (E) and expected (X) time to complete a runlevel, and the percentage of the task complete.

===New core databases===
New databases appear in the ''SAVE'' folder:
$ ls SAVE
ns.db1 ns.wf ns.kb_pp_pwscf '''ndb.gops ndb.kindx'''
ns.wf_fragments_1_1 ...
ns.kb_pp_pwscf_fragment_1 ...
These contain information about the ''G''-vector shells and ''k/q''-point meshes as defined by the DFT calculation.

In general: a database called ''n'''s'''.xxx'' is a ''static'' database, generated once by <code>p2y</code>, while databases called ''n'''db'''.xxx'' are ''dynamically'' generated while you use <code>yambo</code>.

'''TIP''': if you launch <code>yambo</code>, but it does not seem to do anything, check that these files are present.

===Report file===
A report file ''r_setup'' is generated in the run directory.
This mostly reports information about the ground state system as defined by the DFT run, but also adds information about the band gaps, occupations, shells of G-vectors, IBZ/BZ grids, the CPU structure (for parallel runs), and so on. Some points of note:

Up to Yambo version 4.5
[02.03] RL shells
=================
Shells, format: [S#] G_RL(mHa)
[S453]:8029(0.7982E+5) [S452]:8005(0.7982E+5) [S451]:7981(0.7982E+5) [S450]:7957(0.7942E+5)
...
[S4]:11( 1183.) [S3]:5( 532.5123) [S2]:3( 133.1281) [S1]:1( 0.000000)

From Yambo version 5.0
[02.03] Reciprocal space
========================

nG shells : 217
nG charge : 3187
nG WFs : 1477
nC WFs : 1016
G-vecs. in first 21 shells: [ Number ]
1 3 5 11 13 25 37 39 51
63 65 71 83 95 107 113 125 127
139 151 163
...
Shell energy in first 21 shells: [ mHa ]
0.00000 133.128 532.512 1183.37 1198.15 1316.50 1715.88 2130.05 2381.52
3313.42 3328.20 3550.11 3683.24 4082.62 4511.57 4733.48 4748.27 4792.61
4866.61 5266.00 5680.16
...

This reports the set of closed reciprocal lattice (RL) shells defined internally that contain G-vectors with the same modulus.
The highest number of RL vectors we can use is 8029. Yambo will always redefine any input variable in RL units to the nearest closed shell.

Up to Yambo version 4.5
[02.05] Energies [ev] & Occupations
===================================
Fermi Level [ev]: 5.112805
VBM / CBm [ev]: 0.000000 3.876293
Electronic Temp. [ev K]: 0.00 0.00
Bosonic Temp. [ev K]: 0.00 0.00
El. density [cm-3]: 0.460E+24
States summary : Full Metallic Empty
0001-0008 0009-0100
Indirect Gaps [ev]: 3.876293 7.278081
Direct Gaps [ev]: 4.28829 11.35409
X BZ K-points : 72

From Yambo version 5.0
[02.05] Energies & Occupations
==============================

[X] === General ===
[X] Electronic Temperature : 0.000000 0.000000 [eV K]
[X] Bosonic Temperature : 0.000000 0.000000 [eV K]
[X] Finite Temperature mode : no
[X] El. density : 0.46037E+24 [cm-3]
[X] Fermi Level : 5.110835 [eV]

[X] === Gaps and Widths ===
[X] Conduction Band Min : 3.877976 [eV]
[X] Valence Band Max : 0.000000 [eV]
[X] Filled Bands : 8
[X] Empty Bands : 9 100
[X] Direct Gap : 4.289853 [eV]
[X] Direct Gap localized at k-point : 7
[X] Indirect Gap : 3.877976 [eV]
[X] Indirect Gap between k-points : 14 7
[X] Last valence band width : 3.401086 [eV]
[X] 1st conduction band width : 4.266292 [eV]

Yambo recalculates again the Fermi level (close to the value of 5.06 noted in the PWscf SCF calculation). From here on, however, the Fermi level is set to zero, and other eigenvalues are shifted accordingly. The system is insulating (8 filled, 92 empty) with an indirect band gap of 3.87 eV. The minimum and maximum direct and indirect gaps are indicated. There are 72 k-points in the full BZ, generated using symmetry from the 14 k-points in our user-defined grid.

'''TIP''': You should inspect the report file after ''every'' run for errors and warnings.

===Different ways of running yambo===
We just run Yambo interactively.

Let's try to re-run the setup with the command
$ nohup yambo &
$ ls
l_setup nohup.out r_setup r_setup_01 SAVE

If Yambo is launched using a script, or as a background process, or in parallel, this output will appear in a log file prefixed by the letter ''l'', in this case as ''l_setup''.
If this log file already exists from a previous run, it will not be overwritten. Instead, a new file will be created with an incrementing numerical label, e.g. ''l_setup_01, l_setup_02'', etc. '''This applies to all files created by Yambo'''. Here we see that l_setup was created for the first time, but r_setup already existed from the previous run, so now we have r_setup_01
If you check the differences between the two you will notice that in the second run yambo is reading the previously created ndb.kindx in place of re-computing the indexes.
Indeed the output inside l_setup does not show the timing for X and Sigma

As a last step we run the setup in parallel, but first we delete the ndb.kindx file
$ rm SAVE/ndb.kindx
$ mpirun -np 4 yambo
$ ls
LOG l_setup nohup.out r_setup r_setup_01 r_setup_02 SAVE
There is now r_setup_02
In the case of parallel runs, CPU-dependent log files will appear inside a ''LOG'' folder, e.g.
$ ls LOG
l_setup_CPU_1 l_setup_CPU_2 l_setup_CPU_3 l_setup_CPU_4
This behaviour can be controlled at runtime - see the Parallel tutorial for details.

===2D hBN===
Simply repeat the steps above. Go to the folder ''containing'' the hBN-sheet ''SAVE'' directory and launch <code>yambo</code>:
$ cd TUTORIALS/hBN-2D/YAMBO
$ ls
SAVE
$ yambo
Again, inspect the ''r_setup'' file, output logs, and verify that ''ndb.gops'' and ''ndb.kpts'' have been created inside the SAVE folder.

You are now ready to use Yambo!

==Yambo's command line interface==
Yambo uses a command line interface to select tasks, generate input files, and control the runtime behaviour.

In this module you will learn how to select tasks, generate and modify input files, and control the runtime behaviour by using Yambo's command line interface.


=== Input file generator ===
First, move to the appropriate folder and initialize the Yambo databases if you haven't already done so.
$ cd YAMBO_TUTORIALS/hBN/YAMBO
$ yambo ''(initialize)''

Yambo generates its own input files: you just tell the code what you want to calculate by launching Yambo along with one or more options.
To see the list of possible options, run <code>yambo -h</code> (we report here only the part we are focusing in)
$ yambo -h
'A shiny pot of fun and happiness [C.D.Hogan]'

This is : yambo
Version : 5.0.1 Revision 19547 Hash e90d90f2d
Configuration: MPI+OpenMP+SLK+SLEPC+HDF5_MPI_IO

...

Initializations:
-setup (-i) :Initialization
-coulomb (-r) :Coulomb potential

Response Functions:
-optics (-o) <string> :Linear Response optical properties (more with -h optics)
-X (-d) <string> :Inverse Dielectric Matrix (more with -h X)
-dipoles (-q) :Oscillator strenghts (or dipoles)
-kernel (-k) <string> :Kernel (more with -h kernel)

Self-Energy:
-hf (-x) :Hartree-Fock
-gw0 (-p) <string> :GW approximation (more with -h gw0)
-dyson (-g) <string> :Dyson Equation solver (more with -h dyson)
-lifetimes (-l) :GoWo Quasiparticle lifetimes

Bethe-Salpeter Equation:
-Ksolver (-y) <string> :BSE solver (more with -h Ksolver)

Total Energy:
-acfdt :ACFDT Total Energy

Utilites:
...
-slktest :ScaLapacK test

The options can be split into two sets: 
* A set of options which is needed to generate the appropriate input file (default name: ''yambo.in'') selecting the kind of simulation you would like to perform 
* A set of options which can be used to manage auxiliary functions (like redirect the I/O, choose a specific name for the input file, etc ..).

===Runlevel selection===
First of all, you would like to specify which kind of simulation you are going to perform and generate an input file with the first set of options.
By default, when generating the input file, Yambo will launch the <code>vi</code> editor.
Editor choice can be changed when launching the configure before compilation; alternatively you can use the <code>-Q</code> run time option to skip the automatic editing (do this if you are not familiar with <code>vi</code>!):
$ yambo -hf -Q
yambo: input file yambo.in created
$ emacs yambo.in ''or your favourite editing tool''

Multiple options can be used together to activate various tasks or runlevels (in some cases this is actually a necessity).
For instance, to generate an input file for optical spectra including local field effects (Hartree approximation), do (and then exit)
$ yambo -optics c -kernel hartree ''which switches on:''
optics # [R OPT] Optics
chi # [R CHI] Dyson equation for Chi.
Chimod= "Hartree" # [X] IP/Hartree/ALDA/LRC/BSfxc
To perform a Hartree-Fock and GW calculation using a plasmon-pole approximation, do (and then exit):
$ yambo -hf -gw0 p -dyson n ''which switches on:''
HF_and_locXC # [R XX] Hartree-Fock Self-energy and Vxc
gw0 # [R GW] GoWo Quasiparticle energy levels
ppa # [R Xp] Plasmon Pole Approximation
em1d # [R Xd] Dynamical Inverse Dielectric Matrix
Each runlevel activates its own list of variables and flags.

The previous command is also equivalent to
$ yambo -hf -gw0 r -dyson n -X p

===Changing input parameters ===
Yambo reads various parameters from existing database files and/or input files and uses them to suggest values or ranges.
Let's illustrate this by generating the input file for a Hartree-Fock calculation.

$ yambo -hf
Inside the generated input file you should find:
[[Variables#EXXRLvcs|EXXRLvcs]] = 3187 RL # [XX] Exchange RL components
%[[Variables#QPkrange|QPkrange]] # [GW] QP generalized Kpoint/Band indices
1| 14| 1|100|
%
The <code>[[Variables#QPkrange|QPkrange]]</code> variable (follow the link for a "detailed" explanation for any variable) suggests a range of k-points (1 to 14) and bands (1 to 100) based on what it finds in the core database ''SAVE/ns.db1'', i.e. as defined by the DFT code. 
Leave that variable alone, and instead modify the previous variable to <code>EXXRLvcs= 1000 RL</code>

Save the file, and now generate the input a second time with <code>yambo -x</code>. You will see:
[[Variables#EXXRLvcs|EXXRLvcs]]= 1009 RL
This indicates that Yambo has read the new input value (1000 G-vectors), checked the database of G-vector shells ''(SAVE/ndb.gops)'',
and changed the input value to one that fits a completely closed shell.

Last, note that Yambo variables can be expressed in different '''units'''. In this case, <code>RL</code> can be replaced by an energy unit like Ry, eV, Ha, etc. Energy units are generally better as they are independent of the cell size. Technical information is available on the [[Variables]] page.

The input file generator of Yambo is thus an ''intelligent'' parser, which interacts with the user and the existing databases. For this reason we recommend that you always use Yambo to generate the input files, rather than making them yourself.

===Extra options===
Extra options modify some of the code's default settings. They can be used when launching the code but also when generating input files.

Let's have a look again to the possible options (we report here only the part we are focusing in):
$ yambo -h
This is : yambo
Version : 5.0.1 Revision 19547 Hash e90d90f2d
Configuration: MPI+OpenMP+SLK+SLEPC+HDF5_MPI_IO

Help & version:
-help (-h) <string> :<string> can be an option (e.g. -h optics)
-version :Code version & libraries

Input file & Directories:
-Input (-F) <string> :Input file
-Verbosity (-V) <string> :Input file variables verbosity (more with -h Verbosity)
-Job (-J) <string> :Job string
-Idir (-I) <string> :Input directory
-Odir (-O) <string> :I/O directory
-Cdir (-C) <string> :Communication directory

Parallel Control:
-parenv (-E) <string> :Environment Parallel Variables file
-nompi :Switch off MPI support
-noopenmp :Switch off OPENMP support

...

Utilites:
-Quiet (-Q) :Quiet input file creation
-fatlog :Verbose (fatter) log(s)
-DBlist (-D) :Databases properties
...

Command line options are extremely important to master if you want to use yambo productively.
Often, the meaning is clear from the help menu:
$ yambo -F yambo.in_HF -hf ''Make a Hartree-Fock input file called yambo.in_HF''
$ yambo -D ''Summarize the content of the databases in the SAVE folder''
$ yambo -I ../ ''Run the code, using a SAVE folder in a directory one level up''
$ yambo -C MyTest ''Run the code, putting all report, log, plot files inside a folder MyTest''

Other options deserve a closer look.

===Verbosity===
Yambo uses ''many'' input variables, many of which can be left at their default values. To keep input files short and manageable, only a few variables appear by default in the inout file. More advanced variables can be switched on by using the <code>-V</code> verbosity option. These are grouped according to the type of variable. For instance, <code>-V RL</code> switches on variables related to G vector summations, and <code>-V io</code> switches on options related to I/O control. Try:

$ yambo -optics c -V RL ''switches on:''
FFTGvecs= 3951 RL # [FFT] Plane-waves

$ yambo -optics c -V io ''switches on:''
StdoHash= 40 # [IO] Live-timing Hashes
DBsIOoff= "none" # [IO] Space-separated list of DB with NO I/O. DB= ...
DBsFRAGpm= "none" # [IO] Space-separated list of +DB to be FRAG and ...
#WFbuffIO # [IO] Wave-functions buffered I/O

Unfortunately, -V options must be invoked and changed ''one at a time''. When you are more expert, you may go straight to <code>-V all</code>, which turns on all possible variables. However note that <code>yambo -o c -V all</code> adds an extra 30 variables to the input file, which can be confusing: use it with care.

===Job script label===
The best way to keep track of different runs using different parameters is through the <code>-J</code> flag. This inserts a label in all output and report files, and creates a new folder containing any new databases (i.e. they are not written in the core ''SAVE'' folder). Try:
$ yambo -J 1Ry -V RL -hf -F yambo_hf.in ''and modify to''
FFTGvecs = 1 Ry
EXXGvecs = 1 Ry
$ yambo -J 1Ry -F yambo_hf.in ''Run the code''
$ ls
yambo_hf.in SAVE
o-1Ry.hf r-1Ry_HF_and_locXC 1Ry 1Ry/ndb.HF_and_locXC
This is extremely useful when running convergence tests, trying out different parameters, etc.

''Exercise'': use <code>yambo</code> to report the properties of all database files (including ''ndb.HF_and_locXC'')

First steps: walk through from DFT(standalone)

2021-04-06T08:24:39Z

Maurizia: /* Download the Files */

In this tutorial you will learn how to calculate optical spectra using Yambo, starting from a DFT calculation and ending with a look at local field effects in the optical response.

== System characteristics ==
We will use a 3D system (bulk hBN) and a 2D system (hBN sheet).

[[File:HBN-bulk-3x3-annotated.png|x200px|Atomic structure of bulk hBN]]
[[File:HBN2.png|x200px|Atomic structure of 2D hBN]]

'''Hexagonal boron nitride - hBN''':
* HCP lattice, ABAB stacking
* Four atoms per cell, B and N (16 electrons)
* Lattice constants: ''a'' = 4.716 [a.u.], ''c/a'' = 2.582
* Plane wave cutoff 40 Ry (~1500 RL vectors in wavefunctions)
* SCF run: shifted ''6x6x2'' grid (12 k-points) with 8 bands
* Non-SCF run: gamma-centred ''6x6x2'' (14 k-points) grid with 100 bands

=== Prerequisites ===
'''You will need''':
* PWSCF input files and pseudopotentials for hBN bulk
* <code>pw.x</code> executable, version 5.0 or later
* <code>p2y</code> and <code>yambo</code> executables
* <code>gnuplot</code> for plotting spectra

==Download the Files==

Download and unpack the followint files:
[http://www.yambo-code.org/educational/tutorials/files/hBN.tar.gz hBN.tar.gz] [15 MB],
[http://www.yambo-code.org/educational/tutorials/files/hBN-2D.tar.gz hBN-2D.tar.gz] [8,6 MB]

In the next days you could also use this file which you may like to download now
[http://www.yambo-code.org/educational/tutorials/files/hBN-convergence-kpoints.tar.gz hBN-convergence-kpoints.tar.gz] [254 MB]

After downloading the tar.gz files just unpack them in the '''YAMBO_TUTORIALS''' folder. For example
$ mkdir YAMBO_TUTORIALS
$ mv hBN.tar.gz YAMBO_TUTORIALS
$ cd YAMBO_TUTORIALS
$ tar -xvfz hBN.tar.gz
$ ls YAMBO_TUTORIALS
hBN
$ cd hBN
$ ls
$ PWSCF YAMBO

(Advanced users can download and install all tutorial files using git. See the main [[Tutorials#Files|Tutorial Files]] page.)

Now you can go directly in '''YAMBO''' folder where you can find the '''SAVE''' folder which is needed to start and go directly to '''[[Initialization of Yambo databases]]''' which is always the first step you have to perform for any simulation using the Yambo code.

Or if you wish you can learn (see below) how to start from the DFT simulations doing a scf and nscf calculation, entering in '''PWSCF''' folder. In this way you will see how you can create the '''SAVE''' folder starting from *.save directory produced by pw.x.

==DFT calculation of bulk hBN and conversion to Yambo==

In this module you will learn how to generate the Yambo ''SAVE'' folder for bulk hBN starting from a PWscf calculation.

=== DFT calculations ===
$ cd YAMBO_TUTORIALS/hBN/PWSCF
$ ls
Inputs Pseudos PostProcessing References
hBN_scf.in hBN_nscf.in hBN_scf_plot_bands.in hBN_nscf_plot_bands.in

First run the SCF calculation to generate the ground-state charge density, occupations, Fermi level, and so on:
$ pw.x < hBN_scf.in > hBN_scf.out
Inspection of the output shows that the valence band maximum lies at 5.06eV.

Next run a non-SCF calculation to generate a set of Kohn-Sham eigenvalues and eigenvectors for both occupied and unoccupied states (100 bands):
$ pw.x < hBN_nscf.in > hBN_nscf.out ''(serial run, ~1 min) OR''
$ mpirun -np 2 pw.x < hBN_nscf.in > hBN_nscf.out ''(parallel run, 40s)''
Here we use a ''6x6x2'' grid giving 14 k-points, but denser grids should be used for checking convergence of Yambo runs.

Note the presence of the following flags in the input file:
wf_collect=.true.
force_symmorphic=.true.
diago_thr_init=5.0e-6,
diago_full_acc=.true.
which are needed for generating the Yambo databases accurately. Full explanations of these variables are given on the [http://www.quantum-espresso.org/wp-content/uploads/Doc/INPUT_PW.html quantum-ESPRESSO input variables page].

After these two runs, you should have a ''hBN.save'' directory:
$ ls hBN.save
data-file.xml charge-density.dat gvectors.dat B.pz-vbc.UPF N.pz-vbc.UPF
K00001 K00002 .... K00035 K00036
-->

=== Conversion to Yambo format ===
Once you have performed a nscf simulation with pw.x the PWscf ''bBN.save'' should not be empty and you can then convert it to the Yambo format using the <code>p2y</code> executable (pwscf to yambo), found in the yambo ''bin'' directory.
Enter ''hBN.save'' and launch <code>p2y</code>:

$ cd hBN.save
$ p2y
...
<---> DBs path set to .
<---> Index file set to data-file.xml
<---> Header/K-points/Energies... done
...
<---> == DB1 (Gvecs and more) ...
<---> ... Database done
<---> == DB2 (wavefunctions) ... done ==
<---> == DB3 (PseudoPotential) ... done ==
<---> == P2Y completed ==

This output repeats some information about the system and generates a ''SAVE'' directory:
$ ls SAVE
ns.db1 ns.wf ns.kb_pp_pwscf
ns.wf_fragments_1_1 ...
ns.kb_pp_pwscf_fragment_1 ...
These files, with an ''n'' prefix, indicate that they are in netCDF format, and thus not human readable. However, they are perfectly transferable across different architectures. You can check that the databases contain the information you expect by launching Yambo using the <code>-D</code> option:

$ yambo -D
[RD./SAVE//ns.db1]------------------------------------------
Bands : 100
K-points : 14
G-vectors [RL space]: 8029
Components [wavefunctions]: 1016
...
[RD./SAVE//ns.wf]-------------------------------------------
Fragmentation :yes
...
[RD./SAVE//ns.kb_pp_pwscf]----------------------------------
Fragmentation :yes
- S/N 006626 -------------------------- v.04.01.02 r.00000 -

In practice we suggest to move the ''SAVE'' folder into a new clean folder.

In this tutorial however, we ask instead that you continue using a ''SAVE'' folder that we prepared previously:
$ cd ../../YAMBO
$ ls
SAVE

==Initialization of Yambo databases==
Use the ''SAVE'' folders that are already provided, rather than any ones you may have generated previously.

Every Yambo run '''must''' start with this step. Go to the folder ''containing'' the hBN-bulk <code>SAVE</code> directory:
$ cd YAMBO_TUTORIALS/hBN/YAMBO
$ ls
SAVE

'''TIP''': do not run yambo from ''inside'' the <code>SAVE</code> folder!
'''This is the wrong way .. '''
$ cd SAVE
$ yambo
yambo: cannot access CORE database (SAVE/*db1 and/or SAVE/*wf)
In fact, if you ever see such message:
it usually means you are trying to launch Yambo '''from the wrong place'''.
$ cd ..

Now you are in the proper place and
$ ls
SAVE
you can simply launch the code
$ yambo
This will run the initialization (setup) ''runlevel''.

===Run-time output===
This is typically written to standard output (on screen) and tracks the progress of the run in real time:
<---> [01] MPI/OPENMP structure, Files & I/O Directories
<---> [02] CORE Variables Setup
<---> [02.01] Unit cells
<---> [02.02] Symmetries
<---> [02.03] Reciprocal space
<---> Shells finder |########################################| [100%] --(E) --(X)
<---> [02.04] K-grid lattice
<---> Grid dimensions : 6 6 2
<---> [02.05] Energies & Occupations
<---> [03] Transferred momenta grid and indexing
<---> BZ -> IBZ reduction |########################################| [100%] --(E) --(X)
<---> [03.01] X indexes
<---> X [eval] |########################################| [100%] --(E) --(X)
<---> X[REDUX] |########################################| [100%] --(E) --(X)
<---> [03.01.01] Sigma indexes
<---> Sigma [eval] |########################################| [100%] --(E) --(X)
<---> Sigma[REDUX] |########################################| [100%] --(E) --(X)
<---> [04] Timing Overview
<---> [05] Memory Overview
<---> [06] Game Over & Game summary
Specific runlevels are indicated with numeric labels like [02.02]. 
The hashes (#) indicate progress of the run in Wall Clock time, indicating the elapsed (E) and expected (X) time to complete a runlevel, and the percentage of the task complete.

===New core databases===
New databases appear in the ''SAVE'' folder:
$ ls SAVE
ns.db1 ns.wf ns.kb_pp_pwscf '''ndb.gops ndb.kindx'''
ns.wf_fragments_1_1 ...
ns.kb_pp_pwscf_fragment_1 ...
These contain information about the ''G''-vector shells and ''k/q''-point meshes as defined by the DFT calculation.

In general: a database called ''n'''s'''.xxx'' is a ''static'' database, generated once by <code>p2y</code>, while databases called ''n'''db'''.xxx'' are ''dynamically'' generated while you use <code>yambo</code>.

'''TIP''': if you launch <code>yambo</code>, but it does not seem to do anything, check that these files are present.

===Report file===
A report file ''r_setup'' is generated in the run directory.
This mostly reports information about the ground state system as defined by the DFT run, but also adds information about the band gaps, occupations, shells of G-vectors, IBZ/BZ grids, the CPU structure (for parallel runs), and so on. Some points of note:

Up to Yambo version 4.5
[02.03] RL shells
=================
Shells, format: [S#] G_RL(mHa)
[S453]:8029(0.7982E+5) [S452]:8005(0.7982E+5) [S451]:7981(0.7982E+5) [S450]:7957(0.7942E+5)
...
[S4]:11( 1183.) [S3]:5( 532.5123) [S2]:3( 133.1281) [S1]:1( 0.000000)

From Yambo version 5.0
[02.03] Reciprocal space
========================

nG shells : 217
nG charge : 3187
nG WFs : 1477
nC WFs : 1016
G-vecs. in first 21 shells: [ Number ]
1 3 5 11 13 25 37 39 51
63 65 71 83 95 107 113 125 127
139 151 163
...
Shell energy in first 21 shells: [ mHa ]
0.00000 133.128 532.512 1183.37 1198.15 1316.50 1715.88 2130.05 2381.52
3313.42 3328.20 3550.11 3683.24 4082.62 4511.57 4733.48 4748.27 4792.61
4866.61 5266.00 5680.16
...

This reports the set of closed reciprocal lattice (RL) shells defined internally that contain G-vectors with the same modulus.
The highest number of RL vectors we can use is 8029. Yambo will always redefine any input variable in RL units to the nearest closed shell.

Up to Yambo version 4.5
[02.05] Energies [ev] & Occupations
===================================
Fermi Level [ev]: 5.112805
VBM / CBm [ev]: 0.000000 3.876293
Electronic Temp. [ev K]: 0.00 0.00
Bosonic Temp. [ev K]: 0.00 0.00
El. density [cm-3]: 0.460E+24
States summary : Full Metallic Empty
0001-0008 0009-0100
Indirect Gaps [ev]: 3.876293 7.278081
Direct Gaps [ev]: 4.28829 11.35409
X BZ K-points : 72

From Yambo version 5.0
[02.05] Energies & Occupations
==============================

[X] === General ===
[X] Electronic Temperature : 0.000000 0.000000 [eV K]
[X] Bosonic Temperature : 0.000000 0.000000 [eV K]
[X] Finite Temperature mode : no
[X] El. density : 0.46037E+24 [cm-3]
[X] Fermi Level : 5.110835 [eV]

[X] === Gaps and Widths ===
[X] Conduction Band Min : 3.877976 [eV]
[X] Valence Band Max : 0.000000 [eV]
[X] Filled Bands : 8
[X] Empty Bands : 9 100
[X] Direct Gap : 4.289853 [eV]
[X] Direct Gap localized at k-point : 7
[X] Indirect Gap : 3.877976 [eV]
[X] Indirect Gap between k-points : 14 7
[X] Last valence band width : 3.401086 [eV]
[X] 1st conduction band width : 4.266292 [eV]

Yambo recalculates again the Fermi level (close to the value of 5.06 noted in the PWscf SCF calculation). From here on, however, the Fermi level is set to zero, and other eigenvalues are shifted accordingly. The system is insulating (8 filled, 92 empty) with an indirect band gap of 3.87 eV. The minimum and maximum direct and indirect gaps are indicated. There are 72 k-points in the full BZ, generated using symmetry from the 14 k-points in our user-defined grid.

'''TIP''': You should inspect the report file after ''every'' run for errors and warnings.

===Different ways of running yambo===
We just run Yambo interactively.

Let's try to re-run the setup with the command
$ nohup yambo &
$ ls
l_setup nohup.out r_setup r_setup_01 SAVE

If Yambo is launched using a script, or as a background process, or in parallel, this output will appear in a log file prefixed by the letter ''l'', in this case as ''l_setup''.
If this log file already exists from a previous run, it will not be overwritten. Instead, a new file will be created with an incrementing numerical label, e.g. ''l_setup_01, l_setup_02'', etc. '''This applies to all files created by Yambo'''. Here we see that l_setup was created for the first time, but r_setup already existed from the previous run, so now we have r_setup_01
If you check the differences between the two you will notice that in the second run yambo is reading the previously created ndb.kindx in place of re-computing the indexes.
Indeed the output inside l_setup does not show the timing for X and Sigma

As a last step we run the setup in parallel, but first we delete the ndb.kindx file
$ rm SAVE/ndb.kindx
$ mpirun -np 4 yambo
$ ls
LOG l_setup nohup.out r_setup r_setup_01 r_setup_02 SAVE
There is now r_setup_02
In the case of parallel runs, CPU-dependent log files will appear inside a ''LOG'' folder, e.g.
$ ls LOG
l_setup_CPU_1 l_setup_CPU_2 l_setup_CPU_3 l_setup_CPU_4
This behaviour can be controlled at runtime - see the Parallel tutorial for details.

===2D hBN===
Simply repeat the steps above. Go to the folder ''containing'' the hBN-sheet ''SAVE'' directory and launch <code>yambo</code>:
$ cd TUTORIALS/hBN-2D/YAMBO
$ ls
SAVE
$ yambo
Again, inspect the ''r_setup'' file, output logs, and verify that ''ndb.gops'' and ''ndb.kpts'' have been created inside the SAVE folder.

You are now ready to use Yambo!

==Yambo's command line interface==
Yambo uses a command line interface to select tasks, generate input files, and control the runtime behaviour.

In this module you will learn how to select tasks, generate and modify input files, and control the runtime behaviour by using Yambo's command line interface.


=== Input file generator ===
First, move to the appropriate folder and initialize the Yambo databases if you haven't already done so.
$ cd YAMBO_TUTORIALS/hBN/YAMBO
$ yambo ''(initialize)''

Yambo generates its own input files: you just tell the code what you want to calculate by launching Yambo along with one or more options.
To see the list of possible options, run <code>yambo -h</code> (we report here only the part we are focusing in)
$ yambo -h
'A shiny pot of fun and happiness [C.D.Hogan]'

This is : yambo
Version : 5.0.1 Revision 19547 Hash e90d90f2d
Configuration: MPI+OpenMP+SLK+SLEPC+HDF5_MPI_IO

...

Initializations:
-setup (-i) :Initialization
-coulomb (-r) :Coulomb potential

Response Functions:
-optics (-o) <string> :Linear Response optical properties (more with -h optics)
-X (-d) <string> :Inverse Dielectric Matrix (more with -h X)
-dipoles (-q) :Oscillator strenghts (or dipoles)
-kernel (-k) <string> :Kernel (more with -h kernel)

Self-Energy:
-hf (-x) :Hartree-Fock
-gw0 (-p) <string> :GW approximation (more with -h gw0)
-dyson (-g) <string> :Dyson Equation solver (more with -h dyson)
-lifetimes (-l) :GoWo Quasiparticle lifetimes

Bethe-Salpeter Equation:
-Ksolver (-y) <string> :BSE solver (more with -h Ksolver)

Total Energy:
-acfdt :ACFDT Total Energy

Utilites:
...
-slktest :ScaLapacK test

The options can be split into two sets: 
* A set of options which is needed to generate the appropriate input file (default name: ''yambo.in'') selecting the kind of simulation you would like to perform 
* A set of options which can be used to manage auxiliary functions (like redirect the I/O, choose a specific name for the input file, etc ..).

===Runlevel selection===
First of all, you would like to specify which kind of simulation you are going to perform and generate an input file with the first set of options.
By default, when generating the input file, Yambo will launch the <code>vi</code> editor.
Editor choice can be changed when launching the configure before compilation; alternatively you can use the <code>-Q</code> run time option to skip the automatic editing (do this if you are not familiar with <code>vi</code>!):
$ yambo -hf -Q
yambo: input file yambo.in created
$ emacs yambo.in ''or your favourite editing tool''

Multiple options can be used together to activate various tasks or runlevels (in some cases this is actually a necessity).
For instance, to generate an input file for optical spectra including local field effects (Hartree approximation), do (and then exit)
$ yambo -optics c -kernel hartree ''which switches on:''
optics # [R OPT] Optics
chi # [R CHI] Dyson equation for Chi.
Chimod= "Hartree" # [X] IP/Hartree/ALDA/LRC/BSfxc
To perform a Hartree-Fock and GW calculation using a plasmon-pole approximation, do (and then exit):
$ yambo -hf -gw0 p -dyson n ''which switches on:''
HF_and_locXC # [R XX] Hartree-Fock Self-energy and Vxc
gw0 # [R GW] GoWo Quasiparticle energy levels
ppa # [R Xp] Plasmon Pole Approximation
em1d # [R Xd] Dynamical Inverse Dielectric Matrix
Each runlevel activates its own list of variables and flags.

The previous command is also equivalent to
$ yambo -hf -gw0 r -dyson n -X p

===Changing input parameters ===
Yambo reads various parameters from existing database files and/or input files and uses them to suggest values or ranges.
Let's illustrate this by generating the input file for a Hartree-Fock calculation.

$ yambo -hf
Inside the generated input file you should find:
[[Variables#EXXRLvcs|EXXRLvcs]] = 3187 RL # [XX] Exchange RL components
%[[Variables#QPkrange|QPkrange]] # [GW] QP generalized Kpoint/Band indices
1| 14| 1|100|
%
The <code>[[Variables#QPkrange|QPkrange]]</code> variable (follow the link for a "detailed" explanation for any variable) suggests a range of k-points (1 to 14) and bands (1 to 100) based on what it finds in the core database ''SAVE/ns.db1'', i.e. as defined by the DFT code. 
Leave that variable alone, and instead modify the previous variable to <code>EXXRLvcs= 1000 RL</code>

Save the file, and now generate the input a second time with <code>yambo -x</code>. You will see:
[[Variables#EXXRLvcs|EXXRLvcs]]= 1009 RL
This indicates that Yambo has read the new input value (1000 G-vectors), checked the database of G-vector shells ''(SAVE/ndb.gops)'',
and changed the input value to one that fits a completely closed shell.

Last, note that Yambo variables can be expressed in different '''units'''. In this case, <code>RL</code> can be replaced by an energy unit like Ry, eV, Ha, etc. Energy units are generally better as they are independent of the cell size. Technical information is available on the [[Variables]] page.

The input file generator of Yambo is thus an ''intelligent'' parser, which interacts with the user and the existing databases. For this reason we recommend that you always use Yambo to generate the input files, rather than making them yourself.

===Extra options===
Extra options modify some of the code's default settings. They can be used when launching the code but also when generating input files.

Let's have a look again to the possible options (we report here only the part we are focusing in):
$ yambo -h
This is : yambo
Version : 5.0.1 Revision 19547 Hash e90d90f2d
Configuration: MPI+OpenMP+SLK+SLEPC+HDF5_MPI_IO

Help & version:
-help (-h) <string> :<string> can be an option (e.g. -h optics)
-version :Code version & libraries

Input file & Directories:
-Input (-F) <string> :Input file
-Verbosity (-V) <string> :Input file variables verbosity (more with -h Verbosity)
-Job (-J) <string> :Job string
-Idir (-I) <string> :Input directory
-Odir (-O) <string> :I/O directory
-Cdir (-C) <string> :Communication directory

Parallel Control:
-parenv (-E) <string> :Environment Parallel Variables file
-nompi :Switch off MPI support
-noopenmp :Switch off OPENMP support

...

Utilites:
-Quiet (-Q) :Quiet input file creation
-fatlog :Verbose (fatter) log(s)
-DBlist (-D) :Databases properties
...

Command line options are extremely important to master if you want to use yambo productively.
Often, the meaning is clear from the help menu:
$ yambo -F yambo.in_HF -hf ''Make a Hartree-Fock input file called yambo.in_HF''
$ yambo -D ''Summarize the content of the databases in the SAVE folder''
$ yambo -I ../ ''Run the code, using a SAVE folder in a directory one level up''
$ yambo -C MyTest ''Run the code, putting all report, log, plot files inside a folder MyTest''

Other options deserve a closer look.

===Verbosity===
Yambo uses ''many'' input variables, many of which can be left at their default values. To keep input files short and manageable, only a few variables appear by default in the inout file. More advanced variables can be switched on by using the <code>-V</code> verbosity option. These are grouped according to the type of variable. For instance, <code>-V RL</code> switches on variables related to G vector summations, and <code>-V io</code> switches on options related to I/O control. Try:

$ yambo -optics c -V RL ''switches on:''
FFTGvecs= 3951 RL # [FFT] Plane-waves

$ yambo -optics c -V io ''switches on:''
StdoHash= 40 # [IO] Live-timing Hashes
DBsIOoff= "none" # [IO] Space-separated list of DB with NO I/O. DB= ...
DBsFRAGpm= "none" # [IO] Space-separated list of +DB to be FRAG and ...
#WFbuffIO # [IO] Wave-functions buffered I/O

Unfortunately, -V options must be invoked and changed ''one at a time''. When you are more expert, you may go straight to <code>-V all</code>, which turns on all possible variables. However note that <code>yambo -o c -V all</code> adds an extra 30 variables to the input file, which can be confusing: use it with care.

===Job script label===
The best way to keep track of different runs using different parameters is through the <code>-J</code> flag. This inserts a label in all output and report files, and creates a new folder containing any new databases (i.e. they are not written in the core ''SAVE'' folder). Try:
$ yambo -J 1Ry -V RL -hf -F yambo_hf.in ''and modify to''
FFTGvecs = 1 Ry
EXXGvecs = 1 Ry
$ yambo -J 1Ry -F yambo_hf.in ''Run the code''
$ ls
yambo_hf.in SAVE
o-1Ry.hf r-1Ry_HF_and_locXC 1Ry 1Ry/ndb.HF_and_locXC
This is extremely useful when running convergence tests, trying out different parameters, etc.

''Exercise'': use <code>yambo</code> to report the properties of all database files (including ''ndb.HF_and_locXC'')

First steps: walk through from DFT(standalone)

2021-04-06T08:20:47Z

Maurizia: /* Download the Files */

In this tutorial you will learn how to calculate optical spectra using Yambo, starting from a DFT calculation and ending with a look at local field effects in the optical response.

== System characteristics ==
We will use a 3D system (bulk hBN) and a 2D system (hBN sheet).

[[File:HBN-bulk-3x3-annotated.png|x200px|Atomic structure of bulk hBN]]
[[File:HBN2.png|x200px|Atomic structure of 2D hBN]]

'''Hexagonal boron nitride - hBN''':
* HCP lattice, ABAB stacking
* Four atoms per cell, B and N (16 electrons)
* Lattice constants: ''a'' = 4.716 [a.u.], ''c/a'' = 2.582
* Plane wave cutoff 40 Ry (~1500 RL vectors in wavefunctions)
* SCF run: shifted ''6x6x2'' grid (12 k-points) with 8 bands
* Non-SCF run: gamma-centred ''6x6x2'' (14 k-points) grid with 100 bands

=== Prerequisites ===
'''You will need''':
* PWSCF input files and pseudopotentials for hBN bulk
* <code>pw.x</code> executable, version 5.0 or later
* <code>p2y</code> and <code>yambo</code> executables
* <code>gnuplot</code> for plotting spectra

==Download the Files==

Download and unpack the followint files:
[http://www.yambo-code.org/educational/tutorials/files/hBN.tar.gz hBN.tar.gz] [15 MB],
[http://www.yambo-code.org/educational/tutorials/files/hBN-2D.tar.gz hBN-2D.tar.gz] [8,6 MB]

In the next days you could also use this file which you may like to download now
[http://www.yambo-code.org/educational/tutorials/files/hBN-convergence-kpoints.tar.gz hBN-convergence-kpoints.tar.gz] [254 MB]

After downloading the tar.gz files just unpack them in the '''YAMBO_TUTORIALS''' folder. For example
$ mkdir YAMBO_TUTORIALS
$ mv hBN.tar.gz YAMBO_TUTORIALS
$ cd YAMBO_TUTORIALS
$ tar -xvfz hBN.tar.gz
$ ls YAMBO_TUTORIALS
hBN
$ cd hBN
$ ls
$ PWSCF YAMBO

(Advanced users can download and install all tutorial files using git. See the main [[Tutorials#Files|Tutorial Files]] page.)

Now you can go directly in '''YAMBO''' folder where you can find the '''SAVE''' folder which is needed to start the yambo tutorials (for hBN bulk in this case) and go directly to the [Initialization of Yambo databases] which is always the first step you have to perform for any simulation using the Yambo code.

Or if you wish you can learn (see below) how to start from the DFT simulations doing a scf and nscf calculation, entering in '''PWSCF''' folder. In this way you will see how you can create the '''SAVE''' folder starting from *.save directory produced by pw.x.

==DFT calculation of bulk hBN and conversion to Yambo==

In this module you will learn how to generate the Yambo ''SAVE'' folder for bulk hBN starting from a PWscf calculation.

=== DFT calculations ===
$ cd YAMBO_TUTORIALS/hBN/PWSCF
$ ls
Inputs Pseudos PostProcessing References
hBN_scf.in hBN_nscf.in hBN_scf_plot_bands.in hBN_nscf_plot_bands.in

First run the SCF calculation to generate the ground-state charge density, occupations, Fermi level, and so on:
$ pw.x < hBN_scf.in > hBN_scf.out
Inspection of the output shows that the valence band maximum lies at 5.06eV.

Next run a non-SCF calculation to generate a set of Kohn-Sham eigenvalues and eigenvectors for both occupied and unoccupied states (100 bands):
$ pw.x < hBN_nscf.in > hBN_nscf.out ''(serial run, ~1 min) OR''
$ mpirun -np 2 pw.x < hBN_nscf.in > hBN_nscf.out ''(parallel run, 40s)''
Here we use a ''6x6x2'' grid giving 14 k-points, but denser grids should be used for checking convergence of Yambo runs.

Note the presence of the following flags in the input file:
wf_collect=.true.
force_symmorphic=.true.
diago_thr_init=5.0e-6,
diago_full_acc=.true.
which are needed for generating the Yambo databases accurately. Full explanations of these variables are given on the [http://www.quantum-espresso.org/wp-content/uploads/Doc/INPUT_PW.html quantum-ESPRESSO input variables page].

After these two runs, you should have a ''hBN.save'' directory:
$ ls hBN.save
data-file.xml charge-density.dat gvectors.dat B.pz-vbc.UPF N.pz-vbc.UPF
K00001 K00002 .... K00035 K00036
-->

=== Conversion to Yambo format ===
Once you have performed a nscf simulation with pw.x the PWscf ''bBN.save'' should not be empty and you can then convert it to the Yambo format using the <code>p2y</code> executable (pwscf to yambo), found in the yambo ''bin'' directory.
Enter ''hBN.save'' and launch <code>p2y</code>:

$ cd hBN.save
$ p2y
...
<---> DBs path set to .
<---> Index file set to data-file.xml
<---> Header/K-points/Energies... done
...
<---> == DB1 (Gvecs and more) ...
<---> ... Database done
<---> == DB2 (wavefunctions) ... done ==
<---> == DB3 (PseudoPotential) ... done ==
<---> == P2Y completed ==

This output repeats some information about the system and generates a ''SAVE'' directory:
$ ls SAVE
ns.db1 ns.wf ns.kb_pp_pwscf
ns.wf_fragments_1_1 ...
ns.kb_pp_pwscf_fragment_1 ...
These files, with an ''n'' prefix, indicate that they are in netCDF format, and thus not human readable. However, they are perfectly transferable across different architectures. You can check that the databases contain the information you expect by launching Yambo using the <code>-D</code> option:

$ yambo -D
[RD./SAVE//ns.db1]------------------------------------------
Bands : 100
K-points : 14
G-vectors [RL space]: 8029
Components [wavefunctions]: 1016
...
[RD./SAVE//ns.wf]-------------------------------------------
Fragmentation :yes
...
[RD./SAVE//ns.kb_pp_pwscf]----------------------------------
Fragmentation :yes
- S/N 006626 -------------------------- v.04.01.02 r.00000 -

In practice we suggest to move the ''SAVE'' folder into a new clean folder.

In this tutorial however, we ask instead that you continue using a ''SAVE'' folder that we prepared previously:
$ cd ../../YAMBO
$ ls
SAVE

==Initialization of Yambo databases==
Use the ''SAVE'' folders that are already provided, rather than any ones you may have generated previously.

Every Yambo run '''must''' start with this step. Go to the folder ''containing'' the hBN-bulk <code>SAVE</code> directory:
$ cd YAMBO_TUTORIALS/hBN/YAMBO
$ ls
SAVE

'''TIP''': do not run yambo from ''inside'' the <code>SAVE</code> folder!
'''This is the wrong way .. '''
$ cd SAVE
$ yambo
yambo: cannot access CORE database (SAVE/*db1 and/or SAVE/*wf)
In fact, if you ever see such message:
it usually means you are trying to launch Yambo '''from the wrong place'''.
$ cd ..

Now you are in the proper place and
$ ls
SAVE
you can simply launch the code
$ yambo
This will run the initialization (setup) ''runlevel''.

===Run-time output===
This is typically written to standard output (on screen) and tracks the progress of the run in real time:
<---> [01] MPI/OPENMP structure, Files & I/O Directories
<---> [02] CORE Variables Setup
<---> [02.01] Unit cells
<---> [02.02] Symmetries
<---> [02.03] Reciprocal space
<---> Shells finder |########################################| [100%] --(E) --(X)
<---> [02.04] K-grid lattice
<---> Grid dimensions : 6 6 2
<---> [02.05] Energies & Occupations
<---> [03] Transferred momenta grid and indexing
<---> BZ -> IBZ reduction |########################################| [100%] --(E) --(X)
<---> [03.01] X indexes
<---> X [eval] |########################################| [100%] --(E) --(X)
<---> X[REDUX] |########################################| [100%] --(E) --(X)
<---> [03.01.01] Sigma indexes
<---> Sigma [eval] |########################################| [100%] --(E) --(X)
<---> Sigma[REDUX] |########################################| [100%] --(E) --(X)
<---> [04] Timing Overview
<---> [05] Memory Overview
<---> [06] Game Over & Game summary
Specific runlevels are indicated with numeric labels like [02.02]. 
The hashes (#) indicate progress of the run in Wall Clock time, indicating the elapsed (E) and expected (X) time to complete a runlevel, and the percentage of the task complete.

===New core databases===
New databases appear in the ''SAVE'' folder:
$ ls SAVE
ns.db1 ns.wf ns.kb_pp_pwscf '''ndb.gops ndb.kindx'''
ns.wf_fragments_1_1 ...
ns.kb_pp_pwscf_fragment_1 ...
These contain information about the ''G''-vector shells and ''k/q''-point meshes as defined by the DFT calculation.

In general: a database called ''n'''s'''.xxx'' is a ''static'' database, generated once by <code>p2y</code>, while databases called ''n'''db'''.xxx'' are ''dynamically'' generated while you use <code>yambo</code>.

'''TIP''': if you launch <code>yambo</code>, but it does not seem to do anything, check that these files are present.

===Report file===
A report file ''r_setup'' is generated in the run directory.
This mostly reports information about the ground state system as defined by the DFT run, but also adds information about the band gaps, occupations, shells of G-vectors, IBZ/BZ grids, the CPU structure (for parallel runs), and so on. Some points of note:

Up to Yambo version 4.5
[02.03] RL shells
=================
Shells, format: [S#] G_RL(mHa)
[S453]:8029(0.7982E+5) [S452]:8005(0.7982E+5) [S451]:7981(0.7982E+5) [S450]:7957(0.7942E+5)
...
[S4]:11( 1183.) [S3]:5( 532.5123) [S2]:3( 133.1281) [S1]:1( 0.000000)

From Yambo version 5.0
[02.03] Reciprocal space
========================

nG shells : 217
nG charge : 3187
nG WFs : 1477
nC WFs : 1016
G-vecs. in first 21 shells: [ Number ]
1 3 5 11 13 25 37 39 51
63 65 71 83 95 107 113 125 127
139 151 163
...
Shell energy in first 21 shells: [ mHa ]
0.00000 133.128 532.512 1183.37 1198.15 1316.50 1715.88 2130.05 2381.52
3313.42 3328.20 3550.11 3683.24 4082.62 4511.57 4733.48 4748.27 4792.61
4866.61 5266.00 5680.16
...

This reports the set of closed reciprocal lattice (RL) shells defined internally that contain G-vectors with the same modulus.
The highest number of RL vectors we can use is 8029. Yambo will always redefine any input variable in RL units to the nearest closed shell.

Up to Yambo version 4.5
[02.05] Energies [ev] & Occupations
===================================
Fermi Level [ev]: 5.112805
VBM / CBm [ev]: 0.000000 3.876293
Electronic Temp. [ev K]: 0.00 0.00
Bosonic Temp. [ev K]: 0.00 0.00
El. density [cm-3]: 0.460E+24
States summary : Full Metallic Empty
0001-0008 0009-0100
Indirect Gaps [ev]: 3.876293 7.278081
Direct Gaps [ev]: 4.28829 11.35409
X BZ K-points : 72

From Yambo version 5.0
[02.05] Energies & Occupations
==============================

[X] === General ===
[X] Electronic Temperature : 0.000000 0.000000 [eV K]
[X] Bosonic Temperature : 0.000000 0.000000 [eV K]
[X] Finite Temperature mode : no
[X] El. density : 0.46037E+24 [cm-3]
[X] Fermi Level : 5.110835 [eV]

[X] === Gaps and Widths ===
[X] Conduction Band Min : 3.877976 [eV]
[X] Valence Band Max : 0.000000 [eV]
[X] Filled Bands : 8
[X] Empty Bands : 9 100
[X] Direct Gap : 4.289853 [eV]
[X] Direct Gap localized at k-point : 7
[X] Indirect Gap : 3.877976 [eV]
[X] Indirect Gap between k-points : 14 7
[X] Last valence band width : 3.401086 [eV]
[X] 1st conduction band width : 4.266292 [eV]

Yambo recalculates again the Fermi level (close to the value of 5.06 noted in the PWscf SCF calculation). From here on, however, the Fermi level is set to zero, and other eigenvalues are shifted accordingly. The system is insulating (8 filled, 92 empty) with an indirect band gap of 3.87 eV. The minimum and maximum direct and indirect gaps are indicated. There are 72 k-points in the full BZ, generated using symmetry from the 14 k-points in our user-defined grid.

'''TIP''': You should inspect the report file after ''every'' run for errors and warnings.

===Different ways of running yambo===
We just run Yambo interactively.

Let's try to re-run the setup with the command
$ nohup yambo &
$ ls
l_setup nohup.out r_setup r_setup_01 SAVE

If Yambo is launched using a script, or as a background process, or in parallel, this output will appear in a log file prefixed by the letter ''l'', in this case as ''l_setup''.
If this log file already exists from a previous run, it will not be overwritten. Instead, a new file will be created with an incrementing numerical label, e.g. ''l_setup_01, l_setup_02'', etc. '''This applies to all files created by Yambo'''. Here we see that l_setup was created for the first time, but r_setup already existed from the previous run, so now we have r_setup_01
If you check the differences between the two you will notice that in the second run yambo is reading the previously created ndb.kindx in place of re-computing the indexes.
Indeed the output inside l_setup does not show the timing for X and Sigma

As a last step we run the setup in parallel, but first we delete the ndb.kindx file
$ rm SAVE/ndb.kindx
$ mpirun -np 4 yambo
$ ls
LOG l_setup nohup.out r_setup r_setup_01 r_setup_02 SAVE
There is now r_setup_02
In the case of parallel runs, CPU-dependent log files will appear inside a ''LOG'' folder, e.g.
$ ls LOG
l_setup_CPU_1 l_setup_CPU_2 l_setup_CPU_3 l_setup_CPU_4
This behaviour can be controlled at runtime - see the Parallel tutorial for details.

===2D hBN===
Simply repeat the steps above. Go to the folder ''containing'' the hBN-sheet ''SAVE'' directory and launch <code>yambo</code>:
$ cd TUTORIALS/hBN-2D/YAMBO
$ ls
SAVE
$ yambo
Again, inspect the ''r_setup'' file, output logs, and verify that ''ndb.gops'' and ''ndb.kpts'' have been created inside the SAVE folder.

You are now ready to use Yambo!

==Yambo's command line interface==
Yambo uses a command line interface to select tasks, generate input files, and control the runtime behaviour.

In this module you will learn how to select tasks, generate and modify input files, and control the runtime behaviour by using Yambo's command line interface.


=== Input file generator ===
First, move to the appropriate folder and initialize the Yambo databases if you haven't already done so.
$ cd YAMBO_TUTORIALS/hBN/YAMBO
$ yambo ''(initialize)''

Yambo generates its own input files: you just tell the code what you want to calculate by launching Yambo along with one or more options.
To see the list of possible options, run <code>yambo -h</code> (we report here only the part we are focusing in)
$ yambo -h
'A shiny pot of fun and happiness [C.D.Hogan]'

This is : yambo
Version : 5.0.1 Revision 19547 Hash e90d90f2d
Configuration: MPI+OpenMP+SLK+SLEPC+HDF5_MPI_IO

...

Initializations:
-setup (-i) :Initialization
-coulomb (-r) :Coulomb potential

Response Functions:
-optics (-o) <string> :Linear Response optical properties (more with -h optics)
-X (-d) <string> :Inverse Dielectric Matrix (more with -h X)
-dipoles (-q) :Oscillator strenghts (or dipoles)
-kernel (-k) <string> :Kernel (more with -h kernel)

Self-Energy:
-hf (-x) :Hartree-Fock
-gw0 (-p) <string> :GW approximation (more with -h gw0)
-dyson (-g) <string> :Dyson Equation solver (more with -h dyson)
-lifetimes (-l) :GoWo Quasiparticle lifetimes

Bethe-Salpeter Equation:
-Ksolver (-y) <string> :BSE solver (more with -h Ksolver)

Total Energy:
-acfdt :ACFDT Total Energy

Utilites:
...
-slktest :ScaLapacK test

The options can be split into two sets: 
* A set of options which is needed to generate the appropriate input file (default name: ''yambo.in'') selecting the kind of simulation you would like to perform 
* A set of options which can be used to manage auxiliary functions (like redirect the I/O, choose a specific name for the input file, etc ..).

===Runlevel selection===
First of all, you would like to specify which kind of simulation you are going to perform and generate an input file with the first set of options.
By default, when generating the input file, Yambo will launch the <code>vi</code> editor.
Editor choice can be changed when launching the configure before compilation; alternatively you can use the <code>-Q</code> run time option to skip the automatic editing (do this if you are not familiar with <code>vi</code>!):
$ yambo -hf -Q
yambo: input file yambo.in created
$ emacs yambo.in ''or your favourite editing tool''

Multiple options can be used together to activate various tasks or runlevels (in some cases this is actually a necessity).
For instance, to generate an input file for optical spectra including local field effects (Hartree approximation), do (and then exit)
$ yambo -optics c -kernel hartree ''which switches on:''
optics # [R OPT] Optics
chi # [R CHI] Dyson equation for Chi.
Chimod= "Hartree" # [X] IP/Hartree/ALDA/LRC/BSfxc
To perform a Hartree-Fock and GW calculation using a plasmon-pole approximation, do (and then exit):
$ yambo -hf -gw0 p -dyson n ''which switches on:''
HF_and_locXC # [R XX] Hartree-Fock Self-energy and Vxc
gw0 # [R GW] GoWo Quasiparticle energy levels
ppa # [R Xp] Plasmon Pole Approximation
em1d # [R Xd] Dynamical Inverse Dielectric Matrix
Each runlevel activates its own list of variables and flags.

The previous command is also equivalent to
$ yambo -hf -gw0 r -dyson n -X p

===Changing input parameters ===
Yambo reads various parameters from existing database files and/or input files and uses them to suggest values or ranges.
Let's illustrate this by generating the input file for a Hartree-Fock calculation.

$ yambo -hf
Inside the generated input file you should find:
[[Variables#EXXRLvcs|EXXRLvcs]] = 3187 RL # [XX] Exchange RL components
%[[Variables#QPkrange|QPkrange]] # [GW] QP generalized Kpoint/Band indices
1| 14| 1|100|
%
The <code>[[Variables#QPkrange|QPkrange]]</code> variable (follow the link for a "detailed" explanation for any variable) suggests a range of k-points (1 to 14) and bands (1 to 100) based on what it finds in the core database ''SAVE/ns.db1'', i.e. as defined by the DFT code. 
Leave that variable alone, and instead modify the previous variable to <code>EXXRLvcs= 1000 RL</code>

Save the file, and now generate the input a second time with <code>yambo -x</code>. You will see:
[[Variables#EXXRLvcs|EXXRLvcs]]= 1009 RL
This indicates that Yambo has read the new input value (1000 G-vectors), checked the database of G-vector shells ''(SAVE/ndb.gops)'',
and changed the input value to one that fits a completely closed shell.

Last, note that Yambo variables can be expressed in different '''units'''. In this case, <code>RL</code> can be replaced by an energy unit like Ry, eV, Ha, etc. Energy units are generally better as they are independent of the cell size. Technical information is available on the [[Variables]] page.

The input file generator of Yambo is thus an ''intelligent'' parser, which interacts with the user and the existing databases. For this reason we recommend that you always use Yambo to generate the input files, rather than making them yourself.

===Extra options===
Extra options modify some of the code's default settings. They can be used when launching the code but also when generating input files.

Let's have a look again to the possible options (we report here only the part we are focusing in):
$ yambo -h
This is : yambo
Version : 5.0.1 Revision 19547 Hash e90d90f2d
Configuration: MPI+OpenMP+SLK+SLEPC+HDF5_MPI_IO

Help & version:
-help (-h) <string> :<string> can be an option (e.g. -h optics)
-version :Code version & libraries

Input file & Directories:
-Input (-F) <string> :Input file
-Verbosity (-V) <string> :Input file variables verbosity (more with -h Verbosity)
-Job (-J) <string> :Job string
-Idir (-I) <string> :Input directory
-Odir (-O) <string> :I/O directory
-Cdir (-C) <string> :Communication directory

Parallel Control:
-parenv (-E) <string> :Environment Parallel Variables file
-nompi :Switch off MPI support
-noopenmp :Switch off OPENMP support

...

Utilites:
-Quiet (-Q) :Quiet input file creation
-fatlog :Verbose (fatter) log(s)
-DBlist (-D) :Databases properties
...

Command line options are extremely important to master if you want to use yambo productively.
Often, the meaning is clear from the help menu:
$ yambo -F yambo.in_HF -hf ''Make a Hartree-Fock input file called yambo.in_HF''
$ yambo -D ''Summarize the content of the databases in the SAVE folder''
$ yambo -I ../ ''Run the code, using a SAVE folder in a directory one level up''
$ yambo -C MyTest ''Run the code, putting all report, log, plot files inside a folder MyTest''

Other options deserve a closer look.

===Verbosity===
Yambo uses ''many'' input variables, many of which can be left at their default values. To keep input files short and manageable, only a few variables appear by default in the inout file. More advanced variables can be switched on by using the <code>-V</code> verbosity option. These are grouped according to the type of variable. For instance, <code>-V RL</code> switches on variables related to G vector summations, and <code>-V io</code> switches on options related to I/O control. Try:

$ yambo -optics c -V RL ''switches on:''
FFTGvecs= 3951 RL # [FFT] Plane-waves

$ yambo -optics c -V io ''switches on:''
StdoHash= 40 # [IO] Live-timing Hashes
DBsIOoff= "none" # [IO] Space-separated list of DB with NO I/O. DB= ...
DBsFRAGpm= "none" # [IO] Space-separated list of +DB to be FRAG and ...
#WFbuffIO # [IO] Wave-functions buffered I/O

Unfortunately, -V options must be invoked and changed ''one at a time''. When you are more expert, you may go straight to <code>-V all</code>, which turns on all possible variables. However note that <code>yambo -o c -V all</code> adds an extra 30 variables to the input file, which can be confusing: use it with care.

===Job script label===
The best way to keep track of different runs using different parameters is through the <code>-J</code> flag. This inserts a label in all output and report files, and creates a new folder containing any new databases (i.e. they are not written in the core ''SAVE'' folder). Try:
$ yambo -J 1Ry -V RL -hf -F yambo_hf.in ''and modify to''
FFTGvecs = 1 Ry
EXXGvecs = 1 Ry
$ yambo -J 1Ry -F yambo_hf.in ''Run the code''
$ ls
yambo_hf.in SAVE
o-1Ry.hf r-1Ry_HF_and_locXC 1Ry 1Ry/ndb.HF_and_locXC
This is extremely useful when running convergence tests, trying out different parameters, etc.

''Exercise'': use <code>yambo</code> to report the properties of all database files (including ''ndb.HF_and_locXC'')

First steps: walk through from DFT(standalone)

2021-04-06T08:19:16Z

Maurizia: /* Download the Files */

In this tutorial you will learn how to calculate optical spectra using Yambo, starting from a DFT calculation and ending with a look at local field effects in the optical response.

== System characteristics ==
We will use a 3D system (bulk hBN) and a 2D system (hBN sheet).

[[File:HBN-bulk-3x3-annotated.png|x200px|Atomic structure of bulk hBN]]
[[File:HBN2.png|x200px|Atomic structure of 2D hBN]]

'''Hexagonal boron nitride - hBN''':
* HCP lattice, ABAB stacking
* Four atoms per cell, B and N (16 electrons)
* Lattice constants: ''a'' = 4.716 [a.u.], ''c/a'' = 2.582
* Plane wave cutoff 40 Ry (~1500 RL vectors in wavefunctions)
* SCF run: shifted ''6x6x2'' grid (12 k-points) with 8 bands
* Non-SCF run: gamma-centred ''6x6x2'' (14 k-points) grid with 100 bands

=== Prerequisites ===
'''You will need''':
* PWSCF input files and pseudopotentials for hBN bulk
* <code>pw.x</code> executable, version 5.0 or later
* <code>p2y</code> and <code>yambo</code> executables
* <code>gnuplot</code> for plotting spectra

==Download the Files==

Download and unpack the followint files:
[http://www.yambo-code.org/educational/tutorials/files/hBN.tar.gz hBN.tar.gz] [15 MB],
[http://www.yambo-code.org/educational/tutorials/files/hBN-2D.tar.gz hBN-2D.tar.gz] [8,6 MB]

In the next days you could also use this file which you may like to download now
[http://www.yambo-code.org/educational/tutorials/files/hBN-convergence-kpoints.tar.gz hBN-convergence-kpoints.tar.gz] [254 MB]

After downloading the tar.gz files just unpack them in the '''YAMBO_TUTORIALS''' folder. For example
$ mkdir YAMBO_TUTORIALS
$ mv hBN.tar.gz YAMBO_TUTORIALS
$ cd YAMBO_TUTORIALS
$ tar -xvfz hBN.tar.gz
$ ls YAMBO_TUTORIALS
hBN
$ cd hBN
$ ls
$ PWSCF YAMBO

(Advanced users can download and install all tutorial files using git. See the main [[Tutorials#Files|Tutorial Files]] page.)

Now you can go directly in '''YAMBO''' folder where you can find the '''SAVE''' folder which is needed to start the yambo tutorials (for hBN bulk in this case) and go directly to the initialiation step [[Initialization step]]

Or if you wish you can learn (see below) how to start from the DFT simulations doing a scf and nscf calculation, entering in '''PWSCF''' folder. In this way you will see how you can create the '''SAVE''' folder starting from *.save directory produced by pw.x.

==DFT calculation of bulk hBN and conversion to Yambo==

In this module you will learn how to generate the Yambo ''SAVE'' folder for bulk hBN starting from a PWscf calculation.

=== DFT calculations ===
$ cd YAMBO_TUTORIALS/hBN/PWSCF
$ ls
Inputs Pseudos PostProcessing References
hBN_scf.in hBN_nscf.in hBN_scf_plot_bands.in hBN_nscf_plot_bands.in

First run the SCF calculation to generate the ground-state charge density, occupations, Fermi level, and so on:
$ pw.x < hBN_scf.in > hBN_scf.out
Inspection of the output shows that the valence band maximum lies at 5.06eV.

Next run a non-SCF calculation to generate a set of Kohn-Sham eigenvalues and eigenvectors for both occupied and unoccupied states (100 bands):
$ pw.x < hBN_nscf.in > hBN_nscf.out ''(serial run, ~1 min) OR''
$ mpirun -np 2 pw.x < hBN_nscf.in > hBN_nscf.out ''(parallel run, 40s)''
Here we use a ''6x6x2'' grid giving 14 k-points, but denser grids should be used for checking convergence of Yambo runs.

Note the presence of the following flags in the input file:
wf_collect=.true.
force_symmorphic=.true.
diago_thr_init=5.0e-6,
diago_full_acc=.true.
which are needed for generating the Yambo databases accurately. Full explanations of these variables are given on the [http://www.quantum-espresso.org/wp-content/uploads/Doc/INPUT_PW.html quantum-ESPRESSO input variables page].

After these two runs, you should have a ''hBN.save'' directory:
$ ls hBN.save
data-file.xml charge-density.dat gvectors.dat B.pz-vbc.UPF N.pz-vbc.UPF
K00001 K00002 .... K00035 K00036
-->

=== Conversion to Yambo format ===
Once you have performed a nscf simulation with pw.x the PWscf ''bBN.save'' should not be empty and you can then convert it to the Yambo format using the <code>p2y</code> executable (pwscf to yambo), found in the yambo ''bin'' directory.
Enter ''hBN.save'' and launch <code>p2y</code>:

$ cd hBN.save
$ p2y
...
<---> DBs path set to .
<---> Index file set to data-file.xml
<---> Header/K-points/Energies... done
...
<---> == DB1 (Gvecs and more) ...
<---> ... Database done
<---> == DB2 (wavefunctions) ... done ==
<---> == DB3 (PseudoPotential) ... done ==
<---> == P2Y completed ==

This output repeats some information about the system and generates a ''SAVE'' directory:
$ ls SAVE
ns.db1 ns.wf ns.kb_pp_pwscf
ns.wf_fragments_1_1 ...
ns.kb_pp_pwscf_fragment_1 ...
These files, with an ''n'' prefix, indicate that they are in netCDF format, and thus not human readable. However, they are perfectly transferable across different architectures. You can check that the databases contain the information you expect by launching Yambo using the <code>-D</code> option:

$ yambo -D
[RD./SAVE//ns.db1]------------------------------------------
Bands : 100
K-points : 14
G-vectors [RL space]: 8029
Components [wavefunctions]: 1016
...
[RD./SAVE//ns.wf]-------------------------------------------
Fragmentation :yes
...
[RD./SAVE//ns.kb_pp_pwscf]----------------------------------
Fragmentation :yes
- S/N 006626 -------------------------- v.04.01.02 r.00000 -

In practice we suggest to move the ''SAVE'' folder into a new clean folder.

In this tutorial however, we ask instead that you continue using a ''SAVE'' folder that we prepared previously:
$ cd ../../YAMBO
$ ls
SAVE

==Initialization of Yambo databases==
Use the ''SAVE'' folders that are already provided, rather than any ones you may have generated previously.

Every Yambo run '''must''' start with this step. Go to the folder ''containing'' the hBN-bulk <code>SAVE</code> directory:
$ cd YAMBO_TUTORIALS/hBN/YAMBO
$ ls
SAVE

'''TIP''': do not run yambo from ''inside'' the <code>SAVE</code> folder!
'''This is the wrong way .. '''
$ cd SAVE
$ yambo
yambo: cannot access CORE database (SAVE/*db1 and/or SAVE/*wf)
In fact, if you ever see such message:
it usually means you are trying to launch Yambo '''from the wrong place'''.
$ cd ..

Now you are in the proper place and
$ ls
SAVE
you can simply launch the code
$ yambo
This will run the initialization (setup) ''runlevel''.

===Run-time output===
This is typically written to standard output (on screen) and tracks the progress of the run in real time:
<---> [01] MPI/OPENMP structure, Files & I/O Directories
<---> [02] CORE Variables Setup
<---> [02.01] Unit cells
<---> [02.02] Symmetries
<---> [02.03] Reciprocal space
<---> Shells finder |########################################| [100%] --(E) --(X)
<---> [02.04] K-grid lattice
<---> Grid dimensions : 6 6 2
<---> [02.05] Energies & Occupations
<---> [03] Transferred momenta grid and indexing
<---> BZ -> IBZ reduction |########################################| [100%] --(E) --(X)
<---> [03.01] X indexes
<---> X [eval] |########################################| [100%] --(E) --(X)
<---> X[REDUX] |########################################| [100%] --(E) --(X)
<---> [03.01.01] Sigma indexes
<---> Sigma [eval] |########################################| [100%] --(E) --(X)
<---> Sigma[REDUX] |########################################| [100%] --(E) --(X)
<---> [04] Timing Overview
<---> [05] Memory Overview
<---> [06] Game Over & Game summary
Specific runlevels are indicated with numeric labels like [02.02]. 
The hashes (#) indicate progress of the run in Wall Clock time, indicating the elapsed (E) and expected (X) time to complete a runlevel, and the percentage of the task complete.

===New core databases===
New databases appear in the ''SAVE'' folder:
$ ls SAVE
ns.db1 ns.wf ns.kb_pp_pwscf '''ndb.gops ndb.kindx'''
ns.wf_fragments_1_1 ...
ns.kb_pp_pwscf_fragment_1 ...
These contain information about the ''G''-vector shells and ''k/q''-point meshes as defined by the DFT calculation.

In general: a database called ''n'''s'''.xxx'' is a ''static'' database, generated once by <code>p2y</code>, while databases called ''n'''db'''.xxx'' are ''dynamically'' generated while you use <code>yambo</code>.

'''TIP''': if you launch <code>yambo</code>, but it does not seem to do anything, check that these files are present.

===Report file===
A report file ''r_setup'' is generated in the run directory.
This mostly reports information about the ground state system as defined by the DFT run, but also adds information about the band gaps, occupations, shells of G-vectors, IBZ/BZ grids, the CPU structure (for parallel runs), and so on. Some points of note:

Up to Yambo version 4.5
[02.03] RL shells
=================
Shells, format: [S#] G_RL(mHa)
[S453]:8029(0.7982E+5) [S452]:8005(0.7982E+5) [S451]:7981(0.7982E+5) [S450]:7957(0.7942E+5)
...
[S4]:11( 1183.) [S3]:5( 532.5123) [S2]:3( 133.1281) [S1]:1( 0.000000)

From Yambo version 5.0
[02.03] Reciprocal space
========================

nG shells : 217
nG charge : 3187
nG WFs : 1477
nC WFs : 1016
G-vecs. in first 21 shells: [ Number ]
1 3 5 11 13 25 37 39 51
63 65 71 83 95 107 113 125 127
139 151 163
...
Shell energy in first 21 shells: [ mHa ]
0.00000 133.128 532.512 1183.37 1198.15 1316.50 1715.88 2130.05 2381.52
3313.42 3328.20 3550.11 3683.24 4082.62 4511.57 4733.48 4748.27 4792.61
4866.61 5266.00 5680.16
...

This reports the set of closed reciprocal lattice (RL) shells defined internally that contain G-vectors with the same modulus.
The highest number of RL vectors we can use is 8029. Yambo will always redefine any input variable in RL units to the nearest closed shell.

Up to Yambo version 4.5
[02.05] Energies [ev] & Occupations
===================================
Fermi Level [ev]: 5.112805
VBM / CBm [ev]: 0.000000 3.876293
Electronic Temp. [ev K]: 0.00 0.00
Bosonic Temp. [ev K]: 0.00 0.00
El. density [cm-3]: 0.460E+24
States summary : Full Metallic Empty
0001-0008 0009-0100
Indirect Gaps [ev]: 3.876293 7.278081
Direct Gaps [ev]: 4.28829 11.35409
X BZ K-points : 72

From Yambo version 5.0
[02.05] Energies & Occupations
==============================

[X] === General ===
[X] Electronic Temperature : 0.000000 0.000000 [eV K]
[X] Bosonic Temperature : 0.000000 0.000000 [eV K]
[X] Finite Temperature mode : no
[X] El. density : 0.46037E+24 [cm-3]
[X] Fermi Level : 5.110835 [eV]

[X] === Gaps and Widths ===
[X] Conduction Band Min : 3.877976 [eV]
[X] Valence Band Max : 0.000000 [eV]
[X] Filled Bands : 8
[X] Empty Bands : 9 100
[X] Direct Gap : 4.289853 [eV]
[X] Direct Gap localized at k-point : 7
[X] Indirect Gap : 3.877976 [eV]
[X] Indirect Gap between k-points : 14 7
[X] Last valence band width : 3.401086 [eV]
[X] 1st conduction band width : 4.266292 [eV]

Yambo recalculates again the Fermi level (close to the value of 5.06 noted in the PWscf SCF calculation). From here on, however, the Fermi level is set to zero, and other eigenvalues are shifted accordingly. The system is insulating (8 filled, 92 empty) with an indirect band gap of 3.87 eV. The minimum and maximum direct and indirect gaps are indicated. There are 72 k-points in the full BZ, generated using symmetry from the 14 k-points in our user-defined grid.

'''TIP''': You should inspect the report file after ''every'' run for errors and warnings.

===Different ways of running yambo===
We just run Yambo interactively.

Let's try to re-run the setup with the command
$ nohup yambo &
$ ls
l_setup nohup.out r_setup r_setup_01 SAVE

If Yambo is launched using a script, or as a background process, or in parallel, this output will appear in a log file prefixed by the letter ''l'', in this case as ''l_setup''.
If this log file already exists from a previous run, it will not be overwritten. Instead, a new file will be created with an incrementing numerical label, e.g. ''l_setup_01, l_setup_02'', etc. '''This applies to all files created by Yambo'''. Here we see that l_setup was created for the first time, but r_setup already existed from the previous run, so now we have r_setup_01
If you check the differences between the two you will notice that in the second run yambo is reading the previously created ndb.kindx in place of re-computing the indexes.
Indeed the output inside l_setup does not show the timing for X and Sigma

As a last step we run the setup in parallel, but first we delete the ndb.kindx file
$ rm SAVE/ndb.kindx
$ mpirun -np 4 yambo
$ ls
LOG l_setup nohup.out r_setup r_setup_01 r_setup_02 SAVE
There is now r_setup_02
In the case of parallel runs, CPU-dependent log files will appear inside a ''LOG'' folder, e.g.
$ ls LOG
l_setup_CPU_1 l_setup_CPU_2 l_setup_CPU_3 l_setup_CPU_4
This behaviour can be controlled at runtime - see the Parallel tutorial for details.

===2D hBN===
Simply repeat the steps above. Go to the folder ''containing'' the hBN-sheet ''SAVE'' directory and launch <code>yambo</code>:
$ cd TUTORIALS/hBN-2D/YAMBO
$ ls
SAVE
$ yambo
Again, inspect the ''r_setup'' file, output logs, and verify that ''ndb.gops'' and ''ndb.kpts'' have been created inside the SAVE folder.

You are now ready to use Yambo!

==Yambo's command line interface==
Yambo uses a command line interface to select tasks, generate input files, and control the runtime behaviour.

In this module you will learn how to select tasks, generate and modify input files, and control the runtime behaviour by using Yambo's command line interface.


=== Input file generator ===
First, move to the appropriate folder and initialize the Yambo databases if you haven't already done so.
$ cd YAMBO_TUTORIALS/hBN/YAMBO
$ yambo ''(initialize)''

Yambo generates its own input files: you just tell the code what you want to calculate by launching Yambo along with one or more options.
To see the list of possible options, run <code>yambo -h</code> (we report here only the part we are focusing in)
$ yambo -h
'A shiny pot of fun and happiness [C.D.Hogan]'

This is : yambo
Version : 5.0.1 Revision 19547 Hash e90d90f2d
Configuration: MPI+OpenMP+SLK+SLEPC+HDF5_MPI_IO

...

Initializations:
-setup (-i) :Initialization
-coulomb (-r) :Coulomb potential

Response Functions:
-optics (-o) <string> :Linear Response optical properties (more with -h optics)
-X (-d) <string> :Inverse Dielectric Matrix (more with -h X)
-dipoles (-q) :Oscillator strenghts (or dipoles)
-kernel (-k) <string> :Kernel (more with -h kernel)

Self-Energy:
-hf (-x) :Hartree-Fock
-gw0 (-p) <string> :GW approximation (more with -h gw0)
-dyson (-g) <string> :Dyson Equation solver (more with -h dyson)
-lifetimes (-l) :GoWo Quasiparticle lifetimes

Bethe-Salpeter Equation:
-Ksolver (-y) <string> :BSE solver (more with -h Ksolver)

Total Energy:
-acfdt :ACFDT Total Energy

Utilites:
...
-slktest :ScaLapacK test

The options can be split into two sets: 
* A set of options which is needed to generate the appropriate input file (default name: ''yambo.in'') selecting the kind of simulation you would like to perform 
* A set of options which can be used to manage auxiliary functions (like redirect the I/O, choose a specific name for the input file, etc ..).

===Runlevel selection===
First of all, you would like to specify which kind of simulation you are going to perform and generate an input file with the first set of options.
By default, when generating the input file, Yambo will launch the <code>vi</code> editor.
Editor choice can be changed when launching the configure before compilation; alternatively you can use the <code>-Q</code> run time option to skip the automatic editing (do this if you are not familiar with <code>vi</code>!):
$ yambo -hf -Q
yambo: input file yambo.in created
$ emacs yambo.in ''or your favourite editing tool''

Multiple options can be used together to activate various tasks or runlevels (in some cases this is actually a necessity).
For instance, to generate an input file for optical spectra including local field effects (Hartree approximation), do (and then exit)
$ yambo -optics c -kernel hartree ''which switches on:''
optics # [R OPT] Optics
chi # [R CHI] Dyson equation for Chi.
Chimod= "Hartree" # [X] IP/Hartree/ALDA/LRC/BSfxc
To perform a Hartree-Fock and GW calculation using a plasmon-pole approximation, do (and then exit):
$ yambo -hf -gw0 p -dyson n ''which switches on:''
HF_and_locXC # [R XX] Hartree-Fock Self-energy and Vxc
gw0 # [R GW] GoWo Quasiparticle energy levels
ppa # [R Xp] Plasmon Pole Approximation
em1d # [R Xd] Dynamical Inverse Dielectric Matrix
Each runlevel activates its own list of variables and flags.

The previous command is also equivalent to
$ yambo -hf -gw0 r -dyson n -X p

===Changing input parameters ===
Yambo reads various parameters from existing database files and/or input files and uses them to suggest values or ranges.
Let's illustrate this by generating the input file for a Hartree-Fock calculation.

$ yambo -hf
Inside the generated input file you should find:
[[Variables#EXXRLvcs|EXXRLvcs]] = 3187 RL # [XX] Exchange RL components
%[[Variables#QPkrange|QPkrange]] # [GW] QP generalized Kpoint/Band indices
1| 14| 1|100|
%
The <code>[[Variables#QPkrange|QPkrange]]</code> variable (follow the link for a "detailed" explanation for any variable) suggests a range of k-points (1 to 14) and bands (1 to 100) based on what it finds in the core database ''SAVE/ns.db1'', i.e. as defined by the DFT code. 
Leave that variable alone, and instead modify the previous variable to <code>EXXRLvcs= 1000 RL</code>

Save the file, and now generate the input a second time with <code>yambo -x</code>. You will see:
[[Variables#EXXRLvcs|EXXRLvcs]]= 1009 RL
This indicates that Yambo has read the new input value (1000 G-vectors), checked the database of G-vector shells ''(SAVE/ndb.gops)'',
and changed the input value to one that fits a completely closed shell.

Last, note that Yambo variables can be expressed in different '''units'''. In this case, <code>RL</code> can be replaced by an energy unit like Ry, eV, Ha, etc. Energy units are generally better as they are independent of the cell size. Technical information is available on the [[Variables]] page.

The input file generator of Yambo is thus an ''intelligent'' parser, which interacts with the user and the existing databases. For this reason we recommend that you always use Yambo to generate the input files, rather than making them yourself.

===Extra options===
Extra options modify some of the code's default settings. They can be used when launching the code but also when generating input files.

Let's have a look again to the possible options (we report here only the part we are focusing in):
$ yambo -h
This is : yambo
Version : 5.0.1 Revision 19547 Hash e90d90f2d
Configuration: MPI+OpenMP+SLK+SLEPC+HDF5_MPI_IO

Help & version:
-help (-h) <string> :<string> can be an option (e.g. -h optics)
-version :Code version & libraries

Input file & Directories:
-Input (-F) <string> :Input file
-Verbosity (-V) <string> :Input file variables verbosity (more with -h Verbosity)
-Job (-J) <string> :Job string
-Idir (-I) <string> :Input directory
-Odir (-O) <string> :I/O directory
-Cdir (-C) <string> :Communication directory

Parallel Control:
-parenv (-E) <string> :Environment Parallel Variables file
-nompi :Switch off MPI support
-noopenmp :Switch off OPENMP support

...

Utilites:
-Quiet (-Q) :Quiet input file creation
-fatlog :Verbose (fatter) log(s)
-DBlist (-D) :Databases properties
...

Command line options are extremely important to master if you want to use yambo productively.
Often, the meaning is clear from the help menu:
$ yambo -F yambo.in_HF -hf ''Make a Hartree-Fock input file called yambo.in_HF''
$ yambo -D ''Summarize the content of the databases in the SAVE folder''
$ yambo -I ../ ''Run the code, using a SAVE folder in a directory one level up''
$ yambo -C MyTest ''Run the code, putting all report, log, plot files inside a folder MyTest''

Other options deserve a closer look.

===Verbosity===
Yambo uses ''many'' input variables, many of which can be left at their default values. To keep input files short and manageable, only a few variables appear by default in the inout file. More advanced variables can be switched on by using the <code>-V</code> verbosity option. These are grouped according to the type of variable. For instance, <code>-V RL</code> switches on variables related to G vector summations, and <code>-V io</code> switches on options related to I/O control. Try:

$ yambo -optics c -V RL ''switches on:''
FFTGvecs= 3951 RL # [FFT] Plane-waves

$ yambo -optics c -V io ''switches on:''
StdoHash= 40 # [IO] Live-timing Hashes
DBsIOoff= "none" # [IO] Space-separated list of DB with NO I/O. DB= ...
DBsFRAGpm= "none" # [IO] Space-separated list of +DB to be FRAG and ...
#WFbuffIO # [IO] Wave-functions buffered I/O

Unfortunately, -V options must be invoked and changed ''one at a time''. When you are more expert, you may go straight to <code>-V all</code>, which turns on all possible variables. However note that <code>yambo -o c -V all</code> adds an extra 30 variables to the input file, which can be confusing: use it with care.

===Job script label===
The best way to keep track of different runs using different parameters is through the <code>-J</code> flag. This inserts a label in all output and report files, and creates a new folder containing any new databases (i.e. they are not written in the core ''SAVE'' folder). Try:
$ yambo -J 1Ry -V RL -hf -F yambo_hf.in ''and modify to''
FFTGvecs = 1 Ry
EXXGvecs = 1 Ry
$ yambo -J 1Ry -F yambo_hf.in ''Run the code''
$ ls
yambo_hf.in SAVE
o-1Ry.hf r-1Ry_HF_and_locXC 1Ry 1Ry/ndb.HF_and_locXC
This is extremely useful when running convergence tests, trying out different parameters, etc.

''Exercise'': use <code>yambo</code> to report the properties of all database files (including ''ndb.HF_and_locXC'')

First steps: walk through from DFT(standalone)

2021-04-06T08:17:45Z

Maurizia: /* Conversion to Yambo format */

In this tutorial you will learn how to calculate optical spectra using Yambo, starting from a DFT calculation and ending with a look at local field effects in the optical response.

== System characteristics ==
We will use a 3D system (bulk hBN) and a 2D system (hBN sheet).

[[File:HBN-bulk-3x3-annotated.png|x200px|Atomic structure of bulk hBN]]
[[File:HBN2.png|x200px|Atomic structure of 2D hBN]]

'''Hexagonal boron nitride - hBN''':
* HCP lattice, ABAB stacking
* Four atoms per cell, B and N (16 electrons)
* Lattice constants: ''a'' = 4.716 [a.u.], ''c/a'' = 2.582
* Plane wave cutoff 40 Ry (~1500 RL vectors in wavefunctions)
* SCF run: shifted ''6x6x2'' grid (12 k-points) with 8 bands
* Non-SCF run: gamma-centred ''6x6x2'' (14 k-points) grid with 100 bands

=== Prerequisites ===
'''You will need''':
* PWSCF input files and pseudopotentials for hBN bulk
* <code>pw.x</code> executable, version 5.0 or later
* <code>p2y</code> and <code>yambo</code> executables
* <code>gnuplot</code> for plotting spectra

==Download the Files==

Download and unpack the followint files:
[http://www.yambo-code.org/educational/tutorials/files/hBN.tar.gz hBN.tar.gz] [15 MB],
[http://www.yambo-code.org/educational/tutorials/files/hBN-2D.tar.gz hBN-2D.tar.gz] [8,6 MB]

In the next days you could also use this file which you may like to download now
[http://www.yambo-code.org/educational/tutorials/files/hBN-convergence-kpoints.tar.gz hBN-convergence-kpoints.tar.gz] [254 MB]

After downloading the tar.gz files just unpack them in the '''YAMBO_TUTORIALS''' folder. For example
$ mkdir YAMBO_TUTORIALS
$ mv hBN.tar.gz YAMBO_TUTORIALS
$ cd YAMBO_TUTORIALS
$ tar -xvfz hBN.tar.gz
$ ls YAMBO_TUTORIALS
hBN
$ cd hBN
$ ls
$ PWSCF YAMBO

(Advanced users can download and install all tutorial files using git. See the main [[Tutorials#Files|Tutorial Files]] page.)

Now you can go directly in '''YAMBO''' folder where you can find the '''SAVE''' folder which is needed to start the yambo tutorials (for hBN bulk in this case) or, if you wish you can learn (see below) how to start from the DFT simulations doing a scf and nscf calculation, entering in '''PWSCF''' folder. In this way you will see how you can create the '''SAVE''' folder starting from *.save directory produced by pw.x.

==DFT calculation of bulk hBN and conversion to Yambo==

In this module you will learn how to generate the Yambo ''SAVE'' folder for bulk hBN starting from a PWscf calculation.

=== DFT calculations ===
$ cd YAMBO_TUTORIALS/hBN/PWSCF
$ ls
Inputs Pseudos PostProcessing References
hBN_scf.in hBN_nscf.in hBN_scf_plot_bands.in hBN_nscf_plot_bands.in

First run the SCF calculation to generate the ground-state charge density, occupations, Fermi level, and so on:
$ pw.x < hBN_scf.in > hBN_scf.out
Inspection of the output shows that the valence band maximum lies at 5.06eV.

Next run a non-SCF calculation to generate a set of Kohn-Sham eigenvalues and eigenvectors for both occupied and unoccupied states (100 bands):
$ pw.x < hBN_nscf.in > hBN_nscf.out ''(serial run, ~1 min) OR''
$ mpirun -np 2 pw.x < hBN_nscf.in > hBN_nscf.out ''(parallel run, 40s)''
Here we use a ''6x6x2'' grid giving 14 k-points, but denser grids should be used for checking convergence of Yambo runs.

Note the presence of the following flags in the input file:
wf_collect=.true.
force_symmorphic=.true.
diago_thr_init=5.0e-6,
diago_full_acc=.true.
which are needed for generating the Yambo databases accurately. Full explanations of these variables are given on the [http://www.quantum-espresso.org/wp-content/uploads/Doc/INPUT_PW.html quantum-ESPRESSO input variables page].

After these two runs, you should have a ''hBN.save'' directory:
$ ls hBN.save
data-file.xml charge-density.dat gvectors.dat B.pz-vbc.UPF N.pz-vbc.UPF
K00001 K00002 .... K00035 K00036
-->

=== Conversion to Yambo format ===
Once you have performed a nscf simulation with pw.x the PWscf ''bBN.save'' should not be empty and you can then convert it to the Yambo format using the <code>p2y</code> executable (pwscf to yambo), found in the yambo ''bin'' directory.
Enter ''hBN.save'' and launch <code>p2y</code>:

$ cd hBN.save
$ p2y
...
<---> DBs path set to .
<---> Index file set to data-file.xml
<---> Header/K-points/Energies... done
...
<---> == DB1 (Gvecs and more) ...
<---> ... Database done
<---> == DB2 (wavefunctions) ... done ==
<---> == DB3 (PseudoPotential) ... done ==
<---> == P2Y completed ==

This output repeats some information about the system and generates a ''SAVE'' directory:
$ ls SAVE
ns.db1 ns.wf ns.kb_pp_pwscf
ns.wf_fragments_1_1 ...
ns.kb_pp_pwscf_fragment_1 ...
These files, with an ''n'' prefix, indicate that they are in netCDF format, and thus not human readable. However, they are perfectly transferable across different architectures. You can check that the databases contain the information you expect by launching Yambo using the <code>-D</code> option:

$ yambo -D
[RD./SAVE//ns.db1]------------------------------------------
Bands : 100
K-points : 14
G-vectors [RL space]: 8029
Components [wavefunctions]: 1016
...
[RD./SAVE//ns.wf]-------------------------------------------
Fragmentation :yes
...
[RD./SAVE//ns.kb_pp_pwscf]----------------------------------
Fragmentation :yes
- S/N 006626 -------------------------- v.04.01.02 r.00000 -

In practice we suggest to move the ''SAVE'' folder into a new clean folder.

In this tutorial however, we ask instead that you continue using a ''SAVE'' folder that we prepared previously:
$ cd ../../YAMBO
$ ls
SAVE

==Initialization of Yambo databases==
Use the ''SAVE'' folders that are already provided, rather than any ones you may have generated previously.

Every Yambo run '''must''' start with this step. Go to the folder ''containing'' the hBN-bulk <code>SAVE</code> directory:
$ cd YAMBO_TUTORIALS/hBN/YAMBO
$ ls
SAVE

'''TIP''': do not run yambo from ''inside'' the <code>SAVE</code> folder!
'''This is the wrong way .. '''
$ cd SAVE
$ yambo
yambo: cannot access CORE database (SAVE/*db1 and/or SAVE/*wf)
In fact, if you ever see such message:
it usually means you are trying to launch Yambo '''from the wrong place'''.
$ cd ..

Now you are in the proper place and
$ ls
SAVE
you can simply launch the code
$ yambo
This will run the initialization (setup) ''runlevel''.

===Run-time output===
This is typically written to standard output (on screen) and tracks the progress of the run in real time:
<---> [01] MPI/OPENMP structure, Files & I/O Directories
<---> [02] CORE Variables Setup
<---> [02.01] Unit cells
<---> [02.02] Symmetries
<---> [02.03] Reciprocal space
<---> Shells finder |########################################| [100%] --(E) --(X)
<---> [02.04] K-grid lattice
<---> Grid dimensions : 6 6 2
<---> [02.05] Energies & Occupations
<---> [03] Transferred momenta grid and indexing
<---> BZ -> IBZ reduction |########################################| [100%] --(E) --(X)
<---> [03.01] X indexes
<---> X [eval] |########################################| [100%] --(E) --(X)
<---> X[REDUX] |########################################| [100%] --(E) --(X)
<---> [03.01.01] Sigma indexes
<---> Sigma [eval] |########################################| [100%] --(E) --(X)
<---> Sigma[REDUX] |########################################| [100%] --(E) --(X)
<---> [04] Timing Overview
<---> [05] Memory Overview
<---> [06] Game Over & Game summary
Specific runlevels are indicated with numeric labels like [02.02]. 
The hashes (#) indicate progress of the run in Wall Clock time, indicating the elapsed (E) and expected (X) time to complete a runlevel, and the percentage of the task complete.

===New core databases===
New databases appear in the ''SAVE'' folder:
$ ls SAVE
ns.db1 ns.wf ns.kb_pp_pwscf '''ndb.gops ndb.kindx'''
ns.wf_fragments_1_1 ...
ns.kb_pp_pwscf_fragment_1 ...
These contain information about the ''G''-vector shells and ''k/q''-point meshes as defined by the DFT calculation.

In general: a database called ''n'''s'''.xxx'' is a ''static'' database, generated once by <code>p2y</code>, while databases called ''n'''db'''.xxx'' are ''dynamically'' generated while you use <code>yambo</code>.

'''TIP''': if you launch <code>yambo</code>, but it does not seem to do anything, check that these files are present.

===Report file===
A report file ''r_setup'' is generated in the run directory.
This mostly reports information about the ground state system as defined by the DFT run, but also adds information about the band gaps, occupations, shells of G-vectors, IBZ/BZ grids, the CPU structure (for parallel runs), and so on. Some points of note:

Up to Yambo version 4.5
[02.03] RL shells
=================
Shells, format: [S#] G_RL(mHa)
[S453]:8029(0.7982E+5) [S452]:8005(0.7982E+5) [S451]:7981(0.7982E+5) [S450]:7957(0.7942E+5)
...
[S4]:11( 1183.) [S3]:5( 532.5123) [S2]:3( 133.1281) [S1]:1( 0.000000)

From Yambo version 5.0
[02.03] Reciprocal space
========================

nG shells : 217
nG charge : 3187
nG WFs : 1477
nC WFs : 1016
G-vecs. in first 21 shells: [ Number ]
1 3 5 11 13 25 37 39 51
63 65 71 83 95 107 113 125 127
139 151 163
...
Shell energy in first 21 shells: [ mHa ]
0.00000 133.128 532.512 1183.37 1198.15 1316.50 1715.88 2130.05 2381.52
3313.42 3328.20 3550.11 3683.24 4082.62 4511.57 4733.48 4748.27 4792.61
4866.61 5266.00 5680.16
...

This reports the set of closed reciprocal lattice (RL) shells defined internally that contain G-vectors with the same modulus.
The highest number of RL vectors we can use is 8029. Yambo will always redefine any input variable in RL units to the nearest closed shell.

Up to Yambo version 4.5
[02.05] Energies [ev] & Occupations
===================================
Fermi Level [ev]: 5.112805
VBM / CBm [ev]: 0.000000 3.876293
Electronic Temp. [ev K]: 0.00 0.00
Bosonic Temp. [ev K]: 0.00 0.00
El. density [cm-3]: 0.460E+24
States summary : Full Metallic Empty
0001-0008 0009-0100
Indirect Gaps [ev]: 3.876293 7.278081
Direct Gaps [ev]: 4.28829 11.35409
X BZ K-points : 72

From Yambo version 5.0
[02.05] Energies & Occupations
==============================

[X] === General ===
[X] Electronic Temperature : 0.000000 0.000000 [eV K]
[X] Bosonic Temperature : 0.000000 0.000000 [eV K]
[X] Finite Temperature mode : no
[X] El. density : 0.46037E+24 [cm-3]
[X] Fermi Level : 5.110835 [eV]

[X] === Gaps and Widths ===
[X] Conduction Band Min : 3.877976 [eV]
[X] Valence Band Max : 0.000000 [eV]
[X] Filled Bands : 8
[X] Empty Bands : 9 100
[X] Direct Gap : 4.289853 [eV]
[X] Direct Gap localized at k-point : 7
[X] Indirect Gap : 3.877976 [eV]
[X] Indirect Gap between k-points : 14 7
[X] Last valence band width : 3.401086 [eV]
[X] 1st conduction band width : 4.266292 [eV]

Yambo recalculates again the Fermi level (close to the value of 5.06 noted in the PWscf SCF calculation). From here on, however, the Fermi level is set to zero, and other eigenvalues are shifted accordingly. The system is insulating (8 filled, 92 empty) with an indirect band gap of 3.87 eV. The minimum and maximum direct and indirect gaps are indicated. There are 72 k-points in the full BZ, generated using symmetry from the 14 k-points in our user-defined grid.

'''TIP''': You should inspect the report file after ''every'' run for errors and warnings.

===Different ways of running yambo===
We just run Yambo interactively.

Let's try to re-run the setup with the command
$ nohup yambo &
$ ls
l_setup nohup.out r_setup r_setup_01 SAVE

If Yambo is launched using a script, or as a background process, or in parallel, this output will appear in a log file prefixed by the letter ''l'', in this case as ''l_setup''.
If this log file already exists from a previous run, it will not be overwritten. Instead, a new file will be created with an incrementing numerical label, e.g. ''l_setup_01, l_setup_02'', etc. '''This applies to all files created by Yambo'''. Here we see that l_setup was created for the first time, but r_setup already existed from the previous run, so now we have r_setup_01
If you check the differences between the two you will notice that in the second run yambo is reading the previously created ndb.kindx in place of re-computing the indexes.
Indeed the output inside l_setup does not show the timing for X and Sigma

As a last step we run the setup in parallel, but first we delete the ndb.kindx file
$ rm SAVE/ndb.kindx
$ mpirun -np 4 yambo
$ ls
LOG l_setup nohup.out r_setup r_setup_01 r_setup_02 SAVE
There is now r_setup_02
In the case of parallel runs, CPU-dependent log files will appear inside a ''LOG'' folder, e.g.
$ ls LOG
l_setup_CPU_1 l_setup_CPU_2 l_setup_CPU_3 l_setup_CPU_4
This behaviour can be controlled at runtime - see the Parallel tutorial for details.

===2D hBN===
Simply repeat the steps above. Go to the folder ''containing'' the hBN-sheet ''SAVE'' directory and launch <code>yambo</code>:
$ cd TUTORIALS/hBN-2D/YAMBO
$ ls
SAVE
$ yambo
Again, inspect the ''r_setup'' file, output logs, and verify that ''ndb.gops'' and ''ndb.kpts'' have been created inside the SAVE folder.

You are now ready to use Yambo!

==Yambo's command line interface==
Yambo uses a command line interface to select tasks, generate input files, and control the runtime behaviour.

In this module you will learn how to select tasks, generate and modify input files, and control the runtime behaviour by using Yambo's command line interface.


=== Input file generator ===
First, move to the appropriate folder and initialize the Yambo databases if you haven't already done so.
$ cd YAMBO_TUTORIALS/hBN/YAMBO
$ yambo ''(initialize)''

Yambo generates its own input files: you just tell the code what you want to calculate by launching Yambo along with one or more options.
To see the list of possible options, run <code>yambo -h</code> (we report here only the part we are focusing in)
$ yambo -h
'A shiny pot of fun and happiness [C.D.Hogan]'

This is : yambo
Version : 5.0.1 Revision 19547 Hash e90d90f2d
Configuration: MPI+OpenMP+SLK+SLEPC+HDF5_MPI_IO

...

Initializations:
-setup (-i) :Initialization
-coulomb (-r) :Coulomb potential

Response Functions:
-optics (-o) <string> :Linear Response optical properties (more with -h optics)
-X (-d) <string> :Inverse Dielectric Matrix (more with -h X)
-dipoles (-q) :Oscillator strenghts (or dipoles)
-kernel (-k) <string> :Kernel (more with -h kernel)

Self-Energy:
-hf (-x) :Hartree-Fock
-gw0 (-p) <string> :GW approximation (more with -h gw0)
-dyson (-g) <string> :Dyson Equation solver (more with -h dyson)
-lifetimes (-l) :GoWo Quasiparticle lifetimes

Bethe-Salpeter Equation:
-Ksolver (-y) <string> :BSE solver (more with -h Ksolver)

Total Energy:
-acfdt :ACFDT Total Energy

Utilites:
...
-slktest :ScaLapacK test

The options can be split into two sets: 
* A set of options which is needed to generate the appropriate input file (default name: ''yambo.in'') selecting the kind of simulation you would like to perform 
* A set of options which can be used to manage auxiliary functions (like redirect the I/O, choose a specific name for the input file, etc ..).

===Runlevel selection===
First of all, you would like to specify which kind of simulation you are going to perform and generate an input file with the first set of options.
By default, when generating the input file, Yambo will launch the <code>vi</code> editor.
Editor choice can be changed when launching the configure before compilation; alternatively you can use the <code>-Q</code> run time option to skip the automatic editing (do this if you are not familiar with <code>vi</code>!):
$ yambo -hf -Q
yambo: input file yambo.in created
$ emacs yambo.in ''or your favourite editing tool''

Multiple options can be used together to activate various tasks or runlevels (in some cases this is actually a necessity).
For instance, to generate an input file for optical spectra including local field effects (Hartree approximation), do (and then exit)
$ yambo -optics c -kernel hartree ''which switches on:''
optics # [R OPT] Optics
chi # [R CHI] Dyson equation for Chi.
Chimod= "Hartree" # [X] IP/Hartree/ALDA/LRC/BSfxc
To perform a Hartree-Fock and GW calculation using a plasmon-pole approximation, do (and then exit):
$ yambo -hf -gw0 p -dyson n ''which switches on:''
HF_and_locXC # [R XX] Hartree-Fock Self-energy and Vxc
gw0 # [R GW] GoWo Quasiparticle energy levels
ppa # [R Xp] Plasmon Pole Approximation
em1d # [R Xd] Dynamical Inverse Dielectric Matrix
Each runlevel activates its own list of variables and flags.

The previous command is also equivalent to
$ yambo -hf -gw0 r -dyson n -X p

===Changing input parameters ===
Yambo reads various parameters from existing database files and/or input files and uses them to suggest values or ranges.
Let's illustrate this by generating the input file for a Hartree-Fock calculation.

$ yambo -hf
Inside the generated input file you should find:
[[Variables#EXXRLvcs|EXXRLvcs]] = 3187 RL # [XX] Exchange RL components
%[[Variables#QPkrange|QPkrange]] # [GW] QP generalized Kpoint/Band indices
1| 14| 1|100|
%
The <code>[[Variables#QPkrange|QPkrange]]</code> variable (follow the link for a "detailed" explanation for any variable) suggests a range of k-points (1 to 14) and bands (1 to 100) based on what it finds in the core database ''SAVE/ns.db1'', i.e. as defined by the DFT code. 
Leave that variable alone, and instead modify the previous variable to <code>EXXRLvcs= 1000 RL</code>

Save the file, and now generate the input a second time with <code>yambo -x</code>. You will see:
[[Variables#EXXRLvcs|EXXRLvcs]]= 1009 RL
This indicates that Yambo has read the new input value (1000 G-vectors), checked the database of G-vector shells ''(SAVE/ndb.gops)'',
and changed the input value to one that fits a completely closed shell.

Last, note that Yambo variables can be expressed in different '''units'''. In this case, <code>RL</code> can be replaced by an energy unit like Ry, eV, Ha, etc. Energy units are generally better as they are independent of the cell size. Technical information is available on the [[Variables]] page.

The input file generator of Yambo is thus an ''intelligent'' parser, which interacts with the user and the existing databases. For this reason we recommend that you always use Yambo to generate the input files, rather than making them yourself.

===Extra options===
Extra options modify some of the code's default settings. They can be used when launching the code but also when generating input files.

Let's have a look again to the possible options (we report here only the part we are focusing in):
$ yambo -h
This is : yambo
Version : 5.0.1 Revision 19547 Hash e90d90f2d
Configuration: MPI+OpenMP+SLK+SLEPC+HDF5_MPI_IO

Help & version:
-help (-h) <string> :<string> can be an option (e.g. -h optics)
-version :Code version & libraries

Input file & Directories:
-Input (-F) <string> :Input file
-Verbosity (-V) <string> :Input file variables verbosity (more with -h Verbosity)
-Job (-J) <string> :Job string
-Idir (-I) <string> :Input directory
-Odir (-O) <string> :I/O directory
-Cdir (-C) <string> :Communication directory

Parallel Control:
-parenv (-E) <string> :Environment Parallel Variables file
-nompi :Switch off MPI support
-noopenmp :Switch off OPENMP support

...

Utilites:
-Quiet (-Q) :Quiet input file creation
-fatlog :Verbose (fatter) log(s)
-DBlist (-D) :Databases properties
...

Command line options are extremely important to master if you want to use yambo productively.
Often, the meaning is clear from the help menu:
$ yambo -F yambo.in_HF -hf ''Make a Hartree-Fock input file called yambo.in_HF''
$ yambo -D ''Summarize the content of the databases in the SAVE folder''
$ yambo -I ../ ''Run the code, using a SAVE folder in a directory one level up''
$ yambo -C MyTest ''Run the code, putting all report, log, plot files inside a folder MyTest''

Other options deserve a closer look.

===Verbosity===
Yambo uses ''many'' input variables, many of which can be left at their default values. To keep input files short and manageable, only a few variables appear by default in the inout file. More advanced variables can be switched on by using the <code>-V</code> verbosity option. These are grouped according to the type of variable. For instance, <code>-V RL</code> switches on variables related to G vector summations, and <code>-V io</code> switches on options related to I/O control. Try:

$ yambo -optics c -V RL ''switches on:''
FFTGvecs= 3951 RL # [FFT] Plane-waves

$ yambo -optics c -V io ''switches on:''
StdoHash= 40 # [IO] Live-timing Hashes
DBsIOoff= "none" # [IO] Space-separated list of DB with NO I/O. DB= ...
DBsFRAGpm= "none" # [IO] Space-separated list of +DB to be FRAG and ...
#WFbuffIO # [IO] Wave-functions buffered I/O

Unfortunately, -V options must be invoked and changed ''one at a time''. When you are more expert, you may go straight to <code>-V all</code>, which turns on all possible variables. However note that <code>yambo -o c -V all</code> adds an extra 30 variables to the input file, which can be confusing: use it with care.

===Job script label===
The best way to keep track of different runs using different parameters is through the <code>-J</code> flag. This inserts a label in all output and report files, and creates a new folder containing any new databases (i.e. they are not written in the core ''SAVE'' folder). Try:
$ yambo -J 1Ry -V RL -hf -F yambo_hf.in ''and modify to''
FFTGvecs = 1 Ry
EXXGvecs = 1 Ry
$ yambo -J 1Ry -F yambo_hf.in ''Run the code''
$ ls
yambo_hf.in SAVE
o-1Ry.hf r-1Ry_HF_and_locXC 1Ry 1Ry/ndb.HF_and_locXC
This is extremely useful when running convergence tests, trying out different parameters, etc.

''Exercise'': use <code>yambo</code> to report the properties of all database files (including ''ndb.HF_and_locXC'')

First steps: walk through from DFT(standalone)

2021-04-06T08:14:00Z

Maurizia: /* Download the Files */

In this tutorial you will learn how to calculate optical spectra using Yambo, starting from a DFT calculation and ending with a look at local field effects in the optical response.

== System characteristics ==
We will use a 3D system (bulk hBN) and a 2D system (hBN sheet).

[[File:HBN-bulk-3x3-annotated.png|x200px|Atomic structure of bulk hBN]]
[[File:HBN2.png|x200px|Atomic structure of 2D hBN]]

'''Hexagonal boron nitride - hBN''':
* HCP lattice, ABAB stacking
* Four atoms per cell, B and N (16 electrons)
* Lattice constants: ''a'' = 4.716 [a.u.], ''c/a'' = 2.582
* Plane wave cutoff 40 Ry (~1500 RL vectors in wavefunctions)
* SCF run: shifted ''6x6x2'' grid (12 k-points) with 8 bands
* Non-SCF run: gamma-centred ''6x6x2'' (14 k-points) grid with 100 bands

=== Prerequisites ===
'''You will need''':
* PWSCF input files and pseudopotentials for hBN bulk
* <code>pw.x</code> executable, version 5.0 or later
* <code>p2y</code> and <code>yambo</code> executables
* <code>gnuplot</code> for plotting spectra

==Download the Files==

Download and unpack the followint files:
[http://www.yambo-code.org/educational/tutorials/files/hBN.tar.gz hBN.tar.gz] [15 MB],
[http://www.yambo-code.org/educational/tutorials/files/hBN-2D.tar.gz hBN-2D.tar.gz] [8,6 MB]

In the next days you could also use this file which you may like to download now
[http://www.yambo-code.org/educational/tutorials/files/hBN-convergence-kpoints.tar.gz hBN-convergence-kpoints.tar.gz] [254 MB]

After downloading the tar.gz files just unpack them in the '''YAMBO_TUTORIALS''' folder. For example
$ mkdir YAMBO_TUTORIALS
$ mv hBN.tar.gz YAMBO_TUTORIALS
$ cd YAMBO_TUTORIALS
$ tar -xvfz hBN.tar.gz
$ ls YAMBO_TUTORIALS
hBN
$ cd hBN
$ ls
$ PWSCF YAMBO

(Advanced users can download and install all tutorial files using git. See the main [[Tutorials#Files|Tutorial Files]] page.)

Now you can go directly in '''YAMBO''' folder where you can find the '''SAVE''' folder which is needed to start the yambo tutorials (for hBN bulk in this case) or, if you wish you can learn (see below) how to start from the DFT simulations doing a scf and nscf calculation, entering in '''PWSCF''' folder. In this way you will see how you can create the '''SAVE''' folder starting from *.save directory produced by pw.x.

==DFT calculation of bulk hBN and conversion to Yambo==

In this module you will learn how to generate the Yambo ''SAVE'' folder for bulk hBN starting from a PWscf calculation.

=== DFT calculations ===
$ cd YAMBO_TUTORIALS/hBN/PWSCF
$ ls
Inputs Pseudos PostProcessing References
hBN_scf.in hBN_nscf.in hBN_scf_plot_bands.in hBN_nscf_plot_bands.in

First run the SCF calculation to generate the ground-state charge density, occupations, Fermi level, and so on:
$ pw.x < hBN_scf.in > hBN_scf.out
Inspection of the output shows that the valence band maximum lies at 5.06eV.

Next run a non-SCF calculation to generate a set of Kohn-Sham eigenvalues and eigenvectors for both occupied and unoccupied states (100 bands):
$ pw.x < hBN_nscf.in > hBN_nscf.out ''(serial run, ~1 min) OR''
$ mpirun -np 2 pw.x < hBN_nscf.in > hBN_nscf.out ''(parallel run, 40s)''
Here we use a ''6x6x2'' grid giving 14 k-points, but denser grids should be used for checking convergence of Yambo runs.

Note the presence of the following flags in the input file:
wf_collect=.true.
force_symmorphic=.true.
diago_thr_init=5.0e-6,
diago_full_acc=.true.
which are needed for generating the Yambo databases accurately. Full explanations of these variables are given on the [http://www.quantum-espresso.org/wp-content/uploads/Doc/INPUT_PW.html quantum-ESPRESSO input variables page].

After these two runs, you should have a ''hBN.save'' directory:
$ ls hBN.save
data-file.xml charge-density.dat gvectors.dat B.pz-vbc.UPF N.pz-vbc.UPF
K00001 K00002 .... K00035 K00036
-->

=== Conversion to Yambo format ===
The PWscf ''bBN.save'' output is converted to the Yambo format using the <code>p2y</code> executable (pwscf to yambo), found in the yambo ''bin'' directory.
Enter ''hBN.save'' and launch <code>p2y</code>:

$ cd hBN.save
$ p2y
...
<---> DBs path set to .
<---> Index file set to data-file.xml
<---> Header/K-points/Energies... done
...
<---> == DB1 (Gvecs and more) ...
<---> ... Database done
<---> == DB2 (wavefunctions) ... done ==
<---> == DB3 (PseudoPotential) ... done ==
<---> == P2Y completed ==

This output repeats some information about the system and generates a ''SAVE'' directory:
$ ls SAVE
ns.db1 ns.wf ns.kb_pp_pwscf
ns.wf_fragments_1_1 ...
ns.kb_pp_pwscf_fragment_1 ...
These files, with an ''n'' prefix, indicate that they are in netCDF format, and thus not human readable. However, they are perfectly transferable across different architectures. You can check that the databases contain the information you expect by launching Yambo using the <code>-D</code> option:

$ yambo -D
[RD./SAVE//ns.db1]------------------------------------------
Bands : 100
K-points : 14
G-vectors [RL space]: 8029
Components [wavefunctions]: 1016
...
[RD./SAVE//ns.wf]-------------------------------------------
Fragmentation :yes
...
[RD./SAVE//ns.kb_pp_pwscf]----------------------------------
Fragmentation :yes
- S/N 006626 -------------------------- v.04.01.02 r.00000 -

In practice we suggest to move the ''SAVE'' folder into a new clean folder.

In this tutorial however, we ask instead that you continue using a ''SAVE'' folder that we prepared previously:
$ cd ../../YAMBO
$ ls
SAVE

==Initialization of Yambo databases==
Use the ''SAVE'' folders that are already provided, rather than any ones you may have generated previously.

Every Yambo run '''must''' start with this step. Go to the folder ''containing'' the hBN-bulk <code>SAVE</code> directory:
$ cd YAMBO_TUTORIALS/hBN/YAMBO
$ ls
SAVE

'''TIP''': do not run yambo from ''inside'' the <code>SAVE</code> folder!
'''This is the wrong way .. '''
$ cd SAVE
$ yambo
yambo: cannot access CORE database (SAVE/*db1 and/or SAVE/*wf)
In fact, if you ever see such message:
it usually means you are trying to launch Yambo '''from the wrong place'''.
$ cd ..

Now you are in the proper place and
$ ls
SAVE
you can simply launch the code
$ yambo
This will run the initialization (setup) ''runlevel''.

===Run-time output===
This is typically written to standard output (on screen) and tracks the progress of the run in real time:
<---> [01] MPI/OPENMP structure, Files & I/O Directories
<---> [02] CORE Variables Setup
<---> [02.01] Unit cells
<---> [02.02] Symmetries
<---> [02.03] Reciprocal space
<---> Shells finder |########################################| [100%] --(E) --(X)
<---> [02.04] K-grid lattice
<---> Grid dimensions : 6 6 2
<---> [02.05] Energies & Occupations
<---> [03] Transferred momenta grid and indexing
<---> BZ -> IBZ reduction |########################################| [100%] --(E) --(X)
<---> [03.01] X indexes
<---> X [eval] |########################################| [100%] --(E) --(X)
<---> X[REDUX] |########################################| [100%] --(E) --(X)
<---> [03.01.01] Sigma indexes
<---> Sigma [eval] |########################################| [100%] --(E) --(X)
<---> Sigma[REDUX] |########################################| [100%] --(E) --(X)
<---> [04] Timing Overview
<---> [05] Memory Overview
<---> [06] Game Over & Game summary
Specific runlevels are indicated with numeric labels like [02.02]. 
The hashes (#) indicate progress of the run in Wall Clock time, indicating the elapsed (E) and expected (X) time to complete a runlevel, and the percentage of the task complete.

===New core databases===
New databases appear in the ''SAVE'' folder:
$ ls SAVE
ns.db1 ns.wf ns.kb_pp_pwscf '''ndb.gops ndb.kindx'''
ns.wf_fragments_1_1 ...
ns.kb_pp_pwscf_fragment_1 ...
These contain information about the ''G''-vector shells and ''k/q''-point meshes as defined by the DFT calculation.

In general: a database called ''n'''s'''.xxx'' is a ''static'' database, generated once by <code>p2y</code>, while databases called ''n'''db'''.xxx'' are ''dynamically'' generated while you use <code>yambo</code>.

'''TIP''': if you launch <code>yambo</code>, but it does not seem to do anything, check that these files are present.

===Report file===
A report file ''r_setup'' is generated in the run directory.
This mostly reports information about the ground state system as defined by the DFT run, but also adds information about the band gaps, occupations, shells of G-vectors, IBZ/BZ grids, the CPU structure (for parallel runs), and so on. Some points of note:

Up to Yambo version 4.5
[02.03] RL shells
=================
Shells, format: [S#] G_RL(mHa)
[S453]:8029(0.7982E+5) [S452]:8005(0.7982E+5) [S451]:7981(0.7982E+5) [S450]:7957(0.7942E+5)
...
[S4]:11( 1183.) [S3]:5( 532.5123) [S2]:3( 133.1281) [S1]:1( 0.000000)

From Yambo version 5.0
[02.03] Reciprocal space
========================

nG shells : 217
nG charge : 3187
nG WFs : 1477
nC WFs : 1016
G-vecs. in first 21 shells: [ Number ]
1 3 5 11 13 25 37 39 51
63 65 71 83 95 107 113 125 127
139 151 163
...
Shell energy in first 21 shells: [ mHa ]
0.00000 133.128 532.512 1183.37 1198.15 1316.50 1715.88 2130.05 2381.52
3313.42 3328.20 3550.11 3683.24 4082.62 4511.57 4733.48 4748.27 4792.61
4866.61 5266.00 5680.16
...

This reports the set of closed reciprocal lattice (RL) shells defined internally that contain G-vectors with the same modulus.
The highest number of RL vectors we can use is 8029. Yambo will always redefine any input variable in RL units to the nearest closed shell.

Up to Yambo version 4.5
[02.05] Energies [ev] & Occupations
===================================
Fermi Level [ev]: 5.112805
VBM / CBm [ev]: 0.000000 3.876293
Electronic Temp. [ev K]: 0.00 0.00
Bosonic Temp. [ev K]: 0.00 0.00
El. density [cm-3]: 0.460E+24
States summary : Full Metallic Empty
0001-0008 0009-0100
Indirect Gaps [ev]: 3.876293 7.278081
Direct Gaps [ev]: 4.28829 11.35409
X BZ K-points : 72

From Yambo version 5.0
[02.05] Energies & Occupations
==============================

[X] === General ===
[X] Electronic Temperature : 0.000000 0.000000 [eV K]
[X] Bosonic Temperature : 0.000000 0.000000 [eV K]
[X] Finite Temperature mode : no
[X] El. density : 0.46037E+24 [cm-3]
[X] Fermi Level : 5.110835 [eV]

[X] === Gaps and Widths ===
[X] Conduction Band Min : 3.877976 [eV]
[X] Valence Band Max : 0.000000 [eV]
[X] Filled Bands : 8
[X] Empty Bands : 9 100
[X] Direct Gap : 4.289853 [eV]
[X] Direct Gap localized at k-point : 7
[X] Indirect Gap : 3.877976 [eV]
[X] Indirect Gap between k-points : 14 7
[X] Last valence band width : 3.401086 [eV]
[X] 1st conduction band width : 4.266292 [eV]

Yambo recalculates again the Fermi level (close to the value of 5.06 noted in the PWscf SCF calculation). From here on, however, the Fermi level is set to zero, and other eigenvalues are shifted accordingly. The system is insulating (8 filled, 92 empty) with an indirect band gap of 3.87 eV. The minimum and maximum direct and indirect gaps are indicated. There are 72 k-points in the full BZ, generated using symmetry from the 14 k-points in our user-defined grid.

'''TIP''': You should inspect the report file after ''every'' run for errors and warnings.

===Different ways of running yambo===
We just run Yambo interactively.

Let's try to re-run the setup with the command
$ nohup yambo &
$ ls
l_setup nohup.out r_setup r_setup_01 SAVE

If Yambo is launched using a script, or as a background process, or in parallel, this output will appear in a log file prefixed by the letter ''l'', in this case as ''l_setup''.
If this log file already exists from a previous run, it will not be overwritten. Instead, a new file will be created with an incrementing numerical label, e.g. ''l_setup_01, l_setup_02'', etc. '''This applies to all files created by Yambo'''. Here we see that l_setup was created for the first time, but r_setup already existed from the previous run, so now we have r_setup_01
If you check the differences between the two you will notice that in the second run yambo is reading the previously created ndb.kindx in place of re-computing the indexes.
Indeed the output inside l_setup does not show the timing for X and Sigma

As a last step we run the setup in parallel, but first we delete the ndb.kindx file
$ rm SAVE/ndb.kindx
$ mpirun -np 4 yambo
$ ls
LOG l_setup nohup.out r_setup r_setup_01 r_setup_02 SAVE
There is now r_setup_02
In the case of parallel runs, CPU-dependent log files will appear inside a ''LOG'' folder, e.g.
$ ls LOG
l_setup_CPU_1 l_setup_CPU_2 l_setup_CPU_3 l_setup_CPU_4
This behaviour can be controlled at runtime - see the Parallel tutorial for details.

===2D hBN===
Simply repeat the steps above. Go to the folder ''containing'' the hBN-sheet ''SAVE'' directory and launch <code>yambo</code>:
$ cd TUTORIALS/hBN-2D/YAMBO
$ ls
SAVE
$ yambo
Again, inspect the ''r_setup'' file, output logs, and verify that ''ndb.gops'' and ''ndb.kpts'' have been created inside the SAVE folder.

You are now ready to use Yambo!

==Yambo's command line interface==
Yambo uses a command line interface to select tasks, generate input files, and control the runtime behaviour.

In this module you will learn how to select tasks, generate and modify input files, and control the runtime behaviour by using Yambo's command line interface.


=== Input file generator ===
First, move to the appropriate folder and initialize the Yambo databases if you haven't already done so.
$ cd YAMBO_TUTORIALS/hBN/YAMBO
$ yambo ''(initialize)''

Yambo generates its own input files: you just tell the code what you want to calculate by launching Yambo along with one or more options.
To see the list of possible options, run <code>yambo -h</code> (we report here only the part we are focusing in)
$ yambo -h
'A shiny pot of fun and happiness [C.D.Hogan]'

This is : yambo
Version : 5.0.1 Revision 19547 Hash e90d90f2d
Configuration: MPI+OpenMP+SLK+SLEPC+HDF5_MPI_IO

...

Initializations:
-setup (-i) :Initialization
-coulomb (-r) :Coulomb potential

Response Functions:
-optics (-o) <string> :Linear Response optical properties (more with -h optics)
-X (-d) <string> :Inverse Dielectric Matrix (more with -h X)
-dipoles (-q) :Oscillator strenghts (or dipoles)
-kernel (-k) <string> :Kernel (more with -h kernel)

Self-Energy:
-hf (-x) :Hartree-Fock
-gw0 (-p) <string> :GW approximation (more with -h gw0)
-dyson (-g) <string> :Dyson Equation solver (more with -h dyson)
-lifetimes (-l) :GoWo Quasiparticle lifetimes

Bethe-Salpeter Equation:
-Ksolver (-y) <string> :BSE solver (more with -h Ksolver)

Total Energy:
-acfdt :ACFDT Total Energy

Utilites:
...
-slktest :ScaLapacK test

The options can be split into two sets: 
* A set of options which is needed to generate the appropriate input file (default name: ''yambo.in'') selecting the kind of simulation you would like to perform 
* A set of options which can be used to manage auxiliary functions (like redirect the I/O, choose a specific name for the input file, etc ..).

===Runlevel selection===
First of all, you would like to specify which kind of simulation you are going to perform and generate an input file with the first set of options.
By default, when generating the input file, Yambo will launch the <code>vi</code> editor.
Editor choice can be changed when launching the configure before compilation; alternatively you can use the <code>-Q</code> run time option to skip the automatic editing (do this if you are not familiar with <code>vi</code>!):
$ yambo -hf -Q
yambo: input file yambo.in created
$ emacs yambo.in ''or your favourite editing tool''

Multiple options can be used together to activate various tasks or runlevels (in some cases this is actually a necessity).
For instance, to generate an input file for optical spectra including local field effects (Hartree approximation), do (and then exit)
$ yambo -optics c -kernel hartree ''which switches on:''
optics # [R OPT] Optics
chi # [R CHI] Dyson equation for Chi.
Chimod= "Hartree" # [X] IP/Hartree/ALDA/LRC/BSfxc
To perform a Hartree-Fock and GW calculation using a plasmon-pole approximation, do (and then exit):
$ yambo -hf -gw0 p -dyson n ''which switches on:''
HF_and_locXC # [R XX] Hartree-Fock Self-energy and Vxc
gw0 # [R GW] GoWo Quasiparticle energy levels
ppa # [R Xp] Plasmon Pole Approximation
em1d # [R Xd] Dynamical Inverse Dielectric Matrix
Each runlevel activates its own list of variables and flags.

The previous command is also equivalent to
$ yambo -hf -gw0 r -dyson n -X p

===Changing input parameters ===
Yambo reads various parameters from existing database files and/or input files and uses them to suggest values or ranges.
Let's illustrate this by generating the input file for a Hartree-Fock calculation.

$ yambo -hf
Inside the generated input file you should find:
[[Variables#EXXRLvcs|EXXRLvcs]] = 3187 RL # [XX] Exchange RL components
%[[Variables#QPkrange|QPkrange]] # [GW] QP generalized Kpoint/Band indices
1| 14| 1|100|
%
The <code>[[Variables#QPkrange|QPkrange]]</code> variable (follow the link for a "detailed" explanation for any variable) suggests a range of k-points (1 to 14) and bands (1 to 100) based on what it finds in the core database ''SAVE/ns.db1'', i.e. as defined by the DFT code. 
Leave that variable alone, and instead modify the previous variable to <code>EXXRLvcs= 1000 RL</code>

Save the file, and now generate the input a second time with <code>yambo -x</code>. You will see:
[[Variables#EXXRLvcs|EXXRLvcs]]= 1009 RL
This indicates that Yambo has read the new input value (1000 G-vectors), checked the database of G-vector shells ''(SAVE/ndb.gops)'',
and changed the input value to one that fits a completely closed shell.

Last, note that Yambo variables can be expressed in different '''units'''. In this case, <code>RL</code> can be replaced by an energy unit like Ry, eV, Ha, etc. Energy units are generally better as they are independent of the cell size. Technical information is available on the [[Variables]] page.

The input file generator of Yambo is thus an ''intelligent'' parser, which interacts with the user and the existing databases. For this reason we recommend that you always use Yambo to generate the input files, rather than making them yourself.

===Extra options===
Extra options modify some of the code's default settings. They can be used when launching the code but also when generating input files.

Let's have a look again to the possible options (we report here only the part we are focusing in):
$ yambo -h
This is : yambo
Version : 5.0.1 Revision 19547 Hash e90d90f2d
Configuration: MPI+OpenMP+SLK+SLEPC+HDF5_MPI_IO

Help & version:
-help (-h) <string> :<string> can be an option (e.g. -h optics)
-version :Code version & libraries

Input file & Directories:
-Input (-F) <string> :Input file
-Verbosity (-V) <string> :Input file variables verbosity (more with -h Verbosity)
-Job (-J) <string> :Job string
-Idir (-I) <string> :Input directory
-Odir (-O) <string> :I/O directory
-Cdir (-C) <string> :Communication directory

Parallel Control:
-parenv (-E) <string> :Environment Parallel Variables file
-nompi :Switch off MPI support
-noopenmp :Switch off OPENMP support

...

Utilites:
-Quiet (-Q) :Quiet input file creation
-fatlog :Verbose (fatter) log(s)
-DBlist (-D) :Databases properties
...

Command line options are extremely important to master if you want to use yambo productively.
Often, the meaning is clear from the help menu:
$ yambo -F yambo.in_HF -hf ''Make a Hartree-Fock input file called yambo.in_HF''
$ yambo -D ''Summarize the content of the databases in the SAVE folder''
$ yambo -I ../ ''Run the code, using a SAVE folder in a directory one level up''
$ yambo -C MyTest ''Run the code, putting all report, log, plot files inside a folder MyTest''

Other options deserve a closer look.

===Verbosity===
Yambo uses ''many'' input variables, many of which can be left at their default values. To keep input files short and manageable, only a few variables appear by default in the inout file. More advanced variables can be switched on by using the <code>-V</code> verbosity option. These are grouped according to the type of variable. For instance, <code>-V RL</code> switches on variables related to G vector summations, and <code>-V io</code> switches on options related to I/O control. Try:

$ yambo -optics c -V RL ''switches on:''
FFTGvecs= 3951 RL # [FFT] Plane-waves

$ yambo -optics c -V io ''switches on:''
StdoHash= 40 # [IO] Live-timing Hashes
DBsIOoff= "none" # [IO] Space-separated list of DB with NO I/O. DB= ...
DBsFRAGpm= "none" # [IO] Space-separated list of +DB to be FRAG and ...
#WFbuffIO # [IO] Wave-functions buffered I/O

Unfortunately, -V options must be invoked and changed ''one at a time''. When you are more expert, you may go straight to <code>-V all</code>, which turns on all possible variables. However note that <code>yambo -o c -V all</code> adds an extra 30 variables to the input file, which can be confusing: use it with care.

===Job script label===
The best way to keep track of different runs using different parameters is through the <code>-J</code> flag. This inserts a label in all output and report files, and creates a new folder containing any new databases (i.e. they are not written in the core ''SAVE'' folder). Try:
$ yambo -J 1Ry -V RL -hf -F yambo_hf.in ''and modify to''
FFTGvecs = 1 Ry
EXXGvecs = 1 Ry
$ yambo -J 1Ry -F yambo_hf.in ''Run the code''
$ ls
yambo_hf.in SAVE
o-1Ry.hf r-1Ry_HF_and_locXC 1Ry 1Ry/ndb.HF_and_locXC
This is extremely useful when running convergence tests, trying out different parameters, etc.

''Exercise'': use <code>yambo</code> to report the properties of all database files (including ''ndb.HF_and_locXC'')

First steps: walk through from DFT(standalone)

2021-04-06T08:07:42Z

Maurizia: /* Download the Files */

In this tutorial you will learn how to calculate optical spectra using Yambo, starting from a DFT calculation and ending with a look at local field effects in the optical response.

== System characteristics ==
We will use a 3D system (bulk hBN) and a 2D system (hBN sheet).

[[File:HBN-bulk-3x3-annotated.png|x200px|Atomic structure of bulk hBN]]
[[File:HBN2.png|x200px|Atomic structure of 2D hBN]]

'''Hexagonal boron nitride - hBN''':
* HCP lattice, ABAB stacking
* Four atoms per cell, B and N (16 electrons)
* Lattice constants: ''a'' = 4.716 [a.u.], ''c/a'' = 2.582
* Plane wave cutoff 40 Ry (~1500 RL vectors in wavefunctions)
* SCF run: shifted ''6x6x2'' grid (12 k-points) with 8 bands
* Non-SCF run: gamma-centred ''6x6x2'' (14 k-points) grid with 100 bands

=== Prerequisites ===
'''You will need''':
* PWSCF input files and pseudopotentials for hBN bulk
* <code>pw.x</code> executable, version 5.0 or later
* <code>p2y</code> and <code>yambo</code> executables
* <code>gnuplot</code> for plotting spectra

==Download the Files==

Download and unpack the followint files:
[http://www.yambo-code.org/educational/tutorials/files/hBN.tar.gz hBN.tar.gz] [15 MB],
[http://www.yambo-code.org/educational/tutorials/files/hBN-2D.tar.gz hBN-2D.tar.gz] [8,6 MB]

In the next days you will also use this file which you may like to download now
[http://www.yambo-code.org/educational/tutorials/files/hBN-convergence-kpoints.tar.gz hBN-convergence-kpoints.tar.gz] [254 MB]

After downloading the tar.gz files just unpack them in the '''YAMBO_TUTORIALS''' folder. For example
$ mkdir YAMBO_TUTORIALS
$ mv hBN.tar.gz YAMBO_TUTORIALS
$ cd YAMBO_TUTORIALS
$ tar -xvfz hBN.tar.gz
$ ls YAMBO_TUTORIALS
hBN
$ cd hBN
$ ls
$ PWSCF YAMBO

(Advanced users can download and install all tutorial files using git. See the main [[Tutorials#Files|Tutorial Files]] page.)

Now you can go directly in '''YAMBO''' folder where you can find the '''SAVE''' folder which is needed to start the yambo tutorials for hBN or, if you wish you can learn (see below) how to start from the DFT simulations doing an scf and nscf calculation, entering in '''PWSCF''' folder. In this way you will learn how to create the '''SAVE''' folder starting from *.save directory produced by pw.x.

==DFT calculation of bulk hBN and conversion to Yambo==

In this module you will learn how to generate the Yambo ''SAVE'' folder for bulk hBN starting from a PWscf calculation.



=== Conversion to Yambo format ===
The PWscf ''bBN.save'' output is converted to the Yambo format using the <code>p2y</code> executable (pwscf to yambo), found in the yambo ''bin'' directory.
Enter ''hBN.save'' and launch <code>p2y</code>:

$ cd hBN.save
$ p2y
...
<---> DBs path set to .
<---> Index file set to data-file.xml
<---> Header/K-points/Energies... done
...
<---> == DB1 (Gvecs and more) ...
<---> ... Database done
<---> == DB2 (wavefunctions) ... done ==
<---> == DB3 (PseudoPotential) ... done ==
<---> == P2Y completed ==

This output repeats some information about the system and generates a ''SAVE'' directory:
$ ls SAVE
ns.db1 ns.wf ns.kb_pp_pwscf
ns.wf_fragments_1_1 ...
ns.kb_pp_pwscf_fragment_1 ...
These files, with an ''n'' prefix, indicate that they are in netCDF format, and thus not human readable. However, they are perfectly transferable across different architectures. You can check that the databases contain the information you expect by launching Yambo using the <code>-D</code> option:

$ yambo -D
[RD./SAVE//ns.db1]------------------------------------------
Bands : 100
K-points : 14
G-vectors [RL space]: 8029
Components [wavefunctions]: 1016
...
[RD./SAVE//ns.wf]-------------------------------------------
Fragmentation :yes
...
[RD./SAVE//ns.kb_pp_pwscf]----------------------------------
Fragmentation :yes
- S/N 006626 -------------------------- v.04.01.02 r.00000 -

In practice we suggest to move the ''SAVE'' folder into a new clean folder.

In this tutorial however, we ask instead that you continue using a ''SAVE'' folder that we prepared previously:
$ cd ../../YAMBO
$ ls
SAVE

==Initialization of Yambo databases==
Use the ''SAVE'' folders that are already provided, rather than any ones you may have generated previously.

Every Yambo run '''must''' start with this step. Go to the folder ''containing'' the hBN-bulk <code>SAVE</code> directory:
$ cd YAMBO_TUTORIALS/hBN/YAMBO
$ ls
SAVE

'''TIP''': do not run yambo from ''inside'' the <code>SAVE</code> folder!
'''This is the wrong way .. '''
$ cd SAVE
$ yambo
yambo: cannot access CORE database (SAVE/*db1 and/or SAVE/*wf)
In fact, if you ever see such message:
it usually means you are trying to launch Yambo '''from the wrong place'''.
$ cd ..

Now you are in the proper place and
$ ls
SAVE
you can simply launch the code
$ yambo
This will run the initialization (setup) ''runlevel''.

===Run-time output===
This is typically written to standard output (on screen) and tracks the progress of the run in real time:
<---> [01] MPI/OPENMP structure, Files & I/O Directories
<---> [02] CORE Variables Setup
<---> [02.01] Unit cells
<---> [02.02] Symmetries
<---> [02.03] Reciprocal space
<---> Shells finder |########################################| [100%] --(E) --(X)
<---> [02.04] K-grid lattice
<---> Grid dimensions : 6 6 2
<---> [02.05] Energies & Occupations
<---> [03] Transferred momenta grid and indexing
<---> BZ -> IBZ reduction |########################################| [100%] --(E) --(X)
<---> [03.01] X indexes
<---> X [eval] |########################################| [100%] --(E) --(X)
<---> X[REDUX] |########################################| [100%] --(E) --(X)
<---> [03.01.01] Sigma indexes
<---> Sigma [eval] |########################################| [100%] --(E) --(X)
<---> Sigma[REDUX] |########################################| [100%] --(E) --(X)
<---> [04] Timing Overview
<---> [05] Memory Overview
<---> [06] Game Over & Game summary
Specific runlevels are indicated with numeric labels like [02.02]. 
The hashes (#) indicate progress of the run in Wall Clock time, indicating the elapsed (E) and expected (X) time to complete a runlevel, and the percentage of the task complete.

===New core databases===
New databases appear in the ''SAVE'' folder:
$ ls SAVE
ns.db1 ns.wf ns.kb_pp_pwscf '''ndb.gops ndb.kindx'''
ns.wf_fragments_1_1 ...
ns.kb_pp_pwscf_fragment_1 ...
These contain information about the ''G''-vector shells and ''k/q''-point meshes as defined by the DFT calculation.

In general: a database called ''n'''s'''.xxx'' is a ''static'' database, generated once by <code>p2y</code>, while databases called ''n'''db'''.xxx'' are ''dynamically'' generated while you use <code>yambo</code>.

'''TIP''': if you launch <code>yambo</code>, but it does not seem to do anything, check that these files are present.

===Report file===
A report file ''r_setup'' is generated in the run directory.
This mostly reports information about the ground state system as defined by the DFT run, but also adds information about the band gaps, occupations, shells of G-vectors, IBZ/BZ grids, the CPU structure (for parallel runs), and so on. Some points of note:

Up to Yambo version 4.5
[02.03] RL shells
=================
Shells, format: [S#] G_RL(mHa)
[S453]:8029(0.7982E+5) [S452]:8005(0.7982E+5) [S451]:7981(0.7982E+5) [S450]:7957(0.7942E+5)
...
[S4]:11( 1183.) [S3]:5( 532.5123) [S2]:3( 133.1281) [S1]:1( 0.000000)

From Yambo version 5.0
[02.03] Reciprocal space
========================

nG shells : 217
nG charge : 3187
nG WFs : 1477
nC WFs : 1016
G-vecs. in first 21 shells: [ Number ]
1 3 5 11 13 25 37 39 51
63 65 71 83 95 107 113 125 127
139 151 163
...
Shell energy in first 21 shells: [ mHa ]
0.00000 133.128 532.512 1183.37 1198.15 1316.50 1715.88 2130.05 2381.52
3313.42 3328.20 3550.11 3683.24 4082.62 4511.57 4733.48 4748.27 4792.61
4866.61 5266.00 5680.16
...

This reports the set of closed reciprocal lattice (RL) shells defined internally that contain G-vectors with the same modulus.
The highest number of RL vectors we can use is 8029. Yambo will always redefine any input variable in RL units to the nearest closed shell.

Up to Yambo version 4.5
[02.05] Energies [ev] & Occupations
===================================
Fermi Level [ev]: 5.112805
VBM / CBm [ev]: 0.000000 3.876293
Electronic Temp. [ev K]: 0.00 0.00
Bosonic Temp. [ev K]: 0.00 0.00
El. density [cm-3]: 0.460E+24
States summary : Full Metallic Empty
0001-0008 0009-0100
Indirect Gaps [ev]: 3.876293 7.278081
Direct Gaps [ev]: 4.28829 11.35409
X BZ K-points : 72

From Yambo version 5.0
[02.05] Energies & Occupations
==============================

[X] === General ===
[X] Electronic Temperature : 0.000000 0.000000 [eV K]
[X] Bosonic Temperature : 0.000000 0.000000 [eV K]
[X] Finite Temperature mode : no
[X] El. density : 0.46037E+24 [cm-3]
[X] Fermi Level : 5.110835 [eV]

[X] === Gaps and Widths ===
[X] Conduction Band Min : 3.877976 [eV]
[X] Valence Band Max : 0.000000 [eV]
[X] Filled Bands : 8
[X] Empty Bands : 9 100
[X] Direct Gap : 4.289853 [eV]
[X] Direct Gap localized at k-point : 7
[X] Indirect Gap : 3.877976 [eV]
[X] Indirect Gap between k-points : 14 7
[X] Last valence band width : 3.401086 [eV]
[X] 1st conduction band width : 4.266292 [eV]

Yambo recalculates again the Fermi level (close to the value of 5.06 noted in the PWscf SCF calculation). From here on, however, the Fermi level is set to zero, and other eigenvalues are shifted accordingly. The system is insulating (8 filled, 92 empty) with an indirect band gap of 3.87 eV. The minimum and maximum direct and indirect gaps are indicated. There are 72 k-points in the full BZ, generated using symmetry from the 14 k-points in our user-defined grid.

'''TIP''': You should inspect the report file after ''every'' run for errors and warnings.

===Different ways of running yambo===
We just run Yambo interactively.

Let's try to re-run the setup with the command
$ nohup yambo &
$ ls
l_setup nohup.out r_setup r_setup_01 SAVE

If Yambo is launched using a script, or as a background process, or in parallel, this output will appear in a log file prefixed by the letter ''l'', in this case as ''l_setup''.
If this log file already exists from a previous run, it will not be overwritten. Instead, a new file will be created with an incrementing numerical label, e.g. ''l_setup_01, l_setup_02'', etc. '''This applies to all files created by Yambo'''. Here we see that l_setup was created for the first time, but r_setup already existed from the previous run, so now we have r_setup_01
If you check the differences between the two you will notice that in the second run yambo is reading the previously created ndb.kindx in place of re-computing the indexes.
Indeed the output inside l_setup does not show the timing for X and Sigma

As a last step we run the setup in parallel, but first we delete the ndb.kindx file
$ rm SAVE/ndb.kindx
$ mpirun -np 4 yambo
$ ls
LOG l_setup nohup.out r_setup r_setup_01 r_setup_02 SAVE
There is now r_setup_02
In the case of parallel runs, CPU-dependent log files will appear inside a ''LOG'' folder, e.g.
$ ls LOG
l_setup_CPU_1 l_setup_CPU_2 l_setup_CPU_3 l_setup_CPU_4
This behaviour can be controlled at runtime - see the Parallel tutorial for details.

===2D hBN===
Simply repeat the steps above. Go to the folder ''containing'' the hBN-sheet ''SAVE'' directory and launch <code>yambo</code>:
$ cd TUTORIALS/hBN-2D/YAMBO
$ ls
SAVE
$ yambo
Again, inspect the ''r_setup'' file, output logs, and verify that ''ndb.gops'' and ''ndb.kpts'' have been created inside the SAVE folder.

You are now ready to use Yambo!

==Yambo's command line interface==
Yambo uses a command line interface to select tasks, generate input files, and control the runtime behaviour.

In this module you will learn how to select tasks, generate and modify input files, and control the runtime behaviour by using Yambo's command line interface.


=== Input file generator ===
First, move to the appropriate folder and initialize the Yambo databases if you haven't already done so.
$ cd YAMBO_TUTORIALS/hBN/YAMBO
$ yambo ''(initialize)''

Yambo generates its own input files: you just tell the code what you want to calculate by launching Yambo along with one or more options.
To see the list of possible options, run <code>yambo -h</code> (we report here only the part we are focusing in)
$ yambo -h
'A shiny pot of fun and happiness [C.D.Hogan]'

This is : yambo
Version : 5.0.1 Revision 19547 Hash e90d90f2d
Configuration: MPI+OpenMP+SLK+SLEPC+HDF5_MPI_IO

...

Initializations:
-setup (-i) :Initialization
-coulomb (-r) :Coulomb potential

Response Functions:
-optics (-o) <string> :Linear Response optical properties (more with -h optics)
-X (-d) <string> :Inverse Dielectric Matrix (more with -h X)
-dipoles (-q) :Oscillator strenghts (or dipoles)
-kernel (-k) <string> :Kernel (more with -h kernel)

Self-Energy:
-hf (-x) :Hartree-Fock
-gw0 (-p) <string> :GW approximation (more with -h gw0)
-dyson (-g) <string> :Dyson Equation solver (more with -h dyson)
-lifetimes (-l) :GoWo Quasiparticle lifetimes

Bethe-Salpeter Equation:
-Ksolver (-y) <string> :BSE solver (more with -h Ksolver)

Total Energy:
-acfdt :ACFDT Total Energy

Utilites:
...
-slktest :ScaLapacK test

The options can be split into two sets: 
* A set of options which is needed to generate the appropriate input file (default name: ''yambo.in'') selecting the kind of simulation you would like to perform 
* A set of options which can be used to manage auxiliary functions (like redirect the I/O, choose a specific name for the input file, etc ..).

===Runlevel selection===
First of all, you would like to specify which kind of simulation you are going to perform and generate an input file with the first set of options.
By default, when generating the input file, Yambo will launch the <code>vi</code> editor.
Editor choice can be changed when launching the configure before compilation; alternatively you can use the <code>-Q</code> run time option to skip the automatic editing (do this if you are not familiar with <code>vi</code>!):
$ yambo -hf -Q
yambo: input file yambo.in created
$ emacs yambo.in ''or your favourite editing tool''

Multiple options can be used together to activate various tasks or runlevels (in some cases this is actually a necessity).
For instance, to generate an input file for optical spectra including local field effects (Hartree approximation), do (and then exit)
$ yambo -optics c -kernel hartree ''which switches on:''
optics # [R OPT] Optics
chi # [R CHI] Dyson equation for Chi.
Chimod= "Hartree" # [X] IP/Hartree/ALDA/LRC/BSfxc
To perform a Hartree-Fock and GW calculation using a plasmon-pole approximation, do (and then exit):
$ yambo -hf -gw0 p -dyson n ''which switches on:''
HF_and_locXC # [R XX] Hartree-Fock Self-energy and Vxc
gw0 # [R GW] GoWo Quasiparticle energy levels
ppa # [R Xp] Plasmon Pole Approximation
em1d # [R Xd] Dynamical Inverse Dielectric Matrix
Each runlevel activates its own list of variables and flags.

The previous command is also equivalent to
$ yambo -hf -gw0 r -dyson n -X p

===Changing input parameters ===
Yambo reads various parameters from existing database files and/or input files and uses them to suggest values or ranges.
Let's illustrate this by generating the input file for a Hartree-Fock calculation.

$ yambo -hf
Inside the generated input file you should find:
[[Variables#EXXRLvcs|EXXRLvcs]] = 3187 RL # [XX] Exchange RL components
%[[Variables#QPkrange|QPkrange]] # [GW] QP generalized Kpoint/Band indices
1| 14| 1|100|
%
The <code>[[Variables#QPkrange|QPkrange]]</code> variable (follow the link for a "detailed" explanation for any variable) suggests a range of k-points (1 to 14) and bands (1 to 100) based on what it finds in the core database ''SAVE/ns.db1'', i.e. as defined by the DFT code. 
Leave that variable alone, and instead modify the previous variable to <code>EXXRLvcs= 1000 RL</code>

Save the file, and now generate the input a second time with <code>yambo -x</code>. You will see:
[[Variables#EXXRLvcs|EXXRLvcs]]= 1009 RL
This indicates that Yambo has read the new input value (1000 G-vectors), checked the database of G-vector shells ''(SAVE/ndb.gops)'',
and changed the input value to one that fits a completely closed shell.

Last, note that Yambo variables can be expressed in different '''units'''. In this case, <code>RL</code> can be replaced by an energy unit like Ry, eV, Ha, etc. Energy units are generally better as they are independent of the cell size. Technical information is available on the [[Variables]] page.

The input file generator of Yambo is thus an ''intelligent'' parser, which interacts with the user and the existing databases. For this reason we recommend that you always use Yambo to generate the input files, rather than making them yourself.

===Extra options===
Extra options modify some of the code's default settings. They can be used when launching the code but also when generating input files.

Let's have a look again to the possible options (we report here only the part we are focusing in):
$ yambo -h
This is : yambo
Version : 5.0.1 Revision 19547 Hash e90d90f2d
Configuration: MPI+OpenMP+SLK+SLEPC+HDF5_MPI_IO

Help & version:
-help (-h) <string> :<string> can be an option (e.g. -h optics)
-version :Code version & libraries

Input file & Directories:
-Input (-F) <string> :Input file
-Verbosity (-V) <string> :Input file variables verbosity (more with -h Verbosity)
-Job (-J) <string> :Job string
-Idir (-I) <string> :Input directory
-Odir (-O) <string> :I/O directory
-Cdir (-C) <string> :Communication directory

Parallel Control:
-parenv (-E) <string> :Environment Parallel Variables file
-nompi :Switch off MPI support
-noopenmp :Switch off OPENMP support

...

Utilites:
-Quiet (-Q) :Quiet input file creation
-fatlog :Verbose (fatter) log(s)
-DBlist (-D) :Databases properties
...

Command line options are extremely important to master if you want to use yambo productively.
Often, the meaning is clear from the help menu:
$ yambo -F yambo.in_HF -hf ''Make a Hartree-Fock input file called yambo.in_HF''
$ yambo -D ''Summarize the content of the databases in the SAVE folder''
$ yambo -I ../ ''Run the code, using a SAVE folder in a directory one level up''
$ yambo -C MyTest ''Run the code, putting all report, log, plot files inside a folder MyTest''

Other options deserve a closer look.

===Verbosity===
Yambo uses ''many'' input variables, many of which can be left at their default values. To keep input files short and manageable, only a few variables appear by default in the inout file. More advanced variables can be switched on by using the <code>-V</code> verbosity option. These are grouped according to the type of variable. For instance, <code>-V RL</code> switches on variables related to G vector summations, and <code>-V io</code> switches on options related to I/O control. Try:

$ yambo -optics c -V RL ''switches on:''
FFTGvecs= 3951 RL # [FFT] Plane-waves

$ yambo -optics c -V io ''switches on:''
StdoHash= 40 # [IO] Live-timing Hashes
DBsIOoff= "none" # [IO] Space-separated list of DB with NO I/O. DB= ...
DBsFRAGpm= "none" # [IO] Space-separated list of +DB to be FRAG and ...
#WFbuffIO # [IO] Wave-functions buffered I/O

Unfortunately, -V options must be invoked and changed ''one at a time''. When you are more expert, you may go straight to <code>-V all</code>, which turns on all possible variables. However note that <code>yambo -o c -V all</code> adds an extra 30 variables to the input file, which can be confusing: use it with care.

===Job script label===
The best way to keep track of different runs using different parameters is through the <code>-J</code> flag. This inserts a label in all output and report files, and creates a new folder containing any new databases (i.e. they are not written in the core ''SAVE'' folder). Try:
$ yambo -J 1Ry -V RL -hf -F yambo_hf.in ''and modify to''
FFTGvecs = 1 Ry
EXXGvecs = 1 Ry
$ yambo -J 1Ry -F yambo_hf.in ''Run the code''
$ ls
yambo_hf.in SAVE
o-1Ry.hf r-1Ry_HF_and_locXC 1Ry 1Ry/ndb.HF_and_locXC
This is extremely useful when running convergence tests, trying out different parameters, etc.

''Exercise'': use <code>yambo</code> to report the properties of all database files (including ''ndb.HF_and_locXC'')

First steps: walk through from DFT(standalone)

2021-04-06T08:00:08Z

Maurizia: /* Download the Files */

In this tutorial you will learn how to calculate optical spectra using Yambo, starting from a DFT calculation and ending with a look at local field effects in the optical response.

== System characteristics ==
We will use a 3D system (bulk hBN) and a 2D system (hBN sheet).

[[File:HBN-bulk-3x3-annotated.png|x200px|Atomic structure of bulk hBN]]
[[File:HBN2.png|x200px|Atomic structure of 2D hBN]]

'''Hexagonal boron nitride - hBN''':
* HCP lattice, ABAB stacking
* Four atoms per cell, B and N (16 electrons)
* Lattice constants: ''a'' = 4.716 [a.u.], ''c/a'' = 2.582
* Plane wave cutoff 40 Ry (~1500 RL vectors in wavefunctions)
* SCF run: shifted ''6x6x2'' grid (12 k-points) with 8 bands
* Non-SCF run: gamma-centred ''6x6x2'' (14 k-points) grid with 100 bands

=== Prerequisites ===
'''You will need''':
* PWSCF input files and pseudopotentials for hBN bulk
* <code>pw.x</code> executable, version 5.0 or later
* <code>p2y</code> and <code>yambo</code> executables
* <code>gnuplot</code> for plotting spectra

==Download the Files==

Download and unpack the followint files:
[http://www.yambo-code.org/educational/tutorials/files/hBN.tar.gz hBN.tar.gz] [15 MB],
[http://www.yambo-code.org/educational/tutorials/files/hBN-2D.tar.gz hBN-2D.tar.gz] [8,6 MB]

In the next days you will also use this file which you may like to download now
[http://www.yambo-code.org/educational/tutorials/files/hBN-convergence-kpoints.tar.gz hBN-convergence-kpoints.tar.gz] [254 MB]

After downloading the tar.gz files just unpack them in the '''YAMBO_TUTORIALS''' folder. For example
$ mkdir YAMBO_TUTORIALS
$ mv hBN.tar.gz YAMBO_TUTORIALS
$ cd YAMBO_TUTORIALS
$ tar -xvfz hBN.tar.gz
$ ls YAMBO_TUTORIALS
hBN
$ cd hBN
$ ls
$ PWSCF YAMBO

(Advanced users can download and install all tutorial files using git. See the main [[Tutorials#Files|Tutorial Files]] page.)

Now you can go directly in '''YAMBO''' directory where you can find the '''SAVE''' directory needed to start the yambo tutorials for hBN or do the DFT scf and nscf simulations entering in '''PWSCF''' directory and learn how to create the '''SAVE''' starting from files produced by pw.x (see below)

==DFT calculation of bulk hBN and conversion to Yambo==

In this module you will learn how to generate the Yambo ''SAVE'' folder for bulk hBN starting from a PWscf calculation.



=== Conversion to Yambo format ===
The PWscf ''bBN.save'' output is converted to the Yambo format using the <code>p2y</code> executable (pwscf to yambo), found in the yambo ''bin'' directory.
Enter ''hBN.save'' and launch <code>p2y</code>:

$ cd hBN.save
$ p2y
...
<---> DBs path set to .
<---> Index file set to data-file.xml
<---> Header/K-points/Energies... done
...
<---> == DB1 (Gvecs and more) ...
<---> ... Database done
<---> == DB2 (wavefunctions) ... done ==
<---> == DB3 (PseudoPotential) ... done ==
<---> == P2Y completed ==

This output repeats some information about the system and generates a ''SAVE'' directory:
$ ls SAVE
ns.db1 ns.wf ns.kb_pp_pwscf
ns.wf_fragments_1_1 ...
ns.kb_pp_pwscf_fragment_1 ...
These files, with an ''n'' prefix, indicate that they are in netCDF format, and thus not human readable. However, they are perfectly transferable across different architectures. You can check that the databases contain the information you expect by launching Yambo using the <code>-D</code> option:

$ yambo -D
[RD./SAVE//ns.db1]------------------------------------------
Bands : 100
K-points : 14
G-vectors [RL space]: 8029
Components [wavefunctions]: 1016
...
[RD./SAVE//ns.wf]-------------------------------------------
Fragmentation :yes
...
[RD./SAVE//ns.kb_pp_pwscf]----------------------------------
Fragmentation :yes
- S/N 006626 -------------------------- v.04.01.02 r.00000 -

In practice we suggest to move the ''SAVE'' folder into a new clean folder.

In this tutorial however, we ask instead that you continue using a ''SAVE'' folder that we prepared previously:
$ cd ../../YAMBO
$ ls
SAVE

==Initialization of Yambo databases==
Use the ''SAVE'' folders that are already provided, rather than any ones you may have generated previously.

Every Yambo run '''must''' start with this step. Go to the folder ''containing'' the hBN-bulk <code>SAVE</code> directory:
$ cd YAMBO_TUTORIALS/hBN/YAMBO
$ ls
SAVE

'''TIP''': do not run yambo from ''inside'' the <code>SAVE</code> folder!
'''This is the wrong way .. '''
$ cd SAVE
$ yambo
yambo: cannot access CORE database (SAVE/*db1 and/or SAVE/*wf)
In fact, if you ever see such message:
it usually means you are trying to launch Yambo '''from the wrong place'''.
$ cd ..

Now you are in the proper place and
$ ls
SAVE
you can simply launch the code
$ yambo
This will run the initialization (setup) ''runlevel''.

===Run-time output===
This is typically written to standard output (on screen) and tracks the progress of the run in real time:
<---> [01] MPI/OPENMP structure, Files & I/O Directories
<---> [02] CORE Variables Setup
<---> [02.01] Unit cells
<---> [02.02] Symmetries
<---> [02.03] Reciprocal space
<---> Shells finder |########################################| [100%] --(E) --(X)
<---> [02.04] K-grid lattice
<---> Grid dimensions : 6 6 2
<---> [02.05] Energies & Occupations
<---> [03] Transferred momenta grid and indexing
<---> BZ -> IBZ reduction |########################################| [100%] --(E) --(X)
<---> [03.01] X indexes
<---> X [eval] |########################################| [100%] --(E) --(X)
<---> X[REDUX] |########################################| [100%] --(E) --(X)
<---> [03.01.01] Sigma indexes
<---> Sigma [eval] |########################################| [100%] --(E) --(X)
<---> Sigma[REDUX] |########################################| [100%] --(E) --(X)
<---> [04] Timing Overview
<---> [05] Memory Overview
<---> [06] Game Over & Game summary
Specific runlevels are indicated with numeric labels like [02.02]. 
The hashes (#) indicate progress of the run in Wall Clock time, indicating the elapsed (E) and expected (X) time to complete a runlevel, and the percentage of the task complete.

===New core databases===
New databases appear in the ''SAVE'' folder:
$ ls SAVE
ns.db1 ns.wf ns.kb_pp_pwscf '''ndb.gops ndb.kindx'''
ns.wf_fragments_1_1 ...
ns.kb_pp_pwscf_fragment_1 ...
These contain information about the ''G''-vector shells and ''k/q''-point meshes as defined by the DFT calculation.

In general: a database called ''n'''s'''.xxx'' is a ''static'' database, generated once by <code>p2y</code>, while databases called ''n'''db'''.xxx'' are ''dynamically'' generated while you use <code>yambo</code>.

'''TIP''': if you launch <code>yambo</code>, but it does not seem to do anything, check that these files are present.

===Report file===
A report file ''r_setup'' is generated in the run directory.
This mostly reports information about the ground state system as defined by the DFT run, but also adds information about the band gaps, occupations, shells of G-vectors, IBZ/BZ grids, the CPU structure (for parallel runs), and so on. Some points of note:

Up to Yambo version 4.5
[02.03] RL shells
=================
Shells, format: [S#] G_RL(mHa)
[S453]:8029(0.7982E+5) [S452]:8005(0.7982E+5) [S451]:7981(0.7982E+5) [S450]:7957(0.7942E+5)
...
[S4]:11( 1183.) [S3]:5( 532.5123) [S2]:3( 133.1281) [S1]:1( 0.000000)

From Yambo version 5.0
[02.03] Reciprocal space
========================

nG shells : 217
nG charge : 3187
nG WFs : 1477
nC WFs : 1016
G-vecs. in first 21 shells: [ Number ]
1 3 5 11 13 25 37 39 51
63 65 71 83 95 107 113 125 127
139 151 163
...
Shell energy in first 21 shells: [ mHa ]
0.00000 133.128 532.512 1183.37 1198.15 1316.50 1715.88 2130.05 2381.52
3313.42 3328.20 3550.11 3683.24 4082.62 4511.57 4733.48 4748.27 4792.61
4866.61 5266.00 5680.16
...

This reports the set of closed reciprocal lattice (RL) shells defined internally that contain G-vectors with the same modulus.
The highest number of RL vectors we can use is 8029. Yambo will always redefine any input variable in RL units to the nearest closed shell.

Up to Yambo version 4.5
[02.05] Energies [ev] & Occupations
===================================
Fermi Level [ev]: 5.112805
VBM / CBm [ev]: 0.000000 3.876293
Electronic Temp. [ev K]: 0.00 0.00
Bosonic Temp. [ev K]: 0.00 0.00
El. density [cm-3]: 0.460E+24
States summary : Full Metallic Empty
0001-0008 0009-0100
Indirect Gaps [ev]: 3.876293 7.278081
Direct Gaps [ev]: 4.28829 11.35409
X BZ K-points : 72

From Yambo version 5.0
[02.05] Energies & Occupations
==============================

[X] === General ===
[X] Electronic Temperature : 0.000000 0.000000 [eV K]
[X] Bosonic Temperature : 0.000000 0.000000 [eV K]
[X] Finite Temperature mode : no
[X] El. density : 0.46037E+24 [cm-3]
[X] Fermi Level : 5.110835 [eV]

[X] === Gaps and Widths ===
[X] Conduction Band Min : 3.877976 [eV]
[X] Valence Band Max : 0.000000 [eV]
[X] Filled Bands : 8
[X] Empty Bands : 9 100
[X] Direct Gap : 4.289853 [eV]
[X] Direct Gap localized at k-point : 7
[X] Indirect Gap : 3.877976 [eV]
[X] Indirect Gap between k-points : 14 7
[X] Last valence band width : 3.401086 [eV]
[X] 1st conduction band width : 4.266292 [eV]

Yambo recalculates again the Fermi level (close to the value of 5.06 noted in the PWscf SCF calculation). From here on, however, the Fermi level is set to zero, and other eigenvalues are shifted accordingly. The system is insulating (8 filled, 92 empty) with an indirect band gap of 3.87 eV. The minimum and maximum direct and indirect gaps are indicated. There are 72 k-points in the full BZ, generated using symmetry from the 14 k-points in our user-defined grid.

'''TIP''': You should inspect the report file after ''every'' run for errors and warnings.

===Different ways of running yambo===
We just run Yambo interactively.

Let's try to re-run the setup with the command
$ nohup yambo &
$ ls
l_setup nohup.out r_setup r_setup_01 SAVE

If Yambo is launched using a script, or as a background process, or in parallel, this output will appear in a log file prefixed by the letter ''l'', in this case as ''l_setup''.
If this log file already exists from a previous run, it will not be overwritten. Instead, a new file will be created with an incrementing numerical label, e.g. ''l_setup_01, l_setup_02'', etc. '''This applies to all files created by Yambo'''. Here we see that l_setup was created for the first time, but r_setup already existed from the previous run, so now we have r_setup_01
If you check the differences between the two you will notice that in the second run yambo is reading the previously created ndb.kindx in place of re-computing the indexes.
Indeed the output inside l_setup does not show the timing for X and Sigma

As a last step we run the setup in parallel, but first we delete the ndb.kindx file
$ rm SAVE/ndb.kindx
$ mpirun -np 4 yambo
$ ls
LOG l_setup nohup.out r_setup r_setup_01 r_setup_02 SAVE
There is now r_setup_02
In the case of parallel runs, CPU-dependent log files will appear inside a ''LOG'' folder, e.g.
$ ls LOG
l_setup_CPU_1 l_setup_CPU_2 l_setup_CPU_3 l_setup_CPU_4
This behaviour can be controlled at runtime - see the Parallel tutorial for details.

===2D hBN===
Simply repeat the steps above. Go to the folder ''containing'' the hBN-sheet ''SAVE'' directory and launch <code>yambo</code>:
$ cd TUTORIALS/hBN-2D/YAMBO
$ ls
SAVE
$ yambo
Again, inspect the ''r_setup'' file, output logs, and verify that ''ndb.gops'' and ''ndb.kpts'' have been created inside the SAVE folder.

You are now ready to use Yambo!

==Yambo's command line interface==
Yambo uses a command line interface to select tasks, generate input files, and control the runtime behaviour.

In this module you will learn how to select tasks, generate and modify input files, and control the runtime behaviour by using Yambo's command line interface.


=== Input file generator ===
First, move to the appropriate folder and initialize the Yambo databases if you haven't already done so.
$ cd YAMBO_TUTORIALS/hBN/YAMBO
$ yambo ''(initialize)''

Yambo generates its own input files: you just tell the code what you want to calculate by launching Yambo along with one or more options.
To see the list of possible options, run <code>yambo -h</code> (we report here only the part we are focusing in)
$ yambo -h
'A shiny pot of fun and happiness [C.D.Hogan]'

This is : yambo
Version : 5.0.1 Revision 19547 Hash e90d90f2d
Configuration: MPI+OpenMP+SLK+SLEPC+HDF5_MPI_IO

...

Initializations:
-setup (-i) :Initialization
-coulomb (-r) :Coulomb potential

Response Functions:
-optics (-o) <string> :Linear Response optical properties (more with -h optics)
-X (-d) <string> :Inverse Dielectric Matrix (more with -h X)
-dipoles (-q) :Oscillator strenghts (or dipoles)
-kernel (-k) <string> :Kernel (more with -h kernel)

Self-Energy:
-hf (-x) :Hartree-Fock
-gw0 (-p) <string> :GW approximation (more with -h gw0)
-dyson (-g) <string> :Dyson Equation solver (more with -h dyson)
-lifetimes (-l) :GoWo Quasiparticle lifetimes

Bethe-Salpeter Equation:
-Ksolver (-y) <string> :BSE solver (more with -h Ksolver)

Total Energy:
-acfdt :ACFDT Total Energy

Utilites:
...
-slktest :ScaLapacK test

The options can be split into two sets: 
* A set of options which is needed to generate the appropriate input file (default name: ''yambo.in'') selecting the kind of simulation you would like to perform 
* A set of options which can be used to manage auxiliary functions (like redirect the I/O, choose a specific name for the input file, etc ..).

===Runlevel selection===
First of all, you would like to specify which kind of simulation you are going to perform and generate an input file with the first set of options.
By default, when generating the input file, Yambo will launch the <code>vi</code> editor.
Editor choice can be changed when launching the configure before compilation; alternatively you can use the <code>-Q</code> run time option to skip the automatic editing (do this if you are not familiar with <code>vi</code>!):
$ yambo -hf -Q
yambo: input file yambo.in created
$ emacs yambo.in ''or your favourite editing tool''

Multiple options can be used together to activate various tasks or runlevels (in some cases this is actually a necessity).
For instance, to generate an input file for optical spectra including local field effects (Hartree approximation), do (and then exit)
$ yambo -optics c -kernel hartree ''which switches on:''
optics # [R OPT] Optics
chi # [R CHI] Dyson equation for Chi.
Chimod= "Hartree" # [X] IP/Hartree/ALDA/LRC/BSfxc
To perform a Hartree-Fock and GW calculation using a plasmon-pole approximation, do (and then exit):
$ yambo -hf -gw0 p -dyson n ''which switches on:''
HF_and_locXC # [R XX] Hartree-Fock Self-energy and Vxc
gw0 # [R GW] GoWo Quasiparticle energy levels
ppa # [R Xp] Plasmon Pole Approximation
em1d # [R Xd] Dynamical Inverse Dielectric Matrix
Each runlevel activates its own list of variables and flags.

The previous command is also equivalent to
$ yambo -hf -gw0 r -dyson n -X p

===Changing input parameters ===
Yambo reads various parameters from existing database files and/or input files and uses them to suggest values or ranges.
Let's illustrate this by generating the input file for a Hartree-Fock calculation.

$ yambo -hf
Inside the generated input file you should find:
[[Variables#EXXRLvcs|EXXRLvcs]] = 3187 RL # [XX] Exchange RL components
%[[Variables#QPkrange|QPkrange]] # [GW] QP generalized Kpoint/Band indices
1| 14| 1|100|
%
The <code>[[Variables#QPkrange|QPkrange]]</code> variable (follow the link for a "detailed" explanation for any variable) suggests a range of k-points (1 to 14) and bands (1 to 100) based on what it finds in the core database ''SAVE/ns.db1'', i.e. as defined by the DFT code. 
Leave that variable alone, and instead modify the previous variable to <code>EXXRLvcs= 1000 RL</code>

Save the file, and now generate the input a second time with <code>yambo -x</code>. You will see:
[[Variables#EXXRLvcs|EXXRLvcs]]= 1009 RL
This indicates that Yambo has read the new input value (1000 G-vectors), checked the database of G-vector shells ''(SAVE/ndb.gops)'',
and changed the input value to one that fits a completely closed shell.

Last, note that Yambo variables can be expressed in different '''units'''. In this case, <code>RL</code> can be replaced by an energy unit like Ry, eV, Ha, etc. Energy units are generally better as they are independent of the cell size. Technical information is available on the [[Variables]] page.

The input file generator of Yambo is thus an ''intelligent'' parser, which interacts with the user and the existing databases. For this reason we recommend that you always use Yambo to generate the input files, rather than making them yourself.

===Extra options===
Extra options modify some of the code's default settings. They can be used when launching the code but also when generating input files.

Let's have a look again to the possible options (we report here only the part we are focusing in):
$ yambo -h
This is : yambo
Version : 5.0.1 Revision 19547 Hash e90d90f2d
Configuration: MPI+OpenMP+SLK+SLEPC+HDF5_MPI_IO

Help & version:
-help (-h) <string> :<string> can be an option (e.g. -h optics)
-version :Code version & libraries

Input file & Directories:
-Input (-F) <string> :Input file
-Verbosity (-V) <string> :Input file variables verbosity (more with -h Verbosity)
-Job (-J) <string> :Job string
-Idir (-I) <string> :Input directory
-Odir (-O) <string> :I/O directory
-Cdir (-C) <string> :Communication directory

Parallel Control:
-parenv (-E) <string> :Environment Parallel Variables file
-nompi :Switch off MPI support
-noopenmp :Switch off OPENMP support

...

Utilites:
-Quiet (-Q) :Quiet input file creation
-fatlog :Verbose (fatter) log(s)
-DBlist (-D) :Databases properties
...

Command line options are extremely important to master if you want to use yambo productively.
Often, the meaning is clear from the help menu:
$ yambo -F yambo.in_HF -hf ''Make a Hartree-Fock input file called yambo.in_HF''
$ yambo -D ''Summarize the content of the databases in the SAVE folder''
$ yambo -I ../ ''Run the code, using a SAVE folder in a directory one level up''
$ yambo -C MyTest ''Run the code, putting all report, log, plot files inside a folder MyTest''

Other options deserve a closer look.

===Verbosity===
Yambo uses ''many'' input variables, many of which can be left at their default values. To keep input files short and manageable, only a few variables appear by default in the inout file. More advanced variables can be switched on by using the <code>-V</code> verbosity option. These are grouped according to the type of variable. For instance, <code>-V RL</code> switches on variables related to G vector summations, and <code>-V io</code> switches on options related to I/O control. Try:

$ yambo -optics c -V RL ''switches on:''
FFTGvecs= 3951 RL # [FFT] Plane-waves

$ yambo -optics c -V io ''switches on:''
StdoHash= 40 # [IO] Live-timing Hashes
DBsIOoff= "none" # [IO] Space-separated list of DB with NO I/O. DB= ...
DBsFRAGpm= "none" # [IO] Space-separated list of +DB to be FRAG and ...
#WFbuffIO # [IO] Wave-functions buffered I/O

Unfortunately, -V options must be invoked and changed ''one at a time''. When you are more expert, you may go straight to <code>-V all</code>, which turns on all possible variables. However note that <code>yambo -o c -V all</code> adds an extra 30 variables to the input file, which can be confusing: use it with care.

===Job script label===
The best way to keep track of different runs using different parameters is through the <code>-J</code> flag. This inserts a label in all output and report files, and creates a new folder containing any new databases (i.e. they are not written in the core ''SAVE'' folder). Try:
$ yambo -J 1Ry -V RL -hf -F yambo_hf.in ''and modify to''
FFTGvecs = 1 Ry
EXXGvecs = 1 Ry
$ yambo -J 1Ry -F yambo_hf.in ''Run the code''
$ ls
yambo_hf.in SAVE
o-1Ry.hf r-1Ry_HF_and_locXC 1Ry 1Ry/ndb.HF_and_locXC
This is extremely useful when running convergence tests, trying out different parameters, etc.

''Exercise'': use <code>yambo</code> to report the properties of all database files (including ''ndb.HF_and_locXC'')

First steps: walk through from DFT(standalone)

2021-04-06T07:56:22Z

Maurizia: /* Download the Files */

In this tutorial you will learn how to calculate optical spectra using Yambo, starting from a DFT calculation and ending with a look at local field effects in the optical response.

== System characteristics ==
We will use a 3D system (bulk hBN) and a 2D system (hBN sheet).

[[File:HBN-bulk-3x3-annotated.png|x200px|Atomic structure of bulk hBN]]
[[File:HBN2.png|x200px|Atomic structure of 2D hBN]]

'''Hexagonal boron nitride - hBN''':
* HCP lattice, ABAB stacking
* Four atoms per cell, B and N (16 electrons)
* Lattice constants: ''a'' = 4.716 [a.u.], ''c/a'' = 2.582
* Plane wave cutoff 40 Ry (~1500 RL vectors in wavefunctions)
* SCF run: shifted ''6x6x2'' grid (12 k-points) with 8 bands
* Non-SCF run: gamma-centred ''6x6x2'' (14 k-points) grid with 100 bands

=== Prerequisites ===
'''You will need''':
* PWSCF input files and pseudopotentials for hBN bulk
* <code>pw.x</code> executable, version 5.0 or later
* <code>p2y</code> and <code>yambo</code> executables
* <code>gnuplot</code> for plotting spectra

==Download the Files==

Download and unpack the followint files:
[http://www.yambo-code.org/educational/tutorials/files/hBN.tar.gz hBN.tar.gz] [15 MB],
[http://www.yambo-code.org/educational/tutorials/files/hBN-2D.tar.gz hBN-2D.tar.gz] [8,6 MB]

In the next days you will also use this file which you may like to download now
[http://www.yambo-code.org/educational/tutorials/files/hBN-convergence-kpoints.tar.gz hBN-convergence-kpoints.tar.gz] [254 MB]

After downloading the tar.gz files just unpack them in the '''YAMBO_TUTORIALS''' folder. For example
$ mkdir YAMBO_TUTORIALS
$ mv hBN.tar.gz YAMBO_TUTORIALS
$ cd YAMBO_TUTORIALS
$ tar -xvfz hBN.tar.gz
$ ls YAMBO_TUTORIALS
hBN
$ cd hBN
$ ls
$ PWSCF YAMBO

(Advanced users can download and install all tutorial files using git. See the main [[Tutorials#Files|Tutorial Files]] page.)

==DFT calculation of bulk hBN and conversion to Yambo==

In this module you will learn how to generate the Yambo ''SAVE'' folder for bulk hBN starting from a PWscf calculation.



=== Conversion to Yambo format ===
The PWscf ''bBN.save'' output is converted to the Yambo format using the <code>p2y</code> executable (pwscf to yambo), found in the yambo ''bin'' directory.
Enter ''hBN.save'' and launch <code>p2y</code>:

$ cd hBN.save
$ p2y
...
<---> DBs path set to .
<---> Index file set to data-file.xml
<---> Header/K-points/Energies... done
...
<---> == DB1 (Gvecs and more) ...
<---> ... Database done
<---> == DB2 (wavefunctions) ... done ==
<---> == DB3 (PseudoPotential) ... done ==
<---> == P2Y completed ==

This output repeats some information about the system and generates a ''SAVE'' directory:
$ ls SAVE
ns.db1 ns.wf ns.kb_pp_pwscf
ns.wf_fragments_1_1 ...
ns.kb_pp_pwscf_fragment_1 ...
These files, with an ''n'' prefix, indicate that they are in netCDF format, and thus not human readable. However, they are perfectly transferable across different architectures. You can check that the databases contain the information you expect by launching Yambo using the <code>-D</code> option:

$ yambo -D
[RD./SAVE//ns.db1]------------------------------------------
Bands : 100
K-points : 14
G-vectors [RL space]: 8029
Components [wavefunctions]: 1016
...
[RD./SAVE//ns.wf]-------------------------------------------
Fragmentation :yes
...
[RD./SAVE//ns.kb_pp_pwscf]----------------------------------
Fragmentation :yes
- S/N 006626 -------------------------- v.04.01.02 r.00000 -

In practice we suggest to move the ''SAVE'' folder into a new clean folder.

In this tutorial however, we ask instead that you continue using a ''SAVE'' folder that we prepared previously:
$ cd ../../YAMBO
$ ls
SAVE

==Initialization of Yambo databases==
Use the ''SAVE'' folders that are already provided, rather than any ones you may have generated previously.

Every Yambo run '''must''' start with this step. Go to the folder ''containing'' the hBN-bulk <code>SAVE</code> directory:
$ cd YAMBO_TUTORIALS/hBN/YAMBO
$ ls
SAVE

'''TIP''': do not run yambo from ''inside'' the <code>SAVE</code> folder!
'''This is the wrong way .. '''
$ cd SAVE
$ yambo
yambo: cannot access CORE database (SAVE/*db1 and/or SAVE/*wf)
In fact, if you ever see such message:
it usually means you are trying to launch Yambo '''from the wrong place'''.
$ cd ..

Now you are in the proper place and
$ ls
SAVE
you can simply launch the code
$ yambo
This will run the initialization (setup) ''runlevel''.

===Run-time output===
This is typically written to standard output (on screen) and tracks the progress of the run in real time:
<---> [01] MPI/OPENMP structure, Files & I/O Directories
<---> [02] CORE Variables Setup
<---> [02.01] Unit cells
<---> [02.02] Symmetries
<---> [02.03] Reciprocal space
<---> Shells finder |########################################| [100%] --(E) --(X)
<---> [02.04] K-grid lattice
<---> Grid dimensions : 6 6 2
<---> [02.05] Energies & Occupations
<---> [03] Transferred momenta grid and indexing
<---> BZ -> IBZ reduction |########################################| [100%] --(E) --(X)
<---> [03.01] X indexes
<---> X [eval] |########################################| [100%] --(E) --(X)
<---> X[REDUX] |########################################| [100%] --(E) --(X)
<---> [03.01.01] Sigma indexes
<---> Sigma [eval] |########################################| [100%] --(E) --(X)
<---> Sigma[REDUX] |########################################| [100%] --(E) --(X)
<---> [04] Timing Overview
<---> [05] Memory Overview
<---> [06] Game Over & Game summary
Specific runlevels are indicated with numeric labels like [02.02]. 
The hashes (#) indicate progress of the run in Wall Clock time, indicating the elapsed (E) and expected (X) time to complete a runlevel, and the percentage of the task complete.

===New core databases===
New databases appear in the ''SAVE'' folder:
$ ls SAVE
ns.db1 ns.wf ns.kb_pp_pwscf '''ndb.gops ndb.kindx'''
ns.wf_fragments_1_1 ...
ns.kb_pp_pwscf_fragment_1 ...
These contain information about the ''G''-vector shells and ''k/q''-point meshes as defined by the DFT calculation.

In general: a database called ''n'''s'''.xxx'' is a ''static'' database, generated once by <code>p2y</code>, while databases called ''n'''db'''.xxx'' are ''dynamically'' generated while you use <code>yambo</code>.

'''TIP''': if you launch <code>yambo</code>, but it does not seem to do anything, check that these files are present.

===Report file===
A report file ''r_setup'' is generated in the run directory.
This mostly reports information about the ground state system as defined by the DFT run, but also adds information about the band gaps, occupations, shells of G-vectors, IBZ/BZ grids, the CPU structure (for parallel runs), and so on. Some points of note:

Up to Yambo version 4.5
[02.03] RL shells
=================
Shells, format: [S#] G_RL(mHa)
[S453]:8029(0.7982E+5) [S452]:8005(0.7982E+5) [S451]:7981(0.7982E+5) [S450]:7957(0.7942E+5)
...
[S4]:11( 1183.) [S3]:5( 532.5123) [S2]:3( 133.1281) [S1]:1( 0.000000)

From Yambo version 5.0
[02.03] Reciprocal space
========================

nG shells : 217
nG charge : 3187
nG WFs : 1477
nC WFs : 1016
G-vecs. in first 21 shells: [ Number ]
1 3 5 11 13 25 37 39 51
63 65 71 83 95 107 113 125 127
139 151 163
...
Shell energy in first 21 shells: [ mHa ]
0.00000 133.128 532.512 1183.37 1198.15 1316.50 1715.88 2130.05 2381.52
3313.42 3328.20 3550.11 3683.24 4082.62 4511.57 4733.48 4748.27 4792.61
4866.61 5266.00 5680.16
...

This reports the set of closed reciprocal lattice (RL) shells defined internally that contain G-vectors with the same modulus.
The highest number of RL vectors we can use is 8029. Yambo will always redefine any input variable in RL units to the nearest closed shell.

Up to Yambo version 4.5
[02.05] Energies [ev] & Occupations
===================================
Fermi Level [ev]: 5.112805
VBM / CBm [ev]: 0.000000 3.876293
Electronic Temp. [ev K]: 0.00 0.00
Bosonic Temp. [ev K]: 0.00 0.00
El. density [cm-3]: 0.460E+24
States summary : Full Metallic Empty
0001-0008 0009-0100
Indirect Gaps [ev]: 3.876293 7.278081
Direct Gaps [ev]: 4.28829 11.35409
X BZ K-points : 72

From Yambo version 5.0
[02.05] Energies & Occupations
==============================

[X] === General ===
[X] Electronic Temperature : 0.000000 0.000000 [eV K]
[X] Bosonic Temperature : 0.000000 0.000000 [eV K]
[X] Finite Temperature mode : no
[X] El. density : 0.46037E+24 [cm-3]
[X] Fermi Level : 5.110835 [eV]

[X] === Gaps and Widths ===
[X] Conduction Band Min : 3.877976 [eV]
[X] Valence Band Max : 0.000000 [eV]
[X] Filled Bands : 8
[X] Empty Bands : 9 100
[X] Direct Gap : 4.289853 [eV]
[X] Direct Gap localized at k-point : 7
[X] Indirect Gap : 3.877976 [eV]
[X] Indirect Gap between k-points : 14 7
[X] Last valence band width : 3.401086 [eV]
[X] 1st conduction band width : 4.266292 [eV]

Yambo recalculates again the Fermi level (close to the value of 5.06 noted in the PWscf SCF calculation). From here on, however, the Fermi level is set to zero, and other eigenvalues are shifted accordingly. The system is insulating (8 filled, 92 empty) with an indirect band gap of 3.87 eV. The minimum and maximum direct and indirect gaps are indicated. There are 72 k-points in the full BZ, generated using symmetry from the 14 k-points in our user-defined grid.

'''TIP''': You should inspect the report file after ''every'' run for errors and warnings.

===Different ways of running yambo===
We just run Yambo interactively.

Let's try to re-run the setup with the command
$ nohup yambo &
$ ls
l_setup nohup.out r_setup r_setup_01 SAVE

If Yambo is launched using a script, or as a background process, or in parallel, this output will appear in a log file prefixed by the letter ''l'', in this case as ''l_setup''.
If this log file already exists from a previous run, it will not be overwritten. Instead, a new file will be created with an incrementing numerical label, e.g. ''l_setup_01, l_setup_02'', etc. '''This applies to all files created by Yambo'''. Here we see that l_setup was created for the first time, but r_setup already existed from the previous run, so now we have r_setup_01
If you check the differences between the two you will notice that in the second run yambo is reading the previously created ndb.kindx in place of re-computing the indexes.
Indeed the output inside l_setup does not show the timing for X and Sigma

As a last step we run the setup in parallel, but first we delete the ndb.kindx file
$ rm SAVE/ndb.kindx
$ mpirun -np 4 yambo
$ ls
LOG l_setup nohup.out r_setup r_setup_01 r_setup_02 SAVE
There is now r_setup_02
In the case of parallel runs, CPU-dependent log files will appear inside a ''LOG'' folder, e.g.
$ ls LOG
l_setup_CPU_1 l_setup_CPU_2 l_setup_CPU_3 l_setup_CPU_4
This behaviour can be controlled at runtime - see the Parallel tutorial for details.

===2D hBN===
Simply repeat the steps above. Go to the folder ''containing'' the hBN-sheet ''SAVE'' directory and launch <code>yambo</code>:
$ cd TUTORIALS/hBN-2D/YAMBO
$ ls
SAVE
$ yambo
Again, inspect the ''r_setup'' file, output logs, and verify that ''ndb.gops'' and ''ndb.kpts'' have been created inside the SAVE folder.

You are now ready to use Yambo!

==Yambo's command line interface==
Yambo uses a command line interface to select tasks, generate input files, and control the runtime behaviour.

In this module you will learn how to select tasks, generate and modify input files, and control the runtime behaviour by using Yambo's command line interface.


=== Input file generator ===
First, move to the appropriate folder and initialize the Yambo databases if you haven't already done so.
$ cd YAMBO_TUTORIALS/hBN/YAMBO
$ yambo ''(initialize)''

Yambo generates its own input files: you just tell the code what you want to calculate by launching Yambo along with one or more options.
To see the list of possible options, run <code>yambo -h</code> (we report here only the part we are focusing in)
$ yambo -h
'A shiny pot of fun and happiness [C.D.Hogan]'

This is : yambo
Version : 5.0.1 Revision 19547 Hash e90d90f2d
Configuration: MPI+OpenMP+SLK+SLEPC+HDF5_MPI_IO

...

Initializations:
-setup (-i) :Initialization
-coulomb (-r) :Coulomb potential

Response Functions:
-optics (-o) <string> :Linear Response optical properties (more with -h optics)
-X (-d) <string> :Inverse Dielectric Matrix (more with -h X)
-dipoles (-q) :Oscillator strenghts (or dipoles)
-kernel (-k) <string> :Kernel (more with -h kernel)

Self-Energy:
-hf (-x) :Hartree-Fock
-gw0 (-p) <string> :GW approximation (more with -h gw0)
-dyson (-g) <string> :Dyson Equation solver (more with -h dyson)
-lifetimes (-l) :GoWo Quasiparticle lifetimes

Bethe-Salpeter Equation:
-Ksolver (-y) <string> :BSE solver (more with -h Ksolver)

Total Energy:
-acfdt :ACFDT Total Energy

Utilites:
...
-slktest :ScaLapacK test

The options can be split into two sets: 
* A set of options which is needed to generate the appropriate input file (default name: ''yambo.in'') selecting the kind of simulation you would like to perform 
* A set of options which can be used to manage auxiliary functions (like redirect the I/O, choose a specific name for the input file, etc ..).

===Runlevel selection===
First of all, you would like to specify which kind of simulation you are going to perform and generate an input file with the first set of options.
By default, when generating the input file, Yambo will launch the <code>vi</code> editor.
Editor choice can be changed when launching the configure before compilation; alternatively you can use the <code>-Q</code> run time option to skip the automatic editing (do this if you are not familiar with <code>vi</code>!):
$ yambo -hf -Q
yambo: input file yambo.in created
$ emacs yambo.in ''or your favourite editing tool''

Multiple options can be used together to activate various tasks or runlevels (in some cases this is actually a necessity).
For instance, to generate an input file for optical spectra including local field effects (Hartree approximation), do (and then exit)
$ yambo -optics c -kernel hartree ''which switches on:''
optics # [R OPT] Optics
chi # [R CHI] Dyson equation for Chi.
Chimod= "Hartree" # [X] IP/Hartree/ALDA/LRC/BSfxc
To perform a Hartree-Fock and GW calculation using a plasmon-pole approximation, do (and then exit):
$ yambo -hf -gw0 p -dyson n ''which switches on:''
HF_and_locXC # [R XX] Hartree-Fock Self-energy and Vxc
gw0 # [R GW] GoWo Quasiparticle energy levels
ppa # [R Xp] Plasmon Pole Approximation
em1d # [R Xd] Dynamical Inverse Dielectric Matrix
Each runlevel activates its own list of variables and flags.

The previous command is also equivalent to
$ yambo -hf -gw0 r -dyson n -X p

===Changing input parameters ===
Yambo reads various parameters from existing database files and/or input files and uses them to suggest values or ranges.
Let's illustrate this by generating the input file for a Hartree-Fock calculation.

$ yambo -hf
Inside the generated input file you should find:
[[Variables#EXXRLvcs|EXXRLvcs]] = 3187 RL # [XX] Exchange RL components
%[[Variables#QPkrange|QPkrange]] # [GW] QP generalized Kpoint/Band indices
1| 14| 1|100|
%
The <code>[[Variables#QPkrange|QPkrange]]</code> variable (follow the link for a "detailed" explanation for any variable) suggests a range of k-points (1 to 14) and bands (1 to 100) based on what it finds in the core database ''SAVE/ns.db1'', i.e. as defined by the DFT code. 
Leave that variable alone, and instead modify the previous variable to <code>EXXRLvcs= 1000 RL</code>

Save the file, and now generate the input a second time with <code>yambo -x</code>. You will see:
[[Variables#EXXRLvcs|EXXRLvcs]]= 1009 RL
This indicates that Yambo has read the new input value (1000 G-vectors), checked the database of G-vector shells ''(SAVE/ndb.gops)'',
and changed the input value to one that fits a completely closed shell.

Last, note that Yambo variables can be expressed in different '''units'''. In this case, <code>RL</code> can be replaced by an energy unit like Ry, eV, Ha, etc. Energy units are generally better as they are independent of the cell size. Technical information is available on the [[Variables]] page.

The input file generator of Yambo is thus an ''intelligent'' parser, which interacts with the user and the existing databases. For this reason we recommend that you always use Yambo to generate the input files, rather than making them yourself.

===Extra options===
Extra options modify some of the code's default settings. They can be used when launching the code but also when generating input files.

Let's have a look again to the possible options (we report here only the part we are focusing in):
$ yambo -h
This is : yambo
Version : 5.0.1 Revision 19547 Hash e90d90f2d
Configuration: MPI+OpenMP+SLK+SLEPC+HDF5_MPI_IO

Help & version:
-help (-h) <string> :<string> can be an option (e.g. -h optics)
-version :Code version & libraries

Input file & Directories:
-Input (-F) <string> :Input file
-Verbosity (-V) <string> :Input file variables verbosity (more with -h Verbosity)
-Job (-J) <string> :Job string
-Idir (-I) <string> :Input directory
-Odir (-O) <string> :I/O directory
-Cdir (-C) <string> :Communication directory

Parallel Control:
-parenv (-E) <string> :Environment Parallel Variables file
-nompi :Switch off MPI support
-noopenmp :Switch off OPENMP support

...

Utilites:
-Quiet (-Q) :Quiet input file creation
-fatlog :Verbose (fatter) log(s)
-DBlist (-D) :Databases properties
...

Command line options are extremely important to master if you want to use yambo productively.
Often, the meaning is clear from the help menu:
$ yambo -F yambo.in_HF -hf ''Make a Hartree-Fock input file called yambo.in_HF''
$ yambo -D ''Summarize the content of the databases in the SAVE folder''
$ yambo -I ../ ''Run the code, using a SAVE folder in a directory one level up''
$ yambo -C MyTest ''Run the code, putting all report, log, plot files inside a folder MyTest''

Other options deserve a closer look.

===Verbosity===
Yambo uses ''many'' input variables, many of which can be left at their default values. To keep input files short and manageable, only a few variables appear by default in the inout file. More advanced variables can be switched on by using the <code>-V</code> verbosity option. These are grouped according to the type of variable. For instance, <code>-V RL</code> switches on variables related to G vector summations, and <code>-V io</code> switches on options related to I/O control. Try:

$ yambo -optics c -V RL ''switches on:''
FFTGvecs= 3951 RL # [FFT] Plane-waves

$ yambo -optics c -V io ''switches on:''
StdoHash= 40 # [IO] Live-timing Hashes
DBsIOoff= "none" # [IO] Space-separated list of DB with NO I/O. DB= ...
DBsFRAGpm= "none" # [IO] Space-separated list of +DB to be FRAG and ...
#WFbuffIO # [IO] Wave-functions buffered I/O

Unfortunately, -V options must be invoked and changed ''one at a time''. When you are more expert, you may go straight to <code>-V all</code>, which turns on all possible variables. However note that <code>yambo -o c -V all</code> adds an extra 30 variables to the input file, which can be confusing: use it with care.

===Job script label===
The best way to keep track of different runs using different parameters is through the <code>-J</code> flag. This inserts a label in all output and report files, and creates a new folder containing any new databases (i.e. they are not written in the core ''SAVE'' folder). Try:
$ yambo -J 1Ry -V RL -hf -F yambo_hf.in ''and modify to''
FFTGvecs = 1 Ry
EXXGvecs = 1 Ry
$ yambo -J 1Ry -F yambo_hf.in ''Run the code''
$ ls
yambo_hf.in SAVE
o-1Ry.hf r-1Ry_HF_and_locXC 1Ry 1Ry/ndb.HF_and_locXC
This is extremely useful when running convergence tests, trying out different parameters, etc.

''Exercise'': use <code>yambo</code> to report the properties of all database files (including ''ndb.HF_and_locXC'')

First steps: walk through from DFT(standalone)

2021-04-06T07:49:34Z

Maurizia: /* Download the Files */

In this tutorial you will learn how to calculate optical spectra using Yambo, starting from a DFT calculation and ending with a look at local field effects in the optical response.

== System characteristics ==
We will use a 3D system (bulk hBN) and a 2D system (hBN sheet).

[[File:HBN-bulk-3x3-annotated.png|x200px|Atomic structure of bulk hBN]]
[[File:HBN2.png|x200px|Atomic structure of 2D hBN]]

'''Hexagonal boron nitride - hBN''':
* HCP lattice, ABAB stacking
* Four atoms per cell, B and N (16 electrons)
* Lattice constants: ''a'' = 4.716 [a.u.], ''c/a'' = 2.582
* Plane wave cutoff 40 Ry (~1500 RL vectors in wavefunctions)
* SCF run: shifted ''6x6x2'' grid (12 k-points) with 8 bands
* Non-SCF run: gamma-centred ''6x6x2'' (14 k-points) grid with 100 bands

=== Prerequisites ===
'''You will need''':
* PWSCF input files and pseudopotentials for hBN bulk
* <code>pw.x</code> executable, version 5.0 or later
* <code>p2y</code> and <code>yambo</code> executables
* <code>gnuplot</code> for plotting spectra

==Download the Files==

Download and unpack the followint files:
[http://www.yambo-code.org/educational/tutorials/files/hBN.tar.gz hBN.tar.gz] [15 MB],
[http://www.yambo-code.org/educational/tutorials/files/hBN-2D.tar.gz hBN-2D.tar.gz] [8,6 MB]

In the next days you will also use this file which you may like to download now
[http://www.yambo-code.org/educational/tutorials/files/hBN-convergence-kpoints.tar.gz hBN-convergence-kpoints.tar.gz] [254 MB]

After downloading the tar.gz files just unpack them in the '''YAMBO_TUTORIALS''' folder. For example
$ mkdir YAMBO_TUTORIALS
$ mv hBN.tar.gz YAMBO_TUTORIALS
$ cd YAMBO_TUTORIALS
$ tar -xvfz hBN.tar.gz
$ ls YAMBO_TUTORIALS
hBN
$ cd hBN
$ ls
$ hBN YAMBO

(Advanced users can download and install all tutorial files using git. See the main [[Tutorials#Files|Tutorial Files]] page.)

==DFT calculation of bulk hBN and conversion to Yambo==

In this module you will learn how to generate the Yambo ''SAVE'' folder for bulk hBN starting from a PWscf calculation.



=== Conversion to Yambo format ===
The PWscf ''bBN.save'' output is converted to the Yambo format using the <code>p2y</code> executable (pwscf to yambo), found in the yambo ''bin'' directory.
Enter ''hBN.save'' and launch <code>p2y</code>:

$ cd hBN.save
$ p2y
...
<---> DBs path set to .
<---> Index file set to data-file.xml
<---> Header/K-points/Energies... done
...
<---> == DB1 (Gvecs and more) ...
<---> ... Database done
<---> == DB2 (wavefunctions) ... done ==
<---> == DB3 (PseudoPotential) ... done ==
<---> == P2Y completed ==

This output repeats some information about the system and generates a ''SAVE'' directory:
$ ls SAVE
ns.db1 ns.wf ns.kb_pp_pwscf
ns.wf_fragments_1_1 ...
ns.kb_pp_pwscf_fragment_1 ...
These files, with an ''n'' prefix, indicate that they are in netCDF format, and thus not human readable. However, they are perfectly transferable across different architectures. You can check that the databases contain the information you expect by launching Yambo using the <code>-D</code> option:

$ yambo -D
[RD./SAVE//ns.db1]------------------------------------------
Bands : 100
K-points : 14
G-vectors [RL space]: 8029
Components [wavefunctions]: 1016
...
[RD./SAVE//ns.wf]-------------------------------------------
Fragmentation :yes
...
[RD./SAVE//ns.kb_pp_pwscf]----------------------------------
Fragmentation :yes
- S/N 006626 -------------------------- v.04.01.02 r.00000 -

In practice we suggest to move the ''SAVE'' folder into a new clean folder.

In this tutorial however, we ask instead that you continue using a ''SAVE'' folder that we prepared previously:
$ cd ../../YAMBO
$ ls
SAVE

==Initialization of Yambo databases==
Use the ''SAVE'' folders that are already provided, rather than any ones you may have generated previously.

Every Yambo run '''must''' start with this step. Go to the folder ''containing'' the hBN-bulk <code>SAVE</code> directory:
$ cd YAMBO_TUTORIALS/hBN/YAMBO
$ ls
SAVE

'''TIP''': do not run yambo from ''inside'' the <code>SAVE</code> folder!
'''This is the wrong way .. '''
$ cd SAVE
$ yambo
yambo: cannot access CORE database (SAVE/*db1 and/or SAVE/*wf)
In fact, if you ever see such message:
it usually means you are trying to launch Yambo '''from the wrong place'''.
$ cd ..

Now you are in the proper place and
$ ls
SAVE
you can simply launch the code
$ yambo
This will run the initialization (setup) ''runlevel''.

===Run-time output===
This is typically written to standard output (on screen) and tracks the progress of the run in real time:
<---> [01] MPI/OPENMP structure, Files & I/O Directories
<---> [02] CORE Variables Setup
<---> [02.01] Unit cells
<---> [02.02] Symmetries
<---> [02.03] Reciprocal space
<---> Shells finder |########################################| [100%] --(E) --(X)
<---> [02.04] K-grid lattice
<---> Grid dimensions : 6 6 2
<---> [02.05] Energies & Occupations
<---> [03] Transferred momenta grid and indexing
<---> BZ -> IBZ reduction |########################################| [100%] --(E) --(X)
<---> [03.01] X indexes
<---> X [eval] |########################################| [100%] --(E) --(X)
<---> X[REDUX] |########################################| [100%] --(E) --(X)
<---> [03.01.01] Sigma indexes
<---> Sigma [eval] |########################################| [100%] --(E) --(X)
<---> Sigma[REDUX] |########################################| [100%] --(E) --(X)
<---> [04] Timing Overview
<---> [05] Memory Overview
<---> [06] Game Over & Game summary
Specific runlevels are indicated with numeric labels like [02.02]. 
The hashes (#) indicate progress of the run in Wall Clock time, indicating the elapsed (E) and expected (X) time to complete a runlevel, and the percentage of the task complete.

===New core databases===
New databases appear in the ''SAVE'' folder:
$ ls SAVE
ns.db1 ns.wf ns.kb_pp_pwscf '''ndb.gops ndb.kindx'''
ns.wf_fragments_1_1 ...
ns.kb_pp_pwscf_fragment_1 ...
These contain information about the ''G''-vector shells and ''k/q''-point meshes as defined by the DFT calculation.

In general: a database called ''n'''s'''.xxx'' is a ''static'' database, generated once by <code>p2y</code>, while databases called ''n'''db'''.xxx'' are ''dynamically'' generated while you use <code>yambo</code>.

'''TIP''': if you launch <code>yambo</code>, but it does not seem to do anything, check that these files are present.

===Report file===
A report file ''r_setup'' is generated in the run directory.
This mostly reports information about the ground state system as defined by the DFT run, but also adds information about the band gaps, occupations, shells of G-vectors, IBZ/BZ grids, the CPU structure (for parallel runs), and so on. Some points of note:

Up to Yambo version 4.5
[02.03] RL shells
=================
Shells, format: [S#] G_RL(mHa)
[S453]:8029(0.7982E+5) [S452]:8005(0.7982E+5) [S451]:7981(0.7982E+5) [S450]:7957(0.7942E+5)
...
[S4]:11( 1183.) [S3]:5( 532.5123) [S2]:3( 133.1281) [S1]:1( 0.000000)

From Yambo version 5.0
[02.03] Reciprocal space
========================

nG shells : 217
nG charge : 3187
nG WFs : 1477
nC WFs : 1016
G-vecs. in first 21 shells: [ Number ]
1 3 5 11 13 25 37 39 51
63 65 71 83 95 107 113 125 127
139 151 163
...
Shell energy in first 21 shells: [ mHa ]
0.00000 133.128 532.512 1183.37 1198.15 1316.50 1715.88 2130.05 2381.52
3313.42 3328.20 3550.11 3683.24 4082.62 4511.57 4733.48 4748.27 4792.61
4866.61 5266.00 5680.16
...

This reports the set of closed reciprocal lattice (RL) shells defined internally that contain G-vectors with the same modulus.
The highest number of RL vectors we can use is 8029. Yambo will always redefine any input variable in RL units to the nearest closed shell.

Up to Yambo version 4.5
[02.05] Energies [ev] & Occupations
===================================
Fermi Level [ev]: 5.112805
VBM / CBm [ev]: 0.000000 3.876293
Electronic Temp. [ev K]: 0.00 0.00
Bosonic Temp. [ev K]: 0.00 0.00
El. density [cm-3]: 0.460E+24
States summary : Full Metallic Empty
0001-0008 0009-0100
Indirect Gaps [ev]: 3.876293 7.278081
Direct Gaps [ev]: 4.28829 11.35409
X BZ K-points : 72

From Yambo version 5.0
[02.05] Energies & Occupations
==============================

[X] === General ===
[X] Electronic Temperature : 0.000000 0.000000 [eV K]
[X] Bosonic Temperature : 0.000000 0.000000 [eV K]
[X] Finite Temperature mode : no
[X] El. density : 0.46037E+24 [cm-3]
[X] Fermi Level : 5.110835 [eV]

[X] === Gaps and Widths ===
[X] Conduction Band Min : 3.877976 [eV]
[X] Valence Band Max : 0.000000 [eV]
[X] Filled Bands : 8
[X] Empty Bands : 9 100
[X] Direct Gap : 4.289853 [eV]
[X] Direct Gap localized at k-point : 7
[X] Indirect Gap : 3.877976 [eV]
[X] Indirect Gap between k-points : 14 7
[X] Last valence band width : 3.401086 [eV]
[X] 1st conduction band width : 4.266292 [eV]

Yambo recalculates again the Fermi level (close to the value of 5.06 noted in the PWscf SCF calculation). From here on, however, the Fermi level is set to zero, and other eigenvalues are shifted accordingly. The system is insulating (8 filled, 92 empty) with an indirect band gap of 3.87 eV. The minimum and maximum direct and indirect gaps are indicated. There are 72 k-points in the full BZ, generated using symmetry from the 14 k-points in our user-defined grid.

'''TIP''': You should inspect the report file after ''every'' run for errors and warnings.

===Different ways of running yambo===
We just run Yambo interactively.

Let's try to re-run the setup with the command
$ nohup yambo &
$ ls
l_setup nohup.out r_setup r_setup_01 SAVE

If Yambo is launched using a script, or as a background process, or in parallel, this output will appear in a log file prefixed by the letter ''l'', in this case as ''l_setup''.
If this log file already exists from a previous run, it will not be overwritten. Instead, a new file will be created with an incrementing numerical label, e.g. ''l_setup_01, l_setup_02'', etc. '''This applies to all files created by Yambo'''. Here we see that l_setup was created for the first time, but r_setup already existed from the previous run, so now we have r_setup_01
If you check the differences between the two you will notice that in the second run yambo is reading the previously created ndb.kindx in place of re-computing the indexes.
Indeed the output inside l_setup does not show the timing for X and Sigma

As a last step we run the setup in parallel, but first we delete the ndb.kindx file
$ rm SAVE/ndb.kindx
$ mpirun -np 4 yambo
$ ls
LOG l_setup nohup.out r_setup r_setup_01 r_setup_02 SAVE
There is now r_setup_02
In the case of parallel runs, CPU-dependent log files will appear inside a ''LOG'' folder, e.g.
$ ls LOG
l_setup_CPU_1 l_setup_CPU_2 l_setup_CPU_3 l_setup_CPU_4
This behaviour can be controlled at runtime - see the Parallel tutorial for details.

===2D hBN===
Simply repeat the steps above. Go to the folder ''containing'' the hBN-sheet ''SAVE'' directory and launch <code>yambo</code>:
$ cd TUTORIALS/hBN-2D/YAMBO
$ ls
SAVE
$ yambo
Again, inspect the ''r_setup'' file, output logs, and verify that ''ndb.gops'' and ''ndb.kpts'' have been created inside the SAVE folder.

You are now ready to use Yambo!

==Yambo's command line interface==
Yambo uses a command line interface to select tasks, generate input files, and control the runtime behaviour.

In this module you will learn how to select tasks, generate and modify input files, and control the runtime behaviour by using Yambo's command line interface.


=== Input file generator ===
First, move to the appropriate folder and initialize the Yambo databases if you haven't already done so.
$ cd YAMBO_TUTORIALS/hBN/YAMBO
$ yambo ''(initialize)''

Yambo generates its own input files: you just tell the code what you want to calculate by launching Yambo along with one or more options.
To see the list of possible options, run <code>yambo -h</code> (we report here only the part we are focusing in)
$ yambo -h
'A shiny pot of fun and happiness [C.D.Hogan]'

This is : yambo
Version : 5.0.1 Revision 19547 Hash e90d90f2d
Configuration: MPI+OpenMP+SLK+SLEPC+HDF5_MPI_IO

...

Initializations:
-setup (-i) :Initialization
-coulomb (-r) :Coulomb potential

Response Functions:
-optics (-o) <string> :Linear Response optical properties (more with -h optics)
-X (-d) <string> :Inverse Dielectric Matrix (more with -h X)
-dipoles (-q) :Oscillator strenghts (or dipoles)
-kernel (-k) <string> :Kernel (more with -h kernel)

Self-Energy:
-hf (-x) :Hartree-Fock
-gw0 (-p) <string> :GW approximation (more with -h gw0)
-dyson (-g) <string> :Dyson Equation solver (more with -h dyson)
-lifetimes (-l) :GoWo Quasiparticle lifetimes

Bethe-Salpeter Equation:
-Ksolver (-y) <string> :BSE solver (more with -h Ksolver)

Total Energy:
-acfdt :ACFDT Total Energy

Utilites:
...
-slktest :ScaLapacK test

The options can be split into two sets: 
* A set of options which is needed to generate the appropriate input file (default name: ''yambo.in'') selecting the kind of simulation you would like to perform 
* A set of options which can be used to manage auxiliary functions (like redirect the I/O, choose a specific name for the input file, etc ..).

===Runlevel selection===
First of all, you would like to specify which kind of simulation you are going to perform and generate an input file with the first set of options.
By default, when generating the input file, Yambo will launch the <code>vi</code> editor.
Editor choice can be changed when launching the configure before compilation; alternatively you can use the <code>-Q</code> run time option to skip the automatic editing (do this if you are not familiar with <code>vi</code>!):
$ yambo -hf -Q
yambo: input file yambo.in created
$ emacs yambo.in ''or your favourite editing tool''

Multiple options can be used together to activate various tasks or runlevels (in some cases this is actually a necessity).
For instance, to generate an input file for optical spectra including local field effects (Hartree approximation), do (and then exit)
$ yambo -optics c -kernel hartree ''which switches on:''
optics # [R OPT] Optics
chi # [R CHI] Dyson equation for Chi.
Chimod= "Hartree" # [X] IP/Hartree/ALDA/LRC/BSfxc
To perform a Hartree-Fock and GW calculation using a plasmon-pole approximation, do (and then exit):
$ yambo -hf -gw0 p -dyson n ''which switches on:''
HF_and_locXC # [R XX] Hartree-Fock Self-energy and Vxc
gw0 # [R GW] GoWo Quasiparticle energy levels
ppa # [R Xp] Plasmon Pole Approximation
em1d # [R Xd] Dynamical Inverse Dielectric Matrix
Each runlevel activates its own list of variables and flags.

The previous command is also equivalent to
$ yambo -hf -gw0 r -dyson n -X p

===Changing input parameters ===
Yambo reads various parameters from existing database files and/or input files and uses them to suggest values or ranges.
Let's illustrate this by generating the input file for a Hartree-Fock calculation.

$ yambo -hf
Inside the generated input file you should find:
[[Variables#EXXRLvcs|EXXRLvcs]] = 3187 RL # [XX] Exchange RL components
%[[Variables#QPkrange|QPkrange]] # [GW] QP generalized Kpoint/Band indices
1| 14| 1|100|
%
The <code>[[Variables#QPkrange|QPkrange]]</code> variable (follow the link for a "detailed" explanation for any variable) suggests a range of k-points (1 to 14) and bands (1 to 100) based on what it finds in the core database ''SAVE/ns.db1'', i.e. as defined by the DFT code. 
Leave that variable alone, and instead modify the previous variable to <code>EXXRLvcs= 1000 RL</code>

Save the file, and now generate the input a second time with <code>yambo -x</code>. You will see:
[[Variables#EXXRLvcs|EXXRLvcs]]= 1009 RL
This indicates that Yambo has read the new input value (1000 G-vectors), checked the database of G-vector shells ''(SAVE/ndb.gops)'',
and changed the input value to one that fits a completely closed shell.

Last, note that Yambo variables can be expressed in different '''units'''. In this case, <code>RL</code> can be replaced by an energy unit like Ry, eV, Ha, etc. Energy units are generally better as they are independent of the cell size. Technical information is available on the [[Variables]] page.

The input file generator of Yambo is thus an ''intelligent'' parser, which interacts with the user and the existing databases. For this reason we recommend that you always use Yambo to generate the input files, rather than making them yourself.

===Extra options===
Extra options modify some of the code's default settings. They can be used when launching the code but also when generating input files.

Let's have a look again to the possible options (we report here only the part we are focusing in):
$ yambo -h
This is : yambo
Version : 5.0.1 Revision 19547 Hash e90d90f2d
Configuration: MPI+OpenMP+SLK+SLEPC+HDF5_MPI_IO

Help & version:
-help (-h) <string> :<string> can be an option (e.g. -h optics)
-version :Code version & libraries

Input file & Directories:
-Input (-F) <string> :Input file
-Verbosity (-V) <string> :Input file variables verbosity (more with -h Verbosity)
-Job (-J) <string> :Job string
-Idir (-I) <string> :Input directory
-Odir (-O) <string> :I/O directory
-Cdir (-C) <string> :Communication directory

Parallel Control:
-parenv (-E) <string> :Environment Parallel Variables file
-nompi :Switch off MPI support
-noopenmp :Switch off OPENMP support

...

Utilites:
-Quiet (-Q) :Quiet input file creation
-fatlog :Verbose (fatter) log(s)
-DBlist (-D) :Databases properties
...

Command line options are extremely important to master if you want to use yambo productively.
Often, the meaning is clear from the help menu:
$ yambo -F yambo.in_HF -hf ''Make a Hartree-Fock input file called yambo.in_HF''
$ yambo -D ''Summarize the content of the databases in the SAVE folder''
$ yambo -I ../ ''Run the code, using a SAVE folder in a directory one level up''
$ yambo -C MyTest ''Run the code, putting all report, log, plot files inside a folder MyTest''

Other options deserve a closer look.

===Verbosity===
Yambo uses ''many'' input variables, many of which can be left at their default values. To keep input files short and manageable, only a few variables appear by default in the inout file. More advanced variables can be switched on by using the <code>-V</code> verbosity option. These are grouped according to the type of variable. For instance, <code>-V RL</code> switches on variables related to G vector summations, and <code>-V io</code> switches on options related to I/O control. Try:

$ yambo -optics c -V RL ''switches on:''
FFTGvecs= 3951 RL # [FFT] Plane-waves

$ yambo -optics c -V io ''switches on:''
StdoHash= 40 # [IO] Live-timing Hashes
DBsIOoff= "none" # [IO] Space-separated list of DB with NO I/O. DB= ...
DBsFRAGpm= "none" # [IO] Space-separated list of +DB to be FRAG and ...
#WFbuffIO # [IO] Wave-functions buffered I/O

Unfortunately, -V options must be invoked and changed ''one at a time''. When you are more expert, you may go straight to <code>-V all</code>, which turns on all possible variables. However note that <code>yambo -o c -V all</code> adds an extra 30 variables to the input file, which can be confusing: use it with care.

===Job script label===
The best way to keep track of different runs using different parameters is through the <code>-J</code> flag. This inserts a label in all output and report files, and creates a new folder containing any new databases (i.e. they are not written in the core ''SAVE'' folder). Try:
$ yambo -J 1Ry -V RL -hf -F yambo_hf.in ''and modify to''
FFTGvecs = 1 Ry
EXXGvecs = 1 Ry
$ yambo -J 1Ry -F yambo_hf.in ''Run the code''
$ ls
yambo_hf.in SAVE
o-1Ry.hf r-1Ry_HF_and_locXC 1Ry 1Ry/ndb.HF_and_locXC
This is extremely useful when running convergence tests, trying out different parameters, etc.

''Exercise'': use <code>yambo</code> to report the properties of all database files (including ''ndb.HF_and_locXC'')

GW hBN Yambo Virtual 2021 version

2021-04-06T07:37:27Z

Maurizia: /* Input file generation */

This is a modified version of the tutorial prepared for the Yambo 2021 virtual school.
In case you are interested you can find the extended version of the tutorial here: [[How to obtain the quasi-particle band structure of a bulk material: h-BN]]

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 focus 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.

====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.

==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 ==

 
'''For self-consistent GW please look this new tutorial: [http://www.yambo-code.org/wiki/index.php?title=Self-consistent_GW_on_eigenvalues_only Self-consistent GW on eigenvalues only]'''
 

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 absolutely 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 anbed 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==

GW hBN Yambo Virtual 2021 version

2021-04-06T07:31:23Z

Maurizia: /* Input file generation */

This is a modified version of the tutorial prepared for the Yambo 2021 virtual school.
In case you are interested you can find the extended version of the tutorial here: [[How to obtain the quasi-particle band structure of a bulk material: h-BN]]

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.

====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.

==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 ==

 
'''For self-consistent GW please look this new tutorial: [http://www.yambo-code.org/wiki/index.php?title=Self-consistent_GW_on_eigenvalues_only Self-consistent GW on eigenvalues only]'''
 

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 absolutely 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 anbed 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==

Download

2021-04-06T07:29:45Z

Maurizia: /* Getting the latest snapshot with git */

== Get in touch with Yambo on git (optional) ==
The Yambo source is hosted on the [https://github.com/yambo-code Git-Hub] hosting service. 
Full access to the git repository or tar-balls are available.
No registration or password is required. 
However We warmly invite all Yambo users to register on Github and, after that:
* if you like the project, go to the [https://github.com/yambo-code/yambo Yambo repository] and push the star button.
* if you would like to receive updates push the watch button.
* if you wish, send your github username to the yambo email address and we will add you to the Users group of the yambo project.

Also if you need any further help regarding the access to the Yambo download page please send us an e-mail.
email: yambo at DOMAIN. DOMAIN=yambo-code.org

== Direct download (for impatient) ==
Tar-balls are available on the github download page:
* [https://github.com/yambo-code/yambo/wiki/Releases-%28tar.gz-format%29 Browse all releases (tar.gz format)]
* [https://github.com/yambo-code/yambo/wiki/Releases-%28zip-format%29 Browse all releases (zip format)]
Please choose your preferred release.

== Getting the latest snapshot with git ==
To obtain the latest source you need to have <code>git</code> installed.
[https://git-scm.com/ Git] is a version control system for tracking changes in computer files and coordinating work on those files among multiple people. It is primarily used for software development.

To obtain the last GPL source, you simply need to do:

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

Please notice that doing so you will download the whole yambo repository, thus included all previous releases.
To see the list of releases just do

git branch -a

and you will see

* 5.0

if you want to switch to a previous version i.e 4.1 do

git checkout 4.1

to switch to a specific version (X.Y) among the ones listed after the command "git branch -a" (X.Y=4.1 in the example).
For production we suggest to always checkout a specific branch and not to stay in the master which maybe less stable. The branch corresponding to the version X.Y is always kept at the last patch-level. However if you need to checkout a specific patch-level you can do

git tag
git checkout 4.1.2

to switch to a specific release (X.Y.Z) among the ones listed after the command "git tag" (X.Y.Z=4.1.2 in the example).

== Getting the latest snapshot with subversion (obsolete) ==
If you are more familiar with subversion you can also download the whole repository in svn form.
Github offers the feature to automatically convert the git repo during the download. However remember that the repository in svn like form will be much bigger (~300 MB) that in git form (16 MB). Thus it is better to directly specify which branch you would like to download in that case:
<pre>svn checkout https://github.com/yambo-code/yambo.git/branches/4.1 yambo-4.1</pre>
or
<pre>svn checkout https://github.com/yambo-code/yambo.git/tags/4.1.2 yambo-4.1.2</pre>

== Getting a dedicated branch inside the gpl repository (experimental) ==
Yambo is a GPL code mantained by a small team of researchers. If you would like to help us coding new features or simply you would like to modify the code for your needs, we advise to follow the online tutorial [http://www.yambo-code.org/tutorials/developing_yambo/index.php Developing yambo]. Together with this tutorial we can also give you write permission inside the GPL repository. Thus, in case you are interested, please contact the yambo team and we will be glad to set up a specific branch for your needs.

Hartree Fock

2021-04-06T07:09:26Z

Maurizia: /* Calculation and analysis of output */

== Prerequisites ==
[[File:Yambo-handbook-v4.1.2-p-9.png|thumb|Cheatsheet on HF|150px]]

* You must first complete the "How to use Yambo" modules (''[[Input_file_generation_and_command_line_options|input file generation and command_line_options]], [[Initialization]]'')

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

== Background ==
The exchange part contribution of the self-energy for a generic state (nk) in reciprocal space reads:
[[File:Sx.png|none|x50px|caption]]
It is important to note that in this way we are adding the HF contribution in a perturbative way to previously calculated DFT energies:

[[File:Ehf.png|x20px|caption]]

and hence they will differ from a standard self-consistent HF calculation.

== Input file generation ==

Let's start by building up an input file for a HF calculation. From <code>yambo -h</code> you should understand that the correct option is <code>yambo -x</code>:

$ cd YAMBO_TUTORIALS/hBN/YAMBO
$ yambo ''(Initialization)''
$ yambo -x -F hf.in

Looking inside the input file you will find:

[[Variables#EXXRLvcs|EXXRLvcs]] = 3187 RL # [XX] Exchange RL components
[[Variables#VXCRLvcs|VXCRLvcs]] = 3187 RL # [XC] XCpotential RL components
%[[Variables#QPkrange|QPkrange]] # [GW] QP generalized Kpoint/Band indices
1| 14| 1|100|
%

The variable [[Variables#EXXRLvcs|EXXRLvcs]] governs the number of G vectors to be summed in the expression of the exchange self-energy reported above.
The variable [[Variables#VXCRLvcs|VXCRLvcs]] set the number of G vectors used in the evaluation of the density for the <Vxc> matrix element. A large number is needed in order to have a precise cancellation with the ground state calculation, in particular when GGA potentials are used. A good practice is to leave it at the maximum number (default). In case it would be needed to reduce (e.g. for memory reason), the accuracy can be checked by comparing the E_xc value printed in Yambo report and QE output file.
The [[Variables#QPkrange|QPkrange]] name list it is a generalized index needed to select the first and last kpoints and bands we want to calculate the QP correction.
In general, we are interested in the gap of the system or in the band structure across the Fermi Energy. Let's start by editing the ''hf.in'' file by selecting the last occupied and first unoccupied bands These are the bands 8 and 9 as reported in the r_setup file.
So we change the [[Variables#QPkrange|QPkrange]] variable in:

%[[Variables#QPkrange|QPkrange]] # [GW] QP generalized Kpoint/Band indices
1| 14| 8| 9|
%

and run calculations to converge the expression above. In the expression of the Exchange Self Energy, we have a summation over bands, an integral over the Brillouin Zone and a Sum over the G vectors. Looking at the occupation factor we realize that occupied states only enters in the expression, so we do not need to worry about the bands as Yambo will include all the occupied bands by default. In order to check convergence of the G vectors in the summation in the Σx expression, we will perform different calculation varying the kinetic energy cutoff governing the number of G vectors entering in the sum. Let's start by setting in ''hf.in'':

[[Variables#EXXRLvcs|EXXRLvcs]]= 10 Ry

== Calculation and analysis of output ==
Let's now run yambo:

$ yambo -F hf.in -J 3D

The result can be found int the output ''o-3D.hf'' file and in the ''r-3D_HF_and_locXC'' file. Looking inside the output file we have:

# K-point Band Eo Ehf DFT HF
#
1.00000 8.00000 -1.29642 -4.79324 -18.03344 -21.53026
1.00000 9.00000 4.83239 9.755507 -9.592554 -4.669446
2.00000 8.00000 -1.33551 -4.80994 -18.07476 -21.54919
2.00000 9.00000 7.56742 13.43122 -11.55012 -5.68633
........

Looking at the definition of the HF energy, the third column is the DFT energy (KS eigenvalue), Ehf is the HF energy, and column 4 and 5 report the different contribution to be subtracted Vx (DFT) and added Σx (HF) to the unperturbed DFT eigenvalue. From these data we can calculate the HF gap: you can recognize that the direct gap is found at k-point number 7, being 4.29 eV at DFT level and 11.95 eV in HF approximation. This information can be also easily found in the
report file ''r-3D_HF_and_locXC'' searching for Direct Gaps:

Before the HF computation:

[X] Direct Gap : 4.289853 [eV]
[X] Direct Gap localized at k-point : 7
[X] Indirect Gap : 3.877976 [eV]
[X] Indirect Gap between k-points : 14 7

... after the HF computation:

[05.01] HF occupations report
=============================

[Hartree-Fock] Direct Gap : 11.94549 [eV]
[Hartree-Fock] Direct Gap localized at k-point : 7
[Hartree-Fock] Indirect Gap : 11.28767 [eV]
[Hartree-Fock] Indirect Gap between k-points : 14 7

or simply by typing:

$ grep "Direct Gap" r-3D_HF_and_locXC

and the gap value before and after the HF correction is shown:
[X] Direct Gap : 4.289853 [eV]
[X] Direct Gap localized at k-point : 7
[Hartree-Fock] Direct Gap : 11.94549 [eV]
[Hartree-Fock] Direct Gap localized at k-point : 7

In the report file, the first value indicates the minimum gap while the second one is the maximum energy gap between the same bands.

In the following, in order to converge the direct gap, we will focus the K point where the direct band is found. Inspecting the ''r_setup'' file, or any other report file it can be recognized that the direct minimum gap is found at the K-point number 7 (M point): this can be seen by searching the DFT "Direct Gap" and looking at the eigenvalues reported for each k point. Note that the zero energy is fixed at the top of the valence band, K point number 14 (H point).
So we can restrict the convergence calculations to the occupied and empty bands at point M, by modifying the input file as:

%[[Variables#QPkrange|QPkrange]] # [GW] QP generalized Kpoint/Band indices
7| 7| 8| 9|
%

Even if for this case the calculations are not at all expensive, reducing the calculations to few bands when performing convergence test allows to save memory and time.

Now we can run different calculations changing the value of [[Variables#EXXRLvcs|EXXRLvcs]], let's say to 10,20,30 and 40 Ry.
Build four different input files differing only for the [[Variables#EXXRLvcs|EXXRLvcs]] values and naming them hf_10Ry.in, hf_20Ry.in, etc.

$ cp hf.in hf_10Ry.in
$ yambo -F hf_10Ry.in -J 3D
$ cp hf.in hf_20Ry.in ''and edit file, changing EXXRLvcs to 20Ry''
$ yambo -F hf_20Ry.in -J 3D
.....

Once the calculations are terminated, collect the results found in the output, for instance, putting in a file named hf.dat the following data:
Cutoff Energy, Number of G vector in the Sum, HF energy for the occupied state (Ehf for the state 8), HF energy for the unoccupied state (Ehf for the state 9).
You can use the ''grep'' command to extract these data from the output e.g by typing.

grep 8.000 o-3D.hf_*
and
grep 9.000 o-3D.hf_*

and looking at the column corresponding to Ehf value (column 4).
For the number of G vectors corresponding to the cutoff energy cutoff in input search ''Exchange RL vectors'' in the report files. Note that it is not possible anymore to extract directly the HF gap from the report file as we did above, as in this case, we did not include all the BZ in the calculation.
Now it possible to plot the energy gap in function of the energy cutoff or number of Gvectors:

$ gnuplot
gnuplot> plot "hf.dat" u 1:($4-$3) w lp t "HF gap vs Energy cutoff"
gnuplot> plot "hf.dat" u 2:($4-$3) w lp t "HF gap vs Number of G vector"

or you can plot the gap in function of both quantities using the [[gnuplot_scripts|hf.gnu]] gnuplot script:

[[File:Hf_plot1.png|none|600px|caption]]

and you can see that at 40Ry the energy gap is very close to convergence. Plotting the occupied and unoccupied bands separately you can recognize that for this system the unoccupied band does converge much faster.

The last important convergence test deals with the accuracy of the integral over the Brillouin zone in the expression of the Exchange Self-Energy, which translates into K point convergence.
In order to test the K point sampling, you should:
# perform a new non-scf calculation with a bigger k point grid,
# 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.

For now, however, you can skip this convergence test and continue the tutorial at
[[How to obtain the quasi-particle band structure of a bulk material: h-BN|How to obtain the quasiparticle band structure of a bulk material]]

 
{| style="width:100%" border="1"
|style="width:15%; text-align:left"|Prev: [[How_to_obtain_the_quasi-particle_band_structure_of_a_bulk_material:_h-BN|GW]]
|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]] --> [[Hartree_Fock]]
|style="width:35%; text-align:right"|Next: Back to [[How_to_obtain_the_quasi-particle_band_structure_of_a_bulk_material:_h-BN|GW]]
|-
|}

[[Category:Modules]]

Hartree Fock

2021-04-06T06:56:41Z

Maurizia: /* Input file generation */

== Prerequisites ==
[[File:Yambo-handbook-v4.1.2-p-9.png|thumb|Cheatsheet on HF|150px]]

* You must first complete the "How to use Yambo" modules (''[[Input_file_generation_and_command_line_options|input file generation and command_line_options]], [[Initialization]]'')

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

== Background ==
The exchange part contribution of the self-energy for a generic state (nk) in reciprocal space reads:
[[File:Sx.png|none|x50px|caption]]
It is important to note that in this way we are adding the HF contribution in a perturbative way to previously calculated DFT energies:

[[File:Ehf.png|x20px|caption]]

and hence they will differ from a standard self-consistent HF calculation.

== Input file generation ==

Let's start by building up an input file for a HF calculation. From <code>yambo -h</code> you should understand that the correct option is <code>yambo -x</code>:

$ cd YAMBO_TUTORIALS/hBN/YAMBO
$ yambo ''(Initialization)''
$ yambo -x -F hf.in

Looking inside the input file you will find:

[[Variables#EXXRLvcs|EXXRLvcs]] = 3187 RL # [XX] Exchange RL components
[[Variables#VXCRLvcs|VXCRLvcs]] = 3187 RL # [XC] XCpotential RL components
%[[Variables#QPkrange|QPkrange]] # [GW] QP generalized Kpoint/Band indices
1| 14| 1|100|
%

The variable [[Variables#EXXRLvcs|EXXRLvcs]] governs the number of G vectors to be summed in the expression of the exchange self-energy reported above.
The variable [[Variables#VXCRLvcs|VXCRLvcs]] set the number of G vectors used in the evaluation of the density for the <Vxc> matrix element. A large number is needed in order to have a precise cancellation with the ground state calculation, in particular when GGA potentials are used. A good practice is to leave it at the maximum number (default). In case it would be needed to reduce (e.g. for memory reason), the accuracy can be checked by comparing the E_xc value printed in Yambo report and QE output file.
The [[Variables#QPkrange|QPkrange]] name list it is a generalized index needed to select the first and last kpoints and bands we want to calculate the QP correction.
In general, we are interested in the gap of the system or in the band structure across the Fermi Energy. Let's start by editing the ''hf.in'' file by selecting the last occupied and first unoccupied bands These are the bands 8 and 9 as reported in the r_setup file.
So we change the [[Variables#QPkrange|QPkrange]] variable in:

%[[Variables#QPkrange|QPkrange]] # [GW] QP generalized Kpoint/Band indices
1| 14| 8| 9|
%

and run calculations to converge the expression above. In the expression of the Exchange Self Energy, we have a summation over bands, an integral over the Brillouin Zone and a Sum over the G vectors. Looking at the occupation factor we realize that occupied states only enters in the expression, so we do not need to worry about the bands as Yambo will include all the occupied bands by default. In order to check convergence of the G vectors in the summation in the Σx expression, we will perform different calculation varying the kinetic energy cutoff governing the number of G vectors entering in the sum. Let's start by setting in ''hf.in'':

[[Variables#EXXRLvcs|EXXRLvcs]]= 10 Ry

== Calculation and analysis of output ==
Let's now run yambo:

$ yambo -F hf.in -J 3D

The result can be found int the output ''o-3D.hf'' file and in the ''r-3D_HF_and_locXC'' file. Looking inside the output file we have:

# K-point Band Eo Ehf DFT HF
#
1.00000 8.00000 -1.29642 -4.79324 -18.03344 -21.53026
1.00000 9.00000 4.83239 9.755507 -9.592554 -4.669446
2.00000 8.00000 -1.33551 -4.80994 -18.07476 -21.54919
2.00000 9.00000 7.56742 13.43122 -11.55012 -5.68633
........

Looking at the definition of the HF energy, the third column is the DFT energy (KS eigenvalue), Ehf is the HF energy, and column 4 and 5 report the different contribution to be subtracted Vx (DFT) and added Σx (HF) to the unperturbed DFT eigenvalue. From these data we can calculate the HF gap: you can recognize that the direct gap is found at k-point number 7, being 4.29 eV at DFT level and 11.95 eV in HF approximation. This information can be also easily found in the
report file ''r-3D_HF_and_locXC'' searching for Direct Gaps:

Before the HF computation:

States summary : Full Metallic Empty
0001-0008 0009-0100
Indirect Gaps [ev]: 3.877976 7.279063
Direct Gaps [ev]: 4.28985 11.35417

... after the HF computation:

[05.01] HF occupations report
=============================

States summary : Full Metallic Empty
0001-0008 0009-0100
Indirect Gaps [ev]: 11.28776 16.09201
Direct Gaps [ev]: 11.94547 21.59526

or simply by typing:

$ grep "Direct Gaps" r-3D_HF_and_locXC

and the gap value before and after the HF correction is shown:
Direct Gaps [ev]: 4.28985 11.35417
Direct Gaps [ev]: 11.94547 21.59526

In the report file, the first value indicates the minimum gap while the second one is the maximum energy gap between the same bands.

In the following, in order to converge the direct gap, we will focus the K point where the direct band is found. Inspecting the ''r_setup'' file, or any other report file it can be recognized that the direct minimum gap is found at the K-point number 7 (M point): this can be seen by searching the DFT "Direct Gap" and looking at the eigenvalues reported for each k point. Note that the zero energy is fixed at the top of the valence band, K point number 14 (H point).
So we can restrict the convergence calculations to the occupied and empty bands at point M, by modifying the input file as:

%[[Variables#QPkrange|QPkrange]] # [GW] QP generalized Kpoint/Band indices
7| 7| 8| 9|
%

Even if for this case the calculations are not at all expensive, reducing the calculations to few bands when performing convergence test allows to save memory and time.

Now we can run different calculations changing the value of [[Variables#EXXRLvcs|EXXRLvcs]], let's say to 10,20,30 and 40 Ry.
Build four different input files differing only for the [[Variables#EXXRLvcs|EXXRLvcs]] values and naming them hf_10Ry.in, hf_20Ry.in, etc.

$ cp hf.in hf_10Ry.in
$ yambo -F hf_10Ry.in -J 3D
$ cp hf.in hf_20Ry.in ''and edit file, changing EXXRLvcs to 20Ry''
$ yambo -F hf_20Ry.in -J 3D
.....

Once the calculations are terminated, collect the results found in the output, for instance, putting in a file named hf.dat the following data:
Cutoff Energy, Number of G vector in the Sum, HF energy for the occupied state (Ehf for the state 8), HF energy for the unoccupied state (Ehf for the state 9).
You can use the ''grep'' command to extract these data from the output e.g by typing.

grep 8.000 o-3D.hf_*
and
grep 9.000 o-3D.hf_*

and looking at the column corresponding to Ehf value (column 4).
For the number of G vectors corresponding to the cutoff energy cutoff in input search ''Exchange RL vectors'' in the report files. Note that it is not possible anymore to extract directly the HF gap from the report file as we did above, as in this case, we did not include all the BZ in the calculation.
Now it possible to plot the energy gap in function of the energy cutoff or number of Gvectors:

$ gnuplot
gnuplot> plot "hf.dat" u 1:($4-$3) w lp t "HF gap vs Energy cutoff"
gnuplot> plot "hf.dat" u 2:($4-$3) w lp t "HF gap vs Number of G vector"

or you can plot the gap in function of both quantities using the [[gnuplot_scripts|hf.gnu]] gnuplot script:

[[File:Hf_plot1.png|none|600px|caption]]

and you can see that at 40Ry the energy gap is very close to convergence. Plotting the occupied and unoccupied bands separately you can recognize that for this system the unoccupied band does converge much faster.

The last important convergence test deals with the accuracy of the integral over the Brillouin zone in the expression of the Exchange Self-Energy, which translates into K point convergence.
In order to test the K point sampling, you should:
# perform a new non-scf calculation with a bigger k point grid,
# 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.

For now, however, you can skip this convergence test and continue the tutorial at
[[How to obtain the quasi-particle band structure of a bulk material: h-BN|How to obtain the quasiparticle band structure of a bulk material]]

 
{| style="width:100%" border="1"
|style="width:15%; text-align:left"|Prev: [[How_to_obtain_the_quasi-particle_band_structure_of_a_bulk_material:_h-BN|GW]]
|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]] --> [[Hartree_Fock]]
|style="width:35%; text-align:right"|Next: Back to [[How_to_obtain_the_quasi-particle_band_structure_of_a_bulk_material:_h-BN|GW]]
|-
|}

[[Category:Modules]]

First steps: walk through from DFT(standalone)

2021-04-02T13:05:04Z

Maurizia: /* Verbosity */

In this tutorial you will learn how to calculate optical spectra using Yambo, starting from a DFT calculation and ending with a look at local field effects in the optical response.

== System characteristics ==
We will use a 3D system (bulk hBN) and a 2D system (hBN sheet).

[[File:HBN-bulk-3x3-annotated.png|x200px|Atomic structure of bulk hBN]]
[[File:HBN2.png|x200px|Atomic structure of 2D hBN]]

'''Hexagonal boron nitride - hBN''':
* HCP lattice, ABAB stacking
* Four atoms per cell, B and N (16 electrons)
* Lattice constants: ''a'' = 4.716 [a.u.], ''c/a'' = 2.582
* Plane wave cutoff 40 Ry (~1500 RL vectors in wavefunctions)
* SCF run: shifted ''6x6x2'' grid (12 k-points) with 8 bands
* Non-SCF run: gamma-centred ''6x6x2'' (14 k-points) grid with 100 bands

=== Prerequisites ===
'''You will need''':
* PWSCF input files and pseudopotentials for hBN bulk
* <code>pw.x</code> executable, version 5.0 or later
* <code>p2y</code> and <code>yambo</code> executables
* <code>gnuplot</code> for plotting spectra

==Download the Files==

Download and unpack the followint files:
[http://www.yambo-code.org/educational/tutorials/files/hBN.tar.gz hBN.tar.gz] [15 MB],
[http://www.yambo-code.org/educational/tutorials/files/hBN-2D.tar.gz hBN-2D.tar.gz] [8,6 MB]

In the next days you will also use this file which you may like to download now
[http://www.yambo-code.org/educational/tutorials/files/hBN-convergence-kpoints.tar.gz hBN-convergence-kpoints.tar.gz] [254 MB]

After downloading the tar.gz files just unpack them in the '''YAMBO_TUTORIALS''' folder. For example
$ mkdir YAMBO_TUTORIALS
$ mv hBN.tar.gz YAMBO_TUTORIALS
$ cd YAMBO_TUTORIALS
$ tar -xvfz hBN.tar.gz
$ ls YAMBO_TUTORIALS
hBN

(Advanced users can download and install all tutorial files using git. See the main [[Tutorials#Files|Tutorial Files]] page.)

==DFT calculation of bulk hBN and conversion to Yambo==

In this module you will learn how to generate the Yambo ''SAVE'' folder for bulk hBN starting from a PWscf calculation.



=== Conversion to Yambo format ===
The PWscf ''bBN.save'' output is converted to the Yambo format using the <code>p2y</code> executable (pwscf to yambo), found in the yambo ''bin'' directory.
Enter ''hBN.save'' and launch <code>p2y</code>:

$ cd hBN.save
$ p2y
...
<---> DBs path set to .
<---> Index file set to data-file.xml
<---> Header/K-points/Energies... done
...
<---> == DB1 (Gvecs and more) ...
<---> ... Database done
<---> == DB2 (wavefunctions) ... done ==
<---> == DB3 (PseudoPotential) ... done ==
<---> == P2Y completed ==

This output repeats some information about the system and generates a ''SAVE'' directory:
$ ls SAVE
ns.db1 ns.wf ns.kb_pp_pwscf
ns.wf_fragments_1_1 ...
ns.kb_pp_pwscf_fragment_1 ...
These files, with an ''n'' prefix, indicate that they are in netCDF format, and thus not human readable. However, they are perfectly transferable across different architectures. You can check that the databases contain the information you expect by launching Yambo using the <code>-D</code> option:

$ yambo -D
[RD./SAVE//ns.db1]------------------------------------------
Bands : 100
K-points : 14
G-vectors [RL space]: 8029
Components [wavefunctions]: 1016
...
[RD./SAVE//ns.wf]-------------------------------------------
Fragmentation :yes
...
[RD./SAVE//ns.kb_pp_pwscf]----------------------------------
Fragmentation :yes
- S/N 006626 -------------------------- v.04.01.02 r.00000 -

In practice we suggest to move the ''SAVE'' folder into a new clean folder.

In this tutorial however, we ask instead that you continue using a ''SAVE'' folder that we prepared previously:
$ cd ../../YAMBO
$ ls
SAVE

==Initialization of Yambo databases==
Use the ''SAVE'' folders that are already provided, rather than any ones you may have generated previously.

Every Yambo run '''must''' start with this step. Go to the folder ''containing'' the hBN-bulk <code>SAVE</code> directory:
$ cd YAMBO_TUTORIALS/hBN/YAMBO
$ ls
SAVE

'''TIP''': do not run yambo from ''inside'' the <code>SAVE</code> folder!
'''This is the wrong way .. '''
$ cd SAVE
$ yambo
yambo: cannot access CORE database (SAVE/*db1 and/or SAVE/*wf)
In fact, if you ever see such message:
it usually means you are trying to launch Yambo '''from the wrong place'''.
$ cd ..

Now you are in the proper place and
$ ls
SAVE
you can simply launch the code
$ yambo
This will run the initialization (setup) ''runlevel''.

===Run-time output===
This is typically written to standard output (on screen) and tracks the progress of the run in real time:
<---> [01] MPI/OPENMP structure, Files & I/O Directories
<---> [02] CORE Variables Setup
<---> [02.01] Unit cells
<---> [02.02] Symmetries
<---> [02.03] Reciprocal space
<---> Shells finder |########################################| [100%] --(E) --(X)
<---> [02.04] K-grid lattice
<---> Grid dimensions : 6 6 2
<---> [02.05] Energies & Occupations
<---> [03] Transferred momenta grid and indexing
<---> BZ -> IBZ reduction |########################################| [100%] --(E) --(X)
<---> [03.01] X indexes
<---> X [eval] |########################################| [100%] --(E) --(X)
<---> X[REDUX] |########################################| [100%] --(E) --(X)
<---> [03.01.01] Sigma indexes
<---> Sigma [eval] |########################################| [100%] --(E) --(X)
<---> Sigma[REDUX] |########################################| [100%] --(E) --(X)
<---> [04] Timing Overview
<---> [05] Memory Overview
<---> [06] Game Over & Game summary
Specific runlevels are indicated with numeric labels like [02.02]. 
The hashes (#) indicate progress of the run in Wall Clock time, indicating the elapsed (E) and expected (X) time to complete a runlevel, and the percentage of the task complete.

===New core databases===
New databases appear in the ''SAVE'' folder:
$ ls SAVE
ns.db1 ns.wf ns.kb_pp_pwscf '''ndb.gops ndb.kindx'''
ns.wf_fragments_1_1 ...
ns.kb_pp_pwscf_fragment_1 ...
These contain information about the ''G''-vector shells and ''k/q''-point meshes as defined by the DFT calculation.

In general: a database called ''n'''s'''.xxx'' is a ''static'' database, generated once by <code>p2y</code>, while databases called ''n'''db'''.xxx'' are ''dynamically'' generated while you use <code>yambo</code>.

'''TIP''': if you launch <code>yambo</code>, but it does not seem to do anything, check that these files are present.

===Report file===
A report file ''r_setup'' is generated in the run directory.
This mostly reports information about the ground state system as defined by the DFT run, but also adds information about the band gaps, occupations, shells of G-vectors, IBZ/BZ grids, the CPU structure (for parallel runs), and so on. Some points of note:

Up to Yambo version 4.5
[02.03] RL shells
=================
Shells, format: [S#] G_RL(mHa)
[S453]:8029(0.7982E+5) [S452]:8005(0.7982E+5) [S451]:7981(0.7982E+5) [S450]:7957(0.7942E+5)
...
[S4]:11( 1183.) [S3]:5( 532.5123) [S2]:3( 133.1281) [S1]:1( 0.000000)

From Yambo version 5.0
[02.03] Reciprocal space
========================

nG shells : 217
nG charge : 3187
nG WFs : 1477
nC WFs : 1016
G-vecs. in first 21 shells: [ Number ]
1 3 5 11 13 25 37 39 51
63 65 71 83 95 107 113 125 127
139 151 163
...
Shell energy in first 21 shells: [ mHa ]
0.00000 133.128 532.512 1183.37 1198.15 1316.50 1715.88 2130.05 2381.52
3313.42 3328.20 3550.11 3683.24 4082.62 4511.57 4733.48 4748.27 4792.61
4866.61 5266.00 5680.16
...

This reports the set of closed reciprocal lattice (RL) shells defined internally that contain G-vectors with the same modulus.
The highest number of RL vectors we can use is 8029. Yambo will always redefine any input variable in RL units to the nearest closed shell.

Up to Yambo version 4.5
[02.05] Energies [ev] & Occupations
===================================
Fermi Level [ev]: 5.112805
VBM / CBm [ev]: 0.000000 3.876293
Electronic Temp. [ev K]: 0.00 0.00
Bosonic Temp. [ev K]: 0.00 0.00
El. density [cm-3]: 0.460E+24
States summary : Full Metallic Empty
0001-0008 0009-0100
Indirect Gaps [ev]: 3.876293 7.278081
Direct Gaps [ev]: 4.28829 11.35409
X BZ K-points : 72

From Yambo version 5.0
[02.05] Energies & Occupations
==============================

[X] === General ===
[X] Electronic Temperature : 0.000000 0.000000 [eV K]
[X] Bosonic Temperature : 0.000000 0.000000 [eV K]
[X] Finite Temperature mode : no
[X] El. density : 0.46037E+24 [cm-3]
[X] Fermi Level : 5.110835 [eV]

[X] === Gaps and Widths ===
[X] Conduction Band Min : 3.877976 [eV]
[X] Valence Band Max : 0.000000 [eV]
[X] Filled Bands : 8
[X] Empty Bands : 9 100
[X] Direct Gap : 4.289853 [eV]
[X] Direct Gap localized at k-point : 7
[X] Indirect Gap : 3.877976 [eV]
[X] Indirect Gap between k-points : 14 7
[X] Last valence band width : 3.401086 [eV]
[X] 1st conduction band width : 4.266292 [eV]

Yambo recalculates again the Fermi level (close to the value of 5.06 noted in the PWscf SCF calculation). From here on, however, the Fermi level is set to zero, and other eigenvalues are shifted accordingly. The system is insulating (8 filled, 92 empty) with an indirect band gap of 3.87 eV. The minimum and maximum direct and indirect gaps are indicated. There are 72 k-points in the full BZ, generated using symmetry from the 14 k-points in our user-defined grid.

'''TIP''': You should inspect the report file after ''every'' run for errors and warnings.

===Different ways of running yambo===
We just run Yambo interactively.

Let's try to re-run the setup with the command
$ nohup yambo &
$ ls
l_setup nohup.out r_setup r_setup_01 SAVE

If Yambo is launched using a script, or as a background process, or in parallel, this output will appear in a log file prefixed by the letter ''l'', in this case as ''l_setup''.
If this log file already exists from a previous run, it will not be overwritten. Instead, a new file will be created with an incrementing numerical label, e.g. ''l_setup_01, l_setup_02'', etc. '''This applies to all files created by Yambo'''. Here we see that l_setup was created for the first time, but r_setup already existed from the previous run, so now we have r_setup_01
If you check the differences between the two you will notice that in the second run yambo is reading the previously created ndb.kindx in place of re-computing the indexes.
Indeed the output inside l_setup does not show the timing for X and Sigma

As a last step we run the setup in parallel, but first we delete the ndb.kindx file
$ rm SAVE/ndb.kindx
$ mpirun -np 4 yambo
$ ls
LOG l_setup nohup.out r_setup r_setup_01 r_setup_02 SAVE
There is now r_setup_02
In the case of parallel runs, CPU-dependent log files will appear inside a ''LOG'' folder, e.g.
$ ls LOG
l_setup_CPU_1 l_setup_CPU_2 l_setup_CPU_3 l_setup_CPU_4
This behaviour can be controlled at runtime - see the Parallel tutorial for details.

===2D hBN===
Simply repeat the steps above. Go to the folder ''containing'' the hBN-sheet ''SAVE'' directory and launch <code>yambo</code>:
$ cd TUTORIALS/hBN-2D/YAMBO
$ ls
SAVE
$ yambo
Again, inspect the ''r_setup'' file, output logs, and verify that ''ndb.gops'' and ''ndb.kpts'' have been created inside the SAVE folder.

You are now ready to use Yambo!

==Yambo's command line interface==
Yambo uses a command line interface to select tasks, generate input files, and control the runtime behaviour.

In this module you will learn how to select tasks, generate and modify input files, and control the runtime behaviour by using Yambo's command line interface.


=== Input file generator ===
First, move to the appropriate folder and initialize the Yambo databases if you haven't already done so.
$ cd YAMBO_TUTORIALS/hBN/YAMBO
$ yambo ''(initialize)''

Yambo generates its own input files: you just tell the code what you want to calculate by launching Yambo along with one or more options.
To see the list of possible options, run <code>yambo -h</code> (we report here only the part we are focusing in)
$ yambo -h
'A shiny pot of fun and happiness [C.D.Hogan]'

This is : yambo
Version : 5.0.1 Revision 19547 Hash e90d90f2d
Configuration: MPI+OpenMP+SLK+SLEPC+HDF5_MPI_IO

...

Initializations:
-setup (-i) :Initialization
-coulomb (-r) :Coulomb potential

Response Functions:
-optics (-o) <string> :Linear Response optical properties (more with -h optics)
-X (-d) <string> :Inverse Dielectric Matrix (more with -h X)
-dipoles (-q) :Oscillator strenghts (or dipoles)
-kernel (-k) <string> :Kernel (more with -h kernel)

Self-Energy:
-hf (-x) :Hartree-Fock
-gw0 (-p) <string> :GW approximation (more with -h gw0)
-dyson (-g) <string> :Dyson Equation solver (more with -h dyson)
-lifetimes (-l) :GoWo Quasiparticle lifetimes

Bethe-Salpeter Equation:
-Ksolver (-y) <string> :BSE solver (more with -h Ksolver)

Total Energy:
-acfdt :ACFDT Total Energy

Utilites:
...
-slktest :ScaLapacK test

The options can be split into two sets: 
* A set of options which is needed to generate the appropriate input file (default name: ''yambo.in'') selecting the kind of simulation you would like to perform 
* A set of options which can be used to manage auxiliary functions (like redirect the I/O, choose a specific name for the input file, etc ..).

===Runlevel selection===
First of all, you would like to specify which kind of simulation you are going to perform and generate an input file with the first set of options.
By default, when generating the input file, Yambo will launch the <code>vi</code> editor.
Editor choice can be changed when launching the configure before compilation; alternatively you can use the <code>-Q</code> run time option to skip the automatic editing (do this if you are not familiar with <code>vi</code>!):
$ yambo -hf -Q
yambo: input file yambo.in created
$ emacs yambo.in ''or your favourite editing tool''

Multiple options can be used together to activate various tasks or runlevels (in some cases this is actually a necessity).
For instance, to generate an input file for optical spectra including local field effects (Hartree approximation), do (and then exit)
$ yambo -optics c -kernel hartree ''which switches on:''
optics # [R OPT] Optics
chi # [R CHI] Dyson equation for Chi.
Chimod= "Hartree" # [X] IP/Hartree/ALDA/LRC/BSfxc
To perform a Hartree-Fock and GW calculation using a plasmon-pole approximation, do (and then exit):
$ yambo -hf -gw0 p -dyson n ''which switches on:''
HF_and_locXC # [R XX] Hartree-Fock Self-energy and Vxc
gw0 # [R GW] GoWo Quasiparticle energy levels
ppa # [R Xp] Plasmon Pole Approximation
em1d # [R Xd] Dynamical Inverse Dielectric Matrix
Each runlevel activates its own list of variables and flags.

The previous command is also equivalent to
$ yambo -hf -gw0 r -dyson n -X p

===Changing input parameters ===
Yambo reads various parameters from existing database files and/or input files and uses them to suggest values or ranges.
Let's illustrate this by generating the input file for a Hartree-Fock calculation.

$ yambo -hf
Inside the generated input file you should find:
[[Variables#EXXRLvcs|EXXRLvcs]] = 3187 RL # [XX] Exchange RL components
%[[Variables#QPkrange|QPkrange]] # [GW] QP generalized Kpoint/Band indices
1| 14| 1|100|
%
The <code>[[Variables#QPkrange|QPkrange]]</code> variable (follow the link for a "detailed" explanation for any variable) suggests a range of k-points (1 to 14) and bands (1 to 100) based on what it finds in the core database ''SAVE/ns.db1'', i.e. as defined by the DFT code. 
Leave that variable alone, and instead modify the previous variable to <code>EXXRLvcs= 1000 RL</code>

Save the file, and now generate the input a second time with <code>yambo -x</code>. You will see:
[[Variables#EXXRLvcs|EXXRLvcs]]= 1009 RL
This indicates that Yambo has read the new input value (1000 G-vectors), checked the database of G-vector shells ''(SAVE/ndb.gops)'',
and changed the input value to one that fits a completely closed shell.

Last, note that Yambo variables can be expressed in different '''units'''. In this case, <code>RL</code> can be replaced by an energy unit like Ry, eV, Ha, etc. Energy units are generally better as they are independent of the cell size. Technical information is available on the [[Variables]] page.

The input file generator of Yambo is thus an ''intelligent'' parser, which interacts with the user and the existing databases. For this reason we recommend that you always use Yambo to generate the input files, rather than making them yourself.

===Extra options===
Extra options modify some of the code's default settings. They can be used when launching the code but also when generating input files.

Let's have a look again to the possible options (we report here only the part we are focusing in):
$ yambo -h
This is : yambo
Version : 5.0.1 Revision 19547 Hash e90d90f2d
Configuration: MPI+OpenMP+SLK+SLEPC+HDF5_MPI_IO

Help & version:
-help (-h) <string> :<string> can be an option (e.g. -h optics)
-version :Code version & libraries

Input file & Directories:
-Input (-F) <string> :Input file
-Verbosity (-V) <string> :Input file variables verbosity (more with -h Verbosity)
-Job (-J) <string> :Job string
-Idir (-I) <string> :Input directory
-Odir (-O) <string> :I/O directory
-Cdir (-C) <string> :Communication directory

Parallel Control:
-parenv (-E) <string> :Environment Parallel Variables file
-nompi :Switch off MPI support
-noopenmp :Switch off OPENMP support

...

Utilites:
-Quiet (-Q) :Quiet input file creation
-fatlog :Verbose (fatter) log(s)
-DBlist (-D) :Databases properties
...

Command line options are extremely important to master if you want to use yambo productively.
Often, the meaning is clear from the help menu:
$ yambo -F yambo.in_HF -hf ''Make a Hartree-Fock input file called yambo.in_HF''
$ yambo -D ''Summarize the content of the databases in the SAVE folder''
$ yambo -I ../ ''Run the code, using a SAVE folder in a directory one level up''
$ yambo -C MyTest ''Run the code, putting all report, log, plot files inside a folder MyTest''

Other options deserve a closer look.

===Verbosity===
Yambo uses ''many'' input variables, many of which can be left at their default values. To keep input files short and manageable, only a few variables appear by default in the inout file. More advanced variables can be switched on by using the <code>-V</code> verbosity option. These are grouped according to the type of variable. For instance, <code>-V RL</code> switches on variables related to G vector summations, and <code>-V io</code> switches on options related to I/O control. Try:

$ yambo -optics c -V RL ''switches on:''
FFTGvecs= 3951 RL # [FFT] Plane-waves

$ yambo -optics c -V io ''switches on:''
StdoHash= 40 # [IO] Live-timing Hashes
DBsIOoff= "none" # [IO] Space-separated list of DB with NO I/O. DB= ...
DBsFRAGpm= "none" # [IO] Space-separated list of +DB to be FRAG and ...
#WFbuffIO # [IO] Wave-functions buffered I/O

Unfortunately, -V options must be invoked and changed ''one at a time''. When you are more expert, you may go straight to <code>-V all</code>, which turns on all possible variables. However note that <code>yambo -o c -V all</code> adds an extra 30 variables to the input file, which can be confusing: use it with care.

===Job script label===
The best way to keep track of different runs using different parameters is through the <code>-J</code> flag. This inserts a label in all output and report files, and creates a new folder containing any new databases (i.e. they are not written in the core ''SAVE'' folder). Try:
$ yambo -J 1Ry -V RL -hf -F yambo_hf.in ''and modify to''
FFTGvecs = 1 Ry
EXXGvecs = 1 Ry
$ yambo -J 1Ry -F yambo_hf.in ''Run the code''
$ ls
yambo_hf.in SAVE
o-1Ry.hf r-1Ry_HF_and_locXC 1Ry 1Ry/ndb.HF_and_locXC
This is extremely useful when running convergence tests, trying out different parameters, etc.

''Exercise'': use <code>yambo</code> to report the properties of all database files (including ''ndb.HF_and_locXC'')

First steps: walk through from DFT(standalone)

2021-04-02T11:31:52Z

Maurizia: /* Allowed options */

In this tutorial you will learn how to calculate optical spectra using Yambo, starting from a DFT calculation and ending with a look at local field effects in the optical response.

== System characteristics ==
We will use a 3D system (bulk hBN) and a 2D system (hBN sheet).

[[File:HBN-bulk-3x3-annotated.png|x200px|Atomic structure of bulk hBN]]
[[File:HBN2.png|x200px|Atomic structure of 2D hBN]]

'''Hexagonal boron nitride - hBN''':
* HCP lattice, ABAB stacking
* Four atoms per cell, B and N (16 electrons)
* Lattice constants: ''a'' = 4.716 [a.u.], ''c/a'' = 2.582
* Plane wave cutoff 40 Ry (~1500 RL vectors in wavefunctions)
* SCF run: shifted ''6x6x2'' grid (12 k-points) with 8 bands
* Non-SCF run: gamma-centred ''6x6x2'' (14 k-points) grid with 100 bands

=== Prerequisites ===
'''You will need''':
* PWSCF input files and pseudopotentials for hBN bulk
* <code>pw.x</code> executable, version 5.0 or later
* <code>p2y</code> and <code>yambo</code> executables
* <code>gnuplot</code> for plotting spectra

==Download the Files==

Download and unpack the followint files:
[http://www.yambo-code.org/educational/tutorials/files/hBN.tar.gz hBN.tar.gz] [15 MB],
[http://www.yambo-code.org/educational/tutorials/files/hBN-2D.tar.gz hBN-2D.tar.gz] [8,6 MB]

In the next days you will also use this file which you may like to download now
[http://www.yambo-code.org/educational/tutorials/files/hBN-convergence-kpoints.tar.gz hBN-convergence-kpoints.tar.gz] [254 MB]

After downloading the tar.gz files just unpack them in the '''YAMBO_TUTORIALS''' folder. For example
$ mkdir YAMBO_TUTORIALS
$ mv hBN.tar.gz YAMBO_TUTORIALS
$ cd YAMBO_TUTORIALS
$ tar -xvfz hBN.tar.gz
$ ls YAMBO_TUTORIALS
hBN

(Advanced users can download and install all tutorial files using git. See the main [[Tutorials#Files|Tutorial Files]] page.)

==DFT calculation of bulk hBN and conversion to Yambo==

In this module you will learn how to generate the Yambo ''SAVE'' folder for bulk hBN starting from a PWscf calculation.



=== Conversion to Yambo format ===
The PWscf ''bBN.save'' output is converted to the Yambo format using the <code>p2y</code> executable (pwscf to yambo), found in the yambo ''bin'' directory.
Enter ''hBN.save'' and launch <code>p2y</code>:

$ cd hBN.save
$ p2y
...
<---> DBs path set to .
<---> Index file set to data-file.xml
<---> Header/K-points/Energies... done
...
<---> == DB1 (Gvecs and more) ...
<---> ... Database done
<---> == DB2 (wavefunctions) ... done ==
<---> == DB3 (PseudoPotential) ... done ==
<---> == P2Y completed ==

This output repeats some information about the system and generates a ''SAVE'' directory:
$ ls SAVE
ns.db1 ns.wf ns.kb_pp_pwscf
ns.wf_fragments_1_1 ...
ns.kb_pp_pwscf_fragment_1 ...
These files, with an ''n'' prefix, indicate that they are in netCDF format, and thus not human readable. However, they are perfectly transferable across different architectures. You can check that the databases contain the information you expect by launching Yambo using the <code>-D</code> option:

$ yambo -D
[RD./SAVE//ns.db1]------------------------------------------
Bands : 100
K-points : 14
G-vectors [RL space]: 8029
Components [wavefunctions]: 1016
...
[RD./SAVE//ns.wf]-------------------------------------------
Fragmentation :yes
...
[RD./SAVE//ns.kb_pp_pwscf]----------------------------------
Fragmentation :yes
- S/N 006626 -------------------------- v.04.01.02 r.00000 -

In practice we suggest to move the ''SAVE'' folder into a new clean folder.

In this tutorial however, we ask instead that you continue using a ''SAVE'' folder that we prepared previously:
$ cd ../../YAMBO
$ ls
SAVE

==Initialization of Yambo databases==
Use the ''SAVE'' folders that are already provided, rather than any ones you may have generated previously.

Every Yambo run '''must''' start with this step. Go to the folder ''containing'' the hBN-bulk <code>SAVE</code> directory:
$ cd YAMBO_TUTORIALS/hBN/YAMBO
$ ls
SAVE

'''TIP''': do not run yambo from ''inside'' the <code>SAVE</code> folder!
'''This is the wrong way .. '''
$ cd SAVE
$ yambo
yambo: cannot access CORE database (SAVE/*db1 and/or SAVE/*wf)
In fact, if you ever see such message:
it usually means you are trying to launch Yambo '''from the wrong place'''.
$ cd ..

Now you are in the proper place and
$ ls
SAVE
you can simply launch the code
$ yambo
This will run the initialization (setup) ''runlevel''.

===Run-time output===
This is typically written to standard output (on screen) and tracks the progress of the run in real time:
<---> [01] MPI/OPENMP structure, Files & I/O Directories
<---> [02] CORE Variables Setup
<---> [02.01] Unit cells
<---> [02.02] Symmetries
<---> [02.03] Reciprocal space
<---> Shells finder |########################################| [100%] --(E) --(X)
<---> [02.04] K-grid lattice
<---> Grid dimensions : 6 6 2
<---> [02.05] Energies & Occupations
<---> [03] Transferred momenta grid and indexing
<---> BZ -> IBZ reduction |########################################| [100%] --(E) --(X)
<---> [03.01] X indexes
<---> X [eval] |########################################| [100%] --(E) --(X)
<---> X[REDUX] |########################################| [100%] --(E) --(X)
<---> [03.01.01] Sigma indexes
<---> Sigma [eval] |########################################| [100%] --(E) --(X)
<---> Sigma[REDUX] |########################################| [100%] --(E) --(X)
<---> [04] Timing Overview
<---> [05] Memory Overview
<---> [06] Game Over & Game summary
Specific runlevels are indicated with numeric labels like [02.02]. 
The hashes (#) indicate progress of the run in Wall Clock time, indicating the elapsed (E) and expected (X) time to complete a runlevel, and the percentage of the task complete.

===New core databases===
New databases appear in the ''SAVE'' folder:
$ ls SAVE
ns.db1 ns.wf ns.kb_pp_pwscf '''ndb.gops ndb.kindx'''
ns.wf_fragments_1_1 ...
ns.kb_pp_pwscf_fragment_1 ...
These contain information about the ''G''-vector shells and ''k/q''-point meshes as defined by the DFT calculation.

In general: a database called ''n'''s'''.xxx'' is a ''static'' database, generated once by <code>p2y</code>, while databases called ''n'''db'''.xxx'' are ''dynamically'' generated while you use <code>yambo</code>.

'''TIP''': if you launch <code>yambo</code>, but it does not seem to do anything, check that these files are present.

===Report file===
A report file ''r_setup'' is generated in the run directory.
This mostly reports information about the ground state system as defined by the DFT run, but also adds information about the band gaps, occupations, shells of G-vectors, IBZ/BZ grids, the CPU structure (for parallel runs), and so on. Some points of note:

[02.03] RL shells
=================
Shells, format: [S#] G_RL(mHa)
[S453]:8029(0.7982E+5) [S452]:8005(0.7982E+5) [S451]:7981(0.7982E+5) [S450]:7957(0.7942E+5)
...
[S4]:11( 1183.) [S3]:5( 532.5123) [S2]:3( 133.1281) [S1]:1( 0.000000)

This reports the set of closed reciprocal lattice (RL) shells defined internally that contain G-vectors with the same modulus.
The highest number of RL vectors we can use is 8029. Yambo will always redefine any input variable in RL units to the nearest closed shell.

[02.05] Energies [ev] & Occupations
===================================
Fermi Level [ev]: 5.112805
VBM / CBm [ev]: 0.000000 3.876293
Electronic Temp. [ev K]: 0.00 0.00
Bosonic Temp. [ev K]: 0.00 0.00
El. density [cm-3]: 0.460E+24
States summary : Full Metallic Empty
0001-0008 0009-0100
Indirect Gaps [ev]: 3.876293 7.278081
Direct Gaps [ev]: 4.28829 11.35409
X BZ K-points : 72

Yambo recalculates again the Fermi level (close to the value of 5.06 noted in the PWscf SCF calculation). From here on, however, the Fermi level is set to zero, and other eigenvalues are shifted accordingly. The system is insulating (8 filled, 92 empty) with an indirect band gap of 3.87 eV. The minimum and maximum direct and indirect gaps are indicated. There are 72 k-points in the full BZ, generated using symmetry from the 14 k-points in our user-defined grid.

'''TIP''': You should inspect the report file after ''every'' run for errors and warnings.

===Different ways of running yambo===
We just run Yambo interactively.

Let's try to re-run the setup with the command
$ nohup yambo &
$ ls
l_setup nohup.out r_setup r_setup_01 SAVE

If Yambo is launched using a script, or as a background process, or in parallel, this output will appear in a log file prefixed by the letter ''l'', in this case as ''l_setup''.
If this log file already exists from a previous run, it will not be overwritten. Instead, a new file will be created with an incrementing numerical label, e.g. ''l_setup_01, l_setup_02'', etc. '''This applies to all files created by Yambo'''. Here we see that l_setup was created for the first time, but r_setup already existed from the previous run, so now we have r_setup_01
If you check the differences between the two you will notice that in the second run yambo is reading the previously created ndb.kindx in place of re-computing the indexes.
Indeed the output inside l_setup does not show the timing for X and Sigma

As a last step we run the setup in parallel, but first we delete the ndb.kindx file
$ rm SAVE/ndb.kindx
$ mpirun -np 4 yambo
$ ls
LOG l_setup nohup.out r_setup r_setup_01 r_setup_02 SAVE
There is now r_setup_02
In the case of parallel runs, CPU-dependent log files will appear inside a ''LOG'' folder, e.g.
$ ls LOG
l_setup_CPU_1 l_setup_CPU_2 l_setup_CPU_3 l_setup_CPU_4
This behaviour can be controlled at runtime - see the Parallel tutorial for details.

===2D hBN===
Simply repeat the steps above. Go to the folder ''containing'' the hBN-sheet ''SAVE'' directory and launch <code>yambo</code>:
$ cd TUTORIALS/hBN-2D/YAMBO
$ ls
SAVE
$ yambo
Again, inspect the ''r_setup'' file, output logs, and verify that ''ndb.gops'' and ''ndb.kpts'' have been created inside the SAVE folder.

You are now ready to use Yambo!

==Yambo's command line interface==
Yambo uses a command line interface to select tasks, generate input files, and control the runtime behaviour.

In this module you will learn how to select tasks, generate and modify input files, and control the runtime behaviour by using Yambo's command line interface.

Command line options are divided into '''uppercase''' and '''lowercase''' options:
* Lowercase: select tasks, generate input files, and (by default) launch a file editor
* Uppercase: modify Yambo's default settings, at run time and when generating input files
Lowercase and uppercase options can be used together.

=== Input file generator ===
First, move to the appropriate folder and initialize the Yambo databases if you haven't already done so.
$ cd YAMBO_TUTORIALS/hBN/YAMBO
$ yambo ''(initialize)''

Yambo generates its own input files: you just tell the code what you want to calculate by launching Yambo along with one or more '''lowercase''' options.

====Allowed options====
To see the list of runlevels and options, run <code>yambo -h</code> or better,
$ yambo -h
This is yambo 4.4.0 rev.148
A shiny pot of fun and happiness [C.D.Hogan]
-h :Short Help
-H :Long Help
-J <opt> :Job string identifier
-V <opt> :Input file verbosity[opt=RL,kpt,sc,qp,io,gen,resp,all,par]
-F <opt> :Input file
-I <opt> :Core I/O directory
-O <opt> :Additional I/O directory
-C <opt> :Communications I/O directory
-D :DataBases properties
-W <opt> :Wall Time limitation (1d2h30m format)
-Q :Don't launch the text editor
-E <opt> :Environment Parallel Variables file
-M :Switch-off MPI support (serial run)
-N :Switch-off OpenMP support (single thread run)
-i :Initialization
-o <opt> :Optics [opt=(c)hi is (G)-space / (b)se is (eh)-space ]
-k <opt> :Kernel [opt=hartree/alda/lrc/hf/sex](hf/sex only eh-space; lrc only G-space)
-y <opt> :BSE solver [opt=h/d/s/(p/f)i](h)aydock/(d)iagonalization/(i)nversion
-r :Coulomb potential
-x :Hartree-Fock Self-energy and local XC
-d :Dynamical Inverse Dielectric Matrix
-b :Static Inverse Dielectric Matrix
-p <opt> :GW approximations [opt=(p)PA/(c)HOSEX]
-g <opt> :Dyson Equation solver[opt=(n)ewton/(s)ecant/(g)reen]
-l :GoWo Quasiparticle lifetimes
-a :ACFDT Total Energy
-s :ScaLapacK test

Any time you launch Yambo with a lowercase option, Yambo will generate the appropriate input file (default name: ''yambo.in'') and launch the <code>vi</code> editor.

Editor choice can be changed at configure; alternatively you can use the <code>-Q</code> run time option to skip the automatic editing (do this if you are not familiar with <code>vi</code>!):
$ yambo -x -Q
yambo: input file yambo.in created
$ emacs yambo.in ''or your favourite editing tool''

====Combining options====
Multiple options can be used together to activate various tasks or runlevels (in some cases this is actually a necessity).
For instance, to generate an input file for optical spectra including local field effects (Hartree approximation), do (and then exit)
$ yambo -o c -k hartree ''which switches on:''
optics # [R OPT] Optics
chi # [R CHI] Dyson equation for Chi.
Chimod= "Hartree" # [X] IP/Hartree/ALDA/LRC/BSfxc
To perform a Hartree-Fock and GW calculation using a plasmon-pole approximation, do (and then exit):
$ yambo -x -g n -p p ''which switches on:''
HF_and_locXC # [R XX] Hartree-Fock Self-energy and Vxc
gw0 # [R GW] GoWo Quasiparticle energy levels
ppa # [R Xp] Plasmon Pole Approximation
em1d # [R Xd] Dynamical Inverse Dielectric Matrix
Each runlevel activates its own list of variables and flags.

===Changing input parameters ===
Yambo reads various parameters from existing database files and/or input files and uses them to suggest values or ranges.
Let's illustrate this by generating the input file for a Hartree-Fock calculation.

$ yambo -x
Inside the generated input file you should find:
[[Variables#EXXRLvcs|EXXRLvcs]] = 3187 RL # [XX] Exchange RL components
%[[Variables#QPkrange|QPkrange]] # [GW] QP generalized Kpoint/Band indices
1| 14| 1|100|
%
The <code>[[Variables#QPkrange|QPkrange]]</code> variable (follow the link for a "detailed" explanation for any variable) suggests a range of k-points (1 to 14) and bands (1 to 100) based on what it finds in the core database ''SAVE/ns.db1'', i.e. as defined by the DFT code. 
Leave that variable alone, and instead modify the previous variable to <code>EXXRLvcs= 1000 RL</code>

Save the file, and now generate the input a second time with <code>yambo -x</code>. You will see:
[[Variables#EXXRLvcs|EXXRLvcs]]= 1009 RL
This indicates that Yambo has read the new input value (1000 G-vectors), checked the database of G-vector shells ''(SAVE/ndb.gops)'',
and changed the input value to one that fits a completely closed shell.

Last, note that Yambo variables can be expressed in different '''units'''. In this case, <code>RL</code> can be replaced by an energy unit like Ry, eV, Ha, etc. Energy units are generally better as they are independent of the cell size. Technical information is available on the [[Variables]] page.

The input file generator of Yambo is thus an ''intelligent'' parser, which interacts with the user and the existing databases. For this reason we recommend that you always use Yambo to generate the input files, rather than making them yourself.

===Uppercase options===
Uppercase options modify some of the code's default settings. They can be used when launching the code but also when generating input files.

====Allowed options====
To see the list of options, again do:
$ yambo -H
Tool: yambo 4.1.2 rev.14024
Description: A shiny pot of fun and happiness [C.D.Hogan]
-J <opt> :Job string identifier
-V <opt> :Input file verbosity
[opt=RL,kpt,sc,qp,io,gen,resp,all,par]
-F <opt> :Input file
-I <opt> :Core I/O directory
-O <opt> :Additional I/O directory
-C <opt> :Communications I/O directory
-D :DataBases properties
-W <opt> :Wall Time limitation (1d2h30m format)
-Q :Don't launch the text editor
-M :Switch-off MPI support (serial run)
-N :Switch-off OpenMP support (single thread run)
[Lower case options]

Command line options are extremely important to master if you want to use yambo productively.
Often, the meaning is clear from the help menu:
$ yambo -F yambo.in_HF -x ''Make a Hartree -Fock input file called yambo.in_HF''
$ yambo -D ''Summarize the content of the databases in the SAVE folder''
$ yambo -I ../ ''Run the code, using a SAVE folder in a directory one level up''
$ yambo -C MyTest ''Run the code, putting all report, log, plot files inside a folder MyTest''

Other options deserve a closer look.
===Verbosity===
Yambo uses ''many'' input variables, many of which can be left at their default values. To keep input files short and manageable, only a few variables appear by default in the inout file. More advanced variables can be switched on by using the <code>-V</code> verbosity option. These are grouped according to the type of variable. For instance, <code>-V RL</code> switches on variables related to G vector summations, and <code>-V io</code> switches on options related to I/O control. Try:

$ yambo -o c -V RL ''switches on:''
FFTGvecs= 3951 RL # [FFT] Plane-waves

$ yambo -o c -V io ''switches on:''
StdoHash= 40 # [IO] Live-timing Hashes
DBsIOoff= "none" # [IO] Space-separated list of DB with NO I/O. DB= ...
DBsFRAGpm= "none" # [IO] Space-separated list of +DB to be FRAG and ...
#WFbuffIO # [IO] Wave-functions buffered I/O

Unfortunately, -V options must be invoked and changed ''one at a time''. When you are more expert, you may go straight to <code>-V all</code>, which turns on all possible variables. However note that <code>yambo -o c -V all</code> adds an extra 30 variables to the input file, which can be confusing: use it with care.

===Job script label===
The best way to keep track of different runs using different parameters is through the <code>-J</code> flag. This inserts a label in all output and report files, and creates a new folder containing any new databases (i.e. they are not written in the core ''SAVE'' folder). Try:
$ yambo -J 1Ry -V RL -x ''and modify to''
FFTGvecs = 1 Ry
EXXGvecs = 1 Ry
$ yambo -J 1Ry ''Run the code''
$ ls
yambo.in SAVE
o-1Ry.hf r-1Ry_HF_and_locXC 1Ry 1Ry/ndb.HF_and_locXC
This is extremely useful when running convergence tests, trying out different parameters, etc.

''Exercise'': use <code>yambo</code> to report the properties of all database files (including ''ndb.HF_and_locXC'')

Bethe-Salpeter solver: diagonalization

2020-01-29T14:12:44Z

Maurizia: /* Prerequisites */

In this module you learn how to obtain an optical absorption spectra within the Bethe-Salpeter equation (BSE) framework by diagonalizing a previously calculated Bethe-Salpeter (BS) kernel.

==Prerequisites==
[[File:Yambo-handbook-v4.1.2-p-15.png|thumb|Cheatsheet on BSS diagonalization|150px]]
* You must first complete the [[Static screening]] and [[Bethe-Salpeter kernel]] modules

'''You will need''':
* The <code>SAVE</code> databases for 3D hBN
* The <code>3D_QP_BSE</code> directory (provided) which contains the database with the GW corrections (create one directory with this name and put the ndb.QP file produced yesterday there)
* The <code>3D_BSE</code> directory containing the databases from the [[Static screening]] and [[Bethe-Salpeter kernel]] modules
* The <code>yambo</code> executable
* <code>gnuplot</code> for plotting spectra

==Background==
The macroscopic dielectric function (from which the absorption and EEL spectra can be computed) is obtained from the eigenvalues ''E''λ (excitonic energies) and eigenvectors Aλ''cv'''''k''' (exciton composition in terms of electron-hole pairs) of the two-particle Hamiltonian:

[[File:BSE1-Eq4.png|none|x50px]]

To get the two-particle Hamiltonian eigensolutions you need to diagonalize the two-particle Hamiltonian (non spin-polarized case):

[[File:BSE1-Eq1.png|none|x50px]]

for which the ''2V - W'' part was evaluated in the [[Bethe-Salpeter kernel]] module.

The difference of quasiparticle energies ''Δεcv'''k'''= εc'''k''' - εv'''k''''' is added to the matrix just before the solver.
There are two possible choices:
* the Kohn-Sham energies (calculated at DFT level) are corrected through a Scissor and the renormalization of the conduction and valence bandwidth (linearly with respect to the conduction band minimum and the valence band maximum respectively):

''Δεcv'''k'''= Mc(εc'''k'''KS - CBM) - Mv(εv'''k'''KS - VBM) + Scissor''

* the quasiparticle energies calculated at [[How to obtain the quasi-particle band structure of a bulk material: h-BN|GW level]] are used. Missing energies are computed by interpolation.

==Choosing the input parameters==

Invoke yambo with the "-y d" option in the command line:

$ yambo -F 03_3D_BSE_diago_solver.in -y d -V qp -J 3D_BSE

The input is open in the editor. The input variable to be changed are
% [[Variables#BEnRange|BEnRange]]
2.00000 | 8.00000 | eV
%
[[Variables#BEnSteps|BEnSteps]]= 200

which define 200 evenly spaced points between 2 and 8 eV at which the spectrum is calculated (ω in the equation for the macroscopic dielectric function),

% [[Variables#BDmRange|BDmRange]]
0.10000 | 0.10000 | eV
%

which defines the spectral broadening (Lorentzian model),

% [[Variables#BLongDir|BLongDir]]
1.000000 | 1.000000 | 0.000000 |
%

which defines the direction of the perturbing electric field (in this case the in-plane direction).

Another parameter to modify is
% [[Variables#KfnQP_E|KfnQP_E]]
1.440000 | 1.000000 | 1.000000 |
%
This gives the quasiparticle corrections to the Kohn-Sham eigenvalues and is deduced either from experiment or previous [[How to obtain the quasi-particle band structure of a bulk material: h-BN|GW calculations]].
With reference to the equation in the Background, the format is
''Scissor'' | ''Mc'' | ''Mv'' |
The alternative of directly input corrections calculated from a previous GW calculation is shown in the next section.

==Bethe-Salpeter solver runlevel==
$ yambo -F 03_3D_BSE_diago_solver.in -J 3D_BSE
In the log (either in standard output or in l-3d_BSE_optics_bse_bsk_bss), after various setup/loading, the BSE is diagonalized using the linked linear algebra libraries:
<01s> [06] BSE solver(s)
<01s> [LA] SERIAL linear algebra
<01s> [06.01] Diagonalization solver
<01s> BSK diagonalize |########################################| [100%] --(E) --(X)
<01s> EPS residuals |########################################| [100%] --(E) --(X)
<01s> BSK epsilon |########################################| [100%] --(E) --(X)
The report r-3d_BSE_optics_bse_bsk_bss contains information relative to this runlevel in section 6:

[06] BSE solver(s)
==================

Take some time to inspect the log and the report to check the consistency with the input variables. This run produces a new database in the 3D_BSE directory
3D_BSE/ndb.BS_diago_Q01
So if you need the spectrum on a different energy range, direction, with a different broadening or on more points the diagonalization is not repeated, just the spectrum is recalculated.

This run produces as well human readable files (o-*). Specifically o-3D_BSE.eps_q1_diago_bse contains the real and imaginary part of the macroscopic dielectric function

$ less o-3D_BSE.eps_q1_diago_bse
...
#
# E/ev[1] EPS-Im[2] EPS-Re[3] EPSo-Im[4] EPSo-Re[5]
#
2.00000 0.16162 5.83681 0.04959 4.14127
2.03015 0.16787 5.88612 0.05090 4.15638
...

which is in the format
Energy in eV | Imaginary part BSE | Real part BSE |Imaginary part IPA | Real part IPA |

where real and imaginary parts refer to the macroscopic dielectric function. The imaginary part is related to the optical absorption. The latter (column 2) can be plotted versus the photon energy (column 1) and compared with the independent particle approximation (IPA, column 4), e.g.:

$ gnuplot
...
plot 'o-3D_BSE.eps_q1_diago_bse' u 1:2 w l t 'BSE', 'o-3D_BSE.eps_q1_diago_bse' u 1:4 w l t 'IPA'

[[file:03_bse_diago.png |none|600px]]
The addition of the kernel has the effect to red-shift the spectrum onset and to redistribute the oscillator strengths. Note that the convergence with respect to k-points smooths out the low energy peaks in the IPA (which are an artifact of poor convergence with k-points producing an artificial confinement) to give the shoulder corresponding to the van Hove singularity in the band structure. On the other hand the low energy peak in the BSE is genuine and it is the signature of a bound exciton.

==Reading the QP corrections from a previous ''GW'' calculation==
In the above calculation we have used a simple scissor operator to correct the Kohn-Sam DFT energies. In this part we see how we can instead take the corrections from a previous Yambo Gw calculation.
We create and edit the input:
$yambo -F 03_3D_QP_BSE.in -y d -V qp -J 3D_BSE
We set all parameters as in the previous calculation, except for the part regarding the QP correction:
[[Variables#KfnQPdb|KfnQPdb]]= "E < 3D_QP_BSE/ndb.QP" # [EXTQP BSK BSS] Database
[[Variables#KfnQP_N|KfnQP_N]]= 1 # [EXTQP BSK BSS] Interpolation neighbours
% [[Variables#KfnQP_E|KfnQP_E]]
0.000000 | 1.000000 | 1.000000 | # [EXTQP BSK BSS] E parameters (c/v) eV|adim|adim
%
Instead of setting the values for the scissor, we give the path to a database (3D_QP_BSE/ndb.QP) which contains the QP corrections. This has been created by running a GW calculation as in the [[How to obtain the quasi-particle band structure of a bulk material: h-BN |GW tutorial]].
Run Yambo:
$ yambo -F 03_3D_QP_BSE.in -J "3D_QP_BSE,3D_BSE"
This produces the following log in the standard output. Note Section 4 (regarding external QP corrections to the kernel):
<01s> [04.01] External QP corrections (K)
<01s> [QP@K] E<3D_QP_BSE/ndb.QP[ PPA XG:39 Xb:1 40 Scb:1 40]
<01s> [QP] Kpts covered exactly [o/o]: 100.0000
This tells you that the file was found, read correctly and that the '''k''' points found in the file matched the ones you are using for the current calculation (otherwise interpolation would be needed).
It is crucial to check that the file has been read, since if not Yambo gives a warning but continues the calculation (with no QP corrections at all!).
As in the previous calculation the final results of the calculation are the files with the spectral functions. Let's compare the results for the optical absorption spectrum with those obtained previously with a simple scissor:
$ gnuplot
...
plot 'o-3D_QP_BSE.eps_q1_diago_bse' u 1:2 w l t 'Explicit QP', 'o-3D_BSE.eps_q1_diago_bse' u 1:2 w l t 'Scissor'
[[File:03 bse diago qp.png|none|600px]]
It is clear that this makes a difference in the peak distribution and intensity. Note that beside a simple shift you can renormalise as well the bandwidth of the valence and conduction bands in KfnQP_E (respectively the third and second value). You can try as an exercise to set up a new calculation using e.g. 1.440000 | 1.200000 | 0.900000 | for KfnQP_E.

==Summary==
From this tutorial you've learned:
* How to compute the optical spectrum by using the diagonal solver within the Bethe-Salpeter equation framework
* Two alternative ways to provide QP energies (explicitly or via a scissor).

==Links==

* Previous module: [[Bethe-Salpeter kernel]]
* Alternative Bethe-Salpeter equation solver: [[Bethe-Salpeter solver: Lanczos-Haydock | Lanczos-Haydock]]
* Back to [[Calculating optical spectra including excitonic effects: a step-by-step guide]] tutorial
* [[Tutorials|Back to tutorials menu]]
* [[Modules|Back to technical modules menu]]

Bethe-Salpeter solver: diagonalization

2020-01-29T14:12:07Z

Maurizia: /* Prerequisites */

In this module you learn how to obtain an optical absorption spectra within the Bethe-Salpeter equation (BSE) framework by diagonalizing a previously calculated Bethe-Salpeter (BS) kernel.

==Prerequisites==
[[File:Yambo-handbook-v4.1.2-p-15.png|thumb|Cheatsheet on BSS diagonalization|150px]]
* You must first complete the [[Static screening]] and [[Bethe-Salpeter kernel]] modules

'''You will need''':
* The <code>SAVE</code> databases for 3D hBN
* The <code>3D_QP_BSE</code> directory (provided) which contains the database with the GW corrections (create one directory with this name and put the ndb.QP file produced yesterady there)
* The <code>3D_BSE</code> directory containing the databases from the [[Static screening]] and [[Bethe-Salpeter kernel]] modules
* The <code>yambo</code> executable
* <code>gnuplot</code> for plotting spectra

==Background==
The macroscopic dielectric function (from which the absorption and EEL spectra can be computed) is obtained from the eigenvalues ''E''λ (excitonic energies) and eigenvectors Aλ''cv'''''k''' (exciton composition in terms of electron-hole pairs) of the two-particle Hamiltonian:

[[File:BSE1-Eq4.png|none|x50px]]

To get the two-particle Hamiltonian eigensolutions you need to diagonalize the two-particle Hamiltonian (non spin-polarized case):

[[File:BSE1-Eq1.png|none|x50px]]

for which the ''2V - W'' part was evaluated in the [[Bethe-Salpeter kernel]] module.

The difference of quasiparticle energies ''Δεcv'''k'''= εc'''k''' - εv'''k''''' is added to the matrix just before the solver.
There are two possible choices:
* the Kohn-Sham energies (calculated at DFT level) are corrected through a Scissor and the renormalization of the conduction and valence bandwidth (linearly with respect to the conduction band minimum and the valence band maximum respectively):

''Δεcv'''k'''= Mc(εc'''k'''KS - CBM) - Mv(εv'''k'''KS - VBM) + Scissor''

* the quasiparticle energies calculated at [[How to obtain the quasi-particle band structure of a bulk material: h-BN|GW level]] are used. Missing energies are computed by interpolation.

==Choosing the input parameters==

Invoke yambo with the "-y d" option in the command line:

$ yambo -F 03_3D_BSE_diago_solver.in -y d -V qp -J 3D_BSE

The input is open in the editor. The input variable to be changed are
% [[Variables#BEnRange|BEnRange]]
2.00000 | 8.00000 | eV
%
[[Variables#BEnSteps|BEnSteps]]= 200

which define 200 evenly spaced points between 2 and 8 eV at which the spectrum is calculated (ω in the equation for the macroscopic dielectric function),

% [[Variables#BDmRange|BDmRange]]
0.10000 | 0.10000 | eV
%

which defines the spectral broadening (Lorentzian model),

% [[Variables#BLongDir|BLongDir]]
1.000000 | 1.000000 | 0.000000 |
%

which defines the direction of the perturbing electric field (in this case the in-plane direction).

Another parameter to modify is
% [[Variables#KfnQP_E|KfnQP_E]]
1.440000 | 1.000000 | 1.000000 |
%
This gives the quasiparticle corrections to the Kohn-Sham eigenvalues and is deduced either from experiment or previous [[How to obtain the quasi-particle band structure of a bulk material: h-BN|GW calculations]].
With reference to the equation in the Background, the format is
''Scissor'' | ''Mc'' | ''Mv'' |
The alternative of directly input corrections calculated from a previous GW calculation is shown in the next section.

==Bethe-Salpeter solver runlevel==
$ yambo -F 03_3D_BSE_diago_solver.in -J 3D_BSE
In the log (either in standard output or in l-3d_BSE_optics_bse_bsk_bss), after various setup/loading, the BSE is diagonalized using the linked linear algebra libraries:
<01s> [06] BSE solver(s)
<01s> [LA] SERIAL linear algebra
<01s> [06.01] Diagonalization solver
<01s> BSK diagonalize |########################################| [100%] --(E) --(X)
<01s> EPS residuals |########################################| [100%] --(E) --(X)
<01s> BSK epsilon |########################################| [100%] --(E) --(X)
The report r-3d_BSE_optics_bse_bsk_bss contains information relative to this runlevel in section 6:

[06] BSE solver(s)
==================

Take some time to inspect the log and the report to check the consistency with the input variables. This run produces a new database in the 3D_BSE directory
3D_BSE/ndb.BS_diago_Q01
So if you need the spectrum on a different energy range, direction, with a different broadening or on more points the diagonalization is not repeated, just the spectrum is recalculated.

This run produces as well human readable files (o-*). Specifically o-3D_BSE.eps_q1_diago_bse contains the real and imaginary part of the macroscopic dielectric function

$ less o-3D_BSE.eps_q1_diago_bse
...
#
# E/ev[1] EPS-Im[2] EPS-Re[3] EPSo-Im[4] EPSo-Re[5]
#
2.00000 0.16162 5.83681 0.04959 4.14127
2.03015 0.16787 5.88612 0.05090 4.15638
...

which is in the format
Energy in eV | Imaginary part BSE | Real part BSE |Imaginary part IPA | Real part IPA |

where real and imaginary parts refer to the macroscopic dielectric function. The imaginary part is related to the optical absorption. The latter (column 2) can be plotted versus the photon energy (column 1) and compared with the independent particle approximation (IPA, column 4), e.g.:

$ gnuplot
...
plot 'o-3D_BSE.eps_q1_diago_bse' u 1:2 w l t 'BSE', 'o-3D_BSE.eps_q1_diago_bse' u 1:4 w l t 'IPA'

[[file:03_bse_diago.png |none|600px]]
The addition of the kernel has the effect to red-shift the spectrum onset and to redistribute the oscillator strengths. Note that the convergence with respect to k-points smooths out the low energy peaks in the IPA (which are an artifact of poor convergence with k-points producing an artificial confinement) to give the shoulder corresponding to the van Hove singularity in the band structure. On the other hand the low energy peak in the BSE is genuine and it is the signature of a bound exciton.

==Reading the QP corrections from a previous ''GW'' calculation==
In the above calculation we have used a simple scissor operator to correct the Kohn-Sam DFT energies. In this part we see how we can instead take the corrections from a previous Yambo Gw calculation.
We create and edit the input:
$yambo -F 03_3D_QP_BSE.in -y d -V qp -J 3D_BSE
We set all parameters as in the previous calculation, except for the part regarding the QP correction:
[[Variables#KfnQPdb|KfnQPdb]]= "E < 3D_QP_BSE/ndb.QP" # [EXTQP BSK BSS] Database
[[Variables#KfnQP_N|KfnQP_N]]= 1 # [EXTQP BSK BSS] Interpolation neighbours
% [[Variables#KfnQP_E|KfnQP_E]]
0.000000 | 1.000000 | 1.000000 | # [EXTQP BSK BSS] E parameters (c/v) eV|adim|adim
%
Instead of setting the values for the scissor, we give the path to a database (3D_QP_BSE/ndb.QP) which contains the QP corrections. This has been created by running a GW calculation as in the [[How to obtain the quasi-particle band structure of a bulk material: h-BN |GW tutorial]].
Run Yambo:
$ yambo -F 03_3D_QP_BSE.in -J "3D_QP_BSE,3D_BSE"
This produces the following log in the standard output. Note Section 4 (regarding external QP corrections to the kernel):
<01s> [04.01] External QP corrections (K)
<01s> [QP@K] E<3D_QP_BSE/ndb.QP[ PPA XG:39 Xb:1 40 Scb:1 40]
<01s> [QP] Kpts covered exactly [o/o]: 100.0000
This tells you that the file was found, read correctly and that the '''k''' points found in the file matched the ones you are using for the current calculation (otherwise interpolation would be needed).
It is crucial to check that the file has been read, since if not Yambo gives a warning but continues the calculation (with no QP corrections at all!).
As in the previous calculation the final results of the calculation are the files with the spectral functions. Let's compare the results for the optical absorption spectrum with those obtained previously with a simple scissor:
$ gnuplot
...
plot 'o-3D_QP_BSE.eps_q1_diago_bse' u 1:2 w l t 'Explicit QP', 'o-3D_BSE.eps_q1_diago_bse' u 1:2 w l t 'Scissor'
[[File:03 bse diago qp.png|none|600px]]
It is clear that this makes a difference in the peak distribution and intensity. Note that beside a simple shift you can renormalise as well the bandwidth of the valence and conduction bands in KfnQP_E (respectively the third and second value). You can try as an exercise to set up a new calculation using e.g. 1.440000 | 1.200000 | 0.900000 | for KfnQP_E.

==Summary==
From this tutorial you've learned:
* How to compute the optical spectrum by using the diagonal solver within the Bethe-Salpeter equation framework
* Two alternative ways to provide QP energies (explicitly or via a scissor).

==Links==

* Previous module: [[Bethe-Salpeter kernel]]
* Alternative Bethe-Salpeter equation solver: [[Bethe-Salpeter solver: Lanczos-Haydock | Lanczos-Haydock]]
* Back to [[Calculating optical spectra including excitonic effects: a step-by-step guide]] tutorial
* [[Tutorials|Back to tutorials menu]]
* [[Modules|Back to technical modules menu]]

How to treat low dimensional systems

2020-01-21T04:57:23Z

Maurizia: /* Use the truncated coulomb potential in a BSE calculation */

In this tutorial you will learn how to treat low-dimensional material.
A small k-sampling is used to reduce the computational cost/time.
Later on you can repeat this tutorial but using denser k-grids to check the convergence.

== Prerequisites ==

* <code>yambo</code> executable
* <code>ypp</code> executable
* <code>gnuplot</code>, for plotting spectra
* Have Completed the [[First steps: a walk through from DFT to optical properties]] tutorial

==Avoid numerical divergences using the Random Integration Method (RIM)==
In DFT runs of low-dimensional materials low dimensional k-grids are generally used. (i.e. NxNx1 for a 2D sheet perpendicular to the z direction)
This can create numerical problems in the convergence of the many-body (MB) results due to the divergence at small q of the coulomb potential,
which appears in all the main equations.
To eliminate this problem YAMBO uses the so-called Random Integration Method
which means to use a Monte Carlo Integration with Random Q-points whose number ''[[Variables#RandQpts|RandQpts]]'' will be given in input.
For example the exchange self-energy matrix element which is:
[[File:sigmax.png|none|x50px|]]
assuming that the integrand is a smooth function of momenta the integral can be approximated as
[[File:rim0.png|none|x50px|]]
where the small Brillouin Zones (sBZ) relative to a given q-point are the Brillouin Zones of the momenta vectors lattice.
They are chosen in such a way to cover the whole BZ.
In the RIM run-level yambo calculates the integrals of the symmetrized Coulomb potential
[[File:rim1.png|none|x50px|]]

So we are ready to start the tutorial
First go in the proper directory and have a look if all the required databases are there
$ cd YAMBO_TUTORIALS/hBN-2D/YAMBO
$ ls ./SAVE
ns.db1 ns.wf ns.kb_pp_pwscf ...
$ yambo ''(initialization, if you haven't already done so)''

Create the input to generate the <code>ndb.RIM</code> database
$ yambo -F yambo_WR.in -r
and change the following variables
[[Variables#RandQpts|RandQpts]] = 1000000 # [RIM] Number of random q-points in the BZ
[[Variables#RandGvec|RandGvec]] = 100 RL # [RIM] Coulomb interaction RS components
N.B ''RandGvec=100'' means to use the RIM for the first 100 G-components of the coulomb potential
(Suggestion : later you can check convergence of the HF gap changing these two values)
Close input and Run yambo
$ yambo -F yambo_WR.in -J 2D_WR
At the end you find a new database ''ndb.RIM'' and a new report file ''r-2D_WR_rim_cut ''. Open it and look inside

Gamma point sphere radius [au]: 0.08028
Points outside the sphere : 799246
[Int_sBZ(q=0) 1/q^2]*(Vol_sBZ)^(-1/3) = 7.665674
should be < 7.795600
[WR./2D_WR//ndb.RIM]--------------------------------------
Brillouin Zone Q/K grids (IBZ/BZ): 7 36 7 36
Coulombian RL components : 111
Coulombian diagonal components :yes
RIM random points : 1000000
RIM RL volume [a.u.]: 0.390293
Real RL volume [a.u.]: 0.390112
Eps^-1 reference component :0
Eps^-1 components : 0.00 0.00 0.00
RIM anysotropy factor : 0.000000
- S/N 005962 -------------------------- v.04.01.02 r.00120 -

Summary of Coulomb integrals for non-metallic bands |Q|[au] RIM/Bare:

Q [1]:0.1000E-40.9833 * Q [2]: 0.256404 1.094818
Q [5]: 0.444104 1.032268 * Q [3]: 0.512807 1.024055
Q [6]: 0.678380 1.013997 * Q [4]: 0.769211 1.010774
Q [7]: 0.888208 1.008393

The RIM and Real RL Volumes are quite similar so one million random q-points seems a reasonable number,
but again you are invited, later on, to check the convergence of one of the main observables (i.e. HF gap, GW gap, absorption..) changing this number.

Close the report file and perform a calculation of the exchange self-energy to estimate the HF gap (very fast calculation) using the RIM.
Generate the input
$ yambo -F yambo_HF_WR.in -J 2D_WR -r -x
In order to calculate the HF gap only for the last k-point (which is the high-simmetry point K) change the last line as
Note also that 4 (5) is the highest occupied (lowest unoccupied) band.
%[[Variables#QPkrange|QPkrange]] # [GW] QP generalized Kpoint/Band indices
7| 7| 4| 5|
%

Close the input and run yambo
$ yambo -F yambo_HF_WR.in -J 2D_WR
At the end you will find the report file ''r-2D_WR_HF_and_locXC_rim_cut'' and the output file ''o-2D_WR.hf''. Open them and have a look
In the output file ''o-2D_WR.hf'' you will see
# K-point Band Eo Ehf DFT HF
#
7.00000 4.00000 0.00000 -3.25329 -16.21953 -19.47282
7.00000 5.00000 4.40109 9.67551 -11.10755 -5.83314

The HF gap is 12.92 eV obtained subtracting the 2 values in the fourth column
Now you can do a similar HF calculation without generating and reading the RIM database

$ yambo -F yambo_HF_NR.in -x
change the variables ''QPkrange'' as before, close the input and run yambo
$ yambo -F yambo_HF_NR.in -J 2D_NR

in this case the HF gap in the file ''o-2D_NR.hf'' results to be 12.69 eV.

Indeed the presence of the numerical instability, discussed before, is evident only using denser k-grids with respect to the one used in this Tutorial (6x6x1)
Suggestion: later you can generate other SAVE directories with denser k-grids and check the HF gap.
The results of the HF gap calculated with different k-grids without (noRIM) and with Random Integration Method (RIM) to show up the problem are reported:

noRIM RIM

6x6x1 12.69eV 12.92eV
12x12x1 12.80eV 12.92eV
15x15x1 12.96eV 12.93eV
45x45x1 15.52eV 12.96eV

So the '''home message''' is : use always the RIM in MB simulations of low-dimensional materials.

==Generate a truncated coulomb potential ==
To simulate an isolated nano-material a convergence with cell vacuum size is in principle required, like in the DFT runs.
The use of a truncated Coulomb potential allows to achieve faster convergence eliminating the interaction between the repeated images
along the non-periodic direction (see i.e. C. A. Rozzi et al Phys. Rev. B 73, 205119)
In this tutorial we learn how to generate a box-like cutoff for a 2D system with the non-periodic direction along z.

In YAMBO you can use :
* spherical cutoff (for 0D systems)
* cylindrical cutoff (for 1D systems)
* box-like cutoff (for 0D, 1D and 2D systems)

The Coulomb potential with a box-like cutoff is defined as
[[File:Vc1.png|none|x80px|]]
where S is a box-shaped region of the space having sides Lx,Ly and Lz, where they can also assume infinite values (untruncated interaction along desired directions).

Then the FT component is
[[File:Vc2.png|none|x60px|]] where [[File:Vc3.png|none|x60px|]]
For a 2D-system with non period direction along z-axis we have
[[File:Vc4.png|none|x60px|]]

Important remarks:
* the Random Integration Method (RIM) is required to perform the Q-space integration
* for sufficiently large supercells a choose L_i slightly smaller than the cell size in the i-direction ensures to avoid interaction between replicas

Create the input file:

$ yambo -F yambo_WR_WC.in -r

Change the RIM Variables as before and activate the ''cutoff'' generation
[[Variables#RandQpts|RandQpts]] = 1000000 # [RIM] Number of random q-points in the BZ
[[Variables#RandGvec|RandGvec]] = 100 RL # [RIM] Coulomb interaction RS components
[[Variables#CUTGeo|CUTGeo]] = "box z" # [CUT] Coulomb Cutoff geometry: box/cylinder/sphere X/Y/Z/XY..
% CUTBox
0.00 | 0.00 | 32.0 | # [CUT] [au] Box sides
%

Close the input file and run yambo:

$ yambo -F yambo_WR_WC.in -J 2D_WR_WC

in the directory 2D_WR_WC you will find a new database <code> ndb.cutoff </code>

==Use the truncated coulomb potential in a G0W0-PPA calculation==

Generate the input reading the databases in the ''2D_WR_WC'' directory
$ yambo -J 2D_WR_WC -F yambo_G0W0.in -p p -g n -r -k hartree -V qp
In the input change the following variables
[[Variables#NGsBlkXp|NGsBlkXp]] = 4 Ry # [Xp] Response block size
[[Variables#QPkrange|QPkrange]] # [GW] QP generalized Kpoint/Band indices
7| 7| 4| 5|
Close the input and run yambo
$ yambo -F yambo_G0W0.in -J 2D_WR_WC
At the end you will find a new report file ''r-2D_WR_WC_em1d_ppa_HF_and_locXC_gw0_rim_cut'', open it and have a look.
You will find also a new output file ''o-2D_WR_WC.qp''. If you open yoi will find that now the G0W0 gap is
4.40 eV (PBE) + 3.70 eV (G0W0 correction) = 8.10 eV
Indeed as you have learned in the previous tutorials the correlation part of the self-energy strongly reduces the HF gap.
Moreover you should note that the QP correction is larger that one found in the h-BN bulk. Why?

==Use the truncated coulomb potential in a BSE calculation==
Generate the input for the BSE calculation:
$ yambo -J 2D_WR_WC -F yambo_BSE.in -r -o b -p p -y d -k sex -V all
Some remarks: the largest verbosity is used <code>-V all </code> and a long input file is generated; with the option <code> -p p </code> the static part of the screening matrix is read from the <code>ndb.pp</code> databases
Change the number of G-vectors in the correlation part of the kernel as:
[[Variables#BSENGBlk|BSENGBlk]]= 4 Ry # [BSK] Screened interaction block size
use the simple rigid scissor to open the correct the KS energies
% [[Variables#KfnQP_E|KfnQP_E]]
3.70000000 | 1.000000 | 1.000000 | # [EXTQP BSK BSS] E parameters (c/v) eV|adim|adim
Set the number of bands to:
% [[Variables#BSEBands|BSEBands]]
2 | 6 | # [BSK] Bands range
This choice means to include in the BSE only three occupied and 2 unoccupied bands.
Increase the number of energy steps
[[Variables#BEnSteps|BEnSteps]]= 500 # [BSS] Energy steps
To do the next Tutorial we need to write the excitonic WFs, so uncomment the following line
#[[Variables#WRbsWF|WRbsWF]] # [BSS] Write to disk excitonic the WFs
Close the input file and run yambo
$ yambo -J 2D_WR_WC -F yambo_BSE.in
Look at the report file ''r-2D_WR_WC_optics_bse_bsk_bss_em1d_ppa_rim_cut'' and plot the real and Imaginary part
of the dielectric function using the file ''o-2D_WR_WC.eps_q1_diago_bse''.

You realize immediately that the real part of the macroscopic dielectric function is almost 1, while the imaginary part is almost zero.
Indeed when the use of the cutoff in the coulomb potential is activated you are simulating a real isolated sheet in vacuum and so you are obtaining almost the dielectric function of vacuum!

For this reason yambo produces another file which contains the macroscopic polarizability (called here 'o-2D_WR_WC.alpha_q1_diago_bse')
which is a well defined quantity strictly related to optical conductivity or absorbance.

For a 2D system has the dimension of a length and it is defined as :

[[File:alpha2D.gif|none|x80px|]] where L is the size of the cell in the non-periodic direction (z in this case)

== Analyze the differences with corresponding GW and BSE calculations without the use of a truncated coulomb potential==

Open the input file yambo_G0W0.in and set back <code>CUTGeo= "none"</code>

Close the input and run yambo

$ yambo -J 2D_WR -F yambo_G0W0.in
You will find a new report ''r-2D_WR_em1d_ppa_HF_and_locXC_gw0_rim_cut''.
You are invited to see the difference with the previous one ''r-2D_WR_WC_em1d_ppa_HF_and_locXC_gw0_rim_cut''

and also a new output file ''o-2D_WR.qp'' is present. Open and check the QP correction at the last k-point. This time
a value of 2.83 eV instead of 3.70 eV is obtained. Are you able to explain this result?

Now redoo the BSE calculation but without reading the cutoff database and applying the QP correction just obtained without using the cutoff.

To do that, open the yambo_BSE.in and put <code>CUTGeo= "none"</code>
and set the QP correction of 2.83 eV, just obtained without uisng the cutoff.
% [[Variables#KfnQP_E|KfnQP_E]]
2.830000 | 1.000000 | 1.000000 | # [EXTQP BSK BSS] E parameters (c/v) eV|adim|adim

Close the input file and run yambo
$ yambo -J 2D_WR -F yambo_BSE.in
Plot the imaginary part of the GW and BSE polarizabilities with and withou cutoff:

$ gnuplot
$ gnuplot> set ylabel 'alpha'
$ gnuplot> plot 'o-2D_WR.eps_q1_diago_bse' u 1:($4*33.012/4/pi) w l title 'GW without cutoff' ,'o-2D_WR_WC.alpha_q1_diago_bse' u 1:4 w l title ' GW with cutoff' , 'o-2D_WR.eps_q1_diago_bse' u 1:($2*33.012/4/pi) w l title 'BSE without cutoff' ,'o-2D_WR_WC.alpha_q1_diago_bse' u 1:2 w l title 'BSE with cutoff'

[[File:BSE_2D_cutnocut.png|none|600px|]]

You can note that the energy of the peaks in the two GW spectra (with and without cutoff) are quite different:
you find the first peak around 7 eV without cutoff and around 8 eV with cutoff.
Instead the two GW+BSE spectra, without and with cutoff, are much more similar. Are you able to explain why?

Also note that, for the case without cutoff, to plot the imaginary part of the polarizability, the Imaginary part of the macroscopic dieletric function has been multiplied by the appropriate prefactor.

Remarks: The convergence in k-space can be done separately for GW and BSE
calculations, because generally more k-points are needed to converge the excitonic with respect to the quasi-particle properties.

N.B. If you will use the same inputs created in this tutorial remember to set up the cutoff variable ''CUTGeo= "box z"'' to use again the truncated coulomb potential in the GW and BSE calculations

Literature on two-dimensional h-BN: L. Wirtz et al Phys Rev Lett 96 126104 (2006), F. Rasmussen et al Phys Rev. B 94 155406 (2016),N. Berseneva et al Phys. Rev. B 87 035404 (2013).

File:Alpha2D.gif

2020-01-21T04:56:06Z

Maurizia: Maurizia uploaded a new version of File:Alpha2D.gif

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

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

This file was uploaded with the UploadWizard extension.

[[Category:Uploaded with UploadWizard]]

How to analyse excitons

2020-01-21T04:54:16Z

Maurizia: /* Plot the exciton spatial distribution */

In this tutorial you will learn (for a 2D-hBN) how to:
* analyze a BSE optical spectrum in terms of excitonic eigenvectors and eigenvalues
* look at the spatial distribution of the exciton

== Prerequisites ==
'''Previous modules'''
* You must have completed the [[How to treat low dimensional systems]] tutorial
'''You will need''':
* <code>ypp </code> executable
* <code>xcrysden</code> executable
* <code>gnuplot or xmgrace</code> executable
'''

== YAMBO calculations ==
If you have completed the tutorials of 2D hBN you should have all the databases required to do this tutorial in your <code>YAMBO_TUTORIALS/hBN-2D/SAVE</code> and <code>2D_WR_WC</code> (databases generated with RIM and cutoff) directories

$ ls ./SAVE
ndb.gops ndb.kindx ns.db1 ns.kb_pp_pwscf_fragment_1 ....
$ ls ./2D_WR_WC
ndb.BS_Q1_CPU_0 ndb.cutoff ndb.dip_iR_and_P_fragment_1 ndb.pp_fragment_1 ...

==Sort the excitonic eigenvalues==

$ ypp -J 2D_WR_WC -e s 1

We are sorting the excitons for the qindex = 1 (optical limit q=0).
The new generated file ''o-2D_WR_WC.exc_qpt1_E_sorted '' (''o-2D_WR_WC.exc_qpt1_I_sorted '') reports
the energies of the excitons and their Dipole Oscillator Strengths sorted by energy (Index).
[[File:strengh.png|none|x120px|]]
Open the first file and look inside. The first exciton is at 4.83 eV and the second one has the highest strenght (normalized to 1)

Or you can make a plot
$ gnuplot
gnuplot> set style line 2 lc rgb 'black' pt 7 # circle
gnuplot> plot 'o-2D_WR_WC.exc_qpt1_E_sorted' with points ls 2 title 'Strenghts'

[[File:strenght.png|none|600px|]]

Attention the convergence of these results with different k-points grids is mandatory!

== Calculate the exciton oscillator strenght and amplitude ==

We can now analyze the excitons in terms of single-particle states, to do that create the appropriate input
$ ypp -F ypp_AMPL.in -J 2D_WR_WC -e a 1

Suppose you wish to analyze the first 5 excitons then change this line as:
States= "1 - 5" # Index of the BS state(s)

Close the input and run ypp

$ ypp -F ypp_AMPL.in -J 2D_WR_WC

$ls o*exc*at*
o-2D_WR_WC.exc_qpt1_amplitude_at_1 o-2D_WR_WC.exc_qpt1_weights_at_1 ...

For an exciton <math>|\lambda></math> , ''o-2D_WR_WC.exc_qpt1_weights_at_*'' report the Weights
[[File:Weights.png|none|x60px|]]
and ''o-2D_WR_WC.exc_qpt1_amplitude_**'' report the amplitudes
[[File:Ampl.png|none|x70px|]]

Open the file ''o-2D_WR_WC.exc_weights_at_1''
# Band_V Band_C K ibz Symm. Weight Energy
#
4.000000 5.000000 7.000000 2.000000 0.922095 4.401093
4.000000 5.000000 7.000000 1.000000 0.922086 4.401093
The first exciton is essentially done of only single particle transitions from VBM to CBM at K (last k-point of the grid).

[[File:Amplitude_plot.png|none|600px|]]

== Plot the exciton spatial distribution ==

To see the spatial character of the exciton YPP writes the exciton spatial distribution, in other words the probability to find the electron somewhere in the space when the hole is fixed in a give position.
Different output formats can be selected and 1D,2D,3D plots done.
Create the input and change the size of the cell where to see the exciton.
Note that If the k-grid of the BSE simulation is a NxNx1 the exciton has an induced fictitious periodicity every Nx Nx1 Cell of the simulation.
For hBN-2D this is not a problem because the exciton is strongly localized but in other systems with more delocalized excitons to look at the real exciton size it is necessary to use
very large k-grids in the BSE
$ ypp -F ypp_WF.in -J 2D_WR_WC -e w 1

excitons # [R] Excitons
wavefunction # [R] Wavefunction
Format= "x" # Output format [(c)ube/(g)nuplot/(x)crysden]
Direction= "12" # [rlu] [1/2/3] for 1d or [12/13/23] for 2d [123] for 3D
FFTGvecs= 3951 RL # [FFT] Plane-waves
States= "1 - 1" # Index of the BS state(s)
Degen_Step= 0.0100 eV # Maximum energy separation of two degenerate states
% Cells
5 | 5 | 1 | # Number of cell repetitions in each direction (odd or 1)
%
% Hole
2.4 | 1.400 | 0.00 | # [cc] Hole position in unit cell

Close the input and run ypp
$ ypp -F ypp_WF.in -J 2D_WR_WC

$ xcrysden --xsf o-2D_WR_WC.exc_2d_1.xsf

[[File:exc_BN2D.png|none|400px|]]

How to analyse excitons

2020-01-20T19:36:23Z

Maurizia: /* Calculate the exciton oscillator strenght and amplitude */

In this tutorial you will learn (for a 2D-hBN) how to:
* analyze a BSE optical spectrum in terms of excitonic eigenvectors and eigenvalues
* look at the spatial distribution of the exciton

== Prerequisites ==
'''Previous modules'''
* You must have completed the [[How to treat low dimensional systems]] tutorial
'''You will need''':
* <code>ypp </code> executable
* <code>xcrysden</code> executable
* <code>gnuplot or xmgrace</code> executable
'''

== YAMBO calculations ==
If you have completed the tutorials of 2D hBN you should have all the databases required to do this tutorial in your <code>YAMBO_TUTORIALS/hBN-2D/SAVE</code> and <code>2D_WR_WC</code> (databases generated with RIM and cutoff) directories

$ ls ./SAVE
ndb.gops ndb.kindx ns.db1 ns.kb_pp_pwscf_fragment_1 ....
$ ls ./2D_WR_WC
ndb.BS_Q1_CPU_0 ndb.cutoff ndb.dip_iR_and_P_fragment_1 ndb.pp_fragment_1 ...

==Sort the excitonic eigenvalues==

$ ypp -J 2D_WR_WC -e s 1

We are sorting the excitons for the qindex = 1 (optical limit q=0).
The new generated file ''o-2D_WR_WC.exc_qpt1_E_sorted '' (''o-2D_WR_WC.exc_qpt1_I_sorted '') reports
the energies of the excitons and their Dipole Oscillator Strengths sorted by energy (Index).
[[File:strengh.png|none|x120px|]]
Open the first file and look inside. The first exciton is at 4.83 eV and the second one has the highest strenght (normalized to 1)

Or you can make a plot
$ gnuplot
gnuplot> set style line 2 lc rgb 'black' pt 7 # circle
gnuplot> plot 'o-2D_WR_WC.exc_qpt1_E_sorted' with points ls 2 title 'Strenghts'

[[File:strenght.png|none|600px|]]

Attention the convergence of these results with different k-points grids is mandatory!

== Calculate the exciton oscillator strenght and amplitude ==

We can now analyze the excitons in terms of single-particle states, to do that create the appropriate input
$ ypp -F ypp_AMPL.in -J 2D_WR_WC -e a 1

Suppose you wish to analyze the first 5 excitons then change this line as:
States= "1 - 5" # Index of the BS state(s)

Close the input and run ypp

$ ypp -F ypp_AMPL.in -J 2D_WR_WC

$ls o*exc*at*
o-2D_WR_WC.exc_qpt1_amplitude_at_1 o-2D_WR_WC.exc_qpt1_weights_at_1 ...

For an exciton <math>|\lambda></math> , ''o-2D_WR_WC.exc_qpt1_weights_at_*'' report the Weights
[[File:Weights.png|none|x60px|]]
and ''o-2D_WR_WC.exc_qpt1_amplitude_**'' report the amplitudes
[[File:Ampl.png|none|x70px|]]

Open the file ''o-2D_WR_WC.exc_weights_at_1''
# Band_V Band_C K ibz Symm. Weight Energy
#
4.000000 5.000000 7.000000 2.000000 0.922095 4.401093
4.000000 5.000000 7.000000 1.000000 0.922086 4.401093
The first exciton is essentially done of only single particle transitions from VBM to CBM at K (last k-point of the grid).

[[File:Amplitude_plot.png|none|600px|]]

== Plot the exciton spatial distribution ==

To see the spatial character of the exciton YPP writes the exciton spatial distribution, in other words the probability to find the electron somewhere in the space when the hole is fixed in a give position.
Different output formats can be selected and 1D,2D,3D plots done.
Create the input and change the size of the cell where to see the exciton.
Note that If the k-grid of the BSE simulation is a NxNx1 the exciton has an induced fictitious periodicity every Nx Nx1 Cell of the simulation.
For hBN-2D this is not a problem because the exciton is strongly localized but in other systems with more delocalized excitons to look at the real exciton size it is necessary to use
very large k-grids in the BSE
$ ypp -F ypp_WF.in -J 2D_WR_WC -e w

excitons # [R] Excitons
wavefunction # [R] Wavefunction
Format= "x" # Output format [(c)ube/(g)nuplot/(x)crysden]
Direction= "12" # [rlu] [1/2/3] for 1d or [12/13/23] for 2d [123] for 3D
FFTGvecs= 3951 RL # [FFT] Plane-waves
States= "1 - 1" # Index of the BS state(s)
Degen_Step= 0.0100 eV # Maximum energy separation of two degenerate states
% Cells
5 | 5 | 1 | # Number of cell repetitions in each direction (odd or 1)
%
% Hole
2.4 | 1.400 | 0.00 | # [cc] Hole position in unit cell

Close the input and run ypp
$ ypp -F ypp_WF.in -J 2D_WR_WC

$ xcrysden --xsf o-2D_WR_WC.exc_2d_1.xsf

[[File:exc_BN2D.png|none|400px|]]

How to analyse excitons

2020-01-20T19:33:58Z

Maurizia: /* Calculate the exciton oscillator strenght and amplitude */

In this tutorial you will learn (for a 2D-hBN) how to:
* analyze a BSE optical spectrum in terms of excitonic eigenvectors and eigenvalues
* look at the spatial distribution of the exciton

== Prerequisites ==
'''Previous modules'''
* You must have completed the [[How to treat low dimensional systems]] tutorial
'''You will need''':
* <code>ypp </code> executable
* <code>xcrysden</code> executable
* <code>gnuplot or xmgrace</code> executable
'''

== YAMBO calculations ==
If you have completed the tutorials of 2D hBN you should have all the databases required to do this tutorial in your <code>YAMBO_TUTORIALS/hBN-2D/SAVE</code> and <code>2D_WR_WC</code> (databases generated with RIM and cutoff) directories

$ ls ./SAVE
ndb.gops ndb.kindx ns.db1 ns.kb_pp_pwscf_fragment_1 ....
$ ls ./2D_WR_WC
ndb.BS_Q1_CPU_0 ndb.cutoff ndb.dip_iR_and_P_fragment_1 ndb.pp_fragment_1 ...

==Sort the excitonic eigenvalues==

$ ypp -J 2D_WR_WC -e s 1

We are sorting the excitons for the qindex = 1 (optical limit q=0).
The new generated file ''o-2D_WR_WC.exc_qpt1_E_sorted '' (''o-2D_WR_WC.exc_qpt1_I_sorted '') reports
the energies of the excitons and their Dipole Oscillator Strengths sorted by energy (Index).
[[File:strengh.png|none|x120px|]]
Open the first file and look inside. The first exciton is at 4.83 eV and the second one has the highest strenght (normalized to 1)

Or you can make a plot
$ gnuplot
gnuplot> set style line 2 lc rgb 'black' pt 7 # circle
gnuplot> plot 'o-2D_WR_WC.exc_qpt1_E_sorted' with points ls 2 title 'Strenghts'

[[File:strenght.png|none|600px|]]

Attention the convergence of these results with different k-points grids is mandatory!

== Calculate the exciton oscillator strenght and amplitude ==

We can now analyze the excitons in terms of single-particle states, to do that create the appropriate input
$ ypp -F ypp_AMPL.in -J 2D_WR_WC -e a 1

Suppose you wish to analyze the first 5 excitons then change this line as:
States= "1 - 5" # Index of the BS state(s)

Close the input and run ypp

$ ypp -F ypp_AMPL.in -J 2D_WR_WC

$ls o*exc*at*
o-2D_WR_WC.exc_amplitude_at_1 o-2D_WR_WC.exc_weights_at_1 ...

For an exciton <math>|\lambda></math> , ''o-2D_WR_WC.exc_weights_at_*'' report the Weights
[[File:Weights.png|none|x60px|]]
and ''o-2D_WR_WC.exc_amplitudes_at_*'' report the amplitudes
[[File:Ampl.png|none|x70px|]]

Open the file ''o-2D_WR_WC.exc_weights_at_1''
# Band_V Band_C K ibz Symm. Weight Energy
#
4.000000 5.000000 7.000000 2.000000 0.922095 4.401093
4.000000 5.000000 7.000000 1.000000 0.922086 4.401093
The first exciton is essentially done of only single particle transitions from VBM to CBM at K (last k-point of the grid).

[[File:Amplitude_plot.png|none|600px|]]

== Plot the exciton spatial distribution ==

To see the spatial character of the exciton YPP writes the exciton spatial distribution, in other words the probability to find the electron somewhere in the space when the hole is fixed in a give position.
Different output formats can be selected and 1D,2D,3D plots done.
Create the input and change the size of the cell where to see the exciton.
Note that If the k-grid of the BSE simulation is a NxNx1 the exciton has an induced fictitious periodicity every Nx Nx1 Cell of the simulation.
For hBN-2D this is not a problem because the exciton is strongly localized but in other systems with more delocalized excitons to look at the real exciton size it is necessary to use
very large k-grids in the BSE
$ ypp -F ypp_WF.in -J 2D_WR_WC -e w

excitons # [R] Excitons
wavefunction # [R] Wavefunction
Format= "x" # Output format [(c)ube/(g)nuplot/(x)crysden]
Direction= "12" # [rlu] [1/2/3] for 1d or [12/13/23] for 2d [123] for 3D
FFTGvecs= 3951 RL # [FFT] Plane-waves
States= "1 - 1" # Index of the BS state(s)
Degen_Step= 0.0100 eV # Maximum energy separation of two degenerate states
% Cells
5 | 5 | 1 | # Number of cell repetitions in each direction (odd or 1)
%
% Hole
2.4 | 1.400 | 0.00 | # [cc] Hole position in unit cell

Close the input and run ypp
$ ypp -F ypp_WF.in -J 2D_WR_WC

$ xcrysden --xsf o-2D_WR_WC.exc_2d_1.xsf

[[File:exc_BN2D.png|none|400px|]]

How to analyse excitons

2020-01-20T19:32:09Z

Maurizia: /* Calculate the exciton oscillator strenght and amplitude */

In this tutorial you will learn (for a 2D-hBN) how to:
* analyze a BSE optical spectrum in terms of excitonic eigenvectors and eigenvalues
* look at the spatial distribution of the exciton

== Prerequisites ==
'''Previous modules'''
* You must have completed the [[How to treat low dimensional systems]] tutorial
'''You will need''':
* <code>ypp </code> executable
* <code>xcrysden</code> executable
* <code>gnuplot or xmgrace</code> executable
'''

== YAMBO calculations ==
If you have completed the tutorials of 2D hBN you should have all the databases required to do this tutorial in your <code>YAMBO_TUTORIALS/hBN-2D/SAVE</code> and <code>2D_WR_WC</code> (databases generated with RIM and cutoff) directories

$ ls ./SAVE
ndb.gops ndb.kindx ns.db1 ns.kb_pp_pwscf_fragment_1 ....
$ ls ./2D_WR_WC
ndb.BS_Q1_CPU_0 ndb.cutoff ndb.dip_iR_and_P_fragment_1 ndb.pp_fragment_1 ...

==Sort the excitonic eigenvalues==

$ ypp -J 2D_WR_WC -e s 1

We are sorting the excitons for the qindex = 1 (optical limit q=0).
The new generated file ''o-2D_WR_WC.exc_qpt1_E_sorted '' (''o-2D_WR_WC.exc_qpt1_I_sorted '') reports
the energies of the excitons and their Dipole Oscillator Strengths sorted by energy (Index).
[[File:strengh.png|none|x120px|]]
Open the first file and look inside. The first exciton is at 4.83 eV and the second one has the highest strenght (normalized to 1)

Or you can make a plot
$ gnuplot
gnuplot> set style line 2 lc rgb 'black' pt 7 # circle
gnuplot> plot 'o-2D_WR_WC.exc_qpt1_E_sorted' with points ls 2 title 'Strenghts'

[[File:strenght.png|none|600px|]]

Attention the convergence of these results with different k-points grids is mandatory!

== Calculate the exciton oscillator strenght and amplitude ==

We can now analyze the excitons in terms of single-particle states, to do that create the appropriate input
$ ypp -F ypp_AMPL.in -J 2D_WR_WC -e a 1

Suppose you wish to analyze the first 5 excitons then change this line as:
States= "1 - 5" # Index of the BS state(s)

Close the input and run ypp

$ ypp -F ypp_AMPL.in -J 2D_WR_WC

$ls ls o*exc*at*
o-2D_WR_WC.exc_amplitude_at_1 o-2D_WR_WC.exc_weights_at_1 ...

For an exciton <math>|\lambda></math> , ''o-2D_WR_WC.exc_weights_at_*'' report the Weights
[[File:Weights.png|none|x60px|]]
and ''o-2D_WR_WC.exc_amplitudes_at_*'' report the amplitudes
[[File:Ampl.png|none|x70px|]]

Open the file ''o-2D_WR_WC.exc_weights_at_1''
# Band_V Band_C K ibz Symm. Weight Energy
#
4.000000 5.000000 7.000000 2.000000 0.922095 4.401093
4.000000 5.000000 7.000000 1.000000 0.922086 4.401093
The first exciton is essentially done of only single particle transitions from VBM to CBM at K (last k-point of the grid).

[[File:Amplitude_plot.png|none|600px|]]

== Plot the exciton spatial distribution ==

To see the spatial character of the exciton YPP writes the exciton spatial distribution, in other words the probability to find the electron somewhere in the space when the hole is fixed in a give position.
Different output formats can be selected and 1D,2D,3D plots done.
Create the input and change the size of the cell where to see the exciton.
Note that If the k-grid of the BSE simulation is a NxNx1 the exciton has an induced fictitious periodicity every Nx Nx1 Cell of the simulation.
For hBN-2D this is not a problem because the exciton is strongly localized but in other systems with more delocalized excitons to look at the real exciton size it is necessary to use
very large k-grids in the BSE
$ ypp -F ypp_WF.in -J 2D_WR_WC -e w

excitons # [R] Excitons
wavefunction # [R] Wavefunction
Format= "x" # Output format [(c)ube/(g)nuplot/(x)crysden]
Direction= "12" # [rlu] [1/2/3] for 1d or [12/13/23] for 2d [123] for 3D
FFTGvecs= 3951 RL # [FFT] Plane-waves
States= "1 - 1" # Index of the BS state(s)
Degen_Step= 0.0100 eV # Maximum energy separation of two degenerate states
% Cells
5 | 5 | 1 | # Number of cell repetitions in each direction (odd or 1)
%
% Hole
2.4 | 1.400 | 0.00 | # [cc] Hole position in unit cell

Close the input and run ypp
$ ypp -F ypp_WF.in -J 2D_WR_WC

$ xcrysden --xsf o-2D_WR_WC.exc_2d_1.xsf

[[File:exc_BN2D.png|none|400px|]]

File:Strenght.png

2020-01-20T19:21:31Z

Maurizia: User created page with UploadWizard

How to analyse excitons

2020-01-20T19:17:58Z

Maurizia: /* Sort the excitonic eigenvalues */

In this tutorial you will learn (for a 2D-hBN) how to:
* analyze a BSE optical spectrum in terms of excitonic eigenvectors and eigenvalues
* look at the spatial distribution of the exciton

== Prerequisites ==
'''Previous modules'''
* You must have completed the [[How to treat low dimensional systems]] tutorial
'''You will need''':
* <code>ypp </code> executable
* <code>xcrysden</code> executable
* <code>gnuplot or xmgrace</code> executable
'''

== YAMBO calculations ==
If you have completed the tutorials of 2D hBN you should have all the databases required to do this tutorial in your <code>YAMBO_TUTORIALS/hBN-2D/SAVE</code> and <code>2D_WR_WC</code> (databases generated with RIM and cutoff) directories

$ ls ./SAVE
ndb.gops ndb.kindx ns.db1 ns.kb_pp_pwscf_fragment_1 ....
$ ls ./2D_WR_WC
ndb.BS_Q1_CPU_0 ndb.cutoff ndb.dip_iR_and_P_fragment_1 ndb.pp_fragment_1 ...

==Sort the excitonic eigenvalues==

$ ypp -J 2D_WR_WC -e s 1

We are sorting the excitons for the qindex = 1 (optical limit q=0).
The new generated file ''o-2D_WR_WC.exc_qpt1_E_sorted '' (''o-2D_WR_WC.exc_qpt1_I_sorted '') reports
the energies of the excitons and their Dipole Oscillator Strengths sorted by energy (Index).
[[File:strengh.png|none|x120px|]]
Open the first file and look inside. The first exciton is at 4.83 eV and the second one has the highest strenght (normalized to 1)

Or you can make a plot
$ gnuplot
gnuplot> set style line 2 lc rgb 'black' pt 7 # circle
gnuplot> plot 'o-2D_WR_WC.exc_qpt1_E_sorted' with points ls 2 title 'Strenghts'

[[File:strenght.png|none|600px|]]

Attention the convergence of these results with different k-points grids is mandatory!

== Calculate the exciton oscillator strenght and amplitude ==

We can now analyze the excitons in terms of single-particle states, to do that create the appropriate input
$ ypp -F ypp_AMPL.in -J 2D_WR_WC -e a

Suppose you wish to analyze the first 5 excitons then change this line as:
States= "1 - 5" # Index of the BS state(s)

Close the input and run ypp

$ ypp -F ypp_AMPL.in -J 2D_WR_WC

$ls ls o*exc*at*
o-2D_WR_WC.exc_amplitude_at_1 o-2D_WR_WC.exc_weights_at_1 ...

For an exciton <math>|\lambda></math> , ''o-2D_WR_WC.exc_weights_at_*'' report the Weights
[[File:Weights.png|none|x60px|]]
and ''o-2D_WR_WC.exc_amplitudes_at_*'' report the amplitudes
[[File:Ampl.png|none|x70px|]]

Open the file ''o-2D_WR_WC.exc_weights_at_1''
# Band_V Band_C K ibz Symm. Weight Energy
#
4.000000 5.000000 7.000000 2.000000 0.922095 4.401093
4.000000 5.000000 7.000000 1.000000 0.922086 4.401093
The first exciton is essentially done of only single particle transitions from VBM to CBM at K (last k-point of the grid).

[[File:Amplitude_plot.png|none|600px|]]

== Plot the exciton spatial distribution ==

To see the spatial character of the exciton YPP writes the exciton spatial distribution, in other words the probability to find the electron somewhere in the space when the hole is fixed in a give position.
Different output formats can be selected and 1D,2D,3D plots done.
Create the input and change the size of the cell where to see the exciton.
Note that If the k-grid of the BSE simulation is a NxNx1 the exciton has an induced fictitious periodicity every Nx Nx1 Cell of the simulation.
For hBN-2D this is not a problem because the exciton is strongly localized but in other systems with more delocalized excitons to look at the real exciton size it is necessary to use
very large k-grids in the BSE
$ ypp -F ypp_WF.in -J 2D_WR_WC -e w

excitons # [R] Excitons
wavefunction # [R] Wavefunction
Format= "x" # Output format [(c)ube/(g)nuplot/(x)crysden]
Direction= "12" # [rlu] [1/2/3] for 1d or [12/13/23] for 2d [123] for 3D
FFTGvecs= 3951 RL # [FFT] Plane-waves
States= "1 - 1" # Index of the BS state(s)
Degen_Step= 0.0100 eV # Maximum energy separation of two degenerate states
% Cells
5 | 5 | 1 | # Number of cell repetitions in each direction (odd or 1)
%
% Hole
2.4 | 1.400 | 0.00 | # [cc] Hole position in unit cell

Close the input and run ypp
$ ypp -F ypp_WF.in -J 2D_WR_WC

$ xcrysden --xsf o-2D_WR_WC.exc_2d_1.xsf

[[File:exc_BN2D.png|none|400px|]]

How to analyse excitons

2020-01-20T18:48:18Z

Maurizia: /* Sort the excitonic eigenvalues */

In this tutorial you will learn (for a 2D-hBN) how to:
* analyze a BSE optical spectrum in terms of excitonic eigenvectors and eigenvalues
* look at the spatial distribution of the exciton

== Prerequisites ==
'''Previous modules'''
* You must have completed the [[How to treat low dimensional systems]] tutorial
'''You will need''':
* <code>ypp </code> executable
* <code>xcrysden</code> executable
* <code>gnuplot or xmgrace</code> executable
'''

== YAMBO calculations ==
If you have completed the tutorials of 2D hBN you should have all the databases required to do this tutorial in your <code>YAMBO_TUTORIALS/hBN-2D/SAVE</code> and <code>2D_WR_WC</code> (databases generated with RIM and cutoff) directories

$ ls ./SAVE
ndb.gops ndb.kindx ns.db1 ns.kb_pp_pwscf_fragment_1 ....
$ ls ./2D_WR_WC
ndb.BS_Q1_CPU_0 ndb.cutoff ndb.dip_iR_and_P_fragment_1 ndb.pp_fragment_1 ...

==Sort the excitonic eigenvalues==

$ ypp -J 2D_WR_WC -e s 1

We are sorting the excitons for the qindex = 1 (optical limit q=0).
The new generated file ''o-2D_WR_WC.exc_qpt1_E_sorted '' (''o-2D_WR_WC.exc_qpt1_I_sorted '') reports
the energies of the excitons and their Dipole Oscillator Strengths sorted by energy (Index).
[[File:strengh.png|none|x120px|]]
Open the first file and look inside. The first exciton is at 4.83 eV and the second one has the highest strenght (normalized to 1)

Or you can make a plot
$ gnuplot
gnuplot> plot "o-2D_WR_WC.exc_qpt1_E sorted " u 1:2 title 'Strenght2D'

[[File:strenght.png|none|600px|]]

Attention the convergence of these results with different k-points grids is mandatory!

== Calculate the exciton oscillator strenght and amplitude ==

We can now analyze the excitons in terms of single-particle states, to do that create the appropriate input
$ ypp -F ypp_AMPL.in -J 2D_WR_WC -e a

Suppose you wish to analyze the first 5 excitons then change this line as:
States= "1 - 5" # Index of the BS state(s)

Close the input and run ypp

$ ypp -F ypp_AMPL.in -J 2D_WR_WC

$ls ls o*exc*at*
o-2D_WR_WC.exc_amplitude_at_1 o-2D_WR_WC.exc_weights_at_1 ...

For an exciton <math>|\lambda></math> , ''o-2D_WR_WC.exc_weights_at_*'' report the Weights
[[File:Weights.png|none|x60px|]]
and ''o-2D_WR_WC.exc_amplitudes_at_*'' report the amplitudes
[[File:Ampl.png|none|x70px|]]

Open the file ''o-2D_WR_WC.exc_weights_at_1''
# Band_V Band_C K ibz Symm. Weight Energy
#
4.000000 5.000000 7.000000 2.000000 0.922095 4.401093
4.000000 5.000000 7.000000 1.000000 0.922086 4.401093
The first exciton is essentially done of only single particle transitions from VBM to CBM at K (last k-point of the grid).

[[File:Amplitude_plot.png|none|600px|]]

== Plot the exciton spatial distribution ==

To see the spatial character of the exciton YPP writes the exciton spatial distribution, in other words the probability to find the electron somewhere in the space when the hole is fixed in a give position.
Different output formats can be selected and 1D,2D,3D plots done.
Create the input and change the size of the cell where to see the exciton.
Note that If the k-grid of the BSE simulation is a NxNx1 the exciton has an induced fictitious periodicity every Nx Nx1 Cell of the simulation.
For hBN-2D this is not a problem because the exciton is strongly localized but in other systems with more delocalized excitons to look at the real exciton size it is necessary to use
very large k-grids in the BSE
$ ypp -F ypp_WF.in -J 2D_WR_WC -e w

excitons # [R] Excitons
wavefunction # [R] Wavefunction
Format= "x" # Output format [(c)ube/(g)nuplot/(x)crysden]
Direction= "12" # [rlu] [1/2/3] for 1d or [12/13/23] for 2d [123] for 3D
FFTGvecs= 3951 RL # [FFT] Plane-waves
States= "1 - 1" # Index of the BS state(s)
Degen_Step= 0.0100 eV # Maximum energy separation of two degenerate states
% Cells
5 | 5 | 1 | # Number of cell repetitions in each direction (odd or 1)
%
% Hole
2.4 | 1.400 | 0.00 | # [cc] Hole position in unit cell

Close the input and run ypp
$ ypp -F ypp_WF.in -J 2D_WR_WC

$ xcrysden --xsf o-2D_WR_WC.exc_2d_1.xsf

[[File:exc_BN2D.png|none|400px|]]

File:BSE 2D cutnocut.png

2020-01-20T18:37:31Z

Maurizia: Maurizia uploaded a new version of File:BSE 2D cutnocut.png

File:BSE 2D cutnocut.png

2020-01-20T18:16:05Z

Maurizia: User created page with UploadWizard

How to treat low dimensional systems

2020-01-20T18:14:33Z

Maurizia: /* Analyze the differences with corresponding GW and BSE calculations without the use of a truncated coulomb potential */

In this tutorial you will learn how to treat low-dimensional material.
A small k-sampling is used to reduce the computational cost/time.
Later on you can repeat this tutorial but using denser k-grids to check the convergence.

== Prerequisites ==

* <code>yambo</code> executable
* <code>ypp</code> executable
* <code>gnuplot</code>, for plotting spectra
* Have Completed the [[First steps: a walk through from DFT to optical properties]] tutorial

==Avoid numerical divergences using the Random Integration Method (RIM)==
In DFT runs of low-dimensional materials low dimensional k-grids are generally used. (i.e. NxNx1 for a 2D sheet perpendicular to the z direction)
This can create numerical problems in the convergence of the many-body (MB) results due to the divergence at small q of the coulomb potential,
which appears in all the main equations.
To eliminate this problem YAMBO uses the so-called Random Integration Method
which means to use a Monte Carlo Integration with Random Q-points whose number ''[[Variables#RandQpts|RandQpts]]'' will be given in input.
For example the exchange self-energy matrix element which is:
[[File:sigmax.png|none|x50px|]]
assuming that the integrand is a smooth function of momenta the integral can be approximated as
[[File:rim0.png|none|x50px|]]
where the small Brillouin Zones (sBZ) relative to a given q-point are the Brillouin Zones of the momenta vectors lattice.
They are chosen in such a way to cover the whole BZ.
In the RIM run-level yambo calculates the integrals of the symmetrized Coulomb potential
[[File:rim1.png|none|x50px|]]

So we are ready to start the tutorial
First go in the proper directory and have a look if all the required databases are there
$ cd YAMBO_TUTORIALS/hBN-2D/YAMBO
$ ls ./SAVE
ns.db1 ns.wf ns.kb_pp_pwscf ...
$ yambo ''(initialization, if you haven't already done so)''

Create the input to generate the <code>ndb.RIM</code> database
$ yambo -F yambo_WR.in -r
and change the following variables
[[Variables#RandQpts|RandQpts]] = 1000000 # [RIM] Number of random q-points in the BZ
[[Variables#RandGvec|RandGvec]] = 100 RL # [RIM] Coulomb interaction RS components
N.B ''RandGvec=100'' means to use the RIM for the first 100 G-components of the coulomb potential
(Suggestion : later you can check convergence of the HF gap changing these two values)
Close input and Run yambo
$ yambo -F yambo_WR.in -J 2D_WR
At the end you find a new database ''ndb.RIM'' and a new report file ''r-2D_WR_rim_cut ''. Open it and look inside

Gamma point sphere radius [au]: 0.08028
Points outside the sphere : 799246
[Int_sBZ(q=0) 1/q^2]*(Vol_sBZ)^(-1/3) = 7.665674
should be < 7.795600
[WR./2D_WR//ndb.RIM]--------------------------------------
Brillouin Zone Q/K grids (IBZ/BZ): 7 36 7 36
Coulombian RL components : 111
Coulombian diagonal components :yes
RIM random points : 1000000
RIM RL volume [a.u.]: 0.390293
Real RL volume [a.u.]: 0.390112
Eps^-1 reference component :0
Eps^-1 components : 0.00 0.00 0.00
RIM anysotropy factor : 0.000000
- S/N 005962 -------------------------- v.04.01.02 r.00120 -

Summary of Coulomb integrals for non-metallic bands |Q|[au] RIM/Bare:

Q [1]:0.1000E-40.9833 * Q [2]: 0.256404 1.094818
Q [5]: 0.444104 1.032268 * Q [3]: 0.512807 1.024055
Q [6]: 0.678380 1.013997 * Q [4]: 0.769211 1.010774
Q [7]: 0.888208 1.008393

The RIM and Real RL Volumes are quite similar so one million random q-points seems a reasonable number,
but again you are invited, later on, to check the convergence of one of the main observables (i.e. HF gap, GW gap, absorption..) changing this number.

Close the report file and perform a calculation of the exchange self-energy to estimate the HF gap (very fast calculation) using the RIM.
Generate the input
$ yambo -F yambo_HF_WR.in -J 2D_WR -r -x
In order to calculate the HF gap only for the last k-point (which is the high-simmetry point K) change the last line as
Note also that 4 (5) is the highest occupied (lowest unoccupied) band.
%[[Variables#QPkrange|QPkrange]] # [GW] QP generalized Kpoint/Band indices
7| 7| 4| 5|
%

Close the input and run yambo
$ yambo -F yambo_HF_WR.in -J 2D_WR
At the end you will find the report file ''r-2D_WR_HF_and_locXC_rim_cut'' and the output file ''o-2D_WR.hf''. Open them and have a look
In the output file ''o-2D_WR.hf'' you will see
# K-point Band Eo Ehf DFT HF
#
7.00000 4.00000 0.00000 -3.25329 -16.21953 -19.47282
7.00000 5.00000 4.40109 9.67551 -11.10755 -5.83314

The HF gap is 12.92 eV obtained subtracting the 2 values in the fourth column
Now you can do a similar HF calculation without generating and reading the RIM database

$ yambo -F yambo_HF_NR.in -x
change the variables ''QPkrange'' as before, close the input and run yambo
$ yambo -F yambo_HF_NR.in -J 2D_NR

in this case the HF gap in the file ''o-2D_NR.hf'' results to be 12.69 eV.

Indeed the presence of the numerical instability, discussed before, is evident only using denser k-grids with respect to the one used in this Tutorial (6x6x1)
Suggestion: later you can generate other SAVE directories with denser k-grids and check the HF gap.
The results of the HF gap calculated with different k-grids without (noRIM) and with Random Integration Method (RIM) to show up the problem are reported:

noRIM RIM

6x6x1 12.69eV 12.92eV
12x12x1 12.80eV 12.92eV
15x15x1 12.96eV 12.93eV
45x45x1 15.52eV 12.96eV

So the '''home message''' is : use always the RIM in MB simulations of low-dimensional materials.

==Generate a truncated coulomb potential ==
To simulate an isolated nano-material a convergence with cell vacuum size is in principle required, like in the DFT runs.
The use of a truncated Coulomb potential allows to achieve faster convergence eliminating the interaction between the repeated images
along the non-periodic direction (see i.e. C. A. Rozzi et al Phys. Rev. B 73, 205119)
In this tutorial we learn how to generate a box-like cutoff for a 2D system with the non-periodic direction along z.

In YAMBO you can use :
* spherical cutoff (for 0D systems)
* cylindrical cutoff (for 1D systems)
* box-like cutoff (for 0D, 1D and 2D systems)

The Coulomb potential with a box-like cutoff is defined as
[[File:Vc1.png|none|x80px|]]
where S is a box-shaped region of the space having sides Lx,Ly and Lz, where they can also assume infinite values (untruncated interaction along desired directions).

Then the FT component is
[[File:Vc2.png|none|x60px|]] where [[File:Vc3.png|none|x60px|]]
For a 2D-system with non period direction along z-axis we have
[[File:Vc4.png|none|x60px|]]

Important remarks:
* the Random Integration Method (RIM) is required to perform the Q-space integration
* for sufficiently large supercells a choose L_i slightly smaller than the cell size in the i-direction ensures to avoid interaction between replicas

Create the input file:

$ yambo -F yambo_WR_WC.in -r

Change the RIM Variables as before and activate the ''cutoff'' generation
[[Variables#RandQpts|RandQpts]] = 1000000 # [RIM] Number of random q-points in the BZ
[[Variables#RandGvec|RandGvec]] = 100 RL # [RIM] Coulomb interaction RS components
[[Variables#CUTGeo|CUTGeo]] = "box z" # [CUT] Coulomb Cutoff geometry: box/cylinder/sphere X/Y/Z/XY..
% CUTBox
0.00 | 0.00 | 32.0 | # [CUT] [au] Box sides
%

Close the input file and run yambo:

$ yambo -F yambo_WR_WC.in -J 2D_WR_WC

in the directory 2D_WR_WC you will find a new database <code> ndb.cutoff </code>

==Use the truncated coulomb potential in a G0W0-PPA calculation==

Generate the input reading the databases in the ''2D_WR_WC'' directory
$ yambo -J 2D_WR_WC -F yambo_G0W0.in -p p -g n -r -k hartree -V qp
In the input change the following variables
[[Variables#NGsBlkXp|NGsBlkXp]] = 4 Ry # [Xp] Response block size
[[Variables#QPkrange|QPkrange]] # [GW] QP generalized Kpoint/Band indices
7| 7| 4| 5|
Close the input and run yambo
$ yambo -F yambo_G0W0.in -J 2D_WR_WC
At the end you will find a new report file ''r-2D_WR_WC_em1d_ppa_HF_and_locXC_gw0_rim_cut'', open it and have a look.
You will find also a new output file ''o-2D_WR_WC.qp''. If you open yoi will find that now the G0W0 gap is
4.40 eV (PBE) + 3.70 eV (G0W0 correction) = 8.10 eV
Indeed as you have learned in the previous tutorials the correlation part of the self-energy strongly reduces the HF gap.
Moreover you should note that the QP correction is larger that one found in the h-BN bulk. Why?

==Use the truncated coulomb potential in a BSE calculation==
Generate the input for the BSE calculation:
$ yambo -J 2D_WR_WC -F yambo_BSE.in -r -o b -p p -y d -k sex -V all
Some remarks: the largest verbosity is used <code>-V all </code> and a long input file is generated; with the option <code> -p p </code> the static part of the screening matrix is read from the <code>ndb.pp</code> databases
Change the number of G-vectors in the correlation part of the kernel as:
[[Variables#BSENGBlk|BSENGBlk]]= 4 Ry # [BSK] Screened interaction block size
use the simple rigid scissor to open the correct the KS energies
% [[Variables#KfnQP_E|KfnQP_E]]
3.70000000 | 1.000000 | 1.000000 | # [EXTQP BSK BSS] E parameters (c/v) eV|adim|adim
Set the number of bands to:
% [[Variables#BSEBands|BSEBands]]
2 | 6 | # [BSK] Bands range
This choice means to include in the BSE only three occupied and 2 unoccupied bands.
Increase the number of energy steps
[[Variables#BEnSteps|BEnSteps]]= 500 # [BSS] Energy steps
To do the next Tutorial we need to write the excitonic WFs, so uncomment the following line
#[[Variables#WRbsWF|WRbsWF]] # [BSS] Write to disk excitonic the WFs
Close the input file and run yambo
$ yambo -J 2D_WR_WC -F yambo_BSE.in
Look at the report file ''r-2D_WR_WC_optics_bse_bsk_bss_em1d_ppa_rim_cut'' and plot the real and Imaginary part
of the dielectric function using the file ''o-2D_WR_WC.eps_q1_diago_bse''.

You realize immediately that the real part of the macroscopic dielectric function is almost 1, while the imaginary part is almost zero.
Indeed when the use of the cutoff in the coulomb potential is activated you are simulating a real isolated sheet in vacuum and so you are obtaining almost the dielectric function of vacuum!

For this reason yambo produces another file which contains the macroscopic polarizability (called here 'o-2D_WR_WC.alpha_q1_diago_bse')
which is a well defined quantity strictly related to optical conductivity or absorbance.

For a 2D system has the dimension of a length and it is defined as :

[[File:alpha2D.gif|none|x80px|]] where [[File:Lz.gif|none|x80px|]] is the size of the cell in the non-periodic direction (z in this case)

== Analyze the differences with corresponding GW and BSE calculations without the use of a truncated coulomb potential==

Open the input file yambo_G0W0.in and set back <code>CUTGeo= "none"</code>

Close the input and run yambo

$ yambo -J 2D_WR -F yambo_G0W0.in
You will find a new report ''r-2D_WR_em1d_ppa_HF_and_locXC_gw0_rim_cut''.
You are invited to see the difference with the previous one ''r-2D_WR_WC_em1d_ppa_HF_and_locXC_gw0_rim_cut''

and also a new output file ''o-2D_WR.qp'' is present. Open and check the QP correction at the last k-point. This time
a value of 2.83 eV instead of 3.70 eV is obtained. Are you able to explain this result?

Now redoo the BSE calculation but without reading the cutoff database and applying the QP correction just obtained without using the cutoff.

To do that, open the yambo_BSE.in and put <code>CUTGeo= "none"</code>
and set the QP correction of 2.83 eV, just obtained without uisng the cutoff.
% [[Variables#KfnQP_E|KfnQP_E]]
2.830000 | 1.000000 | 1.000000 | # [EXTQP BSK BSS] E parameters (c/v) eV|adim|adim

Close the input file and run yambo
$ yambo -J 2D_WR -F yambo_BSE.in
Plot the imaginary part of the GW and BSE polarizabilities with and withou cutoff:

$ gnuplot
$ gnuplot> set ylabel 'alpha'
$ gnuplot> plot 'o-2D_WR.eps_q1_diago_bse' u 1:($4*33.012/4/pi) w l title 'GW without cutoff' ,'o-2D_WR_WC.alpha_q1_diago_bse' u 1:4 w l title ' GW with cutoff' , 'o-2D_WR.eps_q1_diago_bse' u 1:($2*33.012/4/pi) w l title 'BSE without cutoff' ,'o-2D_WR_WC.alpha_q1_diago_bse' u 1:2 w l title 'BSE with cutoff'

[[File:BSE_2D_cutnocut.png|none|600px|]]

You can note that the energy of the peaks in the two GW spectra (with and without cutoff) are quite different:
you find the first peak around 7 eV without cutoff and around 8 eV with cutoff.
Instead the two GW+BSE spectra, without and with cutoff, are much more similar. Are you able to explain why?

Also note that, for the case without cutoff, to plot the imaginary part of the polarizability, the Imaginary part of the macroscopic dieletric function has been multiplied by the appropriate prefactor.

Remarks: The convergence in k-space can be done separately for GW and BSE
calculations, because generally more k-points are needed to converge the excitonic with respect to the quasi-particle properties.

N.B. If you will use the same inputs created in this tutorial remember to set up the cutoff variable ''CUTGeo= "box z"'' to use again the truncated coulomb potential in the GW and BSE calculations

Literature on two-dimensional h-BN: L. Wirtz et al Phys Rev Lett 96 126104 (2006), F. Rasmussen et al Phys Rev. B 94 155406 (2016),N. Berseneva et al Phys. Rev. B 87 035404 (2013).

How to treat low dimensional systems

2020-01-20T15:54:51Z

Maurizia: /* Analyze the differences with corresponding GW and BSE calculations without the use of a truncated coulomb potential */

In this tutorial you will learn how to treat low-dimensional material.
A small k-sampling is used to reduce the computational cost/time.
Later on you can repeat this tutorial but using denser k-grids to check the convergence.

== Prerequisites ==

* <code>yambo</code> executable
* <code>ypp</code> executable
* <code>gnuplot</code>, for plotting spectra
* Have Completed the [[First steps: a walk through from DFT to optical properties]] tutorial

==Avoid numerical divergences using the Random Integration Method (RIM)==
In DFT runs of low-dimensional materials low dimensional k-grids are generally used. (i.e. NxNx1 for a 2D sheet perpendicular to the z direction)
This can create numerical problems in the convergence of the many-body (MB) results due to the divergence at small q of the coulomb potential,
which appears in all the main equations.
To eliminate this problem YAMBO uses the so-called Random Integration Method
which means to use a Monte Carlo Integration with Random Q-points whose number ''[[Variables#RandQpts|RandQpts]]'' will be given in input.
For example the exchange self-energy matrix element which is:
[[File:sigmax.png|none|x50px|]]
assuming that the integrand is a smooth function of momenta the integral can be approximated as
[[File:rim0.png|none|x50px|]]
where the small Brillouin Zones (sBZ) relative to a given q-point are the Brillouin Zones of the momenta vectors lattice.
They are chosen in such a way to cover the whole BZ.
In the RIM run-level yambo calculates the integrals of the symmetrized Coulomb potential
[[File:rim1.png|none|x50px|]]

So we are ready to start the tutorial
First go in the proper directory and have a look if all the required databases are there
$ cd YAMBO_TUTORIALS/hBN-2D/YAMBO
$ ls ./SAVE
ns.db1 ns.wf ns.kb_pp_pwscf ...
$ yambo ''(initialization, if you haven't already done so)''

Create the input to generate the <code>ndb.RIM</code> database
$ yambo -F yambo_WR.in -r
and change the following variables
[[Variables#RandQpts|RandQpts]] = 1000000 # [RIM] Number of random q-points in the BZ
[[Variables#RandGvec|RandGvec]] = 100 RL # [RIM] Coulomb interaction RS components
N.B ''RandGvec=100'' means to use the RIM for the first 100 G-components of the coulomb potential
(Suggestion : later you can check convergence of the HF gap changing these two values)
Close input and Run yambo
$ yambo -F yambo_WR.in -J 2D_WR
At the end you find a new database ''ndb.RIM'' and a new report file ''r-2D_WR_rim_cut ''. Open it and look inside

Gamma point sphere radius [au]: 0.08028
Points outside the sphere : 799246
[Int_sBZ(q=0) 1/q^2]*(Vol_sBZ)^(-1/3) = 7.665674
should be < 7.795600
[WR./2D_WR//ndb.RIM]--------------------------------------
Brillouin Zone Q/K grids (IBZ/BZ): 7 36 7 36
Coulombian RL components : 111
Coulombian diagonal components :yes
RIM random points : 1000000
RIM RL volume [a.u.]: 0.390293
Real RL volume [a.u.]: 0.390112
Eps^-1 reference component :0
Eps^-1 components : 0.00 0.00 0.00
RIM anysotropy factor : 0.000000
- S/N 005962 -------------------------- v.04.01.02 r.00120 -

Summary of Coulomb integrals for non-metallic bands |Q|[au] RIM/Bare:

Q [1]:0.1000E-40.9833 * Q [2]: 0.256404 1.094818
Q [5]: 0.444104 1.032268 * Q [3]: 0.512807 1.024055
Q [6]: 0.678380 1.013997 * Q [4]: 0.769211 1.010774
Q [7]: 0.888208 1.008393

The RIM and Real RL Volumes are quite similar so one million random q-points seems a reasonable number,
but again you are invited, later on, to check the convergence of one of the main observables (i.e. HF gap, GW gap, absorption..) changing this number.

Close the report file and perform a calculation of the exchange self-energy to estimate the HF gap (very fast calculation) using the RIM.
Generate the input
$ yambo -F yambo_HF_WR.in -J 2D_WR -r -x
In order to calculate the HF gap only for the last k-point (which is the high-simmetry point K) change the last line as
Note also that 4 (5) is the highest occupied (lowest unoccupied) band.
%[[Variables#QPkrange|QPkrange]] # [GW] QP generalized Kpoint/Band indices
7| 7| 4| 5|
%

Close the input and run yambo
$ yambo -F yambo_HF_WR.in -J 2D_WR
At the end you will find the report file ''r-2D_WR_HF_and_locXC_rim_cut'' and the output file ''o-2D_WR.hf''. Open them and have a look
In the output file ''o-2D_WR.hf'' you will see
# K-point Band Eo Ehf DFT HF
#
7.00000 4.00000 0.00000 -3.25329 -16.21953 -19.47282
7.00000 5.00000 4.40109 9.67551 -11.10755 -5.83314

The HF gap is 12.92 eV obtained subtracting the 2 values in the fourth column
Now you can do a similar HF calculation without generating and reading the RIM database

$ yambo -F yambo_HF_NR.in -x
change the variables ''QPkrange'' as before, close the input and run yambo
$ yambo -F yambo_HF_NR.in -J 2D_NR

in this case the HF gap in the file ''o-2D_NR.hf'' results to be 12.69 eV.

Indeed the presence of the numerical instability, discussed before, is evident only using denser k-grids with respect to the one used in this Tutorial (6x6x1)
Suggestion: later you can generate other SAVE directories with denser k-grids and check the HF gap.
The results of the HF gap calculated with different k-grids without (noRIM) and with Random Integration Method (RIM) to show up the problem are reported:

noRIM RIM

6x6x1 12.69eV 12.92eV
12x12x1 12.80eV 12.92eV
15x15x1 12.96eV 12.93eV
45x45x1 15.52eV 12.96eV

So the '''home message''' is : use always the RIM in MB simulations of low-dimensional materials.

==Generate a truncated coulomb potential ==
To simulate an isolated nano-material a convergence with cell vacuum size is in principle required, like in the DFT runs.
The use of a truncated Coulomb potential allows to achieve faster convergence eliminating the interaction between the repeated images
along the non-periodic direction (see i.e. C. A. Rozzi et al Phys. Rev. B 73, 205119)
In this tutorial we learn how to generate a box-like cutoff for a 2D system with the non-periodic direction along z.

In YAMBO you can use :
* spherical cutoff (for 0D systems)
* cylindrical cutoff (for 1D systems)
* box-like cutoff (for 0D, 1D and 2D systems)

The Coulomb potential with a box-like cutoff is defined as
[[File:Vc1.png|none|x80px|]]
where S is a box-shaped region of the space having sides Lx,Ly and Lz, where they can also assume infinite values (untruncated interaction along desired directions).

Then the FT component is
[[File:Vc2.png|none|x60px|]] where [[File:Vc3.png|none|x60px|]]
For a 2D-system with non period direction along z-axis we have
[[File:Vc4.png|none|x60px|]]

Important remarks:
* the Random Integration Method (RIM) is required to perform the Q-space integration
* for sufficiently large supercells a choose L_i slightly smaller than the cell size in the i-direction ensures to avoid interaction between replicas

Create the input file:

$ yambo -F yambo_WR_WC.in -r

Change the RIM Variables as before and activate the ''cutoff'' generation
[[Variables#RandQpts|RandQpts]] = 1000000 # [RIM] Number of random q-points in the BZ
[[Variables#RandGvec|RandGvec]] = 100 RL # [RIM] Coulomb interaction RS components
[[Variables#CUTGeo|CUTGeo]] = "box z" # [CUT] Coulomb Cutoff geometry: box/cylinder/sphere X/Y/Z/XY..
% CUTBox
0.00 | 0.00 | 32.0 | # [CUT] [au] Box sides
%

Close the input file and run yambo:

$ yambo -F yambo_WR_WC.in -J 2D_WR_WC

in the directory 2D_WR_WC you will find a new database <code> ndb.cutoff </code>

==Use the truncated coulomb potential in a G0W0-PPA calculation==

Generate the input reading the databases in the ''2D_WR_WC'' directory
$ yambo -J 2D_WR_WC -F yambo_G0W0.in -p p -g n -r -k hartree -V qp
In the input change the following variables
[[Variables#NGsBlkXp|NGsBlkXp]] = 4 Ry # [Xp] Response block size
[[Variables#QPkrange|QPkrange]] # [GW] QP generalized Kpoint/Band indices
7| 7| 4| 5|
Close the input and run yambo
$ yambo -F yambo_G0W0.in -J 2D_WR_WC
At the end you will find a new report file ''r-2D_WR_WC_em1d_ppa_HF_and_locXC_gw0_rim_cut'', open it and have a look.
You will find also a new output file ''o-2D_WR_WC.qp''. If you open yoi will find that now the G0W0 gap is
4.40 eV (PBE) + 3.70 eV (G0W0 correction) = 8.10 eV
Indeed as you have learned in the previous tutorials the correlation part of the self-energy strongly reduces the HF gap.
Moreover you should note that the QP correction is larger that one found in the h-BN bulk. Why?

==Use the truncated coulomb potential in a BSE calculation==
Generate the input for the BSE calculation:
$ yambo -J 2D_WR_WC -F yambo_BSE.in -r -o b -p p -y d -k sex -V all
Some remarks: the largest verbosity is used <code>-V all </code> and a long input file is generated; with the option <code> -p p </code> the static part of the screening matrix is read from the <code>ndb.pp</code> databases
Change the number of G-vectors in the correlation part of the kernel as:
[[Variables#BSENGBlk|BSENGBlk]]= 4 Ry # [BSK] Screened interaction block size
use the simple rigid scissor to open the correct the KS energies
% [[Variables#KfnQP_E|KfnQP_E]]
3.70000000 | 1.000000 | 1.000000 | # [EXTQP BSK BSS] E parameters (c/v) eV|adim|adim
Set the number of bands to:
% [[Variables#BSEBands|BSEBands]]
2 | 6 | # [BSK] Bands range
This choice means to include in the BSE only three occupied and 2 unoccupied bands.
Increase the number of energy steps
[[Variables#BEnSteps|BEnSteps]]= 500 # [BSS] Energy steps
To do the next Tutorial we need to write the excitonic WFs, so uncomment the following line
#[[Variables#WRbsWF|WRbsWF]] # [BSS] Write to disk excitonic the WFs
Close the input file and run yambo
$ yambo -J 2D_WR_WC -F yambo_BSE.in
Look at the report file ''r-2D_WR_WC_optics_bse_bsk_bss_em1d_ppa_rim_cut'' and plot the real and Imaginary part
of the dielectric function using the file ''o-2D_WR_WC.eps_q1_diago_bse''.

You realize immediately that the real part of the macroscopic dielectric function is almost 1, while the imaginary part is almost zero.
Indeed when the use of the cutoff in the coulomb potential is activated you are simulating a real isolated sheet in vacuum and so you are obtaining almost the dielectric function of vacuum!

For this reason yambo produces another file which contains the macroscopic polarizability (called here 'o-2D_WR_WC.alpha_q1_diago_bse')
which is a well defined quantity strictly related to optical conductivity or absorbance.

For a 2D system has the dimension of a length and it is defined as :

[[File:alpha2D.gif|none|x80px|]] where [[File:Lz.gif|none|x80px|]] is the size of the cell in the non-periodic direction (z in this case)

== Analyze the differences with corresponding GW and BSE calculations without the use of a truncated coulomb potential==

Open the input file yambo_G0W0.in and set back <code>CUTGeo= "none"</code>

Close the input and run yambo

$ yambo -J 2D_WR -F yambo_G0W0.in
You will find a new report ''r-2D_WR_em1d_ppa_HF_and_locXC_gw0_rim_cut''.
You are invited to see the difference with the previous one ''r-2D_WR_WC_em1d_ppa_HF_and_locXC_gw0_rim_cut''

and also a new output file ''o-2D_WR.qp'' is present. Open and check the QP correction at the last k-point. This time
a value of 2.83 eV instead of 3.70 eV is obtained. Are you able to explain this result?

Now redoo the BSE calculation but without reading the cutoff database and applying the QP correction just obtained without using the cutoff.

To do that, open the yambo_BSE.in and put <code>CUTGeo= "none"</code>
and set the QP correction of 2.83 eV, just obtained without uisng the cutoff.
% [[Variables#KfnQP_E|KfnQP_E]]
2.830000 | 1.000000 | 1.000000 | # [EXTQP BSK BSS] E parameters (c/v) eV|adim|adim

Close the input file and run yambo
$ yambo -J 2D_WR -F yambo_BSE.in
Plot the imaginary part of the GW and BSE polarizabilities with and withou cutoff:

$ gnuplot
$ gnuplot> set ylabel 'alpha'
$ gnuplot> plot 'o-2D_WR.eps_q1_diago_bse' u 1:($4*33.012/4/pi) w l title 'GW without cutoff' ,'o-2D_WR_WC.alpha_q1_diago_bse' u 1:4 w l title ' GW with cutoff' , 'o-2D_WR.eps_q1_diago_bse' u 1:($2*33.012/4/pi) w l title 'BSE without cutoff' ,'o-2D_WR_WC.alpha_q1_diago_bse' u 1:2 w l title 'BSE with cutoff'

[[File:BSE_2D_cutnocut_new2.png|none|600px|]]

You can note that the energy of the peaks in the two GW spectra (with and without cutoff) are quite different:
you find the first peak around 7 eV without cutoff and around 8 eV with cutoff.
Instead the two GW+BSE spectra, without and with cutoff, are much more similar. Are you able to explain why?

Also note that, for the case without cutoff, to plot the imaginary part of the polarizability, the Imaginary part of the macroscopic dieletric function has been multiplied by the appropriate prefactor.

Remarks: The convergence in k-space can be done separately for GW and BSE
calculations, because generally more k-points are needed to converge the excitonic with respect to the quasi-particle properties.

N.B. If you will use the same inputs created in this tutorial remember to set up the cutoff variable ''CUTGeo= "box z"'' to use again the truncated coulomb potential in the GW and BSE calculations

Literature on two-dimensional h-BN: L. Wirtz et al Phys Rev Lett 96 126104 (2006), F. Rasmussen et al Phys Rev. B 94 155406 (2016),N. Berseneva et al Phys. Rev. B 87 035404 (2013).

How to treat low dimensional systems

2020-01-20T15:49:29Z

Maurizia: /* Analyze the differences with corresponding GW and BSE calculations without the use of a truncated coulomb potential */

In this tutorial you will learn how to treat low-dimensional material.
A small k-sampling is used to reduce the computational cost/time.
Later on you can repeat this tutorial but using denser k-grids to check the convergence.

== Prerequisites ==

* <code>yambo</code> executable
* <code>ypp</code> executable
* <code>gnuplot</code>, for plotting spectra
* Have Completed the [[First steps: a walk through from DFT to optical properties]] tutorial

==Avoid numerical divergences using the Random Integration Method (RIM)==
In DFT runs of low-dimensional materials low dimensional k-grids are generally used. (i.e. NxNx1 for a 2D sheet perpendicular to the z direction)
This can create numerical problems in the convergence of the many-body (MB) results due to the divergence at small q of the coulomb potential,
which appears in all the main equations.
To eliminate this problem YAMBO uses the so-called Random Integration Method
which means to use a Monte Carlo Integration with Random Q-points whose number ''[[Variables#RandQpts|RandQpts]]'' will be given in input.
For example the exchange self-energy matrix element which is:
[[File:sigmax.png|none|x50px|]]
assuming that the integrand is a smooth function of momenta the integral can be approximated as
[[File:rim0.png|none|x50px|]]
where the small Brillouin Zones (sBZ) relative to a given q-point are the Brillouin Zones of the momenta vectors lattice.
They are chosen in such a way to cover the whole BZ.
In the RIM run-level yambo calculates the integrals of the symmetrized Coulomb potential
[[File:rim1.png|none|x50px|]]

So we are ready to start the tutorial
First go in the proper directory and have a look if all the required databases are there
$ cd YAMBO_TUTORIALS/hBN-2D/YAMBO
$ ls ./SAVE
ns.db1 ns.wf ns.kb_pp_pwscf ...
$ yambo ''(initialization, if you haven't already done so)''

Create the input to generate the <code>ndb.RIM</code> database
$ yambo -F yambo_WR.in -r
and change the following variables
[[Variables#RandQpts|RandQpts]] = 1000000 # [RIM] Number of random q-points in the BZ
[[Variables#RandGvec|RandGvec]] = 100 RL # [RIM] Coulomb interaction RS components
N.B ''RandGvec=100'' means to use the RIM for the first 100 G-components of the coulomb potential
(Suggestion : later you can check convergence of the HF gap changing these two values)
Close input and Run yambo
$ yambo -F yambo_WR.in -J 2D_WR
At the end you find a new database ''ndb.RIM'' and a new report file ''r-2D_WR_rim_cut ''. Open it and look inside

Gamma point sphere radius [au]: 0.08028
Points outside the sphere : 799246
[Int_sBZ(q=0) 1/q^2]*(Vol_sBZ)^(-1/3) = 7.665674
should be < 7.795600
[WR./2D_WR//ndb.RIM]--------------------------------------
Brillouin Zone Q/K grids (IBZ/BZ): 7 36 7 36
Coulombian RL components : 111
Coulombian diagonal components :yes
RIM random points : 1000000
RIM RL volume [a.u.]: 0.390293
Real RL volume [a.u.]: 0.390112
Eps^-1 reference component :0
Eps^-1 components : 0.00 0.00 0.00
RIM anysotropy factor : 0.000000
- S/N 005962 -------------------------- v.04.01.02 r.00120 -

Summary of Coulomb integrals for non-metallic bands |Q|[au] RIM/Bare:

Q [1]:0.1000E-40.9833 * Q [2]: 0.256404 1.094818
Q [5]: 0.444104 1.032268 * Q [3]: 0.512807 1.024055
Q [6]: 0.678380 1.013997 * Q [4]: 0.769211 1.010774
Q [7]: 0.888208 1.008393

The RIM and Real RL Volumes are quite similar so one million random q-points seems a reasonable number,
but again you are invited, later on, to check the convergence of one of the main observables (i.e. HF gap, GW gap, absorption..) changing this number.

Close the report file and perform a calculation of the exchange self-energy to estimate the HF gap (very fast calculation) using the RIM.
Generate the input
$ yambo -F yambo_HF_WR.in -J 2D_WR -r -x
In order to calculate the HF gap only for the last k-point (which is the high-simmetry point K) change the last line as
Note also that 4 (5) is the highest occupied (lowest unoccupied) band.
%[[Variables#QPkrange|QPkrange]] # [GW] QP generalized Kpoint/Band indices
7| 7| 4| 5|
%

Close the input and run yambo
$ yambo -F yambo_HF_WR.in -J 2D_WR
At the end you will find the report file ''r-2D_WR_HF_and_locXC_rim_cut'' and the output file ''o-2D_WR.hf''. Open them and have a look
In the output file ''o-2D_WR.hf'' you will see
# K-point Band Eo Ehf DFT HF
#
7.00000 4.00000 0.00000 -3.25329 -16.21953 -19.47282
7.00000 5.00000 4.40109 9.67551 -11.10755 -5.83314

The HF gap is 12.92 eV obtained subtracting the 2 values in the fourth column
Now you can do a similar HF calculation without generating and reading the RIM database

$ yambo -F yambo_HF_NR.in -x
change the variables ''QPkrange'' as before, close the input and run yambo
$ yambo -F yambo_HF_NR.in -J 2D_NR

in this case the HF gap in the file ''o-2D_NR.hf'' results to be 12.69 eV.

Indeed the presence of the numerical instability, discussed before, is evident only using denser k-grids with respect to the one used in this Tutorial (6x6x1)
Suggestion: later you can generate other SAVE directories with denser k-grids and check the HF gap.
The results of the HF gap calculated with different k-grids without (noRIM) and with Random Integration Method (RIM) to show up the problem are reported:

noRIM RIM

6x6x1 12.69eV 12.92eV
12x12x1 12.80eV 12.92eV
15x15x1 12.96eV 12.93eV
45x45x1 15.52eV 12.96eV

So the '''home message''' is : use always the RIM in MB simulations of low-dimensional materials.

==Generate a truncated coulomb potential ==
To simulate an isolated nano-material a convergence with cell vacuum size is in principle required, like in the DFT runs.
The use of a truncated Coulomb potential allows to achieve faster convergence eliminating the interaction between the repeated images
along the non-periodic direction (see i.e. C. A. Rozzi et al Phys. Rev. B 73, 205119)
In this tutorial we learn how to generate a box-like cutoff for a 2D system with the non-periodic direction along z.

In YAMBO you can use :
* spherical cutoff (for 0D systems)
* cylindrical cutoff (for 1D systems)
* box-like cutoff (for 0D, 1D and 2D systems)

The Coulomb potential with a box-like cutoff is defined as
[[File:Vc1.png|none|x80px|]]
where S is a box-shaped region of the space having sides Lx,Ly and Lz, where they can also assume infinite values (untruncated interaction along desired directions).

Then the FT component is
[[File:Vc2.png|none|x60px|]] where [[File:Vc3.png|none|x60px|]]
For a 2D-system with non period direction along z-axis we have
[[File:Vc4.png|none|x60px|]]

Important remarks:
* the Random Integration Method (RIM) is required to perform the Q-space integration
* for sufficiently large supercells a choose L_i slightly smaller than the cell size in the i-direction ensures to avoid interaction between replicas

Create the input file:

$ yambo -F yambo_WR_WC.in -r

Change the RIM Variables as before and activate the ''cutoff'' generation
[[Variables#RandQpts|RandQpts]] = 1000000 # [RIM] Number of random q-points in the BZ
[[Variables#RandGvec|RandGvec]] = 100 RL # [RIM] Coulomb interaction RS components
[[Variables#CUTGeo|CUTGeo]] = "box z" # [CUT] Coulomb Cutoff geometry: box/cylinder/sphere X/Y/Z/XY..
% CUTBox
0.00 | 0.00 | 32.0 | # [CUT] [au] Box sides
%

Close the input file and run yambo:

$ yambo -F yambo_WR_WC.in -J 2D_WR_WC

in the directory 2D_WR_WC you will find a new database <code> ndb.cutoff </code>

==Use the truncated coulomb potential in a G0W0-PPA calculation==

Generate the input reading the databases in the ''2D_WR_WC'' directory
$ yambo -J 2D_WR_WC -F yambo_G0W0.in -p p -g n -r -k hartree -V qp
In the input change the following variables
[[Variables#NGsBlkXp|NGsBlkXp]] = 4 Ry # [Xp] Response block size
[[Variables#QPkrange|QPkrange]] # [GW] QP generalized Kpoint/Band indices
7| 7| 4| 5|
Close the input and run yambo
$ yambo -F yambo_G0W0.in -J 2D_WR_WC
At the end you will find a new report file ''r-2D_WR_WC_em1d_ppa_HF_and_locXC_gw0_rim_cut'', open it and have a look.
You will find also a new output file ''o-2D_WR_WC.qp''. If you open yoi will find that now the G0W0 gap is
4.40 eV (PBE) + 3.70 eV (G0W0 correction) = 8.10 eV
Indeed as you have learned in the previous tutorials the correlation part of the self-energy strongly reduces the HF gap.
Moreover you should note that the QP correction is larger that one found in the h-BN bulk. Why?

==Use the truncated coulomb potential in a BSE calculation==
Generate the input for the BSE calculation:
$ yambo -J 2D_WR_WC -F yambo_BSE.in -r -o b -p p -y d -k sex -V all
Some remarks: the largest verbosity is used <code>-V all </code> and a long input file is generated; with the option <code> -p p </code> the static part of the screening matrix is read from the <code>ndb.pp</code> databases
Change the number of G-vectors in the correlation part of the kernel as:
[[Variables#BSENGBlk|BSENGBlk]]= 4 Ry # [BSK] Screened interaction block size
use the simple rigid scissor to open the correct the KS energies
% [[Variables#KfnQP_E|KfnQP_E]]
3.70000000 | 1.000000 | 1.000000 | # [EXTQP BSK BSS] E parameters (c/v) eV|adim|adim
Set the number of bands to:
% [[Variables#BSEBands|BSEBands]]
2 | 6 | # [BSK] Bands range
This choice means to include in the BSE only three occupied and 2 unoccupied bands.
Increase the number of energy steps
[[Variables#BEnSteps|BEnSteps]]= 500 # [BSS] Energy steps
To do the next Tutorial we need to write the excitonic WFs, so uncomment the following line
#[[Variables#WRbsWF|WRbsWF]] # [BSS] Write to disk excitonic the WFs
Close the input file and run yambo
$ yambo -J 2D_WR_WC -F yambo_BSE.in
Look at the report file ''r-2D_WR_WC_optics_bse_bsk_bss_em1d_ppa_rim_cut'' and plot the real and Imaginary part
of the dielectric function using the file ''o-2D_WR_WC.eps_q1_diago_bse''.

You realize immediately that the real part of the macroscopic dielectric function is almost 1, while the imaginary part is almost zero.
Indeed when the use of the cutoff in the coulomb potential is activated you are simulating a real isolated sheet in vacuum and so you are obtaining almost the dielectric function of vacuum!

For this reason yambo produces another file which contains the macroscopic polarizability (called here 'o-2D_WR_WC.alpha_q1_diago_bse')
which is a well defined quantity strictly related to optical conductivity or absorbance.

For a 2D system has the dimension of a length and it is defined as :

[[File:alpha2D.gif|none|x80px|]] where [[File:Lz.gif|none|x80px|]] is the size of the cell in the non-periodic direction (z in this case)

== Analyze the differences with corresponding GW and BSE calculations without the use of a truncated coulomb potential==

Open the input file yambo_G0W0.in and set back <code>CUTGeo= "none"</code>

Close the input and run yambo

$ yambo -J 2D_WR -F yambo_G0W0.in
You will find a new report ''r-2D_WR_em1d_ppa_HF_and_locXC_gw0_rim_cut''.
You are invited to see the difference with the previous one ''r-2D_WR_WC_em1d_ppa_HF_and_locXC_gw0_rim_cut''

and also a new output file ''o-2D_WR.qp'' is present. Open and check the QP correction at the last k-point. This time
a value of 2.83 eV instead of 3.70 eV is obtained. Are you able to explain this result?

Now redoo the BSE calculation but without reading the cutoff database and applying the QP correction just obtained without using the cutoff.

To do that, open the yambo_BSE.in and put <code>CUTGeo= "none"</code>
and set the QP correction of 2.83 eV, just obtained without uisng the cutoff.
% [[Variables#KfnQP_E|KfnQP_E]]
2.830000 | 1.000000 | 1.000000 | # [EXTQP BSK BSS] E parameters (c/v) eV|adim|adim

Close the input file and run yambo
$ yambo -J 2D_WR -F yambo_BSE.in
Plot the imaginary part of the GW and BSE polarizabilities with and withou cutoff:

$ gnuplot
$ gnuplot> set ylabel 'alpha'
$ gnuplot> plot 'o-2D_WR.eps_q1_diago_bse' u 1:($4*33.012/4/pi) w l title 'GW without cutoff' ,'o-2D_WR_WC.alpha_q1_diago_bse' u 1:4 w l title ' GW with cutoff' , 'o-2D_WR.eps_q1_diago_bse' u 1:($2*33.012/4/pi) w l title 'BSE without cutoff' ,'o-2D_WR_WC.alpha_q1_diago_bse' u 1:2 w l title 'BSE with cutoff'

[[File:BSE_2D_cutnocut_new2.png|none|600px|]]

You can note that the energy of the peaks in the two G0W0 spectra (with and without cutoff) are quite different:
you find the first peak around 7 eV without cutoff and around 8 eV with cutoff.
Instead the two GW+BSE spectra, without and with cutoff, are much more similar. Are you able to explain why?
Remarks: The convergence in k-space can be done separately for GW and BSE
calculations, because generally more k-points are needed to converge the excitonic with respect to the quasi-particle properties.

N.B. If you will use the same inputs created in this tutorial remember to set up the cutoff variable ''CUTGeo= "box z"'' to use again the truncated coulomb potential in the GW and BSE calculations

Literature on two-dimensional h-BN: L. Wirtz et al Phys Rev Lett 96 126104 (2006), F. Rasmussen et al Phys Rev. B 94 155406 (2016),N. Berseneva et al Phys. Rev. B 87 035404 (2013).

How to treat low dimensional systems

2020-01-20T15:37:38Z

Maurizia: /* Analyze the differences with corresponding GW and BSE calculations without the use of a truncated coulomb potential */

In this tutorial you will learn how to treat low-dimensional material.
A small k-sampling is used to reduce the computational cost/time.
Later on you can repeat this tutorial but using denser k-grids to check the convergence.

== Prerequisites ==

* <code>yambo</code> executable
* <code>ypp</code> executable
* <code>gnuplot</code>, for plotting spectra
* Have Completed the [[First steps: a walk through from DFT to optical properties]] tutorial

==Avoid numerical divergences using the Random Integration Method (RIM)==
In DFT runs of low-dimensional materials low dimensional k-grids are generally used. (i.e. NxNx1 for a 2D sheet perpendicular to the z direction)
This can create numerical problems in the convergence of the many-body (MB) results due to the divergence at small q of the coulomb potential,
which appears in all the main equations.
To eliminate this problem YAMBO uses the so-called Random Integration Method
which means to use a Monte Carlo Integration with Random Q-points whose number ''[[Variables#RandQpts|RandQpts]]'' will be given in input.
For example the exchange self-energy matrix element which is:
[[File:sigmax.png|none|x50px|]]
assuming that the integrand is a smooth function of momenta the integral can be approximated as
[[File:rim0.png|none|x50px|]]
where the small Brillouin Zones (sBZ) relative to a given q-point are the Brillouin Zones of the momenta vectors lattice.
They are chosen in such a way to cover the whole BZ.
In the RIM run-level yambo calculates the integrals of the symmetrized Coulomb potential
[[File:rim1.png|none|x50px|]]

So we are ready to start the tutorial
First go in the proper directory and have a look if all the required databases are there
$ cd YAMBO_TUTORIALS/hBN-2D/YAMBO
$ ls ./SAVE
ns.db1 ns.wf ns.kb_pp_pwscf ...
$ yambo ''(initialization, if you haven't already done so)''

Create the input to generate the <code>ndb.RIM</code> database
$ yambo -F yambo_WR.in -r
and change the following variables
[[Variables#RandQpts|RandQpts]] = 1000000 # [RIM] Number of random q-points in the BZ
[[Variables#RandGvec|RandGvec]] = 100 RL # [RIM] Coulomb interaction RS components
N.B ''RandGvec=100'' means to use the RIM for the first 100 G-components of the coulomb potential
(Suggestion : later you can check convergence of the HF gap changing these two values)
Close input and Run yambo
$ yambo -F yambo_WR.in -J 2D_WR
At the end you find a new database ''ndb.RIM'' and a new report file ''r-2D_WR_rim_cut ''. Open it and look inside

Gamma point sphere radius [au]: 0.08028
Points outside the sphere : 799246
[Int_sBZ(q=0) 1/q^2]*(Vol_sBZ)^(-1/3) = 7.665674
should be < 7.795600
[WR./2D_WR//ndb.RIM]--------------------------------------
Brillouin Zone Q/K grids (IBZ/BZ): 7 36 7 36
Coulombian RL components : 111
Coulombian diagonal components :yes
RIM random points : 1000000
RIM RL volume [a.u.]: 0.390293
Real RL volume [a.u.]: 0.390112
Eps^-1 reference component :0
Eps^-1 components : 0.00 0.00 0.00
RIM anysotropy factor : 0.000000
- S/N 005962 -------------------------- v.04.01.02 r.00120 -

Summary of Coulomb integrals for non-metallic bands |Q|[au] RIM/Bare:

Q [1]:0.1000E-40.9833 * Q [2]: 0.256404 1.094818
Q [5]: 0.444104 1.032268 * Q [3]: 0.512807 1.024055
Q [6]: 0.678380 1.013997 * Q [4]: 0.769211 1.010774
Q [7]: 0.888208 1.008393

The RIM and Real RL Volumes are quite similar so one million random q-points seems a reasonable number,
but again you are invited, later on, to check the convergence of one of the main observables (i.e. HF gap, GW gap, absorption..) changing this number.

Close the report file and perform a calculation of the exchange self-energy to estimate the HF gap (very fast calculation) using the RIM.
Generate the input
$ yambo -F yambo_HF_WR.in -J 2D_WR -r -x
In order to calculate the HF gap only for the last k-point (which is the high-simmetry point K) change the last line as
Note also that 4 (5) is the highest occupied (lowest unoccupied) band.
%[[Variables#QPkrange|QPkrange]] # [GW] QP generalized Kpoint/Band indices
7| 7| 4| 5|
%

Close the input and run yambo
$ yambo -F yambo_HF_WR.in -J 2D_WR
At the end you will find the report file ''r-2D_WR_HF_and_locXC_rim_cut'' and the output file ''o-2D_WR.hf''. Open them and have a look
In the output file ''o-2D_WR.hf'' you will see
# K-point Band Eo Ehf DFT HF
#
7.00000 4.00000 0.00000 -3.25329 -16.21953 -19.47282
7.00000 5.00000 4.40109 9.67551 -11.10755 -5.83314

The HF gap is 12.92 eV obtained subtracting the 2 values in the fourth column
Now you can do a similar HF calculation without generating and reading the RIM database

$ yambo -F yambo_HF_NR.in -x
change the variables ''QPkrange'' as before, close the input and run yambo
$ yambo -F yambo_HF_NR.in -J 2D_NR

in this case the HF gap in the file ''o-2D_NR.hf'' results to be 12.69 eV.

Indeed the presence of the numerical instability, discussed before, is evident only using denser k-grids with respect to the one used in this Tutorial (6x6x1)
Suggestion: later you can generate other SAVE directories with denser k-grids and check the HF gap.
The results of the HF gap calculated with different k-grids without (noRIM) and with Random Integration Method (RIM) to show up the problem are reported:

noRIM RIM

6x6x1 12.69eV 12.92eV
12x12x1 12.80eV 12.92eV
15x15x1 12.96eV 12.93eV
45x45x1 15.52eV 12.96eV

So the '''home message''' is : use always the RIM in MB simulations of low-dimensional materials.

==Generate a truncated coulomb potential ==
To simulate an isolated nano-material a convergence with cell vacuum size is in principle required, like in the DFT runs.
The use of a truncated Coulomb potential allows to achieve faster convergence eliminating the interaction between the repeated images
along the non-periodic direction (see i.e. C. A. Rozzi et al Phys. Rev. B 73, 205119)
In this tutorial we learn how to generate a box-like cutoff for a 2D system with the non-periodic direction along z.

In YAMBO you can use :
* spherical cutoff (for 0D systems)
* cylindrical cutoff (for 1D systems)
* box-like cutoff (for 0D, 1D and 2D systems)

The Coulomb potential with a box-like cutoff is defined as
[[File:Vc1.png|none|x80px|]]
where S is a box-shaped region of the space having sides Lx,Ly and Lz, where they can also assume infinite values (untruncated interaction along desired directions).

Then the FT component is
[[File:Vc2.png|none|x60px|]] where [[File:Vc3.png|none|x60px|]]
For a 2D-system with non period direction along z-axis we have
[[File:Vc4.png|none|x60px|]]

Important remarks:
* the Random Integration Method (RIM) is required to perform the Q-space integration
* for sufficiently large supercells a choose L_i slightly smaller than the cell size in the i-direction ensures to avoid interaction between replicas

Create the input file:

$ yambo -F yambo_WR_WC.in -r

Change the RIM Variables as before and activate the ''cutoff'' generation
[[Variables#RandQpts|RandQpts]] = 1000000 # [RIM] Number of random q-points in the BZ
[[Variables#RandGvec|RandGvec]] = 100 RL # [RIM] Coulomb interaction RS components
[[Variables#CUTGeo|CUTGeo]] = "box z" # [CUT] Coulomb Cutoff geometry: box/cylinder/sphere X/Y/Z/XY..
% CUTBox
0.00 | 0.00 | 32.0 | # [CUT] [au] Box sides
%

Close the input file and run yambo:

$ yambo -F yambo_WR_WC.in -J 2D_WR_WC

in the directory 2D_WR_WC you will find a new database <code> ndb.cutoff </code>

==Use the truncated coulomb potential in a G0W0-PPA calculation==

Generate the input reading the databases in the ''2D_WR_WC'' directory
$ yambo -J 2D_WR_WC -F yambo_G0W0.in -p p -g n -r -k hartree -V qp
In the input change the following variables
[[Variables#NGsBlkXp|NGsBlkXp]] = 4 Ry # [Xp] Response block size
[[Variables#QPkrange|QPkrange]] # [GW] QP generalized Kpoint/Band indices
7| 7| 4| 5|
Close the input and run yambo
$ yambo -F yambo_G0W0.in -J 2D_WR_WC
At the end you will find a new report file ''r-2D_WR_WC_em1d_ppa_HF_and_locXC_gw0_rim_cut'', open it and have a look.
You will find also a new output file ''o-2D_WR_WC.qp''. If you open yoi will find that now the G0W0 gap is
4.40 eV (PBE) + 3.70 eV (G0W0 correction) = 8.10 eV
Indeed as you have learned in the previous tutorials the correlation part of the self-energy strongly reduces the HF gap.
Moreover you should note that the QP correction is larger that one found in the h-BN bulk. Why?

==Use the truncated coulomb potential in a BSE calculation==
Generate the input for the BSE calculation:
$ yambo -J 2D_WR_WC -F yambo_BSE.in -r -o b -p p -y d -k sex -V all
Some remarks: the largest verbosity is used <code>-V all </code> and a long input file is generated; with the option <code> -p p </code> the static part of the screening matrix is read from the <code>ndb.pp</code> databases
Change the number of G-vectors in the correlation part of the kernel as:
[[Variables#BSENGBlk|BSENGBlk]]= 4 Ry # [BSK] Screened interaction block size
use the simple rigid scissor to open the correct the KS energies
% [[Variables#KfnQP_E|KfnQP_E]]
3.70000000 | 1.000000 | 1.000000 | # [EXTQP BSK BSS] E parameters (c/v) eV|adim|adim
Set the number of bands to:
% [[Variables#BSEBands|BSEBands]]
2 | 6 | # [BSK] Bands range
This choice means to include in the BSE only three occupied and 2 unoccupied bands.
Increase the number of energy steps
[[Variables#BEnSteps|BEnSteps]]= 500 # [BSS] Energy steps
To do the next Tutorial we need to write the excitonic WFs, so uncomment the following line
#[[Variables#WRbsWF|WRbsWF]] # [BSS] Write to disk excitonic the WFs
Close the input file and run yambo
$ yambo -J 2D_WR_WC -F yambo_BSE.in
Look at the report file ''r-2D_WR_WC_optics_bse_bsk_bss_em1d_ppa_rim_cut'' and plot the real and Imaginary part
of the dielectric function using the file ''o-2D_WR_WC.eps_q1_diago_bse''.

You realize immediately that the real part of the macroscopic dielectric function is almost 1, while the imaginary part is almost zero.
Indeed when the use of the cutoff in the coulomb potential is activated you are simulating a real isolated sheet in vacuum and so you are obtaining almost the dielectric function of vacuum!

For this reason yambo produces another file which contains the macroscopic polarizability (called here 'o-2D_WR_WC.alpha_q1_diago_bse')
which is a well defined quantity strictly related to optical conductivity or absorbance.

For a 2D system has the dimension of a length and it is defined as :

[[File:alpha2D.gif|none|x80px|]] where [[File:Lz.gif|none|x80px|]] is the size of the cell in the non-periodic direction (z in this case)

== Analyze the differences with corresponding GW and BSE calculations without the use of a truncated coulomb potential==

Open the input file yambo_G0W0.in and set back <code>CUTGeo= "none"</code>

Close the input and run yambo

$ yambo -J 2D_WR -F yambo_G0W0.in
You will find a new report ''r-2D_WR_em1d_ppa_HF_and_locXC_gw0_rim_cut''.
You are invited to see the difference with the previous one ''r-2D_WR_WC_em1d_ppa_HF_and_locXC_gw0_rim_cut''

and also a new output file ''o-2D_WR.qp'' is present. Open and check the QP correction at the last k-point. This time
a value of 2.83 eV instead of 3.70 eV is obtained. Are you able to explain this result?

Now redoo the BSE calculation but without reading the cutoff database and applying the QP correction just obtained without using the cutoff.

To do that, open the yambo_BSE.in and put <code>CUTGeo= "none"</code>
and set the QP correction of 2.83 eV, just obtained without uisng the cutoff.
% [[Variables#KfnQP_E|KfnQP_E]]
2.830000 | 1.000000 | 1.000000 | # [EXTQP BSK BSS] E parameters (c/v) eV|adim|adim

Close the input file and run yambo
$ yambo -J 2D_WR -F yambo_BSE.in
Plot the imaginary part of the GW and BSE polarizability :

$ gnuplot
$ gnuplot> set ylabel 'alpha'
$ gnuplot> plot 'o-2D_WR.eps_q1_diago_bse' u 1:($4*33.01/4/pi) w l title 'GW without cutoff' ,'o-2D_WR_WC.alpha_q1_diago_bse' u 1:4 w l title ' GW with cutoff' , 'o-2D_WR.eps_q1_diago_bse' u 1:($2*33.01/4/pi) w l title 'BSE without cutoff' ,'o-2D_WR_WC.alpha_q1_diago_bse' u 1:2 w l title 'BSE with cutoff'

[[File:BSE_2D_cutnocut_new2.png|none|600px|]]

You can note that the energy of the peaks in the two G0W0 spectra (with and without cutoff) are quite different:
you find the first peak around 7 eV without cutoff and around 8 eV with cutoff.
Instead the two GW+BSE spectra, without and with cutoff, are much more similar. Are you able to explain why?
Remarks: The convergence in k-space can be done separately for GW and BSE
calculations, because generally more k-points are needed to converge the excitonic with respect to the quasi-particle properties.

N.B. If you will use the same inputs created in this tutorial remember to set up the cutoff variable ''CUTGeo= "box z"'' to use again the truncated coulomb potential in the GW and BSE calculations

Literature on two-dimensional h-BN: L. Wirtz et al Phys Rev Lett 96 126104 (2006), F. Rasmussen et al Phys Rev. B 94 155406 (2016),N. Berseneva et al Phys. Rev. B 87 035404 (2013).

File:Alpha2D.gif

2020-01-20T15:35:15Z

Maurizia: Maurizia uploaded a new version of File:Alpha2D.gif

How to treat low dimensional systems

2020-01-20T15:31:59Z

Maurizia: /* Analyze the differences with corresponding GW and BSE calculations without the use of a truncated coulomb potential */

In this tutorial you will learn how to treat low-dimensional material.
A small k-sampling is used to reduce the computational cost/time.
Later on you can repeat this tutorial but using denser k-grids to check the convergence.

== Prerequisites ==

* <code>yambo</code> executable
* <code>ypp</code> executable
* <code>gnuplot</code>, for plotting spectra
* Have Completed the [[First steps: a walk through from DFT to optical properties]] tutorial

==Avoid numerical divergences using the Random Integration Method (RIM)==
In DFT runs of low-dimensional materials low dimensional k-grids are generally used. (i.e. NxNx1 for a 2D sheet perpendicular to the z direction)
This can create numerical problems in the convergence of the many-body (MB) results due to the divergence at small q of the coulomb potential,
which appears in all the main equations.
To eliminate this problem YAMBO uses the so-called Random Integration Method
which means to use a Monte Carlo Integration with Random Q-points whose number ''[[Variables#RandQpts|RandQpts]]'' will be given in input.
For example the exchange self-energy matrix element which is:
[[File:sigmax.png|none|x50px|]]
assuming that the integrand is a smooth function of momenta the integral can be approximated as
[[File:rim0.png|none|x50px|]]
where the small Brillouin Zones (sBZ) relative to a given q-point are the Brillouin Zones of the momenta vectors lattice.
They are chosen in such a way to cover the whole BZ.
In the RIM run-level yambo calculates the integrals of the symmetrized Coulomb potential
[[File:rim1.png|none|x50px|]]

So we are ready to start the tutorial
First go in the proper directory and have a look if all the required databases are there
$ cd YAMBO_TUTORIALS/hBN-2D/YAMBO
$ ls ./SAVE
ns.db1 ns.wf ns.kb_pp_pwscf ...
$ yambo ''(initialization, if you haven't already done so)''

Create the input to generate the <code>ndb.RIM</code> database
$ yambo -F yambo_WR.in -r
and change the following variables
[[Variables#RandQpts|RandQpts]] = 1000000 # [RIM] Number of random q-points in the BZ
[[Variables#RandGvec|RandGvec]] = 100 RL # [RIM] Coulomb interaction RS components
N.B ''RandGvec=100'' means to use the RIM for the first 100 G-components of the coulomb potential
(Suggestion : later you can check convergence of the HF gap changing these two values)
Close input and Run yambo
$ yambo -F yambo_WR.in -J 2D_WR
At the end you find a new database ''ndb.RIM'' and a new report file ''r-2D_WR_rim_cut ''. Open it and look inside

Gamma point sphere radius [au]: 0.08028
Points outside the sphere : 799246
[Int_sBZ(q=0) 1/q^2]*(Vol_sBZ)^(-1/3) = 7.665674
should be < 7.795600
[WR./2D_WR//ndb.RIM]--------------------------------------
Brillouin Zone Q/K grids (IBZ/BZ): 7 36 7 36
Coulombian RL components : 111
Coulombian diagonal components :yes
RIM random points : 1000000
RIM RL volume [a.u.]: 0.390293
Real RL volume [a.u.]: 0.390112
Eps^-1 reference component :0
Eps^-1 components : 0.00 0.00 0.00
RIM anysotropy factor : 0.000000
- S/N 005962 -------------------------- v.04.01.02 r.00120 -

Summary of Coulomb integrals for non-metallic bands |Q|[au] RIM/Bare:

Q [1]:0.1000E-40.9833 * Q [2]: 0.256404 1.094818
Q [5]: 0.444104 1.032268 * Q [3]: 0.512807 1.024055
Q [6]: 0.678380 1.013997 * Q [4]: 0.769211 1.010774
Q [7]: 0.888208 1.008393

The RIM and Real RL Volumes are quite similar so one million random q-points seems a reasonable number,
but again you are invited, later on, to check the convergence of one of the main observables (i.e. HF gap, GW gap, absorption..) changing this number.

Close the report file and perform a calculation of the exchange self-energy to estimate the HF gap (very fast calculation) using the RIM.
Generate the input
$ yambo -F yambo_HF_WR.in -J 2D_WR -r -x
In order to calculate the HF gap only for the last k-point (which is the high-simmetry point K) change the last line as
Note also that 4 (5) is the highest occupied (lowest unoccupied) band.
%[[Variables#QPkrange|QPkrange]] # [GW] QP generalized Kpoint/Band indices
7| 7| 4| 5|
%

Close the input and run yambo
$ yambo -F yambo_HF_WR.in -J 2D_WR
At the end you will find the report file ''r-2D_WR_HF_and_locXC_rim_cut'' and the output file ''o-2D_WR.hf''. Open them and have a look
In the output file ''o-2D_WR.hf'' you will see
# K-point Band Eo Ehf DFT HF
#
7.00000 4.00000 0.00000 -3.25329 -16.21953 -19.47282
7.00000 5.00000 4.40109 9.67551 -11.10755 -5.83314

The HF gap is 12.92 eV obtained subtracting the 2 values in the fourth column
Now you can do a similar HF calculation without generating and reading the RIM database

$ yambo -F yambo_HF_NR.in -x
change the variables ''QPkrange'' as before, close the input and run yambo
$ yambo -F yambo_HF_NR.in -J 2D_NR

in this case the HF gap in the file ''o-2D_NR.hf'' results to be 12.69 eV.

Indeed the presence of the numerical instability, discussed before, is evident only using denser k-grids with respect to the one used in this Tutorial (6x6x1)
Suggestion: later you can generate other SAVE directories with denser k-grids and check the HF gap.
The results of the HF gap calculated with different k-grids without (noRIM) and with Random Integration Method (RIM) to show up the problem are reported:

noRIM RIM

6x6x1 12.69eV 12.92eV
12x12x1 12.80eV 12.92eV
15x15x1 12.96eV 12.93eV
45x45x1 15.52eV 12.96eV

So the '''home message''' is : use always the RIM in MB simulations of low-dimensional materials.

==Generate a truncated coulomb potential ==
To simulate an isolated nano-material a convergence with cell vacuum size is in principle required, like in the DFT runs.
The use of a truncated Coulomb potential allows to achieve faster convergence eliminating the interaction between the repeated images
along the non-periodic direction (see i.e. C. A. Rozzi et al Phys. Rev. B 73, 205119)
In this tutorial we learn how to generate a box-like cutoff for a 2D system with the non-periodic direction along z.

In YAMBO you can use :
* spherical cutoff (for 0D systems)
* cylindrical cutoff (for 1D systems)
* box-like cutoff (for 0D, 1D and 2D systems)

The Coulomb potential with a box-like cutoff is defined as
[[File:Vc1.png|none|x80px|]]
where S is a box-shaped region of the space having sides Lx,Ly and Lz, where they can also assume infinite values (untruncated interaction along desired directions).

Then the FT component is
[[File:Vc2.png|none|x60px|]] where [[File:Vc3.png|none|x60px|]]
For a 2D-system with non period direction along z-axis we have
[[File:Vc4.png|none|x60px|]]

Important remarks:
* the Random Integration Method (RIM) is required to perform the Q-space integration
* for sufficiently large supercells a choose L_i slightly smaller than the cell size in the i-direction ensures to avoid interaction between replicas

Create the input file:

$ yambo -F yambo_WR_WC.in -r

Change the RIM Variables as before and activate the ''cutoff'' generation
[[Variables#RandQpts|RandQpts]] = 1000000 # [RIM] Number of random q-points in the BZ
[[Variables#RandGvec|RandGvec]] = 100 RL # [RIM] Coulomb interaction RS components
[[Variables#CUTGeo|CUTGeo]] = "box z" # [CUT] Coulomb Cutoff geometry: box/cylinder/sphere X/Y/Z/XY..
% CUTBox
0.00 | 0.00 | 32.0 | # [CUT] [au] Box sides
%

Close the input file and run yambo:

$ yambo -F yambo_WR_WC.in -J 2D_WR_WC

in the directory 2D_WR_WC you will find a new database <code> ndb.cutoff </code>

==Use the truncated coulomb potential in a G0W0-PPA calculation==

Generate the input reading the databases in the ''2D_WR_WC'' directory
$ yambo -J 2D_WR_WC -F yambo_G0W0.in -p p -g n -r -k hartree -V qp
In the input change the following variables
[[Variables#NGsBlkXp|NGsBlkXp]] = 4 Ry # [Xp] Response block size
[[Variables#QPkrange|QPkrange]] # [GW] QP generalized Kpoint/Band indices
7| 7| 4| 5|
Close the input and run yambo
$ yambo -F yambo_G0W0.in -J 2D_WR_WC
At the end you will find a new report file ''r-2D_WR_WC_em1d_ppa_HF_and_locXC_gw0_rim_cut'', open it and have a look.
You will find also a new output file ''o-2D_WR_WC.qp''. If you open yoi will find that now the G0W0 gap is
4.40 eV (PBE) + 3.70 eV (G0W0 correction) = 8.10 eV
Indeed as you have learned in the previous tutorials the correlation part of the self-energy strongly reduces the HF gap.
Moreover you should note that the QP correction is larger that one found in the h-BN bulk. Why?

==Use the truncated coulomb potential in a BSE calculation==
Generate the input for the BSE calculation:
$ yambo -J 2D_WR_WC -F yambo_BSE.in -r -o b -p p -y d -k sex -V all
Some remarks: the largest verbosity is used <code>-V all </code> and a long input file is generated; with the option <code> -p p </code> the static part of the screening matrix is read from the <code>ndb.pp</code> databases
Change the number of G-vectors in the correlation part of the kernel as:
[[Variables#BSENGBlk|BSENGBlk]]= 4 Ry # [BSK] Screened interaction block size
use the simple rigid scissor to open the correct the KS energies
% [[Variables#KfnQP_E|KfnQP_E]]
3.70000000 | 1.000000 | 1.000000 | # [EXTQP BSK BSS] E parameters (c/v) eV|adim|adim
Set the number of bands to:
% [[Variables#BSEBands|BSEBands]]
2 | 6 | # [BSK] Bands range
This choice means to include in the BSE only three occupied and 2 unoccupied bands.
Increase the number of energy steps
[[Variables#BEnSteps|BEnSteps]]= 500 # [BSS] Energy steps
To do the next Tutorial we need to write the excitonic WFs, so uncomment the following line
#[[Variables#WRbsWF|WRbsWF]] # [BSS] Write to disk excitonic the WFs
Close the input file and run yambo
$ yambo -J 2D_WR_WC -F yambo_BSE.in
Look at the report file ''r-2D_WR_WC_optics_bse_bsk_bss_em1d_ppa_rim_cut'' and plot the real and Imaginary part
of the dielectric function using the file ''o-2D_WR_WC.eps_q1_diago_bse''.

You realize immediately that the real part of the macroscopic dielectric function is almost 1, while the imaginary part is almost zero.
Indeed when the use of the cutoff in the coulomb potential is activated you are simulating a real isolated sheet in vacuum and so you are obtaining almost the dielectric function of vacuum!

For this reason yambo produces another file which contains the macroscopic polarizability (called here 'o-2D_WR_WC.alpha_q1_diago_bse')
which is a well defined quantity strictly related to optical conductivity or absorbance.

For a 2D system has the dimension of a length and it is defined as :

[[File:alpha2D.gif|none|x80px|]] where [[File:Lz.gif|none|x80px|]] is the size of the cell in the non-periodic direction (z in this case)

== Analyze the differences with corresponding GW and BSE calculations without the use of a truncated coulomb potential==

Open the input file yambo_G0W0.in and set back <code>CUTGeo= "none"</code>

Close the input and run yambo

$ yambo -J 2D_WR -F yambo_G0W0.in
You will find a new report ''r-2D_WR_em1d_ppa_HF_and_locXC_gw0_rim_cut''.
You are invited to see the difference with the previous one ''r-2D_WR_WC_em1d_ppa_HF_and_locXC_gw0_rim_cut''

and also a new output file ''o-2D_WR.qp'' is present. Open and check the QP correction at the last k-point. This time
a value of 2.83 eV instead of 3.70 eV is obtained. Are you able to explain this result?

Now redoo the BSE calculation but without reading the cutoff database and applying the QP correction just obtained without using the cutoff.

To do that, open the yambo_BSE.in and put <code>CUTGeo= "none"</code>
and set the QP correction of 2.83 eV, just obtained without uisng the cutoff.
% [[Variables#KfnQP_E|KfnQP_E]]
2.830000 | 1.000000 | 1.000000 | # [EXTQP BSK BSS] E parameters (c/v) eV|adim|adim

Close the input file and run yambo
$ yambo -J 2D_WR -F yambo_BSE.in
Plot the imaginary part of the GW and BSE polarizability :

$ gnuplot
$ gnuplot> set ylabel 'alpha'
$ gnuplot> plot 'o-2D_WR.eps_q1_diago_bse' u 1:($4*33.01/4/pi) w l title 'GW without cutoff' ,'o-2D_WR_WC.alpha_q1_diago_bse' u 1:4 w l title ' GW with cutoff' , 'o-2D_WR.eps_q1_diago_bse' u 1:($2*33.01/4/pi) w l title 'BSE without cutoff' ,'o-2D_WR_WC.alpha_q1_diago_bse' u 1:2 w l title 'BSE with cutoff'

[[File:BSE_2D_cutnocut_new1.png|none|600px|]]

You can note that the energy of the peaks in the two G0W0 spectra (with and without cutoff) are quite different:
you find the first peak around 7 eV without cutoff and around 8 eV with cutoff.
Instead the two GW+BSE spectra, without and with cutoff, are much more similar. Are you able to explain why?
Remarks: The convergence in k-space can be done separately for GW and BSE
calculations, because generally more k-points are needed to converge the excitonic with respect to the quasi-particle properties.

N.B. If you will use the same inputs created in this tutorial remember to set up the cutoff variable ''CUTGeo= "box z"'' to use again the truncated coulomb potential in the GW and BSE calculations

Literature on two-dimensional h-BN: L. Wirtz et al Phys Rev Lett 96 126104 (2006), F. Rasmussen et al Phys Rev. B 94 155406 (2016),N. Berseneva et al Phys. Rev. B 87 035404 (2013).

How to treat low dimensional systems

2020-01-20T15:29:21Z

Maurizia: /* Analyze the differences with corresponding GW and BSE calculations without the use of a truncated coulomb potential */

In this tutorial you will learn how to treat low-dimensional material.
A small k-sampling is used to reduce the computational cost/time.
Later on you can repeat this tutorial but using denser k-grids to check the convergence.

== Prerequisites ==

* <code>yambo</code> executable
* <code>ypp</code> executable
* <code>gnuplot</code>, for plotting spectra
* Have Completed the [[First steps: a walk through from DFT to optical properties]] tutorial

==Avoid numerical divergences using the Random Integration Method (RIM)==
In DFT runs of low-dimensional materials low dimensional k-grids are generally used. (i.e. NxNx1 for a 2D sheet perpendicular to the z direction)
This can create numerical problems in the convergence of the many-body (MB) results due to the divergence at small q of the coulomb potential,
which appears in all the main equations.
To eliminate this problem YAMBO uses the so-called Random Integration Method
which means to use a Monte Carlo Integration with Random Q-points whose number ''[[Variables#RandQpts|RandQpts]]'' will be given in input.
For example the exchange self-energy matrix element which is:
[[File:sigmax.png|none|x50px|]]
assuming that the integrand is a smooth function of momenta the integral can be approximated as
[[File:rim0.png|none|x50px|]]
where the small Brillouin Zones (sBZ) relative to a given q-point are the Brillouin Zones of the momenta vectors lattice.
They are chosen in such a way to cover the whole BZ.
In the RIM run-level yambo calculates the integrals of the symmetrized Coulomb potential
[[File:rim1.png|none|x50px|]]

So we are ready to start the tutorial
First go in the proper directory and have a look if all the required databases are there
$ cd YAMBO_TUTORIALS/hBN-2D/YAMBO
$ ls ./SAVE
ns.db1 ns.wf ns.kb_pp_pwscf ...
$ yambo ''(initialization, if you haven't already done so)''

Create the input to generate the <code>ndb.RIM</code> database
$ yambo -F yambo_WR.in -r
and change the following variables
[[Variables#RandQpts|RandQpts]] = 1000000 # [RIM] Number of random q-points in the BZ
[[Variables#RandGvec|RandGvec]] = 100 RL # [RIM] Coulomb interaction RS components
N.B ''RandGvec=100'' means to use the RIM for the first 100 G-components of the coulomb potential
(Suggestion : later you can check convergence of the HF gap changing these two values)
Close input and Run yambo
$ yambo -F yambo_WR.in -J 2D_WR
At the end you find a new database ''ndb.RIM'' and a new report file ''r-2D_WR_rim_cut ''. Open it and look inside

Gamma point sphere radius [au]: 0.08028
Points outside the sphere : 799246
[Int_sBZ(q=0) 1/q^2]*(Vol_sBZ)^(-1/3) = 7.665674
should be < 7.795600
[WR./2D_WR//ndb.RIM]--------------------------------------
Brillouin Zone Q/K grids (IBZ/BZ): 7 36 7 36
Coulombian RL components : 111
Coulombian diagonal components :yes
RIM random points : 1000000
RIM RL volume [a.u.]: 0.390293
Real RL volume [a.u.]: 0.390112
Eps^-1 reference component :0
Eps^-1 components : 0.00 0.00 0.00
RIM anysotropy factor : 0.000000
- S/N 005962 -------------------------- v.04.01.02 r.00120 -

Summary of Coulomb integrals for non-metallic bands |Q|[au] RIM/Bare:

Q [1]:0.1000E-40.9833 * Q [2]: 0.256404 1.094818
Q [5]: 0.444104 1.032268 * Q [3]: 0.512807 1.024055
Q [6]: 0.678380 1.013997 * Q [4]: 0.769211 1.010774
Q [7]: 0.888208 1.008393

The RIM and Real RL Volumes are quite similar so one million random q-points seems a reasonable number,
but again you are invited, later on, to check the convergence of one of the main observables (i.e. HF gap, GW gap, absorption..) changing this number.

Close the report file and perform a calculation of the exchange self-energy to estimate the HF gap (very fast calculation) using the RIM.
Generate the input
$ yambo -F yambo_HF_WR.in -J 2D_WR -r -x
In order to calculate the HF gap only for the last k-point (which is the high-simmetry point K) change the last line as
Note also that 4 (5) is the highest occupied (lowest unoccupied) band.
%[[Variables#QPkrange|QPkrange]] # [GW] QP generalized Kpoint/Band indices
7| 7| 4| 5|
%

Close the input and run yambo
$ yambo -F yambo_HF_WR.in -J 2D_WR
At the end you will find the report file ''r-2D_WR_HF_and_locXC_rim_cut'' and the output file ''o-2D_WR.hf''. Open them and have a look
In the output file ''o-2D_WR.hf'' you will see
# K-point Band Eo Ehf DFT HF
#
7.00000 4.00000 0.00000 -3.25329 -16.21953 -19.47282
7.00000 5.00000 4.40109 9.67551 -11.10755 -5.83314

The HF gap is 12.92 eV obtained subtracting the 2 values in the fourth column
Now you can do a similar HF calculation without generating and reading the RIM database

$ yambo -F yambo_HF_NR.in -x
change the variables ''QPkrange'' as before, close the input and run yambo
$ yambo -F yambo_HF_NR.in -J 2D_NR

in this case the HF gap in the file ''o-2D_NR.hf'' results to be 12.69 eV.

Indeed the presence of the numerical instability, discussed before, is evident only using denser k-grids with respect to the one used in this Tutorial (6x6x1)
Suggestion: later you can generate other SAVE directories with denser k-grids and check the HF gap.
The results of the HF gap calculated with different k-grids without (noRIM) and with Random Integration Method (RIM) to show up the problem are reported:

noRIM RIM

6x6x1 12.69eV 12.92eV
12x12x1 12.80eV 12.92eV
15x15x1 12.96eV 12.93eV
45x45x1 15.52eV 12.96eV

So the '''home message''' is : use always the RIM in MB simulations of low-dimensional materials.

==Generate a truncated coulomb potential ==
To simulate an isolated nano-material a convergence with cell vacuum size is in principle required, like in the DFT runs.
The use of a truncated Coulomb potential allows to achieve faster convergence eliminating the interaction between the repeated images
along the non-periodic direction (see i.e. C. A. Rozzi et al Phys. Rev. B 73, 205119)
In this tutorial we learn how to generate a box-like cutoff for a 2D system with the non-periodic direction along z.

In YAMBO you can use :
* spherical cutoff (for 0D systems)
* cylindrical cutoff (for 1D systems)
* box-like cutoff (for 0D, 1D and 2D systems)

The Coulomb potential with a box-like cutoff is defined as
[[File:Vc1.png|none|x80px|]]
where S is a box-shaped region of the space having sides Lx,Ly and Lz, where they can also assume infinite values (untruncated interaction along desired directions).

Then the FT component is
[[File:Vc2.png|none|x60px|]] where [[File:Vc3.png|none|x60px|]]
For a 2D-system with non period direction along z-axis we have
[[File:Vc4.png|none|x60px|]]

Important remarks:
* the Random Integration Method (RIM) is required to perform the Q-space integration
* for sufficiently large supercells a choose L_i slightly smaller than the cell size in the i-direction ensures to avoid interaction between replicas

Create the input file:

$ yambo -F yambo_WR_WC.in -r

Change the RIM Variables as before and activate the ''cutoff'' generation
[[Variables#RandQpts|RandQpts]] = 1000000 # [RIM] Number of random q-points in the BZ
[[Variables#RandGvec|RandGvec]] = 100 RL # [RIM] Coulomb interaction RS components
[[Variables#CUTGeo|CUTGeo]] = "box z" # [CUT] Coulomb Cutoff geometry: box/cylinder/sphere X/Y/Z/XY..
% CUTBox
0.00 | 0.00 | 32.0 | # [CUT] [au] Box sides
%

Close the input file and run yambo:

$ yambo -F yambo_WR_WC.in -J 2D_WR_WC

in the directory 2D_WR_WC you will find a new database <code> ndb.cutoff </code>

==Use the truncated coulomb potential in a G0W0-PPA calculation==

Generate the input reading the databases in the ''2D_WR_WC'' directory
$ yambo -J 2D_WR_WC -F yambo_G0W0.in -p p -g n -r -k hartree -V qp
In the input change the following variables
[[Variables#NGsBlkXp|NGsBlkXp]] = 4 Ry # [Xp] Response block size
[[Variables#QPkrange|QPkrange]] # [GW] QP generalized Kpoint/Band indices
7| 7| 4| 5|
Close the input and run yambo
$ yambo -F yambo_G0W0.in -J 2D_WR_WC
At the end you will find a new report file ''r-2D_WR_WC_em1d_ppa_HF_and_locXC_gw0_rim_cut'', open it and have a look.
You will find also a new output file ''o-2D_WR_WC.qp''. If you open yoi will find that now the G0W0 gap is
4.40 eV (PBE) + 3.70 eV (G0W0 correction) = 8.10 eV
Indeed as you have learned in the previous tutorials the correlation part of the self-energy strongly reduces the HF gap.
Moreover you should note that the QP correction is larger that one found in the h-BN bulk. Why?

==Use the truncated coulomb potential in a BSE calculation==
Generate the input for the BSE calculation:
$ yambo -J 2D_WR_WC -F yambo_BSE.in -r -o b -p p -y d -k sex -V all
Some remarks: the largest verbosity is used <code>-V all </code> and a long input file is generated; with the option <code> -p p </code> the static part of the screening matrix is read from the <code>ndb.pp</code> databases
Change the number of G-vectors in the correlation part of the kernel as:
[[Variables#BSENGBlk|BSENGBlk]]= 4 Ry # [BSK] Screened interaction block size
use the simple rigid scissor to open the correct the KS energies
% [[Variables#KfnQP_E|KfnQP_E]]
3.70000000 | 1.000000 | 1.000000 | # [EXTQP BSK BSS] E parameters (c/v) eV|adim|adim
Set the number of bands to:
% [[Variables#BSEBands|BSEBands]]
2 | 6 | # [BSK] Bands range
This choice means to include in the BSE only three occupied and 2 unoccupied bands.
Increase the number of energy steps
[[Variables#BEnSteps|BEnSteps]]= 500 # [BSS] Energy steps
To do the next Tutorial we need to write the excitonic WFs, so uncomment the following line
#[[Variables#WRbsWF|WRbsWF]] # [BSS] Write to disk excitonic the WFs
Close the input file and run yambo
$ yambo -J 2D_WR_WC -F yambo_BSE.in
Look at the report file ''r-2D_WR_WC_optics_bse_bsk_bss_em1d_ppa_rim_cut'' and plot the real and Imaginary part
of the dielectric function using the file ''o-2D_WR_WC.eps_q1_diago_bse''.

You realize immediately that the real part of the macroscopic dielectric function is almost 1, while the imaginary part is almost zero.
Indeed when the use of the cutoff in the coulomb potential is activated you are simulating a real isolated sheet in vacuum and so you are obtaining almost the dielectric function of vacuum!

For this reason yambo produces another file which contains the macroscopic polarizability (called here 'o-2D_WR_WC.alpha_q1_diago_bse')
which is a well defined quantity strictly related to optical conductivity or absorbance.

For a 2D system has the dimension of a length and it is defined as :

[[File:alpha2D.gif|none|x80px|]] where [[File:Lz.gif|none|x80px|]] is the size of the cell in the non-periodic direction (z in this case)

== Analyze the differences with corresponding GW and BSE calculations without the use of a truncated coulomb potential==

Open the input file yambo_G0W0.in and set back <code>CUTGeo= "none"</code>

Close the input and run yambo

$ yambo -J 2D_WR -F yambo_G0W0.in
You will find a new report ''r-2D_WR_em1d_ppa_HF_and_locXC_gw0_rim_cut''.
You are invited to see the difference with the previous one ''r-2D_WR_WC_em1d_ppa_HF_and_locXC_gw0_rim_cut''

and also a new output file ''o-2D_WR.qp'' is present. Open and check the QP correction at the last k-point. This time
a value of 2.83 eV instead of 3.70 eV is obtained. Are you able to explain this result?

Now redoo the BSE calculation but without reading the cutoff database and applying the QP correction just obtained without using the cutoff.

To do that, open the yambo_BSE.in and put <code>CUTGeo= "none"</code>
and set the QP correction of 2.83 eV, just obtained without uisng the cutoff.
% [[Variables#KfnQP_E|KfnQP_E]]
2.830000 | 1.000000 | 1.000000 | # [EXTQP BSK BSS] E parameters (c/v) eV|adim|adim

Close the input file and run yambo
$ yambo -J 2D_WR -F yambo_BSE.in
Plot the imaginary part of the GW and BSE polarizability :

$ gnuplot
$ gnuplot> set ylabel 'alpha'
$ gnuplot> plot 'o-2D_WR.eps_q1_diago_bse' u 1:($4*33.01/4/pi) w l title 'GW without cutoff' ,'o-2D_WR_WC.alpha_q1_diago_bse' u 1:4 w l title ' GW with cutoff' , 'o-2D_WR.eps_q1_diago_bse' u 1:($2*33.01/4/pi) w l title 'BSE without cutoff' ,'o-2D_WR_WC.alpha_q1_diago_bse' u 1:2 w l title 'BSE with cutoff'

[[File:BSE_2D_cutnocut_new.png|none|600px|]]

You can note that the energy of the peaks in the two G0W0 spectra (with and without cutoff) are quite different:
you find the first peak around 7 eV without cutoff and around 8 eV with cutoff.
Instead the two GW+BSE spectra, without and with cutoff, are much more similar. Are you able to explain why?
Remarks: The convergence in k-space can be done separately for GW and BSE
calculations, because generally more k-points are needed to converge the excitonic with respect to the quasi-particle properties.

N.B. If you will use the same inputs created in this tutorial remember to set up the cutoff variable ''CUTGeo= "box z"'' to use again the truncated coulomb potential in the GW and BSE calculations

Literature on two-dimensional h-BN: L. Wirtz et al Phys Rev Lett 96 126104 (2006), F. Rasmussen et al Phys Rev. B 94 155406 (2016),N. Berseneva et al Phys. Rev. B 87 035404 (2013).

How to treat low dimensional systems

2020-01-20T15:26:06Z

Maurizia: /* Use the truncated coulomb potential in a BSE calculation */

In this tutorial you will learn how to treat low-dimensional material.
A small k-sampling is used to reduce the computational cost/time.
Later on you can repeat this tutorial but using denser k-grids to check the convergence.

== Prerequisites ==

* <code>yambo</code> executable
* <code>ypp</code> executable
* <code>gnuplot</code>, for plotting spectra
* Have Completed the [[First steps: a walk through from DFT to optical properties]] tutorial

==Avoid numerical divergences using the Random Integration Method (RIM)==
In DFT runs of low-dimensional materials low dimensional k-grids are generally used. (i.e. NxNx1 for a 2D sheet perpendicular to the z direction)
This can create numerical problems in the convergence of the many-body (MB) results due to the divergence at small q of the coulomb potential,
which appears in all the main equations.
To eliminate this problem YAMBO uses the so-called Random Integration Method
which means to use a Monte Carlo Integration with Random Q-points whose number ''[[Variables#RandQpts|RandQpts]]'' will be given in input.
For example the exchange self-energy matrix element which is:
[[File:sigmax.png|none|x50px|]]
assuming that the integrand is a smooth function of momenta the integral can be approximated as
[[File:rim0.png|none|x50px|]]
where the small Brillouin Zones (sBZ) relative to a given q-point are the Brillouin Zones of the momenta vectors lattice.
They are chosen in such a way to cover the whole BZ.
In the RIM run-level yambo calculates the integrals of the symmetrized Coulomb potential
[[File:rim1.png|none|x50px|]]

So we are ready to start the tutorial
First go in the proper directory and have a look if all the required databases are there
$ cd YAMBO_TUTORIALS/hBN-2D/YAMBO
$ ls ./SAVE
ns.db1 ns.wf ns.kb_pp_pwscf ...
$ yambo ''(initialization, if you haven't already done so)''

Create the input to generate the <code>ndb.RIM</code> database
$ yambo -F yambo_WR.in -r
and change the following variables
[[Variables#RandQpts|RandQpts]] = 1000000 # [RIM] Number of random q-points in the BZ
[[Variables#RandGvec|RandGvec]] = 100 RL # [RIM] Coulomb interaction RS components
N.B ''RandGvec=100'' means to use the RIM for the first 100 G-components of the coulomb potential
(Suggestion : later you can check convergence of the HF gap changing these two values)
Close input and Run yambo
$ yambo -F yambo_WR.in -J 2D_WR
At the end you find a new database ''ndb.RIM'' and a new report file ''r-2D_WR_rim_cut ''. Open it and look inside

Gamma point sphere radius [au]: 0.08028
Points outside the sphere : 799246
[Int_sBZ(q=0) 1/q^2]*(Vol_sBZ)^(-1/3) = 7.665674
should be < 7.795600
[WR./2D_WR//ndb.RIM]--------------------------------------
Brillouin Zone Q/K grids (IBZ/BZ): 7 36 7 36
Coulombian RL components : 111
Coulombian diagonal components :yes
RIM random points : 1000000
RIM RL volume [a.u.]: 0.390293
Real RL volume [a.u.]: 0.390112
Eps^-1 reference component :0
Eps^-1 components : 0.00 0.00 0.00
RIM anysotropy factor : 0.000000
- S/N 005962 -------------------------- v.04.01.02 r.00120 -

Summary of Coulomb integrals for non-metallic bands |Q|[au] RIM/Bare:

Q [1]:0.1000E-40.9833 * Q [2]: 0.256404 1.094818
Q [5]: 0.444104 1.032268 * Q [3]: 0.512807 1.024055
Q [6]: 0.678380 1.013997 * Q [4]: 0.769211 1.010774
Q [7]: 0.888208 1.008393

The RIM and Real RL Volumes are quite similar so one million random q-points seems a reasonable number,
but again you are invited, later on, to check the convergence of one of the main observables (i.e. HF gap, GW gap, absorption..) changing this number.

Close the report file and perform a calculation of the exchange self-energy to estimate the HF gap (very fast calculation) using the RIM.
Generate the input
$ yambo -F yambo_HF_WR.in -J 2D_WR -r -x
In order to calculate the HF gap only for the last k-point (which is the high-simmetry point K) change the last line as
Note also that 4 (5) is the highest occupied (lowest unoccupied) band.
%[[Variables#QPkrange|QPkrange]] # [GW] QP generalized Kpoint/Band indices
7| 7| 4| 5|
%

Close the input and run yambo
$ yambo -F yambo_HF_WR.in -J 2D_WR
At the end you will find the report file ''r-2D_WR_HF_and_locXC_rim_cut'' and the output file ''o-2D_WR.hf''. Open them and have a look
In the output file ''o-2D_WR.hf'' you will see
# K-point Band Eo Ehf DFT HF
#
7.00000 4.00000 0.00000 -3.25329 -16.21953 -19.47282
7.00000 5.00000 4.40109 9.67551 -11.10755 -5.83314

The HF gap is 12.92 eV obtained subtracting the 2 values in the fourth column
Now you can do a similar HF calculation without generating and reading the RIM database

$ yambo -F yambo_HF_NR.in -x
change the variables ''QPkrange'' as before, close the input and run yambo
$ yambo -F yambo_HF_NR.in -J 2D_NR

in this case the HF gap in the file ''o-2D_NR.hf'' results to be 12.69 eV.

Indeed the presence of the numerical instability, discussed before, is evident only using denser k-grids with respect to the one used in this Tutorial (6x6x1)
Suggestion: later you can generate other SAVE directories with denser k-grids and check the HF gap.
The results of the HF gap calculated with different k-grids without (noRIM) and with Random Integration Method (RIM) to show up the problem are reported:

noRIM RIM

6x6x1 12.69eV 12.92eV
12x12x1 12.80eV 12.92eV
15x15x1 12.96eV 12.93eV
45x45x1 15.52eV 12.96eV

So the '''home message''' is : use always the RIM in MB simulations of low-dimensional materials.

==Generate a truncated coulomb potential ==
To simulate an isolated nano-material a convergence with cell vacuum size is in principle required, like in the DFT runs.
The use of a truncated Coulomb potential allows to achieve faster convergence eliminating the interaction between the repeated images
along the non-periodic direction (see i.e. C. A. Rozzi et al Phys. Rev. B 73, 205119)
In this tutorial we learn how to generate a box-like cutoff for a 2D system with the non-periodic direction along z.

In YAMBO you can use :
* spherical cutoff (for 0D systems)
* cylindrical cutoff (for 1D systems)
* box-like cutoff (for 0D, 1D and 2D systems)

The Coulomb potential with a box-like cutoff is defined as
[[File:Vc1.png|none|x80px|]]
where S is a box-shaped region of the space having sides Lx,Ly and Lz, where they can also assume infinite values (untruncated interaction along desired directions).

Then the FT component is
[[File:Vc2.png|none|x60px|]] where [[File:Vc3.png|none|x60px|]]
For a 2D-system with non period direction along z-axis we have
[[File:Vc4.png|none|x60px|]]

Important remarks:
* the Random Integration Method (RIM) is required to perform the Q-space integration
* for sufficiently large supercells a choose L_i slightly smaller than the cell size in the i-direction ensures to avoid interaction between replicas

Create the input file:

$ yambo -F yambo_WR_WC.in -r

Change the RIM Variables as before and activate the ''cutoff'' generation
[[Variables#RandQpts|RandQpts]] = 1000000 # [RIM] Number of random q-points in the BZ
[[Variables#RandGvec|RandGvec]] = 100 RL # [RIM] Coulomb interaction RS components
[[Variables#CUTGeo|CUTGeo]] = "box z" # [CUT] Coulomb Cutoff geometry: box/cylinder/sphere X/Y/Z/XY..
% CUTBox
0.00 | 0.00 | 32.0 | # [CUT] [au] Box sides
%

Close the input file and run yambo:

$ yambo -F yambo_WR_WC.in -J 2D_WR_WC

in the directory 2D_WR_WC you will find a new database <code> ndb.cutoff </code>

==Use the truncated coulomb potential in a G0W0-PPA calculation==

Generate the input reading the databases in the ''2D_WR_WC'' directory
$ yambo -J 2D_WR_WC -F yambo_G0W0.in -p p -g n -r -k hartree -V qp
In the input change the following variables
[[Variables#NGsBlkXp|NGsBlkXp]] = 4 Ry # [Xp] Response block size
[[Variables#QPkrange|QPkrange]] # [GW] QP generalized Kpoint/Band indices
7| 7| 4| 5|
Close the input and run yambo
$ yambo -F yambo_G0W0.in -J 2D_WR_WC
At the end you will find a new report file ''r-2D_WR_WC_em1d_ppa_HF_and_locXC_gw0_rim_cut'', open it and have a look.
You will find also a new output file ''o-2D_WR_WC.qp''. If you open yoi will find that now the G0W0 gap is
4.40 eV (PBE) + 3.70 eV (G0W0 correction) = 8.10 eV
Indeed as you have learned in the previous tutorials the correlation part of the self-energy strongly reduces the HF gap.
Moreover you should note that the QP correction is larger that one found in the h-BN bulk. Why?

==Use the truncated coulomb potential in a BSE calculation==
Generate the input for the BSE calculation:
$ yambo -J 2D_WR_WC -F yambo_BSE.in -r -o b -p p -y d -k sex -V all
Some remarks: the largest verbosity is used <code>-V all </code> and a long input file is generated; with the option <code> -p p </code> the static part of the screening matrix is read from the <code>ndb.pp</code> databases
Change the number of G-vectors in the correlation part of the kernel as:
[[Variables#BSENGBlk|BSENGBlk]]= 4 Ry # [BSK] Screened interaction block size
use the simple rigid scissor to open the correct the KS energies
% [[Variables#KfnQP_E|KfnQP_E]]
3.70000000 | 1.000000 | 1.000000 | # [EXTQP BSK BSS] E parameters (c/v) eV|adim|adim
Set the number of bands to:
% [[Variables#BSEBands|BSEBands]]
2 | 6 | # [BSK] Bands range
This choice means to include in the BSE only three occupied and 2 unoccupied bands.
Increase the number of energy steps
[[Variables#BEnSteps|BEnSteps]]= 500 # [BSS] Energy steps
To do the next Tutorial we need to write the excitonic WFs, so uncomment the following line
#[[Variables#WRbsWF|WRbsWF]] # [BSS] Write to disk excitonic the WFs
Close the input file and run yambo
$ yambo -J 2D_WR_WC -F yambo_BSE.in
Look at the report file ''r-2D_WR_WC_optics_bse_bsk_bss_em1d_ppa_rim_cut'' and plot the real and Imaginary part
of the dielectric function using the file ''o-2D_WR_WC.eps_q1_diago_bse''.

You realize immediately that the real part of the macroscopic dielectric function is almost 1, while the imaginary part is almost zero.
Indeed when the use of the cutoff in the coulomb potential is activated you are simulating a real isolated sheet in vacuum and so you are obtaining almost the dielectric function of vacuum!

For this reason yambo produces another file which contains the macroscopic polarizability (called here 'o-2D_WR_WC.alpha_q1_diago_bse')
which is a well defined quantity strictly related to optical conductivity or absorbance.

For a 2D system has the dimension of a length and it is defined as :

[[File:alpha2D.gif|none|x80px|]] where [[File:Lz.gif|none|x80px|]] is the size of the cell in the non-periodic direction (z in this case)

== Analyze the differences with corresponding GW and BSE calculations without the use of a truncated coulomb potential==

Open the input file yambo_G0W0.in and set back <code>CUTGeo= "none"</code>

Close the input and run yambo

$ yambo -J 2D_WR -F yambo_G0W0.in
You will find a new report ''r-2D_WR_em1d_ppa_HF_and_locXC_gw0_rim_cut''.
You are invited to see the difference with the previous one ''r-2D_WR_WC_em1d_ppa_HF_and_locXC_gw0_rim_cut''

and also a new output file ''o-2D_WR.qp'' is present. Open and check the QP correction at the last k-point. This time
a value of 2.83 eV instead of 3.70 eV is obtained. Are you able to explain this result?

Now redoo the BSE calculation but without reading the cutoff database and applying the QP correction just obtained without using the cutoff.

To do that, open the yambo_BSE.in and put <code>CUTGeo= "none"</code>
and set the QP correction of 2.83 eV, just obtained without uisng the cutoff.
% [[Variables#KfnQP_E|KfnQP_E]]
2.830000 | 1.000000 | 1.000000 | # [EXTQP BSK BSS] E parameters (c/v) eV|adim|adim

Close the input file and run yambo
$ yambo -J 2D_WR -F yambo_BSE.in
Plot the imaginary part of the GW and BSE polarizability :

$ gnuplot
$ gnuplot> set ylabel 'alpha'
$ gnuplot> plot 'o-2D_WR.eps_q1_diago_bse' u 1:($4*33.01/4/pi) w l title 'GW without cutoff' ,'o-2D_WR_WC.alpha_q1_diago_bse' u 1:4 w l title ' GW with cutoff' , 'o-2D_WR.eps_q1_diago_bse' u 1:($2*33.01/4/pi) w l title 'BSE without cutoff' ,'o-2D_WR_WC.alpha_q1_diago_bse' u 1:2 w l title 'BSE with cutoff'

[[File:BSE_2D_cutnocut.png|none|600px|]]

You can note that the energy of the peaks in the two G0W0 spectra (with and without cutoff) are quite different:
you find the first peak around 7 eV without cutoff and around 8 eV with cutoff.
Instead the two GW+BSE spectra, without and with cutoff, are much more similar. Are you able to explain why?
Remarks: The convergence in k-space can be done separately for GW and BSE
calculations, because generally more k-points are needed to converge the excitonic with respect to the quasi-particle properties.

N.B. If you will use the same inputs created in this tutorial remember to set up the cutoff variable ''CUTGeo= "box z"'' to use again the truncated coulomb potential in the GW and BSE calculations

Literature on two-dimensional h-BN: L. Wirtz et al Phys Rev Lett 96 126104 (2006), F. Rasmussen et al Phys Rev. B 94 155406 (2016),N. Berseneva et al Phys. Rev. B 87 035404 (2013).

How to treat low dimensional systems

2020-01-20T15:06:52Z

Maurizia: /* Use the truncated coulomb potential in a BSE calculation */

In this tutorial you will learn how to treat low-dimensional material.
A small k-sampling is used to reduce the computational cost/time.
Later on you can repeat this tutorial but using denser k-grids to check the convergence.

== Prerequisites ==

* <code>yambo</code> executable
* <code>ypp</code> executable
* <code>gnuplot</code>, for plotting spectra
* Have Completed the [[First steps: a walk through from DFT to optical properties]] tutorial

==Avoid numerical divergences using the Random Integration Method (RIM)==
In DFT runs of low-dimensional materials low dimensional k-grids are generally used. (i.e. NxNx1 for a 2D sheet perpendicular to the z direction)
This can create numerical problems in the convergence of the many-body (MB) results due to the divergence at small q of the coulomb potential,
which appears in all the main equations.
To eliminate this problem YAMBO uses the so-called Random Integration Method
which means to use a Monte Carlo Integration with Random Q-points whose number ''[[Variables#RandQpts|RandQpts]]'' will be given in input.
For example the exchange self-energy matrix element which is:
[[File:sigmax.png|none|x50px|]]
assuming that the integrand is a smooth function of momenta the integral can be approximated as
[[File:rim0.png|none|x50px|]]
where the small Brillouin Zones (sBZ) relative to a given q-point are the Brillouin Zones of the momenta vectors lattice.
They are chosen in such a way to cover the whole BZ.
In the RIM run-level yambo calculates the integrals of the symmetrized Coulomb potential
[[File:rim1.png|none|x50px|]]

So we are ready to start the tutorial
First go in the proper directory and have a look if all the required databases are there
$ cd YAMBO_TUTORIALS/hBN-2D/YAMBO
$ ls ./SAVE
ns.db1 ns.wf ns.kb_pp_pwscf ...
$ yambo ''(initialization, if you haven't already done so)''

Create the input to generate the <code>ndb.RIM</code> database
$ yambo -F yambo_WR.in -r
and change the following variables
[[Variables#RandQpts|RandQpts]] = 1000000 # [RIM] Number of random q-points in the BZ
[[Variables#RandGvec|RandGvec]] = 100 RL # [RIM] Coulomb interaction RS components
N.B ''RandGvec=100'' means to use the RIM for the first 100 G-components of the coulomb potential
(Suggestion : later you can check convergence of the HF gap changing these two values)
Close input and Run yambo
$ yambo -F yambo_WR.in -J 2D_WR
At the end you find a new database ''ndb.RIM'' and a new report file ''r-2D_WR_rim_cut ''. Open it and look inside

Gamma point sphere radius [au]: 0.08028
Points outside the sphere : 799246
[Int_sBZ(q=0) 1/q^2]*(Vol_sBZ)^(-1/3) = 7.665674
should be < 7.795600
[WR./2D_WR//ndb.RIM]--------------------------------------
Brillouin Zone Q/K grids (IBZ/BZ): 7 36 7 36
Coulombian RL components : 111
Coulombian diagonal components :yes
RIM random points : 1000000
RIM RL volume [a.u.]: 0.390293
Real RL volume [a.u.]: 0.390112
Eps^-1 reference component :0
Eps^-1 components : 0.00 0.00 0.00
RIM anysotropy factor : 0.000000
- S/N 005962 -------------------------- v.04.01.02 r.00120 -

Summary of Coulomb integrals for non-metallic bands |Q|[au] RIM/Bare:

Q [1]:0.1000E-40.9833 * Q [2]: 0.256404 1.094818
Q [5]: 0.444104 1.032268 * Q [3]: 0.512807 1.024055
Q [6]: 0.678380 1.013997 * Q [4]: 0.769211 1.010774
Q [7]: 0.888208 1.008393

The RIM and Real RL Volumes are quite similar so one million random q-points seems a reasonable number,
but again you are invited, later on, to check the convergence of one of the main observables (i.e. HF gap, GW gap, absorption..) changing this number.

Close the report file and perform a calculation of the exchange self-energy to estimate the HF gap (very fast calculation) using the RIM.
Generate the input
$ yambo -F yambo_HF_WR.in -J 2D_WR -r -x
In order to calculate the HF gap only for the last k-point (which is the high-simmetry point K) change the last line as
Note also that 4 (5) is the highest occupied (lowest unoccupied) band.
%[[Variables#QPkrange|QPkrange]] # [GW] QP generalized Kpoint/Band indices
7| 7| 4| 5|
%

Close the input and run yambo
$ yambo -F yambo_HF_WR.in -J 2D_WR
At the end you will find the report file ''r-2D_WR_HF_and_locXC_rim_cut'' and the output file ''o-2D_WR.hf''. Open them and have a look
In the output file ''o-2D_WR.hf'' you will see
# K-point Band Eo Ehf DFT HF
#
7.00000 4.00000 0.00000 -3.25329 -16.21953 -19.47282
7.00000 5.00000 4.40109 9.67551 -11.10755 -5.83314

The HF gap is 12.92 eV obtained subtracting the 2 values in the fourth column
Now you can do a similar HF calculation without generating and reading the RIM database

$ yambo -F yambo_HF_NR.in -x
change the variables ''QPkrange'' as before, close the input and run yambo
$ yambo -F yambo_HF_NR.in -J 2D_NR

in this case the HF gap in the file ''o-2D_NR.hf'' results to be 12.69 eV.

Indeed the presence of the numerical instability, discussed before, is evident only using denser k-grids with respect to the one used in this Tutorial (6x6x1)
Suggestion: later you can generate other SAVE directories with denser k-grids and check the HF gap.
The results of the HF gap calculated with different k-grids without (noRIM) and with Random Integration Method (RIM) to show up the problem are reported:

noRIM RIM

6x6x1 12.69eV 12.92eV
12x12x1 12.80eV 12.92eV
15x15x1 12.96eV 12.93eV
45x45x1 15.52eV 12.96eV

So the '''home message''' is : use always the RIM in MB simulations of low-dimensional materials.

==Generate a truncated coulomb potential ==
To simulate an isolated nano-material a convergence with cell vacuum size is in principle required, like in the DFT runs.
The use of a truncated Coulomb potential allows to achieve faster convergence eliminating the interaction between the repeated images
along the non-periodic direction (see i.e. C. A. Rozzi et al Phys. Rev. B 73, 205119)
In this tutorial we learn how to generate a box-like cutoff for a 2D system with the non-periodic direction along z.

In YAMBO you can use :
* spherical cutoff (for 0D systems)
* cylindrical cutoff (for 1D systems)
* box-like cutoff (for 0D, 1D and 2D systems)

The Coulomb potential with a box-like cutoff is defined as
[[File:Vc1.png|none|x80px|]]
where S is a box-shaped region of the space having sides Lx,Ly and Lz, where they can also assume infinite values (untruncated interaction along desired directions).

Then the FT component is
[[File:Vc2.png|none|x60px|]] where [[File:Vc3.png|none|x60px|]]
For a 2D-system with non period direction along z-axis we have
[[File:Vc4.png|none|x60px|]]

Important remarks:
* the Random Integration Method (RIM) is required to perform the Q-space integration
* for sufficiently large supercells a choose L_i slightly smaller than the cell size in the i-direction ensures to avoid interaction between replicas

Create the input file:

$ yambo -F yambo_WR_WC.in -r

Change the RIM Variables as before and activate the ''cutoff'' generation
[[Variables#RandQpts|RandQpts]] = 1000000 # [RIM] Number of random q-points in the BZ
[[Variables#RandGvec|RandGvec]] = 100 RL # [RIM] Coulomb interaction RS components
[[Variables#CUTGeo|CUTGeo]] = "box z" # [CUT] Coulomb Cutoff geometry: box/cylinder/sphere X/Y/Z/XY..
% CUTBox
0.00 | 0.00 | 32.0 | # [CUT] [au] Box sides
%

Close the input file and run yambo:

$ yambo -F yambo_WR_WC.in -J 2D_WR_WC

in the directory 2D_WR_WC you will find a new database <code> ndb.cutoff </code>

==Use the truncated coulomb potential in a G0W0-PPA calculation==

Generate the input reading the databases in the ''2D_WR_WC'' directory
$ yambo -J 2D_WR_WC -F yambo_G0W0.in -p p -g n -r -k hartree -V qp
In the input change the following variables
[[Variables#NGsBlkXp|NGsBlkXp]] = 4 Ry # [Xp] Response block size
[[Variables#QPkrange|QPkrange]] # [GW] QP generalized Kpoint/Band indices
7| 7| 4| 5|
Close the input and run yambo
$ yambo -F yambo_G0W0.in -J 2D_WR_WC
At the end you will find a new report file ''r-2D_WR_WC_em1d_ppa_HF_and_locXC_gw0_rim_cut'', open it and have a look.
You will find also a new output file ''o-2D_WR_WC.qp''. If you open yoi will find that now the G0W0 gap is
4.40 eV (PBE) + 3.70 eV (G0W0 correction) = 8.10 eV
Indeed as you have learned in the previous tutorials the correlation part of the self-energy strongly reduces the HF gap.
Moreover you should note that the QP correction is larger that one found in the h-BN bulk. Why?

==Use the truncated coulomb potential in a BSE calculation==
Generate the input for the BSE calculation:
$ yambo -J 2D_WR_WC -F yambo_BSE.in -r -o b -p p -y d -k sex -V all
Some remarks: the largest verbosity is used <code>-V all </code> and a long input file is generated; with the option <code> -p p </code> the static part of the screening matrix is read from the <code>ndb.pp</code> databases
Change the number of G-vectors in the correlation part of the kernel as:
[[Variables#BSENGBlk|BSENGBlk]]= 4 Ry # [BSK] Screened interaction block size
use the simple rigid scissor to open the correct the KS energies
% [[Variables#KfnQP_E|KfnQP_E]]
3.70000000 | 1.000000 | 1.000000 | # [EXTQP BSK BSS] E parameters (c/v) eV|adim|adim
Set the number of bands to:
% [[Variables#BSEBands|BSEBands]]
2 | 6 | # [BSK] Bands range
This choice means to include in the BSE only three occupied and 2 unoccupied bands.
Increase the number of energy steps
[[Variables#BEnSteps|BEnSteps]]= 500 # [BSS] Energy steps
To do the next Tutorial we need to write the excitonic WFs, so uncomment the following line
#[[Variables#WRbsWF|WRbsWF]] # [BSS] Write to disk excitonic the WFs
Close the input file and run yambo
$ yambo -J 2D_WR_WC -F yambo_BSE.in
Look at the report file ''r-2D_WR_WC_optics_bse_bsk_bss_em1d_ppa_rim_cut'' and plot the real and Imaginary part''o-2D_WR_WC.eps_q1_diago_bse''
You realize immediately when the use of the cutoff in the coulomb potential is activated, the real part is almost 1, while the imaginary part is almost zero, being essentially the dieletric function of vacuum.

For this reason yambo produces another file called here 'o-2D_WR_WC.alpha_q1_diago_bse' which contains the macroscopic polarizability
defined for a 2D system (with non-periodic direction along z) as :

[File:alpha2D.gif|none|x80px|] where [File:Lz.gif|none|x80px|] is the size of the cell in the non-periodic direction (z in this case)

== Analyze the differences with corresponding GW and BSE calculations without the use of a truncated coulomb potential==

Open the input file yambo_G0W0.in and set back <code>CUTGeo= "none"</code>

Close the input and run yambo

$ yambo -J 2D_WR -F yambo_G0W0.in
You will find a new report ''r-2D_WR_em1d_ppa_HF_and_locXC_gw0_rim_cut''.
You are invited to see the difference with the previous one ''r-2D_WR_WC_em1d_ppa_HF_and_locXC_gw0_rim_cut''

and also a new output file ''o-2D_WR.qp'' is present. Open and check the QP correction at the last k-point. This time
a value of 2.83 eV instead of 3.70 eV is obtained. Are you able to explain this result?

Now redoo the BSE calculation but without reading the cutoff database and applying the QP correction just obtained without using the cutoff.

To do that, open the yambo_BSE.in and put <code>CUTGeo= "none"</code>
and set the QP correction of 2.83 eV, just obtained without uisng the cutoff.
% [[Variables#KfnQP_E|KfnQP_E]]
2.830000 | 1.000000 | 1.000000 | # [EXTQP BSK BSS] E parameters (c/v) eV|adim|adim

Close the input file and run yambo
$ yambo -J 2D_WR -F yambo_BSE.in
Plot the imaginary part of the GW and BSE polarizability :

$ gnuplot
$ gnuplot> set ylabel 'alpha'
$ gnuplot> plot 'o-2D_WR.eps_q1_diago_bse' u 1:($4*33.01/4/pi) w l title 'GW without cutoff' ,'o-2D_WR_WC.alpha_q1_diago_bse' u 1:4 w l title ' GW with cutoff' , 'o-2D_WR.eps_q1_diago_bse' u 1:($2*33.01/4/pi) w l title 'BSE without cutoff' ,'o-2D_WR_WC.alpha_q1_diago_bse' u 1:2 w l title 'BSE with cutoff'

[[File:BSE_2D_cutnocut.png|none|600px|]]

You can note that the energy of the peaks in the two G0W0 spectra (with and without cutoff) are quite different:
you find the first peak around 7 eV without cutoff and around 8 eV with cutoff.
Instead the two GW+BSE spectra, without and with cutoff, are much more similar. Are you able to explain why?
Remarks: The convergence in k-space can be done separately for GW and BSE
calculations, because generally more k-points are needed to converge the excitonic with respect to the quasi-particle properties.

N.B. If you will use the same inputs created in this tutorial remember to set up the cutoff variable ''CUTGeo= "box z"'' to use again the truncated coulomb potential in the GW and BSE calculations

Literature on two-dimensional h-BN: L. Wirtz et al Phys Rev Lett 96 126104 (2006), F. Rasmussen et al Phys Rev. B 94 155406 (2016),N. Berseneva et al Phys. Rev. B 87 035404 (2013).

How to treat low dimensional systems

2020-01-20T15:02:02Z

Maurizia: /* Use the truncated coulomb potential in a BSE calculation */

In this tutorial you will learn how to treat low-dimensional material.
A small k-sampling is used to reduce the computational cost/time.
Later on you can repeat this tutorial but using denser k-grids to check the convergence.

== Prerequisites ==

* <code>yambo</code> executable
* <code>ypp</code> executable
* <code>gnuplot</code>, for plotting spectra
* Have Completed the [[First steps: a walk through from DFT to optical properties]] tutorial

==Avoid numerical divergences using the Random Integration Method (RIM)==
In DFT runs of low-dimensional materials low dimensional k-grids are generally used. (i.e. NxNx1 for a 2D sheet perpendicular to the z direction)
This can create numerical problems in the convergence of the many-body (MB) results due to the divergence at small q of the coulomb potential,
which appears in all the main equations.
To eliminate this problem YAMBO uses the so-called Random Integration Method
which means to use a Monte Carlo Integration with Random Q-points whose number ''[[Variables#RandQpts|RandQpts]]'' will be given in input.
For example the exchange self-energy matrix element which is:
[[File:sigmax.png|none|x50px|]]
assuming that the integrand is a smooth function of momenta the integral can be approximated as
[[File:rim0.png|none|x50px|]]
where the small Brillouin Zones (sBZ) relative to a given q-point are the Brillouin Zones of the momenta vectors lattice.
They are chosen in such a way to cover the whole BZ.
In the RIM run-level yambo calculates the integrals of the symmetrized Coulomb potential
[[File:rim1.png|none|x50px|]]

So we are ready to start the tutorial
First go in the proper directory and have a look if all the required databases are there
$ cd YAMBO_TUTORIALS/hBN-2D/YAMBO
$ ls ./SAVE
ns.db1 ns.wf ns.kb_pp_pwscf ...
$ yambo ''(initialization, if you haven't already done so)''

Create the input to generate the <code>ndb.RIM</code> database
$ yambo -F yambo_WR.in -r
and change the following variables
[[Variables#RandQpts|RandQpts]] = 1000000 # [RIM] Number of random q-points in the BZ
[[Variables#RandGvec|RandGvec]] = 100 RL # [RIM] Coulomb interaction RS components
N.B ''RandGvec=100'' means to use the RIM for the first 100 G-components of the coulomb potential
(Suggestion : later you can check convergence of the HF gap changing these two values)
Close input and Run yambo
$ yambo -F yambo_WR.in -J 2D_WR
At the end you find a new database ''ndb.RIM'' and a new report file ''r-2D_WR_rim_cut ''. Open it and look inside

Gamma point sphere radius [au]: 0.08028
Points outside the sphere : 799246
[Int_sBZ(q=0) 1/q^2]*(Vol_sBZ)^(-1/3) = 7.665674
should be < 7.795600
[WR./2D_WR//ndb.RIM]--------------------------------------
Brillouin Zone Q/K grids (IBZ/BZ): 7 36 7 36
Coulombian RL components : 111
Coulombian diagonal components :yes
RIM random points : 1000000
RIM RL volume [a.u.]: 0.390293
Real RL volume [a.u.]: 0.390112
Eps^-1 reference component :0
Eps^-1 components : 0.00 0.00 0.00
RIM anysotropy factor : 0.000000
- S/N 005962 -------------------------- v.04.01.02 r.00120 -

Summary of Coulomb integrals for non-metallic bands |Q|[au] RIM/Bare:

Q [1]:0.1000E-40.9833 * Q [2]: 0.256404 1.094818
Q [5]: 0.444104 1.032268 * Q [3]: 0.512807 1.024055
Q [6]: 0.678380 1.013997 * Q [4]: 0.769211 1.010774
Q [7]: 0.888208 1.008393

The RIM and Real RL Volumes are quite similar so one million random q-points seems a reasonable number,
but again you are invited, later on, to check the convergence of one of the main observables (i.e. HF gap, GW gap, absorption..) changing this number.

Close the report file and perform a calculation of the exchange self-energy to estimate the HF gap (very fast calculation) using the RIM.
Generate the input
$ yambo -F yambo_HF_WR.in -J 2D_WR -r -x
In order to calculate the HF gap only for the last k-point (which is the high-simmetry point K) change the last line as
Note also that 4 (5) is the highest occupied (lowest unoccupied) band.
%[[Variables#QPkrange|QPkrange]] # [GW] QP generalized Kpoint/Band indices
7| 7| 4| 5|
%

Close the input and run yambo
$ yambo -F yambo_HF_WR.in -J 2D_WR
At the end you will find the report file ''r-2D_WR_HF_and_locXC_rim_cut'' and the output file ''o-2D_WR.hf''. Open them and have a look
In the output file ''o-2D_WR.hf'' you will see
# K-point Band Eo Ehf DFT HF
#
7.00000 4.00000 0.00000 -3.25329 -16.21953 -19.47282
7.00000 5.00000 4.40109 9.67551 -11.10755 -5.83314

The HF gap is 12.92 eV obtained subtracting the 2 values in the fourth column
Now you can do a similar HF calculation without generating and reading the RIM database

$ yambo -F yambo_HF_NR.in -x
change the variables ''QPkrange'' as before, close the input and run yambo
$ yambo -F yambo_HF_NR.in -J 2D_NR

in this case the HF gap in the file ''o-2D_NR.hf'' results to be 12.69 eV.

Indeed the presence of the numerical instability, discussed before, is evident only using denser k-grids with respect to the one used in this Tutorial (6x6x1)
Suggestion: later you can generate other SAVE directories with denser k-grids and check the HF gap.
The results of the HF gap calculated with different k-grids without (noRIM) and with Random Integration Method (RIM) to show up the problem are reported:

noRIM RIM

6x6x1 12.69eV 12.92eV
12x12x1 12.80eV 12.92eV
15x15x1 12.96eV 12.93eV
45x45x1 15.52eV 12.96eV

So the '''home message''' is : use always the RIM in MB simulations of low-dimensional materials.

==Generate a truncated coulomb potential ==
To simulate an isolated nano-material a convergence with cell vacuum size is in principle required, like in the DFT runs.
The use of a truncated Coulomb potential allows to achieve faster convergence eliminating the interaction between the repeated images
along the non-periodic direction (see i.e. C. A. Rozzi et al Phys. Rev. B 73, 205119)
In this tutorial we learn how to generate a box-like cutoff for a 2D system with the non-periodic direction along z.

In YAMBO you can use :
* spherical cutoff (for 0D systems)
* cylindrical cutoff (for 1D systems)
* box-like cutoff (for 0D, 1D and 2D systems)

The Coulomb potential with a box-like cutoff is defined as
[[File:Vc1.png|none|x80px|]]
where S is a box-shaped region of the space having sides Lx,Ly and Lz, where they can also assume infinite values (untruncated interaction along desired directions).

Then the FT component is
[[File:Vc2.png|none|x60px|]] where [[File:Vc3.png|none|x60px|]]
For a 2D-system with non period direction along z-axis we have
[[File:Vc4.png|none|x60px|]]

Important remarks:
* the Random Integration Method (RIM) is required to perform the Q-space integration
* for sufficiently large supercells a choose L_i slightly smaller than the cell size in the i-direction ensures to avoid interaction between replicas

Create the input file:

$ yambo -F yambo_WR_WC.in -r

Change the RIM Variables as before and activate the ''cutoff'' generation
[[Variables#RandQpts|RandQpts]] = 1000000 # [RIM] Number of random q-points in the BZ
[[Variables#RandGvec|RandGvec]] = 100 RL # [RIM] Coulomb interaction RS components
[[Variables#CUTGeo|CUTGeo]] = "box z" # [CUT] Coulomb Cutoff geometry: box/cylinder/sphere X/Y/Z/XY..
% CUTBox
0.00 | 0.00 | 32.0 | # [CUT] [au] Box sides
%

Close the input file and run yambo:

$ yambo -F yambo_WR_WC.in -J 2D_WR_WC

in the directory 2D_WR_WC you will find a new database <code> ndb.cutoff </code>

==Use the truncated coulomb potential in a G0W0-PPA calculation==

Generate the input reading the databases in the ''2D_WR_WC'' directory
$ yambo -J 2D_WR_WC -F yambo_G0W0.in -p p -g n -r -k hartree -V qp
In the input change the following variables
[[Variables#NGsBlkXp|NGsBlkXp]] = 4 Ry # [Xp] Response block size
[[Variables#QPkrange|QPkrange]] # [GW] QP generalized Kpoint/Band indices
7| 7| 4| 5|
Close the input and run yambo
$ yambo -F yambo_G0W0.in -J 2D_WR_WC
At the end you will find a new report file ''r-2D_WR_WC_em1d_ppa_HF_and_locXC_gw0_rim_cut'', open it and have a look.
You will find also a new output file ''o-2D_WR_WC.qp''. If you open yoi will find that now the G0W0 gap is
4.40 eV (PBE) + 3.70 eV (G0W0 correction) = 8.10 eV
Indeed as you have learned in the previous tutorials the correlation part of the self-energy strongly reduces the HF gap.
Moreover you should note that the QP correction is larger that one found in the h-BN bulk. Why?

==Use the truncated coulomb potential in a BSE calculation==
Generate the input for the BSE calculation:
$ yambo -J 2D_WR_WC -F yambo_BSE.in -r -o b -p p -y d -k sex -V all
Some remarks: the largest verbosity is used <code>-V all </code> and a long input file is generated; with the option <code> -p p </code> the static part of the screening matrix is read from the <code>ndb.pp</code> databases
Change the number of G-vectors in the correlation part of the kernel as:
[[Variables#BSENGBlk|BSENGBlk]]= 4 Ry # [BSK] Screened interaction block size
use the simple rigid scissor to open the correct the KS energies
% [[Variables#KfnQP_E|KfnQP_E]]
3.70000000 | 1.000000 | 1.000000 | # [EXTQP BSK BSS] E parameters (c/v) eV|adim|adim
Set the number of bands to:
% [[Variables#BSEBands|BSEBands]]
2 | 6 | # [BSK] Bands range
This choice means to include in the BSE only three occupied and 2 unoccupied bands.
Increase the number of energy steps
[[Variables#BEnSteps|BEnSteps]]= 500 # [BSS] Energy steps
To do the next Tutorial we need to write the excitonic WFs, so uncomment the following line
#[[Variables#WRbsWF|WRbsWF]] # [BSS] Write to disk excitonic the WFs
Close the input file and run yambo
$ yambo -J 2D_WR_WC -F yambo_BSE.in
Look at the report file ''r-2D_WR_WC_optics_bse_bsk_bss_em1d_ppa_rim_cut'' and plot ''o-2D_WR_WC.eps_q1_diago_bse''.
You realize immediately that the real part is almost 1, while the imaginary part is almost zero, being essentially the dieletric function of vacuum.

For this reason yambo produces another file called here 'o-2D_WR_WC.alpha_q1_diago_bse' which contains the macroscopic polarizability
defined for a 2D system (with non-periodic direction along z) as :

[File:alpha2D.gif|none|x80px|] where [File:Lz.gif|none|x80px|] is the size of the cell in the non-periodic direction (z in this case)

== Analyze the differences with corresponding GW and BSE calculations without the use of a truncated coulomb potential==

Open the input file yambo_G0W0.in and set back <code>CUTGeo= "none"</code>

Close the input and run yambo

$ yambo -J 2D_WR -F yambo_G0W0.in
You will find a new report ''r-2D_WR_em1d_ppa_HF_and_locXC_gw0_rim_cut''.
You are invited to see the difference with the previous one ''r-2D_WR_WC_em1d_ppa_HF_and_locXC_gw0_rim_cut''

and also a new output file ''o-2D_WR.qp'' is present. Open and check the QP correction at the last k-point. This time
a value of 2.83 eV instead of 3.70 eV is obtained. Are you able to explain this result?

Now redoo the BSE calculation but without reading the cutoff database and applying the QP correction just obtained without using the cutoff.

To do that, open the yambo_BSE.in and put <code>CUTGeo= "none"</code>
and set the QP correction of 2.83 eV, just obtained without uisng the cutoff.
% [[Variables#KfnQP_E|KfnQP_E]]
2.830000 | 1.000000 | 1.000000 | # [EXTQP BSK BSS] E parameters (c/v) eV|adim|adim

Close the input file and run yambo
$ yambo -J 2D_WR -F yambo_BSE.in
Plot the imaginary part of the GW and BSE polarizability :

$ gnuplot
$ gnuplot> set ylabel 'alpha'
$ gnuplot> plot 'o-2D_WR.eps_q1_diago_bse' u 1:($4*33.01/4/pi) w l title 'GW without cutoff' ,'o-2D_WR_WC.alpha_q1_diago_bse' u 1:4 w l title ' GW with cutoff' , 'o-2D_WR.eps_q1_diago_bse' u 1:($2*33.01/4/pi) w l title 'BSE without cutoff' ,'o-2D_WR_WC.alpha_q1_diago_bse' u 1:2 w l title 'BSE with cutoff'

[[File:BSE_2D_cutnocut.png|none|600px|]]

You can note that the energy of the peaks in the two G0W0 spectra (with and without cutoff) are quite different:
you find the first peak around 7 eV without cutoff and around 8 eV with cutoff.
Instead the two GW+BSE spectra, without and with cutoff, are much more similar. Are you able to explain why?
Remarks: The convergence in k-space can be done separately for GW and BSE
calculations, because generally more k-points are needed to converge the excitonic with respect to the quasi-particle properties.

N.B. If you will use the same inputs created in this tutorial remember to set up the cutoff variable ''CUTGeo= "box z"'' to use again the truncated coulomb potential in the GW and BSE calculations

Literature on two-dimensional h-BN: L. Wirtz et al Phys Rev Lett 96 126104 (2006), F. Rasmussen et al Phys Rev. B 94 155406 (2016),N. Berseneva et al Phys. Rev. B 87 035404 (2013).