The Yambo Project - User contributions [en]

CECAM VIRTUAL 2021

2021-04-09T07:22:46Z

Aferretti: /* Thursday 15 April */

Plan for the CECAM VIRTUAL 2021 school tutorials.
https://www.cecam.org/workshop-details/1081

[[File:Cecam_school_program.png|thumb|160px| Click to enlarge the full program]]

== Setting up Yambo ==

In order to get the yambo code in your machine you have multiple options:

* Yambo Virtual Machine
* Yambo Container
* Install the Yambo source in your computer

=== Setting up the Yambo Virtual Machine ===
The tutorials can be run on a dedicated Virtual Machine (called '''Yambo Quantum Mobile''' and adapted from the [https://quantum-mobile.readthedocs.io/en/latest/ Quantum Mobile] VM).
This is run by installing it as Virtual Machine with the VirtualBox program.
To install the Yambo VM in your computer you need to:
* Download and install Virtualbox software
* Download the Yambo Virtual Machine image
* Install the Yambo Virtual Machine
* Start the Yambo Virtual Machine
* Update and install the Tutorials

To this end follow exactly the step listed here: [[Yambo_Virtual_Machine#Install_the_Yambo_Quantum_Mobile_VM|Install the Yambo Quantum Mobile VM]]

=== Setting up the Yambo Container===

An alternative to get the Yambo code is to install the Yambo container in your machine and this can be done in few steps:

* Install the docker platform (Linux or Mac). Follow the instruction in the docker [https://docs.docker.com/engine/install/ website].
* Pull the Yambo container:

sudo docker pull nicspalla/yambo-gcc_openmp_petsc:latest

sudo it is not necessary if your user is part of the group named docker (suggested on Linux!).

For Linux users:

sudo groupadd docker
sudo usermod -aG docker $USER

For Mac users:

sudo dscl . create /Groups/docker
sudo dseditgroup -o edit -a $USER -t user docker

Log out and log back in so that your group membership is re-evaluated.

* You are done. To run Yambo into the container:

docker run -ti --user $(id -u):$(id -g) \
--mount type=bind,source="$(pwd)",target=/tmpdir \
-e OMP_NUM_THREADS=4 \
nicspalla/yambo-gcc_openmp_petsc:latest \
yambo -F yambo.in -J yambo.out

Otherwise (suggested!), copy and paste the code below in a file, i.e called drun.sh:

#!/bin/bash
docker run -ti --user $(id -u):$(id -g) \
--mount type=bind,source="$(pwd)",target=/tmpdir \
-e OMP_NUM_THREADS=4 \
nicspalla/yambo-gcc_openmp_petsc:latest $@

then give the file execute privileges:

chmod +x drun.sh

Move (or copy) this file in the directory where you want to use Yambo and use it as prefix of your Yambo calculation:

./drun.sh yambo -F yambo.in -J yambo.out

If the yambo container is working correctly you should obtain:

./drun.sh yambo

yambo: cannot access CORE database (SAVE/*db1 and/or SAVE/*wf)

./drun.sh yambo -h

should provide in output the help for yambo usage.

=== Install Yambo ===
If you have some experience with compiling codes, you can [[Download| get the source]] and [[Installation | install]] it. If you never compiled a code, it is better to choose one of the above options as the technical assistance we can offer is limited.

== Tutorials ==

Before starting, [[Get_Tutorial_files_CECAM2021|get the tutorial files]].

=== Thursday 8 April ===
'''14:00 - 14:30 Hands-on setup '''

'''14:30 - 17:00 From the DFT ground state to the complete setup of a Many Body calculation using Yambo''', Davide Sangalli (CNR-ISM, Italy), Pedro Melo (University of Utrecht, the Netherlands)


* [[First steps: walk through from DFT(standalone)|First steps: Initialization and more ]]
* [[Next steps: RPA calculations (standalone)|Next steps: RPA calculations ]]

=== Friday 9 April ===

'''13:30 - 16:30 A complete tour through GW simulation in a complex material (from the blackboard to numerical computation: convergence, algorithms, parallel usage)''', Daniele Varsano (CNR-NANO, Italy), Andrea Ferretti (CNR-NANO, Italy)

* [[GW hBN Yambo Virtual 2021 version|How to obtain the quasi-particle band structure of a bulk material: h-BN]]

=== Thursday 15 April ===

'''13:30 to 15: Calculating optical spectra including excitonic effects: a step-by-step guide'''

'''15 to 16:30: Analysis of excitonic spectra, BSE solvers and convergence'',' Fulvio Paleari (CNR-ISM, Italy), Myrta Grüning (Queen's University Belfast, Northern Ireland)

* [[BSE hBN Yambo Virtual 2021 version|How to obtain an optical spectrum]]

== Lectures ==

All the lectures will be available in the Yambo-code YouTube [https://www.youtube.com/channel/UCO3LzAqb9W2Qk4EbG_83ATw channel]

=== Thursday 8 April ===

'''10:00 to 10:10 - Welcome & Introduction''', Daniele Varsano (CNR-NANO, Italy)

'''10:10 to 10:30 - Material Science and Yambo, what we can calculate''', Andrea Marini (CNR-IAM, Italy)

'''10:40 to 11:00 - Introduction to Many Body Perturbation Theory''', Pedro Melo (University of Utrecht, the Nederlands)

'''11:25 to 11:45 - The linear response theory''', Claudio Attaccalite (CNRS Marseille, France)

'''12:00 to 12:20 - From equations to simulations: the hard life of a Materials scientist''', Myrta Grüning (Queen's University Belfast, Northern Ireland)

=== Friday 9 April ===

'''10:00 to 10:30 - ARPES, quasiparticles and lifetimes: A theory overview''', Andrea Ferretti (CNR-NANO, Italy)

'''10:45 to 11:15 - GW implementation and common approximations''', Daniele Varsano (CNR-NANO, Italy)

'''11:30 to 12:00 - Q&A '''

=== Thursday 15 April ===

'''10:00 to 10:20 - Optical properties & excitons''', Maurizia Palummo (Uni Roma2 Tor Vergata, Italy)

'''10:30 to 10:50 - Derivation of the Bethe-Salpeter Equation and main physical concepts''', Claudio Attaccalite (CNRS Marseille, France)

'''11:20 to 11:40 - BSE implementation and common approximations''', Davide Sangalli (CNR-ISM, Italy)

CECAM VIRTUAL 2021

2021-04-09T07:21:38Z

Aferretti: /* Friday 9 April */

Plan for the CECAM VIRTUAL 2021 school tutorials.
https://www.cecam.org/workshop-details/1081

[[File:Cecam_school_program.png|thumb|160px| Click to enlarge the full program]]

== Setting up Yambo ==

In order to get the yambo code in your machine you have multiple options:

* Yambo Virtual Machine
* Yambo Container
* Install the Yambo source in your computer

=== Setting up the Yambo Virtual Machine ===
The tutorials can be run on a dedicated Virtual Machine (called '''Yambo Quantum Mobile''' and adapted from the [https://quantum-mobile.readthedocs.io/en/latest/ Quantum Mobile] VM).
This is run by installing it as Virtual Machine with the VirtualBox program.
To install the Yambo VM in your computer you need to:
* Download and install Virtualbox software
* Download the Yambo Virtual Machine image
* Install the Yambo Virtual Machine
* Start the Yambo Virtual Machine
* Update and install the Tutorials

To this end follow exactly the step listed here: [[Yambo_Virtual_Machine#Install_the_Yambo_Quantum_Mobile_VM|Install the Yambo Quantum Mobile VM]]

=== Setting up the Yambo Container===

An alternative to get the Yambo code is to install the Yambo container in your machine and this can be done in few steps:

* Install the docker platform (Linux or Mac). Follow the instruction in the docker [https://docs.docker.com/engine/install/ website].
* Pull the Yambo container:

sudo docker pull nicspalla/yambo-gcc_openmp_petsc:latest

sudo it is not necessary if your user is part of the group named docker (suggested on Linux!).

For Linux users:

sudo groupadd docker
sudo usermod -aG docker $USER

For Mac users:

sudo dscl . create /Groups/docker
sudo dseditgroup -o edit -a $USER -t user docker

Log out and log back in so that your group membership is re-evaluated.

* You are done. To run Yambo into the container:

docker run -ti --user $(id -u):$(id -g) \
--mount type=bind,source="$(pwd)",target=/tmpdir \
-e OMP_NUM_THREADS=4 \
nicspalla/yambo-gcc_openmp_petsc:latest \
yambo -F yambo.in -J yambo.out

Otherwise (suggested!), copy and paste the code below in a file, i.e called drun.sh:

#!/bin/bash
docker run -ti --user $(id -u):$(id -g) \
--mount type=bind,source="$(pwd)",target=/tmpdir \
-e OMP_NUM_THREADS=4 \
nicspalla/yambo-gcc_openmp_petsc:latest $@

then give the file execute privileges:

chmod +x drun.sh

Move (or copy) this file in the directory where you want to use Yambo and use it as prefix of your Yambo calculation:

./drun.sh yambo -F yambo.in -J yambo.out

If the yambo container is working correctly you should obtain:

./drun.sh yambo

yambo: cannot access CORE database (SAVE/*db1 and/or SAVE/*wf)

./drun.sh yambo -h

should provide in output the help for yambo usage.

=== Install Yambo ===
If you have some experience with compiling codes, you can [[Download| get the source]] and [[Installation | install]] it. If you never compiled a code, it is better to choose one of the above options as the technical assistance we can offer is limited.

== Tutorials ==

Before starting, [[Get_Tutorial_files_CECAM2021|get the tutorial files]].

=== Thursday 8 April ===
'''14:00 - 14:30 Hands-on setup '''

'''14:30 - 17:00 From the DFT ground state to the complete setup of a Many Body calculation using Yambo''', Davide Sangalli (CNR-ISM, Italy), Pedro Melo (University of Utrecht, the Netherlands)


* [[First steps: walk through from DFT(standalone)|First steps: Initialization and more ]]
* [[Next steps: RPA calculations (standalone)|Next steps: RPA calculations ]]

=== Friday 9 April ===

'''13:30 - 16:30 A complete tour through GW simulation in a complex material (from the blackboard to numerical computation: convergence, algorithms, parallel usage)''', Daniele Varsano (CNR-NANO, Italy), Andrea Ferretti (CNR-NANO, Italy)

* [[GW hBN Yambo Virtual 2021 version|How to obtain the quasi-particle band structure of a bulk material: h-BN]]

=== Thursday 15 April ===

'''13:30 to 15: Calculating optical spectra including excitonic effects: a step-by-step guide'''

'''15 to 16:30: Analysis of excitonic spectra, BSE solvers and convergence'',' Fulvio Paleari (CNR-ISM, Italy), Myrta Grüning (Queen's University Belfast, Northern Ireland)

* [[BSE hBN Yambo Virtual 2021 version|How to obtain an optical spectrum]]

== Lectures ==

All the lectures will be available in the Yambo-code YouTube [https://www.youtube.com/channel/UCO3LzAqb9W2Qk4EbG_83ATw channel]

=== Thursday 8 April ===

'''10:00 to 10:10 - Welcome & Introduction''', Daniele Varsano (CNR-NANO, Italy)

'''10:10 to 10:30 - Material Science and Yambo, what we can calculate''', Andrea Marini (CNR-IAM, Italy)

'''10:40 to 11:00 - Introduction to Many Body Perturbation Theory''', Pedro Melo (University of Utrecht, the Nederlands)

'''11:25 to 11:45 - The linear response theory''', Claudio Attaccalite (CNRS Marseille, France)

'''12:00 to 12:20 - From equations to simulations: the hard life of a Materials scientist''', Myrta Grüning (Queen's University Belfast, Northern Ireland)

=== Friday 9 April ===

'''10:00 to 10:30 - ARPES, quasiparticles and lifetimes: A theory overview''', Andrea Ferretti (CNR-NANO, Italy)

'''10:45 to 11:15 - GW implementation and common approximations''', Daniele Varsano (CNR-NANO, Italy)

'''11:30 to 12:00 - Q&A '''

=== Thursday 15 April ===

'''10:00 to 10:20 - Optical properties & excitons''' Maurizia Palummo

'''10:30 to 10:50 - Derivation of the Bethe-Salpeter Equation and main physical concepts''' Claudio Attaccalite

'''11:20 to 11:40 - BSE implementation and common approximations''' Davide Sangalli

CECAM VIRTUAL 2021

2021-04-09T07:20:25Z

Aferretti: /* Thursday 8 April */

Plan for the CECAM VIRTUAL 2021 school tutorials.
https://www.cecam.org/workshop-details/1081

[[File:Cecam_school_program.png|thumb|160px| Click to enlarge the full program]]

== Setting up Yambo ==

In order to get the yambo code in your machine you have multiple options:

* Yambo Virtual Machine
* Yambo Container
* Install the Yambo source in your computer

=== Setting up the Yambo Virtual Machine ===
The tutorials can be run on a dedicated Virtual Machine (called '''Yambo Quantum Mobile''' and adapted from the [https://quantum-mobile.readthedocs.io/en/latest/ Quantum Mobile] VM).
This is run by installing it as Virtual Machine with the VirtualBox program.
To install the Yambo VM in your computer you need to:
* Download and install Virtualbox software
* Download the Yambo Virtual Machine image
* Install the Yambo Virtual Machine
* Start the Yambo Virtual Machine
* Update and install the Tutorials

To this end follow exactly the step listed here: [[Yambo_Virtual_Machine#Install_the_Yambo_Quantum_Mobile_VM|Install the Yambo Quantum Mobile VM]]

=== Setting up the Yambo Container===

An alternative to get the Yambo code is to install the Yambo container in your machine and this can be done in few steps:

* Install the docker platform (Linux or Mac). Follow the instruction in the docker [https://docs.docker.com/engine/install/ website].
* Pull the Yambo container:

sudo docker pull nicspalla/yambo-gcc_openmp_petsc:latest

sudo it is not necessary if your user is part of the group named docker (suggested on Linux!).

For Linux users:

sudo groupadd docker
sudo usermod -aG docker $USER

For Mac users:

sudo dscl . create /Groups/docker
sudo dseditgroup -o edit -a $USER -t user docker

Log out and log back in so that your group membership is re-evaluated.

* You are done. To run Yambo into the container:

docker run -ti --user $(id -u):$(id -g) \
--mount type=bind,source="$(pwd)",target=/tmpdir \
-e OMP_NUM_THREADS=4 \
nicspalla/yambo-gcc_openmp_petsc:latest \
yambo -F yambo.in -J yambo.out

Otherwise (suggested!), copy and paste the code below in a file, i.e called drun.sh:

#!/bin/bash
docker run -ti --user $(id -u):$(id -g) \
--mount type=bind,source="$(pwd)",target=/tmpdir \
-e OMP_NUM_THREADS=4 \
nicspalla/yambo-gcc_openmp_petsc:latest $@

then give the file execute privileges:

chmod +x drun.sh

Move (or copy) this file in the directory where you want to use Yambo and use it as prefix of your Yambo calculation:

./drun.sh yambo -F yambo.in -J yambo.out

If the yambo container is working correctly you should obtain:

./drun.sh yambo

yambo: cannot access CORE database (SAVE/*db1 and/or SAVE/*wf)

./drun.sh yambo -h

should provide in output the help for yambo usage.

=== Install Yambo ===
If you have some experience with compiling codes, you can [[Download| get the source]] and [[Installation | install]] it. If you never compiled a code, it is better to choose one of the above options as the technical assistance we can offer is limited.

== Tutorials ==

Before starting, [[Get_Tutorial_files_CECAM2021|get the tutorial files]].

=== Thursday 8 April ===
'''14:00 - 14:30 Hands-on setup '''

'''14:30 - 17:00 From the DFT ground state to the complete setup of a Many Body calculation using Yambo''', Davide Sangalli (CNR-ISM, Italy), Pedro Melo (University of Utrecht, the Netherlands)


* [[First steps: walk through from DFT(standalone)|First steps: Initialization and more ]]
* [[Next steps: RPA calculations (standalone)|Next steps: RPA calculations ]]

=== Friday 9 April ===

'''13:30 - 16:30 A complete tour through GW simulation in a complex material (from the blackboard to numerical computation: convergence, algorithms, parallel usage)''', Daniele Varsano (CNR-NANO, Italy), Andrea Ferretti (CNR-NANO, Italy)

* [[GW hBN Yambo Virtual 2021 version|How to obtain the quasi-particle band structure of a bulk material: h-BN]]

=== Thursday 15 April ===

'''13:30 to 15: Calculating optical spectra including excitonic effects: a step-by-step guide'''

'''15 to 16:30: Analysis of excitonic spectra, BSE solvers and convergence'',' Fulvio Paleari (CNR-ISM, Italy), Myrta Grüning (Queen's University Belfast, Northern Ireland)

* [[BSE hBN Yambo Virtual 2021 version|How to obtain an optical spectrum]]

== Lectures ==

All the lectures will be available in the Yambo-code YouTube [https://www.youtube.com/channel/UCO3LzAqb9W2Qk4EbG_83ATw channel]

=== Thursday 8 April ===

'''10:00 to 10:10 - Welcome & Introduction''', Daniele Varsano (CNR-NANO, Italy)

'''10:10 to 10:30 - Material Science and Yambo, what we can calculate''', Andrea Marini (CNR-IAM, Italy)

'''10:40 to 11:00 - Introduction to Many Body Perturbation Theory''', Pedro Melo (University of Utrecht, the Nederlands)

'''11:25 to 11:45 - The linear response theory''', Claudio Attaccalite (CNRS Marseille, France)

'''12:00 to 12:20 - From equations to simulations: the hard life of a Materials scientist''', Myrta Grüning (Queen's University Belfast, Northern Ireland)

=== Friday 9 April ===

'''10:00 to 10:45 - ARPES, quasiparticles and lifetimes: A theory overview''' Andrea Ferretti (CNR-NANO, Italy)

'''10:45 to 11:30 - GW implementation and common approximations''' Daniele Varsano (CNR-NANO, Italy)

'''11:30 to 12:00 - Q&A '''

=== Thursday 15 April ===

'''10:00 to 10:20 - Optical properties & excitons''' Maurizia Palummo

'''10:30 to 10:50 - Derivation of the Bethe-Salpeter Equation and main physical concepts''' Claudio Attaccalite

'''11:20 to 11:40 - BSE implementation and common approximations''' Davide Sangalli

CECAM VIRTUAL 2021

2021-04-09T07:19:12Z

Aferretti: /* Thursday 8 April */

Plan for the CECAM VIRTUAL 2021 school tutorials.
https://www.cecam.org/workshop-details/1081

[[File:Cecam_school_program.png|thumb|160px| Click to enlarge the full program]]

== Setting up Yambo ==

In order to get the yambo code in your machine you have multiple options:

* Yambo Virtual Machine
* Yambo Container
* Install the Yambo source in your computer

=== Setting up the Yambo Virtual Machine ===
The tutorials can be run on a dedicated Virtual Machine (called '''Yambo Quantum Mobile''' and adapted from the [https://quantum-mobile.readthedocs.io/en/latest/ Quantum Mobile] VM).
This is run by installing it as Virtual Machine with the VirtualBox program.
To install the Yambo VM in your computer you need to:
* Download and install Virtualbox software
* Download the Yambo Virtual Machine image
* Install the Yambo Virtual Machine
* Start the Yambo Virtual Machine
* Update and install the Tutorials

To this end follow exactly the step listed here: [[Yambo_Virtual_Machine#Install_the_Yambo_Quantum_Mobile_VM|Install the Yambo Quantum Mobile VM]]

=== Setting up the Yambo Container===

An alternative to get the Yambo code is to install the Yambo container in your machine and this can be done in few steps:

* Install the docker platform (Linux or Mac). Follow the instruction in the docker [https://docs.docker.com/engine/install/ website].
* Pull the Yambo container:

sudo docker pull nicspalla/yambo-gcc_openmp_petsc:latest

sudo it is not necessary if your user is part of the group named docker (suggested on Linux!).

For Linux users:

sudo groupadd docker
sudo usermod -aG docker $USER

For Mac users:

sudo dscl . create /Groups/docker
sudo dseditgroup -o edit -a $USER -t user docker

Log out and log back in so that your group membership is re-evaluated.

* You are done. To run Yambo into the container:

docker run -ti --user $(id -u):$(id -g) \
--mount type=bind,source="$(pwd)",target=/tmpdir \
-e OMP_NUM_THREADS=4 \
nicspalla/yambo-gcc_openmp_petsc:latest \
yambo -F yambo.in -J yambo.out

Otherwise (suggested!), copy and paste the code below in a file, i.e called drun.sh:

#!/bin/bash
docker run -ti --user $(id -u):$(id -g) \
--mount type=bind,source="$(pwd)",target=/tmpdir \
-e OMP_NUM_THREADS=4 \
nicspalla/yambo-gcc_openmp_petsc:latest $@

then give the file execute privileges:

chmod +x drun.sh

Move (or copy) this file in the directory where you want to use Yambo and use it as prefix of your Yambo calculation:

./drun.sh yambo -F yambo.in -J yambo.out

If the yambo container is working correctly you should obtain:

./drun.sh yambo

yambo: cannot access CORE database (SAVE/*db1 and/or SAVE/*wf)

./drun.sh yambo -h

should provide in output the help for yambo usage.

=== Install Yambo ===
If you have some experience with compiling codes, you can [[Download| get the source]] and [[Installation | install]] it. If you never compiled a code, it is better to choose one of the above options as the technical assistance we can offer is limited.

== Tutorials ==

Before starting, [[Get_Tutorial_files_CECAM2021|get the tutorial files]].

=== Thursday 8 April ===
'''14:00 - 14:30 Hands-on setup '''

'''14:30 - 17:00 From the DFT ground state to the complete setup of a Many Body calculation using Yambo''', Davide Sangalli (CNR-ISM, Italy), Pedro Melo (University of Utrecht, the Netherlands)


* [[First steps: walk through from DFT(standalone)|First steps: Initialization and more ]]
* [[Next steps: RPA calculations (standalone)|Next steps: RPA calculations ]]

=== Friday 9 April ===

'''13:30 - 16:30 A complete tour through GW simulation in a complex material (from the blackboard to numerical computation: convergence, algorithms, parallel usage)''', Daniele Varsano (CNR-NANO, Italy), Andrea Ferretti (CNR-NANO, Italy)

* [[GW hBN Yambo Virtual 2021 version|How to obtain the quasi-particle band structure of a bulk material: h-BN]]

=== Thursday 15 April ===

'''13:30 to 15: Calculating optical spectra including excitonic effects: a step-by-step guide'''

'''15 to 16:30: Analysis of excitonic spectra, BSE solvers and convergence'',' Fulvio Paleari (CNR-ISM, Italy), Myrta Grüning (Queen's University Belfast, Northern Ireland)

* [[BSE hBN Yambo Virtual 2021 version|How to obtain an optical spectrum]]

== Lectures ==

All the lectures will be available in the Yambo-code YouTube [https://www.youtube.com/channel/UCO3LzAqb9W2Qk4EbG_83ATw channel]

=== Thursday 8 April ===

'''10:00 to 10:10 - Welcome & Introduction''', Daniele Varsano (CNR-NANO, Italy)

'''10:10 to 10:30 - Material Science and Yambo, what we can calculate''', Andrea Marini (CNR-IAM, Italy)

'''10:40 to 11:00 - Introduction to Many Body Perturbation Theory''', Pedro Melo (University of Utrecth, the Nederlands)

'''11:25 to 11:45 - The linear response theory''', Claudio Attaccalite (CNRS Marseille, France)

'''12:00 to 12:20 - From equations to simulations: the hard life of a Materials scientist''', Myrta Grüning (Queen's University Belfast, Northern Ireland)

=== Friday 9 April ===

'''10:00 to 10:45 - ARPES, quasiparticles and lifetimes: A theory overview''' Andrea Ferretti (CNR-NANO, Italy)

'''10:45 to 11:30 - GW implementation and common approximations''' Daniele Varsano (CNR-NANO, Italy)

'''11:30 to 12:00 - Q&A '''

=== Thursday 15 April ===

'''10:00 to 10:20 - Optical properties & excitons''' Maurizia Palummo

'''10:30 to 10:50 - Derivation of the Bethe-Salpeter Equation and main physical concepts''' Claudio Attaccalite

'''11:20 to 11:40 - BSE implementation and common approximations''' Davide Sangalli

CECAM VIRTUAL 2021

2021-04-09T07:17:04Z

Aferretti: /* Lectures */

Plan for the CECAM VIRTUAL 2021 school tutorials.
https://www.cecam.org/workshop-details/1081

[[File:Cecam_school_program.png|thumb|160px| Click to enlarge the full program]]

== Setting up Yambo ==

In order to get the yambo code in your machine you have multiple options:

* Yambo Virtual Machine
* Yambo Container
* Install the Yambo source in your computer

=== Setting up the Yambo Virtual Machine ===
The tutorials can be run on a dedicated Virtual Machine (called '''Yambo Quantum Mobile''' and adapted from the [https://quantum-mobile.readthedocs.io/en/latest/ Quantum Mobile] VM).
This is run by installing it as Virtual Machine with the VirtualBox program.
To install the Yambo VM in your computer you need to:
* Download and install Virtualbox software
* Download the Yambo Virtual Machine image
* Install the Yambo Virtual Machine
* Start the Yambo Virtual Machine
* Update and install the Tutorials

To this end follow exactly the step listed here: [[Yambo_Virtual_Machine#Install_the_Yambo_Quantum_Mobile_VM|Install the Yambo Quantum Mobile VM]]

=== Setting up the Yambo Container===

An alternative to get the Yambo code is to install the Yambo container in your machine and this can be done in few steps:

* Install the docker platform (Linux or Mac). Follow the instruction in the docker [https://docs.docker.com/engine/install/ website].
* Pull the Yambo container:

sudo docker pull nicspalla/yambo-gcc_openmp_petsc:latest

sudo it is not necessary if your user is part of the group named docker (suggested on Linux!).

For Linux users:

sudo groupadd docker
sudo usermod -aG docker $USER

For Mac users:

sudo dscl . create /Groups/docker
sudo dseditgroup -o edit -a $USER -t user docker

Log out and log back in so that your group membership is re-evaluated.

* You are done. To run Yambo into the container:

docker run -ti --user $(id -u):$(id -g) \
--mount type=bind,source="$(pwd)",target=/tmpdir \
-e OMP_NUM_THREADS=4 \
nicspalla/yambo-gcc_openmp_petsc:latest \
yambo -F yambo.in -J yambo.out

Otherwise (suggested!), copy and paste the code below in a file, i.e called drun.sh:

#!/bin/bash
docker run -ti --user $(id -u):$(id -g) \
--mount type=bind,source="$(pwd)",target=/tmpdir \
-e OMP_NUM_THREADS=4 \
nicspalla/yambo-gcc_openmp_petsc:latest $@

then give the file execute privileges:

chmod +x drun.sh

Move (or copy) this file in the directory where you want to use Yambo and use it as prefix of your Yambo calculation:

./drun.sh yambo -F yambo.in -J yambo.out

If the yambo container is working correctly you should obtain:

./drun.sh yambo

yambo: cannot access CORE database (SAVE/*db1 and/or SAVE/*wf)

./drun.sh yambo -h

should provide in output the help for yambo usage.

=== Install Yambo ===
If you have some experience with compiling codes, you can [[Download| get the source]] and [[Installation | install]] it. If you never compiled a code, it is better to choose one of the above options as the technical assistance we can offer is limited.

== Tutorials ==

Before starting, [[Get_Tutorial_files_CECAM2021|get the tutorial files]].

=== Thursday 8 April ===
'''14:00 - 14:30 Hands-on setup '''

'''14:30 - 17:00 From the DFT ground state to the complete setup of a Many Body calculation using Yambo''', Davide Sangalli (CNR-ISM, Italy), Pedro Melo (University of Utrecht, the Netherlands)


* [[First steps: walk through from DFT(standalone)|First steps: Initialization and more ]]
* [[Next steps: RPA calculations (standalone)|Next steps: RPA calculations ]]

=== Friday 9 April ===

'''13:30 - 16:30 A complete tour through GW simulation in a complex material (from the blackboard to numerical computation: convergence, algorithms, parallel usage)''', Daniele Varsano (CNR-NANO, Italy), Andrea Ferretti (CNR-NANO, Italy)

* [[GW hBN Yambo Virtual 2021 version|How to obtain the quasi-particle band structure of a bulk material: h-BN]]

=== Thursday 15 April ===

'''13:30 to 15: Calculating optical spectra including excitonic effects: a step-by-step guide'''

'''15 to 16:30: Analysis of excitonic spectra, BSE solvers and convergence'',' Fulvio Paleari (CNR-ISM, Italy), Myrta Grüning (Queen's University Belfast, Northern Ireland)

* [[BSE hBN Yambo Virtual 2021 version|How to obtain an optical spectrum]]

== Lectures ==

All the lectures will be available in the Yambo-code YouTube [https://www.youtube.com/channel/UCO3LzAqb9W2Qk4EbG_83ATw channel]

=== Thursday 8 April ===

'''10:00 to 10:10 - Welcome & Introduction''', Daniele Varsano (CNR-NANO, Italy)

'''10:10 to 10:30 - Material Science and Yambo, what we can calculate''', Andrea Marini (CNR-IAM, Italy)

'''10:40 to 11:00 - Introduction to Many Body Perturbation Theory''', Pedro Melo (Uni Utrecth, Nederlands)

'''11:25 to 11:45 - The linear response theory''', Claudio Attaccalite (Uni Marseille, France)

'''12:00 to 12:20 - From equations to simulations: the hard life of a Materials scientist''', Myrta Grüning (Queen's University, Northern Ireland)

=== Friday 9 April ===

'''10:00 to 10:45 - ARPES, quasiparticles and lifetimes: A theory overview''' Andrea Ferretti (CNR-NANO, Italy)

'''10:45 to 11:30 - GW implementation and common approximations''' Daniele Varsano (CNR-NANO, Italy)

'''11:30 to 12:00 - Q&A '''

=== Thursday 15 April ===

'''10:00 to 10:20 - Optical properties & excitons''' Maurizia Palummo

'''10:30 to 10:50 - Derivation of the Bethe-Salpeter Equation and main physical concepts''' Claudio Attaccalite

'''11:20 to 11:40 - BSE implementation and common approximations''' Davide Sangalli

CECAM VIRTUAL 2021

2021-04-09T07:15:44Z

Aferretti: /* Thursday 15 April */

Plan for the CECAM VIRTUAL 2021 school tutorials.
https://www.cecam.org/workshop-details/1081

[[File:Cecam_school_program.png|thumb|160px| Click to enlarge the full program]]

== Setting up Yambo ==

In order to get the yambo code in your machine you have multiple options:

* Yambo Virtual Machine
* Yambo Container
* Install the Yambo source in your computer

=== Setting up the Yambo Virtual Machine ===
The tutorials can be run on a dedicated Virtual Machine (called '''Yambo Quantum Mobile''' and adapted from the [https://quantum-mobile.readthedocs.io/en/latest/ Quantum Mobile] VM).
This is run by installing it as Virtual Machine with the VirtualBox program.
To install the Yambo VM in your computer you need to:
* Download and install Virtualbox software
* Download the Yambo Virtual Machine image
* Install the Yambo Virtual Machine
* Start the Yambo Virtual Machine
* Update and install the Tutorials

To this end follow exactly the step listed here: [[Yambo_Virtual_Machine#Install_the_Yambo_Quantum_Mobile_VM|Install the Yambo Quantum Mobile VM]]

=== Setting up the Yambo Container===

An alternative to get the Yambo code is to install the Yambo container in your machine and this can be done in few steps:

* Install the docker platform (Linux or Mac). Follow the instruction in the docker [https://docs.docker.com/engine/install/ website].
* Pull the Yambo container:

sudo docker pull nicspalla/yambo-gcc_openmp_petsc:latest

sudo it is not necessary if your user is part of the group named docker (suggested on Linux!).

For Linux users:

sudo groupadd docker
sudo usermod -aG docker $USER

For Mac users:

sudo dscl . create /Groups/docker
sudo dseditgroup -o edit -a $USER -t user docker

Log out and log back in so that your group membership is re-evaluated.

* You are done. To run Yambo into the container:

docker run -ti --user $(id -u):$(id -g) \
--mount type=bind,source="$(pwd)",target=/tmpdir \
-e OMP_NUM_THREADS=4 \
nicspalla/yambo-gcc_openmp_petsc:latest \
yambo -F yambo.in -J yambo.out

Otherwise (suggested!), copy and paste the code below in a file, i.e called drun.sh:

#!/bin/bash
docker run -ti --user $(id -u):$(id -g) \
--mount type=bind,source="$(pwd)",target=/tmpdir \
-e OMP_NUM_THREADS=4 \
nicspalla/yambo-gcc_openmp_petsc:latest $@

then give the file execute privileges:

chmod +x drun.sh

Move (or copy) this file in the directory where you want to use Yambo and use it as prefix of your Yambo calculation:

./drun.sh yambo -F yambo.in -J yambo.out

If the yambo container is working correctly you should obtain:

./drun.sh yambo

yambo: cannot access CORE database (SAVE/*db1 and/or SAVE/*wf)

./drun.sh yambo -h

should provide in output the help for yambo usage.

=== Install Yambo ===
If you have some experience with compiling codes, you can [[Download| get the source]] and [[Installation | install]] it. If you never compiled a code, it is better to choose one of the above options as the technical assistance we can offer is limited.

== Tutorials ==

Before starting, [[Get_Tutorial_files_CECAM2021|get the tutorial files]].

=== Thursday 8 April ===
'''14:00 - 14:30 Hands-on setup '''

'''14:30 - 17:00 From the DFT ground state to the complete setup of a Many Body calculation using Yambo''', Davide Sangalli (CNR-ISM, Italy), Pedro Melo (University of Utrecht, the Netherlands)


* [[First steps: walk through from DFT(standalone)|First steps: Initialization and more ]]
* [[Next steps: RPA calculations (standalone)|Next steps: RPA calculations ]]

=== Friday 9 April ===

'''13:30 - 16:30 A complete tour through GW simulation in a complex material (from the blackboard to numerical computation: convergence, algorithms, parallel usage)''', Daniele Varsano (CNR-NANO, Italy), Andrea Ferretti (CNR-NANO, Italy)

* [[GW hBN Yambo Virtual 2021 version|How to obtain the quasi-particle band structure of a bulk material: h-BN]]

=== Thursday 15 April ===

'''13:30 to 15: Calculating optical spectra including excitonic effects: a step-by-step guide'''

'''15 to 16:30: Analysis of excitonic spectra, BSE solvers and convergence'',' Fulvio Paleari (CNR-ISM, Italy), Myrta Grüning (Queen's University Belfast, Northern Ireland)

* [[BSE hBN Yambo Virtual 2021 version|How to obtain an optical spectrum]]

== Lectures ==

All the lectures will be available in the Yambo-code YouTube [https://www.youtube.com/channel/UCO3LzAqb9W2Qk4EbG_83ATw channel]

=== Thursday 8 April ===

'''10:00 to 10:10 - Welcome & Introduction''' Daniele Varsano

'''10:10 to 10:30 - Material Science and Yambo, what we can calculate''' Andrea Marini

'''10:40 to 11:00 - Introduction to Many Body Perturbation Theory''' Pedro Melo

'''11:25 to 11:45 - The linear response theory''' Claudio Attaccalite

'''12:00 to 12:20 - From equations to simulations: the hard life of a Materials scientist''' Myrta Grüning

=== Friday 9 April ===

'''10:00 to 10:45 - ARPES, quasiparticles and lifetimes: A theory overview''' Andrea Ferretti (CNR-NANO, Italy)

'''10:45 to 11:30 - GW implementation and common approximations''' Daniele Varsano (CNR-NANO, Italy)

'''11:30 to 12:00 - Q&A '''

=== Thursday 15 April ===

'''10:00 to 10:20 - Optical properties & excitons''' Maurizia Palummo

'''10:30 to 10:50 - Derivation of the Bethe-Salpeter Equation and main physical concepts''' Claudio Attaccalite

'''11:20 to 11:40 - BSE implementation and common approximations''' Davide Sangalli

CECAM VIRTUAL 2021

2021-04-09T07:15:30Z

Aferretti: /* Friday 9 April */

Plan for the CECAM VIRTUAL 2021 school tutorials.
https://www.cecam.org/workshop-details/1081

[[File:Cecam_school_program.png|thumb|160px| Click to enlarge the full program]]

== Setting up Yambo ==

In order to get the yambo code in your machine you have multiple options:

* Yambo Virtual Machine
* Yambo Container
* Install the Yambo source in your computer

=== Setting up the Yambo Virtual Machine ===
The tutorials can be run on a dedicated Virtual Machine (called '''Yambo Quantum Mobile''' and adapted from the [https://quantum-mobile.readthedocs.io/en/latest/ Quantum Mobile] VM).
This is run by installing it as Virtual Machine with the VirtualBox program.
To install the Yambo VM in your computer you need to:
* Download and install Virtualbox software
* Download the Yambo Virtual Machine image
* Install the Yambo Virtual Machine
* Start the Yambo Virtual Machine
* Update and install the Tutorials

To this end follow exactly the step listed here: [[Yambo_Virtual_Machine#Install_the_Yambo_Quantum_Mobile_VM|Install the Yambo Quantum Mobile VM]]

=== Setting up the Yambo Container===

An alternative to get the Yambo code is to install the Yambo container in your machine and this can be done in few steps:

* Install the docker platform (Linux or Mac). Follow the instruction in the docker [https://docs.docker.com/engine/install/ website].
* Pull the Yambo container:

sudo docker pull nicspalla/yambo-gcc_openmp_petsc:latest

sudo it is not necessary if your user is part of the group named docker (suggested on Linux!).

For Linux users:

sudo groupadd docker
sudo usermod -aG docker $USER

For Mac users:

sudo dscl . create /Groups/docker
sudo dseditgroup -o edit -a $USER -t user docker

Log out and log back in so that your group membership is re-evaluated.

* You are done. To run Yambo into the container:

docker run -ti --user $(id -u):$(id -g) \
--mount type=bind,source="$(pwd)",target=/tmpdir \
-e OMP_NUM_THREADS=4 \
nicspalla/yambo-gcc_openmp_petsc:latest \
yambo -F yambo.in -J yambo.out

Otherwise (suggested!), copy and paste the code below in a file, i.e called drun.sh:

#!/bin/bash
docker run -ti --user $(id -u):$(id -g) \
--mount type=bind,source="$(pwd)",target=/tmpdir \
-e OMP_NUM_THREADS=4 \
nicspalla/yambo-gcc_openmp_petsc:latest $@

then give the file execute privileges:

chmod +x drun.sh

Move (or copy) this file in the directory where you want to use Yambo and use it as prefix of your Yambo calculation:

./drun.sh yambo -F yambo.in -J yambo.out

If the yambo container is working correctly you should obtain:

./drun.sh yambo

yambo: cannot access CORE database (SAVE/*db1 and/or SAVE/*wf)

./drun.sh yambo -h

should provide in output the help for yambo usage.

=== Install Yambo ===
If you have some experience with compiling codes, you can [[Download| get the source]] and [[Installation | install]] it. If you never compiled a code, it is better to choose one of the above options as the technical assistance we can offer is limited.

== Tutorials ==

Before starting, [[Get_Tutorial_files_CECAM2021|get the tutorial files]].

=== Thursday 8 April ===
'''14:00 - 14:30 Hands-on setup '''

'''14:30 - 17:00 From the DFT ground state to the complete setup of a Many Body calculation using Yambo''', Davide Sangalli (CNR-ISM, Italy), Pedro Melo (University of Utrecht, the Netherlands)


* [[First steps: walk through from DFT(standalone)|First steps: Initialization and more ]]
* [[Next steps: RPA calculations (standalone)|Next steps: RPA calculations ]]

=== Friday 9 April ===

'''13:30 - 16:30 A complete tour through GW simulation in a complex material (from the blackboard to numerical computation: convergence, algorithms, parallel usage)''', Daniele Varsano (CNR-NANO, Italy), Andrea Ferretti (CNR-NANO, Italy)

* [[GW hBN Yambo Virtual 2021 version|How to obtain the quasi-particle band structure of a bulk material: h-BN]]

=== Thursday 15 April ===

'''13:30 to 15: Calculating optical spectra including excitonic effects: a step-by-step guide'''

'''15 to 16:30: Analysis of excitonic spectra, BSE solvers and convergence''' Fulvio Paleari (CNR-ISM, Italy), Myrta Grüning (Queen's University Belfast, Northern Ireland)

* [[BSE hBN Yambo Virtual 2021 version|How to obtain an optical spectrum]]

== Lectures ==

All the lectures will be available in the Yambo-code YouTube [https://www.youtube.com/channel/UCO3LzAqb9W2Qk4EbG_83ATw channel]

=== Thursday 8 April ===

'''10:00 to 10:10 - Welcome & Introduction''' Daniele Varsano

'''10:10 to 10:30 - Material Science and Yambo, what we can calculate''' Andrea Marini

'''10:40 to 11:00 - Introduction to Many Body Perturbation Theory''' Pedro Melo

'''11:25 to 11:45 - The linear response theory''' Claudio Attaccalite

'''12:00 to 12:20 - From equations to simulations: the hard life of a Materials scientist''' Myrta Grüning

=== Friday 9 April ===

'''10:00 to 10:45 - ARPES, quasiparticles and lifetimes: A theory overview''' Andrea Ferretti (CNR-NANO, Italy)

'''10:45 to 11:30 - GW implementation and common approximations''' Daniele Varsano (CNR-NANO, Italy)

'''11:30 to 12:00 - Q&A '''

=== Thursday 15 April ===

'''10:00 to 10:20 - Optical properties & excitons''' Maurizia Palummo

'''10:30 to 10:50 - Derivation of the Bethe-Salpeter Equation and main physical concepts''' Claudio Attaccalite

'''11:20 to 11:40 - BSE implementation and common approximations''' Davide Sangalli

CECAM VIRTUAL 2021

2021-04-09T07:14:39Z

Aferretti: /* Thursday 8 April */

Plan for the CECAM VIRTUAL 2021 school tutorials.
https://www.cecam.org/workshop-details/1081

[[File:Cecam_school_program.png|thumb|160px| Click to enlarge the full program]]

== Setting up Yambo ==

In order to get the yambo code in your machine you have multiple options:

* Yambo Virtual Machine
* Yambo Container
* Install the Yambo source in your computer

=== Setting up the Yambo Virtual Machine ===
The tutorials can be run on a dedicated Virtual Machine (called '''Yambo Quantum Mobile''' and adapted from the [https://quantum-mobile.readthedocs.io/en/latest/ Quantum Mobile] VM).
This is run by installing it as Virtual Machine with the VirtualBox program.
To install the Yambo VM in your computer you need to:
* Download and install Virtualbox software
* Download the Yambo Virtual Machine image
* Install the Yambo Virtual Machine
* Start the Yambo Virtual Machine
* Update and install the Tutorials

To this end follow exactly the step listed here: [[Yambo_Virtual_Machine#Install_the_Yambo_Quantum_Mobile_VM|Install the Yambo Quantum Mobile VM]]

=== Setting up the Yambo Container===

An alternative to get the Yambo code is to install the Yambo container in your machine and this can be done in few steps:

* Install the docker platform (Linux or Mac). Follow the instruction in the docker [https://docs.docker.com/engine/install/ website].
* Pull the Yambo container:

sudo docker pull nicspalla/yambo-gcc_openmp_petsc:latest

sudo it is not necessary if your user is part of the group named docker (suggested on Linux!).

For Linux users:

sudo groupadd docker
sudo usermod -aG docker $USER

For Mac users:

sudo dscl . create /Groups/docker
sudo dseditgroup -o edit -a $USER -t user docker

Log out and log back in so that your group membership is re-evaluated.

* You are done. To run Yambo into the container:

docker run -ti --user $(id -u):$(id -g) \
--mount type=bind,source="$(pwd)",target=/tmpdir \
-e OMP_NUM_THREADS=4 \
nicspalla/yambo-gcc_openmp_petsc:latest \
yambo -F yambo.in -J yambo.out

Otherwise (suggested!), copy and paste the code below in a file, i.e called drun.sh:

#!/bin/bash
docker run -ti --user $(id -u):$(id -g) \
--mount type=bind,source="$(pwd)",target=/tmpdir \
-e OMP_NUM_THREADS=4 \
nicspalla/yambo-gcc_openmp_petsc:latest $@

then give the file execute privileges:

chmod +x drun.sh

Move (or copy) this file in the directory where you want to use Yambo and use it as prefix of your Yambo calculation:

./drun.sh yambo -F yambo.in -J yambo.out

If the yambo container is working correctly you should obtain:

./drun.sh yambo

yambo: cannot access CORE database (SAVE/*db1 and/or SAVE/*wf)

./drun.sh yambo -h

should provide in output the help for yambo usage.

=== Install Yambo ===
If you have some experience with compiling codes, you can [[Download| get the source]] and [[Installation | install]] it. If you never compiled a code, it is better to choose one of the above options as the technical assistance we can offer is limited.

== Tutorials ==

Before starting, [[Get_Tutorial_files_CECAM2021|get the tutorial files]].

=== Thursday 8 April ===
'''14:00 - 14:30 Hands-on setup '''

'''14:30 - 17:00 From the DFT ground state to the complete setup of a Many Body calculation using Yambo''', Davide Sangalli (CNR-ISM, Italy), Pedro Melo (University of Utrecht, the Netherlands)


* [[First steps: walk through from DFT(standalone)|First steps: Initialization and more ]]
* [[Next steps: RPA calculations (standalone)|Next steps: RPA calculations ]]

=== Friday 9 April ===

'''13:30 - 16:30 A complete tour through GW simulation in a complex material (from the blackboard to numerical computation: convergence, algorithms, parallel usage)''' Daniele Varsano (CNR-NANO, Italy), Andrea Ferretti (CNR-NANO, Italy)

* [[GW hBN Yambo Virtual 2021 version|How to obtain the quasi-particle band structure of a bulk material: h-BN]]

=== Thursday 15 April ===

'''13:30 to 15: Calculating optical spectra including excitonic effects: a step-by-step guide'''

'''15 to 16:30: Analysis of excitonic spectra, BSE solvers and convergence''' Fulvio Paleari (CNR-ISM, Italy), Myrta Grüning (Queen's University Belfast, Northern Ireland)

* [[BSE hBN Yambo Virtual 2021 version|How to obtain an optical spectrum]]

== Lectures ==

All the lectures will be available in the Yambo-code YouTube [https://www.youtube.com/channel/UCO3LzAqb9W2Qk4EbG_83ATw channel]

=== Thursday 8 April ===

'''10:00 to 10:10 - Welcome & Introduction''' Daniele Varsano

'''10:10 to 10:30 - Material Science and Yambo, what we can calculate''' Andrea Marini

'''10:40 to 11:00 - Introduction to Many Body Perturbation Theory''' Pedro Melo

'''11:25 to 11:45 - The linear response theory''' Claudio Attaccalite

'''12:00 to 12:20 - From equations to simulations: the hard life of a Materials scientist''' Myrta Grüning

=== Friday 9 April ===

'''10:00 to 10:45 - ARPES, quasiparticles and lifetimes: A theory overview''' Andrea Ferretti (CNR-NANO, Italy)

'''10:45 to 11:30 - GW implementation and common approximations''' Daniele Varsano (CNR-NANO, Italy)

'''11:30 to 12:00 - Q&A '''

=== Thursday 15 April ===

'''10:00 to 10:20 - Optical properties & excitons''' Maurizia Palummo

'''10:30 to 10:50 - Derivation of the Bethe-Salpeter Equation and main physical concepts''' Claudio Attaccalite

'''11:20 to 11:40 - BSE implementation and common approximations''' Davide Sangalli

CECAM VIRTUAL 2021

2021-04-09T07:13:09Z

Aferretti: /* Friday 9 April */

Plan for the CECAM VIRTUAL 2021 school tutorials.
https://www.cecam.org/workshop-details/1081

[[File:Cecam_school_program.png|thumb|160px| Click to enlarge the full program]]

== Setting up Yambo ==

In order to get the yambo code in your machine you have multiple options:

* Yambo Virtual Machine
* Yambo Container
* Install the Yambo source in your computer

=== Setting up the Yambo Virtual Machine ===
The tutorials can be run on a dedicated Virtual Machine (called '''Yambo Quantum Mobile''' and adapted from the [https://quantum-mobile.readthedocs.io/en/latest/ Quantum Mobile] VM).
This is run by installing it as Virtual Machine with the VirtualBox program.
To install the Yambo VM in your computer you need to:
* Download and install Virtualbox software
* Download the Yambo Virtual Machine image
* Install the Yambo Virtual Machine
* Start the Yambo Virtual Machine
* Update and install the Tutorials

To this end follow exactly the step listed here: [[Yambo_Virtual_Machine#Install_the_Yambo_Quantum_Mobile_VM|Install the Yambo Quantum Mobile VM]]

=== Setting up the Yambo Container===

An alternative to get the Yambo code is to install the Yambo container in your machine and this can be done in few steps:

* Install the docker platform (Linux or Mac). Follow the instruction in the docker [https://docs.docker.com/engine/install/ website].
* Pull the Yambo container:

sudo docker pull nicspalla/yambo-gcc_openmp_petsc:latest

sudo it is not necessary if your user is part of the group named docker (suggested on Linux!).

For Linux users:

sudo groupadd docker
sudo usermod -aG docker $USER

For Mac users:

sudo dscl . create /Groups/docker
sudo dseditgroup -o edit -a $USER -t user docker

Log out and log back in so that your group membership is re-evaluated.

* You are done. To run Yambo into the container:

docker run -ti --user $(id -u):$(id -g) \
--mount type=bind,source="$(pwd)",target=/tmpdir \
-e OMP_NUM_THREADS=4 \
nicspalla/yambo-gcc_openmp_petsc:latest \
yambo -F yambo.in -J yambo.out

Otherwise (suggested!), copy and paste the code below in a file, i.e called drun.sh:

#!/bin/bash
docker run -ti --user $(id -u):$(id -g) \
--mount type=bind,source="$(pwd)",target=/tmpdir \
-e OMP_NUM_THREADS=4 \
nicspalla/yambo-gcc_openmp_petsc:latest $@

then give the file execute privileges:

chmod +x drun.sh

Move (or copy) this file in the directory where you want to use Yambo and use it as prefix of your Yambo calculation:

./drun.sh yambo -F yambo.in -J yambo.out

If the yambo container is working correctly you should obtain:

./drun.sh yambo

yambo: cannot access CORE database (SAVE/*db1 and/or SAVE/*wf)

./drun.sh yambo -h

should provide in output the help for yambo usage.

=== Install Yambo ===
If you have some experience with compiling codes, you can [[Download| get the source]] and [[Installation | install]] it. If you never compiled a code, it is better to choose one of the above options as the technical assistance we can offer is limited.

== Tutorials ==

Before starting, [[Get_Tutorial_files_CECAM2021|get the tutorial files]].

=== Thursday 8 April ===
'''14:00 - 14:30 Hands-on setup '''

'''14:30 - 17:00 From the DFT ground state to the complete setup of a Many Body calculation using Yambo''' Davide Sangalli (CNR-ISM, Italy), Pedro Melo (University of Utrecht, the Netherlands)


* [[First steps: walk through from DFT(standalone)|First steps: Initialization and more ]]
* [[Next steps: RPA calculations (standalone)|Next steps: RPA calculations ]]

=== Friday 9 April ===

'''13:30 - 16:30 A complete tour through GW simulation in a complex material (from the blackboard to numerical computation: convergence, algorithms, parallel usage)''' Daniele Varsano (CNR-NANO, Italy), Andrea Ferretti (CNR-NANO, Italy)

* [[GW hBN Yambo Virtual 2021 version|How to obtain the quasi-particle band structure of a bulk material: h-BN]]

=== Thursday 15 April ===

'''13:30 to 15: Calculating optical spectra including excitonic effects: a step-by-step guide'''

'''15 to 16:30: Analysis of excitonic spectra, BSE solvers and convergence''' Fulvio Paleari (CNR-ISM, Italy), Myrta Grüning (Queen's University Belfast, Northern Ireland)

* [[BSE hBN Yambo Virtual 2021 version|How to obtain an optical spectrum]]

== Lectures ==

All the lectures will be available in the Yambo-code YouTube [https://www.youtube.com/channel/UCO3LzAqb9W2Qk4EbG_83ATw channel]

=== Thursday 8 April ===

'''10:00 to 10:10 - Welcome & Introduction''' Daniele Varsano

'''10:10 to 10:30 - Material Science and Yambo, what we can calculate''' Andrea Marini

'''10:40 to 11:00 - Introduction to Many Body Perturbation Theory''' Pedro Melo

'''11:25 to 11:45 - The linear response theory''' Claudio Attaccalite

'''12:00 to 12:20 - From equations to simulations: the hard life of a Materials scientist''' Myrta Grüning

=== Friday 9 April ===

'''10:00 to 10:45 - ARPES, quasiparticles and lifetimes: A theory overview''' Andrea Ferretti (CNR-NANO, Italy)

'''10:45 to 11:30 - GW implementation and common approximations''' Daniele Varsano (CNR-NANO, Italy)

'''11:30 to 12:00 - Q&A '''

=== Thursday 15 April ===

'''10:00 to 10:20 - Optical properties & excitons''' Maurizia Palummo

'''10:30 to 10:50 - Derivation of the Bethe-Salpeter Equation and main physical concepts''' Claudio Attaccalite

'''11:20 to 11:40 - BSE implementation and common approximations''' Davide Sangalli

CECAM VIRTUAL 2021

2021-04-09T07:12:34Z

Aferretti: /* Friday 9 April */

Plan for the CECAM VIRTUAL 2021 school tutorials.
https://www.cecam.org/workshop-details/1081

[[File:Cecam_school_program.png|thumb|160px| Click to enlarge the full program]]

== Setting up Yambo ==

In order to get the yambo code in your machine you have multiple options:

* Yambo Virtual Machine
* Yambo Container
* Install the Yambo source in your computer

=== Setting up the Yambo Virtual Machine ===
The tutorials can be run on a dedicated Virtual Machine (called '''Yambo Quantum Mobile''' and adapted from the [https://quantum-mobile.readthedocs.io/en/latest/ Quantum Mobile] VM).
This is run by installing it as Virtual Machine with the VirtualBox program.
To install the Yambo VM in your computer you need to:
* Download and install Virtualbox software
* Download the Yambo Virtual Machine image
* Install the Yambo Virtual Machine
* Start the Yambo Virtual Machine
* Update and install the Tutorials

To this end follow exactly the step listed here: [[Yambo_Virtual_Machine#Install_the_Yambo_Quantum_Mobile_VM|Install the Yambo Quantum Mobile VM]]

=== Setting up the Yambo Container===

An alternative to get the Yambo code is to install the Yambo container in your machine and this can be done in few steps:

* Install the docker platform (Linux or Mac). Follow the instruction in the docker [https://docs.docker.com/engine/install/ website].
* Pull the Yambo container:

sudo docker pull nicspalla/yambo-gcc_openmp_petsc:latest

sudo it is not necessary if your user is part of the group named docker (suggested on Linux!).

For Linux users:

sudo groupadd docker
sudo usermod -aG docker $USER

For Mac users:

sudo dscl . create /Groups/docker
sudo dseditgroup -o edit -a $USER -t user docker

Log out and log back in so that your group membership is re-evaluated.

* You are done. To run Yambo into the container:

docker run -ti --user $(id -u):$(id -g) \
--mount type=bind,source="$(pwd)",target=/tmpdir \
-e OMP_NUM_THREADS=4 \
nicspalla/yambo-gcc_openmp_petsc:latest \
yambo -F yambo.in -J yambo.out

Otherwise (suggested!), copy and paste the code below in a file, i.e called drun.sh:

#!/bin/bash
docker run -ti --user $(id -u):$(id -g) \
--mount type=bind,source="$(pwd)",target=/tmpdir \
-e OMP_NUM_THREADS=4 \
nicspalla/yambo-gcc_openmp_petsc:latest $@

then give the file execute privileges:

chmod +x drun.sh

Move (or copy) this file in the directory where you want to use Yambo and use it as prefix of your Yambo calculation:

./drun.sh yambo -F yambo.in -J yambo.out

If the yambo container is working correctly you should obtain:

./drun.sh yambo

yambo: cannot access CORE database (SAVE/*db1 and/or SAVE/*wf)

./drun.sh yambo -h

should provide in output the help for yambo usage.

=== Install Yambo ===
If you have some experience with compiling codes, you can [[Download| get the source]] and [[Installation | install]] it. If you never compiled a code, it is better to choose one of the above options as the technical assistance we can offer is limited.

== Tutorials ==

Before starting, [[Get_Tutorial_files_CECAM2021|get the tutorial files]].

=== Thursday 8 April ===
'''14:00 - 14:30 Hands-on setup '''

'''14:30 - 17:00 From the DFT ground state to the complete setup of a Many Body calculation using Yambo''' Davide Sangalli (CNR-ISM, Italy), Pedro Melo (University of Utrecht, the Netherlands)


* [[First steps: walk through from DFT(standalone)|First steps: Initialization and more ]]
* [[Next steps: RPA calculations (standalone)|Next steps: RPA calculations ]]

=== Friday 9 April ===

'''13:30 - 16:30 A complete tour through GW simulation in a complex material (from the blackboard to numerical computation: convergence, algorithms, parallel usage)''' Daniele Varsano (CNR-NANO, Italy), Andrea Ferretti (CNR-NANO, Italy)

* [[GW hBN Yambo Virtual 2021 version|How to obtain the quasi-particle band structure of a bulk material: h-BN]]

=== Thursday 15 April ===

'''13:30 to 15: Calculating optical spectra including excitonic effects: a step-by-step guide'''

'''15 to 16:30: Analysis of excitonic spectra, BSE solvers and convergence''' Fulvio Paleari (CNR-ISM, Italy), Myrta Grüning (Queen's University Belfast, Northern Ireland)

* [[BSE hBN Yambo Virtual 2021 version|How to obtain an optical spectrum]]

== Lectures ==

All the lectures will be available in the Yambo-code YouTube [https://www.youtube.com/channel/UCO3LzAqb9W2Qk4EbG_83ATw channel]

=== Thursday 8 April ===

'''10:00 to 10:10 - Welcome & Introduction''' Daniele Varsano

'''10:10 to 10:30 - Material Science and Yambo, what we can calculate''' Andrea Marini

'''10:40 to 11:00 - Introduction to Many Body Perturbation Theory''' Pedro Melo

'''11:25 to 11:45 - The linear response theory''' Claudio Attaccalite

'''12:00 to 12:20 - From equations to simulations: the hard life of a Materials scientist''' Myrta Grüning

=== Friday 9 April ===

'''10:00 to 10:45 - ARPES, quasiparticles and lifetimes: a theory overview''' Andrea Ferretti (CNR-NANO, Modena)
'''10:45 to 11:30 - GW implementation and common approximations''' Daniele Varsano (CNR-NANO, Modena)
'''11:30 to 12:00 - Q&A '''

=== Thursday 15 April ===

'''10:00 to 10:20 - Optical properties & excitons''' Maurizia Palummo

'''10:30 to 10:50 - Derivation of the Bethe-Salpeter Equation and main physical concepts''' Claudio Attaccalite

'''11:20 to 11:40 - BSE implementation and common approximations''' Davide Sangalli

GW hBN Yambo Virtual 2021 version

2021-04-07T08:26:49Z

Aferretti: /* Converging the sum over states in the correlation self-energy */

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 $3+$4}'
for the valence bands, and
$ grep "^ *7 *8" o-Gbnd* | awk '{print $3+$4}'
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= "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 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-07T08:26:04Z

Aferretti: /* Converging the sum over states in the correlation self-energy */

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 $3+$4}'
for the valence bands, and
$ grep "^ *7 *8" o-Gbnd* | awk '{print $3+$4}'
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= "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 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-07T08:13:02Z

Aferretti: /* Step 5: Eigenvalue only self-consistent evGW0 and evGW */

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 ''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 "^ *7 *8" o-Gbnd* | awk '{print $3+$4}'
for the valence bands, and
$ grep "^ *7 *8" o-Gbnd* | awk '{print $3+$4}'
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= "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 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-07T07:58:50Z

Aferretti: /* Converging the sum over states in the correlation self-energy */

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 ''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 "^ *7 *8" o-Gbnd* | awk '{print $3+$4}'
for the valence bands, and
$ grep "^ *7 *8" o-Gbnd* | awk '{print $3+$4}'
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= "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-07T07:54:52Z

Aferretti: /* 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''.

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 ''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-07T07:54:17Z

Aferretti: /* 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''.

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 data sets unto 40 bands>
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 ''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-07T07:44:15Z

Aferretti: /* Understanding the output */

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 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-07T07:43:35Z

Aferretti: /* Understanding the output */

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 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-07T07:43:06Z

Aferretti: /* Understanding the output */

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

Bash scripts

2021-04-07T07:40:35Z

Aferretti: /* parse_qps.sh (parse QP energies) */

= Hexagonal-BN tutorial =

===generate_inputs_1.sh (GW ecut_X and nbnd_X convergence input fles) ===

#!/bin/bash
#
# NGsBlkXp and BndsRnXp convergence input files
#
bands='10 20 30 40'
blocks='1 2 3 4 5'
#
for i in ${bands} ; do
for j in ${blocks}; do
sed -e "s/1 | 10/1 | $i/g" gw_ppa.in > tmp$i
sed -e "s/NGsBlkXp= 1/ NGsBlkXp= $j/g" tmp$i > gw_ppa_$i'b_'$j'Ry.in'
rm tmp*
done
done

===parse_qps.sh (parse QP energies)===

#! /bin/bash
#
# parse QP energies from output files calculated with BndsRnXp bands
# and put them in files ordered by NGsBlkXp
#
label=10b
fileout=10b.dat
#
file_list=`ls o-${label}_* `
#
echo "# ecut NumG QP1 QP2" > $fileout
for file in $file_list; do
#
ecut=` grep "NGsBlkXp" $file | awk '{print $4}' `
numG=` grep "used" $file |awk '{print $5}'`
qp1=` cat $file | grep "^ *7 *8" | awk '{print $3+$4}' `
qp2=` cat $file | grep "^ *7 *9" | awk '{print $3+$4}' `
#
echo $ecut $numG $qp1 $qp2 >> $fileout
done

===generate_inputs_2.sh (GW Gbnd convergence input files) ===

#!/bin/bash
#
# Gbnd convergence input files
#
bands='10 20 30 40 50 60 70 80'
for i in ${bands}
do
sed -e "s/1 | 40/1 | $i/g" gw_ppa_30b_3Ry.in > gw_ppa_Gbnd$i'.in'
done

===generate_inputs_3.sh (Real axis convergence input files)===
#!/bin/bash
bands='10 50 100 150 200 250'
for i in ${bands}
do
sed -e "s/ETStpsXd= 100/ETStpsXd=$i/g" gw_ff.in > gw_ff$i'.in'
done

= Silicon Tutorial =

=== parse_gap.sh (to parse the gap corrections) ===

#!/bin/bash
if [ ! -f GAMMA/References/$1 ]
then
echo "File not found"
exit
fi
rm -f $2
kpts='GAMMA 2x2x2 4x4x4 6x6x6 8x8x8'
NK=(1 8 64 216 512)
j=0
for i in ${kpts}
do
VBMo=`grep " 1.000" $i/References/$1 | grep " 4.0000" | grep " 0.000" | awk '{print $3}'`
VBM=`grep " 1.000" $i/References/$1 | grep " 4.0000" | grep " 0.000" | awk '{print $4}'`
CBMo=`grep " 2.576" $i/References/$1 | grep " 5.000" | awk '{print $3}'`
CBM=`grep " 2.576" $i/References/$1 | grep " 5.000" | awk '{print $4}'`
case "$1" in
*-01HF*)
echo ${NK[$j]} $VBMo $VBM $CBMo $CBM | awk '{print $1 " " $5-$3 }' >> "$2"
;;
*-Cohsex*)
echo ${NK[$j]} $VBMo $VBM $CBMo $CBM | awk '{print $1 " " $4+$5 }' >> "$2"
;;
esac
j=`expr $j + 1`
done

= Hydrogen chain tutorial =

=== launch_xcrysden.sh ===

#! /bin/sh
#
if [ $# != 1 ] ; then
echo $0 "o- file"
exit 0
fi
twoD=`echo $1 |grep '2d'`
threeD=`echo $1 |grep '3d'`
if test -n "$twoD" ; then
cp $1 file.xsf
xcrysden -s ../Xcrysden_scripts2D.xcrysden
rm -f file.xsf
fi
if test -n "$threeD" ; then
cp $1 file.xsf
xcrysden -s ../Xcrysden_scripts/3D.xcrysden
rm -f file.xsf
fi

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

Bash scripts

2021-04-07T07:37:58Z

Aferretti: /* Silicon Tutorial */

= Hexagonal-BN tutorial =

===generate_inputs_1.sh (GW ecut_X and nbnd_X convergence input fles) ===

#!/bin/bash
#
# NGsBlkXp and BndsRnXp convergence input files
#
bands='10 20 30 40'
blocks='1 2 3 4 5'
#
for i in ${bands} ; do
for j in ${blocks}; do
sed -e "s/1 | 10/1 | $i/g" gw_ppa.in > tmp$i
sed -e "s/NGsBlkXp= 1/ NGsBlkXp= $j/g" tmp$i > gw_ppa_$i'b_'$j'Ry.in'
rm tmp*
done
done

===parse_qps.sh (parse QP energies)===

#!/bin/bash -x
#
# parse QP energies from output files calculated with BndsRnXp bands
# and put them in files ordered by NGsBlkXp
#
label=10b
fileout=10b.dat
#
file_list=`ls o-${label}_* `
#
echo "# ecut NumG QP1 QP2" > $fileout
for file in $file_list; do
#
ecut=` grep "NGsBlkXp" $file | awk '{print $4}' `
numG=` grep "used" $file |awk '{print $5}'`
qp1=` cat $file | grep "^ *7 *8" | awk '{print $3+$4}' `
qp2=` cat $file | grep "^ *7 *9" | awk '{print $3+$4}' `
#
echo $ecut $numG $qp1 $qp2 >> $fileout
done

===generate_inputs_2.sh (GW Gbnd convergence input files) ===

#!/bin/bash
#
# Gbnd convergence input files
#
bands='10 20 30 40 50 60 70 80'
for i in ${bands}
do
sed -e "s/1 | 40/1 | $i/g" gw_ppa_30b_3Ry.in > gw_ppa_Gbnd$i'.in'
done

===generate_inputs_3.sh (Real axis convergence input files)===
#!/bin/bash
bands='10 50 100 150 200 250'
for i in ${bands}
do
sed -e "s/ETStpsXd= 100/ETStpsXd=$i/g" gw_ff.in > gw_ff$i'.in'
done

= Silicon Tutorial =

=== parse_gap.sh (to parse the gap corrections) ===

#!/bin/bash
if [ ! -f GAMMA/References/$1 ]
then
echo "File not found"
exit
fi
rm -f $2
kpts='GAMMA 2x2x2 4x4x4 6x6x6 8x8x8'
NK=(1 8 64 216 512)
j=0
for i in ${kpts}
do
VBMo=`grep " 1.000" $i/References/$1 | grep " 4.0000" | grep " 0.000" | awk '{print $3}'`
VBM=`grep " 1.000" $i/References/$1 | grep " 4.0000" | grep " 0.000" | awk '{print $4}'`
CBMo=`grep " 2.576" $i/References/$1 | grep " 5.000" | awk '{print $3}'`
CBM=`grep " 2.576" $i/References/$1 | grep " 5.000" | awk '{print $4}'`
case "$1" in
*-01HF*)
echo ${NK[$j]} $VBMo $VBM $CBMo $CBM | awk '{print $1 " " $5-$3 }' >> "$2"
;;
*-Cohsex*)
echo ${NK[$j]} $VBMo $VBM $CBMo $CBM | awk '{print $1 " " $4+$5 }' >> "$2"
;;
esac
j=`expr $j + 1`
done

= Hydrogen chain tutorial =

=== launch_xcrysden.sh ===

#! /bin/sh
#
if [ $# != 1 ] ; then
echo $0 "o- file"
exit 0
fi
twoD=`echo $1 |grep '2d'`
threeD=`echo $1 |grep '3d'`
if test -n "$twoD" ; then
cp $1 file.xsf
xcrysden -s ../Xcrysden_scripts2D.xcrysden
rm -f file.xsf
fi
if test -n "$threeD" ; then
cp $1 file.xsf
xcrysden -s ../Xcrysden_scripts/3D.xcrysden
rm -f file.xsf
fi

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

Bash scripts

2021-04-07T07:37:21Z

Aferretti: /* Hexagonal-BN tutorial */

= Hexagonal-BN tutorial =

===generate_inputs_1.sh (GW ecut_X and nbnd_X convergence input fles) ===

#!/bin/bash
#
# NGsBlkXp and BndsRnXp convergence input files
#
bands='10 20 30 40'
blocks='1 2 3 4 5'
#
for i in ${bands} ; do
for j in ${blocks}; do
sed -e "s/1 | 10/1 | $i/g" gw_ppa.in > tmp$i
sed -e "s/NGsBlkXp= 1/ NGsBlkXp= $j/g" tmp$i > gw_ppa_$i'b_'$j'Ry.in'
rm tmp*
done
done

===parse_qps.sh (parse QP energies)===

#!/bin/bash -x
#
# parse QP energies from output files calculated with BndsRnXp bands
# and put them in files ordered by NGsBlkXp
#
label=10b
fileout=10b.dat
#
file_list=`ls o-${label}_* `
#
echo "# ecut NumG QP1 QP2" > $fileout
for file in $file_list; do
#
ecut=` grep "NGsBlkXp" $file | awk '{print $4}' `
numG=` grep "used" $file |awk '{print $5}'`
qp1=` cat $file | grep "^ *7 *8" | awk '{print $3+$4}' `
qp2=` cat $file | grep "^ *7 *9" | awk '{print $3+$4}' `
#
echo $ecut $numG $qp1 $qp2 >> $fileout
done

===generate_inputs_2.sh (GW Gbnd convergence input files) ===

#!/bin/bash
#
# Gbnd convergence input files
#
bands='10 20 30 40 50 60 70 80'
for i in ${bands}
do
sed -e "s/1 | 40/1 | $i/g" gw_ppa_30b_3Ry.in > gw_ppa_Gbnd$i'.in'
done

===generate_inputs_3.sh (Real axis convergence input files)===
#!/bin/bash
bands='10 50 100 150 200 250'
for i in ${bands}
do
sed -e "s/ETStpsXd= 100/ETStpsXd=$i/g" gw_ff.in > gw_ff$i'.in'
done

= Silicon Tutorial =

=== parse_gap.sh (shell script to parse the gap corrections) ===

#!/bin/bash
if [ ! -f GAMMA/References/$1 ]
then
echo "File not found"
exit
fi
rm -f $2
kpts='GAMMA 2x2x2 4x4x4 6x6x6 8x8x8'
NK=(1 8 64 216 512)
j=0
for i in ${kpts}
do
VBMo=`grep " 1.000" $i/References/$1 | grep " 4.0000" | grep " 0.000" | awk '{print $3}'`
VBM=`grep " 1.000" $i/References/$1 | grep " 4.0000" | grep " 0.000" | awk '{print $4}'`
CBMo=`grep " 2.576" $i/References/$1 | grep " 5.000" | awk '{print $3}'`
CBM=`grep " 2.576" $i/References/$1 | grep " 5.000" | awk '{print $4}'`
case "$1" in
*-01HF*)
echo ${NK[$j]} $VBMo $VBM $CBMo $CBM | awk '{print $1 " " $5-$3 }' >> "$2"
;;
*-Cohsex*)
echo ${NK[$j]} $VBMo $VBM $CBMo $CBM | awk '{print $1 " " $4+$5 }' >> "$2"
;;
esac
j=`expr $j + 1`
done

= Hydrogen chain tutorial =

=== launch_xcrysden.sh ===

#! /bin/sh
#
if [ $# != 1 ] ; then
echo $0 "o- file"
exit 0
fi
twoD=`echo $1 |grep '2d'`
threeD=`echo $1 |grep '3d'`
if test -n "$twoD" ; then
cp $1 file.xsf
xcrysden -s ../Xcrysden_scripts2D.xcrysden
rm -f file.xsf
fi
if test -n "$threeD" ; then
cp $1 file.xsf
xcrysden -s ../Xcrysden_scripts/3D.xcrysden
rm -f file.xsf
fi

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

Bash scripts

2021-04-07T07:33:30Z

Aferretti: /* Hexagonal-BN tutorial */

= Hexagonal-BN tutorial =

===generate_inputs_1.sh===

#!/bin/bash
#
# NGsBlkXp and BndsRnXp convergence input files
#
bands='10 20 30 40'
blocks='1 2 3 4 5'
#
for i in ${bands} ; do
for j in ${blocks}; do
sed -e "s/1 | 10/1 | $i/g" gw_ppa.in > tmp$i
sed -e "s/NGsBlkXp= 1/ NGsBlkXp= $j/g" tmp$i > gw_ppa_$i'b_'$j'Ry.in'
rm tmp*
done
done

===parse_qps.sh ===

#!/bin/bash -x
#
# parse QP energies from output files calculated with BndsRnXp bands and put them in files ordered by NGsBlkXp)
#
label=10b
fileout=10b.dat
#
file_list=`ls o-${label}_* `
#
echo "# ecut NumG QP1 QP2" > $fileout
for file in $file_list; do
#
ecut=` grep "NGsBlkXp" $file | awk '{print $4}' `
numG=` grep "used" $file |awk '{print $5}'`
qp1=` cat $file | grep "^ *7 *8" | awk '{print $3+$4}' `
qp2=` cat $file | grep "^ *7 *9" | awk '{print $3+$4}' `
#
echo $ecut $numG $qp1 $qp2 >> $fileout
done

===generate_inputs_2.sh===

#!/bin/bash
#
# Gbnd convergence input files
#
bands='10 20 30 40 50 60 70 80'
for i in ${bands}
do
sed -e "s/1 | 40/1 | $i/g" gw_ppa_30b_3Ry.in > gw_ppa_Gbnd$i'.in'
done

===generate_inputs_3.sh (Real axis convergence input files)===
#!/bin/bash
bands='10 50 100 150 200 250'
for i in ${bands}
do
sed -e "s/ETStpsXd= 100/ETStpsXd=$i/g" gw_ff.in > gw_ff$i'.in'
done

= Silicon Tutorial =

=== parse_gap.sh (shell script to parse the gap corrections) ===

#!/bin/bash
if [ ! -f GAMMA/References/$1 ]
then
echo "File not found"
exit
fi
rm -f $2
kpts='GAMMA 2x2x2 4x4x4 6x6x6 8x8x8'
NK=(1 8 64 216 512)
j=0
for i in ${kpts}
do
VBMo=`grep " 1.000" $i/References/$1 | grep " 4.0000" | grep " 0.000" | awk '{print $3}'`
VBM=`grep " 1.000" $i/References/$1 | grep " 4.0000" | grep " 0.000" | awk '{print $4}'`
CBMo=`grep " 2.576" $i/References/$1 | grep " 5.000" | awk '{print $3}'`
CBM=`grep " 2.576" $i/References/$1 | grep " 5.000" | awk '{print $4}'`
case "$1" in
*-01HF*)
echo ${NK[$j]} $VBMo $VBM $CBMo $CBM | awk '{print $1 " " $5-$3 }' >> "$2"
;;
*-Cohsex*)
echo ${NK[$j]} $VBMo $VBM $CBMo $CBM | awk '{print $1 " " $4+$5 }' >> "$2"
;;
esac
j=`expr $j + 1`
done

= Hydrogen chain tutorial =

=== launch_xcrysden.sh ===

#! /bin/sh
#
if [ $# != 1 ] ; then
echo $0 "o- file"
exit 0
fi
twoD=`echo $1 |grep '2d'`
threeD=`echo $1 |grep '3d'`
if test -n "$twoD" ; then
cp $1 file.xsf
xcrysden -s ../Xcrysden_scripts2D.xcrysden
rm -f file.xsf
fi
if test -n "$threeD" ; then
cp $1 file.xsf
xcrysden -s ../Xcrysden_scripts/3D.xcrysden
rm -f file.xsf
fi

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

GW hBN Yambo Virtual 2021 version

2021-04-07T07:13:10Z

Aferretti: /* 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''.

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: 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-06T17:50:35Z

Aferretti: /* Understanding the output */

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

Yambo Virtual Machine

2021-04-06T17:29:27Z

Aferretti: /* Updating the Yambo tutorial files */

'''VirtualBox''' is a software to run a ('virtualized') operating system as a client of a host operating system. The host operating system is what you boot your computer into. The client operating system (called a 'virtual machine', or a 'software appliance') has been prepared by us specifically for this School.
The '''Yambo Quantum Mobile''' VM is entirely based on the '''Quantum Mobile''' developed by the [https://people.epfl.ch/nicola.marzari/?lang=en EPFL group of Nicola Marzari] and supported by the [http://nccr-marvel.ch/ MARVEL NCCR] and the [http://max-centre.eu/ MaX H2020 Centre of Excellence].

== Download and Install VirtualBox Software ==

Go to [https://www.virtualbox.org Virtualbox Home] and click on the big button to download the latest Version, select your host system on the next page and start the download of the package.

* For Windows users the download provides an `.exe` file that can be started by double-clicking on its icon
* For Mac users the download provides a disk image `.dmg` file that also can be started by double-clicking
* For Linux users more choices are available, depending on distribution. There is also the option to use a repository for Debian-based Linux distributions.

This should be all. If something goes wrong, try to reboot your host and try to re-install on the freshly booted machine. (In the past, it was often found (at least on MacOSX) that upgrades of VirtualBox do not work when having run VirtualBox clients before.)

== Download the Yambo Quantum Mobile image==

Download the virtual machine image clicking on the following link

[[File:yambo_VM.png|link=http://www.yambo-code.org/educational/VirtualMachine/YAMBO_Quantum_Mobile.ova]]

Note that this image has a large size of 4 GBytes. Don't attempt to download it from a poor wireless connection. Having downloaded the VM Image, it needs to be '''imported''' into VirtualBox.

== Install the Yambo Quantum Mobile VM ==

* Find where VirtualBox is installed on your PC. To find it open a terminal and
> which virtualbox
/usr/bin/virtualbox
> /usr/bin/virtualbo
* Goto Menu Item "File", then "Import Appliance" (File->Import Appliance)
* In the topmost field, type in the name of the downloaded Appliance File or search for it via the finder that opens when clicking the button to the right.

[[File:QM1.png|400px|Screenshot before Import]]

[[File:QM2.png|400px|Screenshot Image selection]]

[[File:QM3.png|400px|Screenshot during Import]]

* Proceed until the virtual machine has been successfully created.

== Starting the Virtual Machine ==

After import, the VirtualBox window looks roughly so:

[[File:QM4.png|400px|irtualBox Window after Import]]

* Double-Click on the Virtual Machine Icon of the VirtualBox program.
* Within a few seconds, the window of the virtual machine will open and eventually you will see the graphical window of a running VM, into which you are automatically logged in as user `max`.

[[File:QM5.png|400px|irtualBox Window after Import]]

== Updating the Yambo tutorial files ==

Now, that the Yambo VM is running, open a terminal window (black icon with '>' on the left) and

* read the ''RELEASE_NOTES.txt'' that are on your Desktop.
* update the Yambo tutorial files

> cd YAMBO_TUTORIALS
> git pull
> ./setup.pl -install

Now you are ready to do your tutorials.

== Reducing the size of the VM image ==
Open a terminal in the VM and type

sudo dd if=/dev/zero | pv | sudo dd of=/bigemptyfile bs=4096k
sudo rm -rf /bigemptyfile

CECAM VIRTUAL 2021

2021-04-06T16:55:26Z

Aferretti: /* Setting up the Yambo Container */

Plan for the CECAM VIRTUAL 2021 school tutorials.
https://www.cecam.org/workshop-details/1081

[[File:Cecam_school_program.png|thumb|160px| Click to enlarge the full program]]

== Setting up Yambo ==

In order to get the yambo code in your machine you have multiple options:

* Yambo Virtual Machine
* Yambo Container
* Install the Yambo source in your computer

=== Setting up the Yambo Virtual Machine ===
The tutorials can be run on a dedicated Virtual Machine (called '''Yambo Quantum Mobile''' and adapted from the [https://quantum-mobile.readthedocs.io/en/latest/ Quantum Mobile] VM).
This is run by installing it as Virtual Machine with the VirtualBox program.
To install the Yambo VM in your computer you need to:
* Download and install Virtualbox software
* Download the Yambo Virtual Machine image
* Install the Yambo Virtual Machine
* Start the Yambo Virtual Machine
* Update and install the Tutorials

To this end follow exactly the step listed here: [[Yambo_Virtual_Machine#Install_the_Yambo_Quantum_Mobile_VM|Install the Yambo Quantum Mobile VM]]

=== Setting up the Yambo Container===

An alternative to get the Yambo code is to install the Yambo container in your machine and this can be done in few steps:

* Install the docker platform (Linux or Mac). Follow the instruction in the docker [https://docs.docker.com/engine/install/ website].
* Pull the Yambo container:

sudo docker pull nicspalla/yambo-gcc_openmp_mkl:latest

sudo it is not necessary if your user is part of the group named docker (suggested on Linux!).

For Linux users:

sudo groupadd docker
sudo usermod -aG docker $USER

For Mac users:

sudo dscl . create /Groups/docker
sudo dseditgroup -o edit -a $USER -t user docker

Log out and log back in so that your group membership is re-evaluated.

* You are done. To run Yambo into the container:

docker run -ti --user $(id -u):$(id -g) \
--mount type=bind,source="$(pwd)",target=/tmpdir \
-e OMP_NUM_THREADS=4 \
nicspalla/yambo-gcc_openmp_mkl:latest \
yambo -F yambo.in -J yambo.out

Otherwise (suggested!), copy and paste the code below in a file, i.e called drun.sh:

#!/bin/bash
docker run -ti --user $(id -u):$(id -g) \
--mount type=bind,source="$(pwd)",target=/tmpdir \
-e OMP_NUM_THREADS=4 \
nicspalla/yambo-gcc_openmp_mkl:latest $@

then give the file execute privileges:

chmod +x drun.sh

Move (or copy) this file in the directory where you want to use Yambo and use it as prefix of your Yambo calculation:

./drun.sh yambo -F yambo.in -J yambo.out

If the yambo container is working correctly you should obtain:

./drun.sh yambo

yambo: cannot access CORE database (SAVE/*db1 and/or SAVE/*wf)

./drun.sh yambo -h

should provide in output the help for yambo usage.

=== Install Yambo ===
If you have some experience with compiling codes, you can [[Download| get the source]] and [[Installation | install]] it. If you never compiled a code, it is better to choose one of the above options as the technical assistance we can offer is limited.

== Tutorials ==

Before starting, [[Get_Tutorial_files_CECAM2021|get the tutorial files]].

=== Thursday 8 April ===
'''14:30 - 17:00 From the DFT ground state to the complete setup of a Many Body calculation using Yambo''' Davide Sangalli (CNR-ISM, Italy), Pedro Melo (University of Liege, Belgium)


* [[First steps: walk through from DFT(standalone)|First steps: Initialization and more ]]
* [[Next steps: RPA calculations (standalone)|Next steps: RPA calculations ]]

=== Friday 9 April ===

'''13:30 - 16:30 A complete tour through GW simulation in a complex material (from the blackboard to numerical computation: convergence, algorithms, parallel usage)''' Daniele Varsano (CNR-NANO, Italy), Andrea Ferretti (CNR-NANO, Italy)

* [[GW hBN Yambo Virtual 2021 version|How to obtain the quasi-particle band structure of a bulk material: h-BN]]

=== Thursday 15 April ===

'''13:30 - 15:00 A guided tour through calculations of spectroscopic properties using the BSE approach''' Fulvio Paleari (CNR-ISM, Italy), Myrta Grüning (Queen's University Belfast, Northern Ireland)

* [[BSE hBN Yambo Virtual 2021 version|How to obtain an optical spectrum]]

== Lectures ==

=== Thursday 8 April ===

'''10:00 to 10:10 - Welcome & Introduction''' Andrea Marini

'''10:10 to 10:30 - Material Science and Yambo, what we can calculate''' Andrea Marini

'''10:40 to 11:00 - Introduction to Many Body Perturbation Theory''' Pedro Melo

'''11:25 to 11:45 - The linear response theory''' Claudio Attaccalite

'''12:00 to 12:20 - From equations to simulations: the hard life of a Materials scientist''' Myrta Grüning

=== Friday 9 April ===

'''10:00 to 10:20 - from ARPES to quasiparticles''' Andrea Ferretti

'''10:30 to 10:50 - The Quasi Particle concept and the GW method''' Andrea Ferretti & Daniele Varsano

'''11:20 to 11:40 - GW implementation and common approximations''' Daniele Varsano

=== Thursday 15 April ===

'''10:00 to 10:20 - Optical properties & excitons''' Maurizia Palummo

'''10:30 to 10:50 - Derivation of the Bethe-Salpeter Equation and main physical concepts''' Claudio Attaccalite

'''11:20 to 11:40 - BSE implementation and common approximations''' Davide Sangalli

=== Friday 16 April ===

CECAM VIRTUAL 2021

2021-04-06T16:46:58Z

Aferretti: /* Setting up Yambo */

Plan for the CECAM VIRTUAL 2021 school tutorials.
https://www.cecam.org/workshop-details/1081

[[File:Cecam_school_program.png|thumb|160px| Click to enlarge the full program]]

== Setting up Yambo ==

In order to get the yambo code in your machine you have multiple options:

* Yambo Virtual Machine
* Yambo Container
* Install the Yambo source in your computer

=== Setting up the Yambo Virtual Machine ===
The tutorials can be run on a dedicated Virtual Machine (called '''Yambo Quantum Mobile''' and adapted from the [https://quantum-mobile.readthedocs.io/en/latest/ Quantum Mobile] VM).
This is run by installing it as Virtual Machine with the VirtualBox program.
To install the Yambo VM in your computer you need to:
* Download and install Virtualbox software
* Download the Yambo Virtual Machine image
* Install the Yambo Virtual Machine
* Start the Yambo Virtual Machine
* Update and install the Tutorials

To this end follow exactly the step listed here: [[Yambo_Virtual_Machine#Install_the_Yambo_Quantum_Mobile_VM|Install the Yambo Quantum Mobile VM]]

=== Setting up the Yambo Container===

An alternative to get the Yambo code is to install the Yambo container in your machine and this can be done in few steps:

* Install the docker platform (Linux or Mac). Follow the instruction in the docker [https://docs.docker.com/engine/install/ website].
* Pull the Yambo container:

>sudo docker pull nicspalla/yambo-gcc_openmp_mkl:latest

sudo it is not necessary if your user is part of the group named docker (suggested on Linux!).

For Linux users:

sudo groupadd docker
sudo usermod -aG docker $USER

For Mac users:

sudo dscl . create /Groups/docker
sudo dseditgroup -o edit -a $USER -t user docker

Log out and log back in so that your group membership is re-evaluated.

* You are done. To run Yambo into the container:

docker run -ti --user $(id -u):$(id -g) \
--mount type=bind,source="$(pwd)",target=/tmpdir \
-e OMP_NUM_THREADS=4 \
nicspalla/yambo-gcc_openmp_mkl:latest \
yambo -F yambo.in -J yambo.out

Otherwise (suggested!), copy and paste the code below in a file, i.e called drun.sh:

#!/bin/bash
docker run -ti --user $(id -u):$(id -g) \
--mount type=bind,source="$(pwd)",target=/tmpdir \
-e OMP_NUM_THREADS=4 \
nicspalla/yambo-gcc_openmp_mkl:latest $@

then give the file execute privileges:

chmod +x drun.sh

Move (or copy) this file in the directory where you want to use Yambo and use it as prefix of your Yambo calculation:

./drun.sh yambo -F yambo.in -J yambo.out

If the yambo container is working correctly you should obtain:

./drun.sh yambo

yambo: cannot access CORE database (SAVE/*db1 and/or SAVE/*wf)

>./drun.sh yambo -h

should provide in output the help for yambo usage.

=== Install Yambo ===
If you have some experience with compiling codes, you can [[Download| get the source]] and [[Installation | install]] it. If you never compiled a code, it is better to choose one of the above options as the technical assistance we can offer is limited.

== Tutorials ==

Before starting, [[Get_Tutorial_files_CECAM2021|get the tutorial files]].

=== Thursday 8 April ===
'''14:30 - 17:00 From the DFT ground state to the complete setup of a Many Body calculation using Yambo''' Davide Sangalli (CNR-ISM, Italy), Pedro Melo (University of Liege, Belgium)


* [[First steps: walk through from DFT(standalone)|First steps: Initialization and more ]]
* [[Next steps: RPA calculations (standalone)|Next steps: RPA calculations ]]

=== Friday 9 April ===

'''13:30 - 16:30 A complete tour through GW simulation in a complex material (from the blackboard to numerical computation: convergence, algorithms, parallel usage)''' Daniele Varsano (CNR-NANO, Italy), Andrea Ferretti (CNR-NANO, Italy)

* [[GW hBN Yambo Virtual 2021 version|How to obtain the quasi-particle band structure of a bulk material: h-BN]]

=== Thursday 15 April ===

'''13:30 - 15:00 A guided tour through calculations of spectroscopic properties using the BSE approach''' Fulvio Paleari (CNR-ISM, Italy), Myrta Grüning (Queen's University Belfast, Northern Ireland)

* [[BSE hBN Yambo Virtual 2021 version|How to obtain an optical spectrum]]

== Lectures ==

=== Thursday 8 April ===

'''10:00 to 10:10 - Welcome & Introduction''' Andrea Marini

'''10:10 to 10:30 - Material Science and Yambo, what we can calculate''' Andrea Marini

'''10:40 to 11:00 - Introduction to Many Body Perturbation Theory''' Pedro Melo

'''11:25 to 11:45 - The linear response theory''' Claudio Attaccalite

'''12:00 to 12:20 - From equations to simulations: the hard life of a Materials scientist''' Myrta Grüning

=== Friday 9 April ===

'''10:00 to 10:20 - from ARPES to quasiparticles''' Andrea Ferretti

'''10:30 to 10:50 - The Quasi Particle concept and the GW method''' Andrea Ferretti & Daniele Varsano

'''11:20 to 11:40 - GW implementation and common approximations''' Daniele Varsano

=== Thursday 15 April ===

'''10:00 to 10:20 - Optical properties & excitons''' Maurizia Palummo

'''10:30 to 10:50 - Derivation of the Bethe-Salpeter Equation and main physical concepts''' Claudio Attaccalite

'''11:20 to 11:40 - BSE implementation and common approximations''' Davide Sangalli

=== Friday 16 April ===

Yambo Virtual Machine

2021-04-06T16:42:34Z

Aferretti:

'''VirtualBox''' is a software to run a ('virtualized') operating system as a client of a host operating system. The host operating system is what you boot your computer into. The client operating system (called a 'virtual machine', or a 'software appliance') has been prepared by us specifically for this School.
The '''Yambo Quantum Mobile''' VM is entirely based on the '''Quantum Mobile''' developed by the [https://people.epfl.ch/nicola.marzari/?lang=en EPFL group of Nicola Marzari] and supported by the [http://nccr-marvel.ch/ MARVEL NCCR] and the [http://max-centre.eu/ MaX H2020 Centre of Excellence].

== Download and Install VirtualBox Software ==

Go to [https://www.virtualbox.org Virtualbox Home] and click on the big button to download the latest Version, select your host system on the next page and start the download of the package.

* For Windows users the download provides an `.exe` file that can be started by double-clicking on its icon
* For Mac users the download provides a disk image `.dmg` file that also can be started by double-clicking
* For Linux users more choices are available, depending on distribution. There is also the option to use a repository for Debian-based Linux distributions.

This should be all. If something goes wrong, try to reboot your host and try to re-install on the freshly booted machine. (In the past, it was often found (at least on MacOSX) that upgrades of VirtualBox do not work when having run VirtualBox clients before.)

== Download the Yambo Quantum Mobile image==

Download the virtual machine image clicking on the following link

[[File:yambo_VM.png|link=http://www.yambo-code.org/educational/VirtualMachine/YAMBO_Quantum_Mobile.ova]]

Note that this image has a large size of 4 GBytes. Don't attempt to download it from a poor wireless connection. Having downloaded the VM Image, it needs to be '''imported''' into VirtualBox.

== Install the Yambo Quantum Mobile VM ==

* Find where VirtualBox is installed on your PC. To find it open a terminal and
> which virtualbox
/usr/bin/virtualbox
> /usr/bin/virtualbo
* Goto Menu Item "File", then "Import Appliance" (File->Import Appliance)
* In the topmost field, type in the name of the downloaded Appliance File or search for it via the finder that opens when clicking the button to the right.

[[File:QM1.png|400px|Screenshot before Import]]

[[File:QM2.png|400px|Screenshot Image selection]]

[[File:QM3.png|400px|Screenshot during Import]]

* Proceed until the virtual machine has been successfully created.

== Starting the Virtual Machine ==

After import, the VirtualBox window looks roughly so:

[[File:QM4.png|400px|irtualBox Window after Import]]

* Double-Click on the Virtual Machine Icon of the VirtualBox program.
* Within a few seconds, the window of the virtual machine will open and eventually you will see the graphical window of a running VM, into which you are automatically logged in as user `max`.

[[File:QM5.png|400px|irtualBox Window after Import]]

== Updating the Yambo tutorial files ==

Now that the Yambo VM is running open a terminal window (black icon with '>' on the left) and

* read the ''RELEASE_NOTES.txt'' that are on your Desktop.
* update the Yambo tutorial files

> cd YAMBO_TUTORIALS
> git pull
> ./setup.pl -install

Now you are ready to do your tutorials.

== Reducing the size of the VM image ==
Open a terminal in the VM and type

sudo dd if=/dev/zero | pv | sudo dd of=/bigemptyfile bs=4096k
sudo rm -rf /bigemptyfile

Yambo Virtual Machine

2021-04-06T16:33:29Z

Aferretti:

VirtualBox is a software to run a ('virtualized') operating system as a client of a host operating system. The host operating system is what you boot your computer into. The client operating system (called a 'virtual machine', or a 'software appliance') has been prepared by us specifically for this School.
The Yambo Quantum Mobile VM is entirely based on the '''Quantum Mobile''' developed by the [https://people.epfl.ch/nicola.marzari/?lang=en EPFL group of Nicola Marzari] and supported by the [http://nccr-marvel.ch/ MARVEL NCCR] and the [http://max-centre.eu/ MaX H2020 Centre of Excellence].

== Download and Install VirtualBox Software ==

Go to [https://www.virtualbox.org Virtualbox Home] and click on the big button to download the latest Version, select your host system on the next page and start the download of the package.

* For Windows users the download provides an `.exe` file that can be started by double-clicking on its icon
* For Mac users the download provides a disk image `.dmg` file that also can be started by double-clicking
* For Linux users more choices are available, depending on distribution. There is also the option to use a repository for Debian-based Linux distributions.

This should be all. If something goes wrong, try to reboot your host and try to re-install on the freshly booted machine. (In the past, it was often found (at least on MacOSX) that upgrades of VirtualBox do not work when having run VirtualBox clients before.)

== Download the Yambo Quantum Mobile image==

Download the virtual machine image clicking on the following link

[[File:yambo_VM.png|link=http://www.yambo-code.org/educational/VirtualMachine/YAMBO_Quantum_Mobile.ova]]

Note that this image has a large size of 4 GBytes. Don't attempt to download it from a poor wireless connection. Having downloaded the VM Image, it needs to be '''imported''' into VirtualBox.

== Install the Yambo Quantum Mobile VM ==

* Find where VirtualBox is installed on your PC. To find it open a terminal and
> which virtualbox
/usr/bin/virtualbox
> /usr/bin/virtualbo
* Goto Menu Item "File", then "Import Appliance" (File->Import Appliance)
* In the topmost field, type in the name of the downloaded Appliance File or search for it via the finder that opens when clicking the button to the right.

[[File:QM1.png|400px|Screenshot before Import]]

[[File:QM2.png|400px|Screenshot Image selection]]

[[File:QM3.png|400px|Screenshot during Import]]

* Proceed until the virtual machine has been successfully created.

== Starting the Virtual Machine ==

After import, the VirtualBox window looks roughly so:

[[File:QM4.png|400px|irtualBox Window after Import]]

* Double-Click on the Virtual Machine Icon of the VirtualBox program.
* Within a few seconds, the window of the virtual machine will open and eventually you will see the graphical window of a running VM, into which you are automatically logged in as user `max`.

[[File:QM5.png|400px|irtualBox Window after Import]]

== Updating the Yambo tutorial files ==

Now that the Yambo VM is running open a terminal window (black icon with '>' on the left) and

* read the ''RELEASE_NOTES.txt'' that are on your Desktop.
* update the Yambo tutorial files

> cd YAMBO_TUTORIALS
> git pull
> ./setup.pl -install

Now you are ready to do your tutorials.

== Reducing the size of the VM image ==
Open a terminal in the VM and type

sudo dd if=/dev/zero | pv | sudo dd of=/bigemptyfile bs=4096k
sudo rm -rf /bigemptyfile

Yambo Virtual Machine

2021-04-06T16:32:59Z

Aferretti:

VirtualBox is a software to run a ('virtualized') operating system as a client of a host operating system. The host operating system is what you boot your computer into. The client operating system (called a 'virtual machine', or a 'software appliance') has been prepared by us specifically for this School.
The Yambo Quantum Mobile VM is entirely based on the '''Quantum Mobile''' developed by the [https://people.epfl.ch/nicola.marzari/?lang=en EPFL group of Nicola Marzari] and supported by the [http://nccr-marvel.ch/ MARVEL NCCR] and the [http://max-centre.eu/ MaX H2020 Centre of Excellence].

== Download and Install VirtualBox Software ==

Go to [https://www.virtualbox.org Virtualbox Home] and click on the big button to download the latest Version, select your host system on the next page and start the download of the package.

* For Windows users the download provides an `.exe` file that can be started by double-clicking on its icon
* For Mac users the download provides a disk image `.dmg` file that also can be started by double-clicking
* For Linux users more choices are available, depending on distribution. There is also the option to use a repository for Debian-based Linux distributions.

This should be all. If something goes wrong, try to reboot your host and try to re-install on the freshly booted machine. (In the past, it was often found (at least on MacOSX) that upgrades of VirtualBox do not work when having run VirtualBox clients before.)

== Download the Yambo Quantum Mobile ==

Download the virtual machine image clicking on the following link

[[File:yambo_VM.png|link=http://www.yambo-code.org/educational/VirtualMachine/YAMBO_Quantum_Mobile.ova]]

Note that this image has a large size of 4 GBytes. Don't attempt to download it from a poor wireless connection. Having downloaded the VM Image, it needs to be '''imported''' into VirtualBox.

== Install the Yambo Quantum Mobile VM ==

* Find where VirtualBox is installed on your PC. To find it open a terminal and
> which virtualbox
/usr/bin/virtualbox
> /usr/bin/virtualbo
* Goto Menu Item "File", then "Import Appliance" (File->Import Appliance)
* In the topmost field, type in the name of the downloaded Appliance File or search for it via the finder that opens when clicking the button to the right.

[[File:QM1.png|400px|Screenshot before Import]]

[[File:QM2.png|400px|Screenshot Image selection]]

[[File:QM3.png|400px|Screenshot during Import]]

* Proceed until the virtual machine has been successfully created.

== Starting the Virtual Machine ==

After import, the VirtualBox window looks roughly so:

[[File:QM4.png|400px|irtualBox Window after Import]]

* Double-Click on the Virtual Machine Icon of the VirtualBox program.
* Within a few seconds, the window of the virtual machine will open and eventually you will see the graphical window of a running VM, into which you are automatically logged in as user `max`.

[[File:QM5.png|400px|irtualBox Window after Import]]

== Updating the Yambo tutorial files ==

Now that the Yambo VM is running open a terminal window (black icon with '>' on the left) and

* read the ''RELEASE_NOTES.txt'' that are on your Desktop.
* update the Yambo tutorial files

> cd YAMBO_TUTORIALS
> git pull
> ./setup.pl -install

Now you are ready to do your tutorials.

== Reducing the size of the VM image ==
Open a terminal in the VM and type

sudo dd if=/dev/zero | pv | sudo dd of=/bigemptyfile bs=4096k
sudo rm -rf /bigemptyfile

CECAM VIRTUAL 2021

2021-04-06T16:29:13Z

Aferretti:

Plan for the CECAM VIRTUAL 2021 school tutorials.
https://www.cecam.org/workshop-details/1081

[[File:Cecam_school_program.png|thumb|160px| Click to enlarge the full program]]

== Setting up Yambo ==

In order to get the yambo code in your machine you have multiple options:

* Yambo Virtual Machine
* Yambo Container
* Install the Yambo source in your computer

=== Setting up the Yambo Virtual Machine ===
The tutorials can be run on a dedicated Virtual Machine (adapted from the [https://quantum-mobile.readthedocs.io/en/latest/Quantum Mobile] VM).
This is run by installing it as Virtual Machine with the VirtualBox program.
To install the Yambo Virtual Machine in your computer you need to:
* Download and install Virtualbox software
* Download the Yambo Virtual Machine image
* Install the Yambo Virtual Machine
* Start the Yambo Virtual Machine
* Update and install the Tutorials

To this end follow exactly the step listed here: [[Yambo_Virtual_Machine#Install_the_Yambo_Quantum_Machine|The Yambo Virtual Machine]]

=== Setting up the Yambo Container===

An alternative to get the Yambo code is to install the Yambo container in your machine and this can be done in few steps:

* Install the docker platform (Linux or Mac). Follow the instruction in the docker [https://docs.docker.com/engine/install/ website].
* Pull the Yambo container:

>sudo docker pull nicspalla/yambo-gcc_openmp_mkl:latest

sudo it is not necessary if your user is part of the group named docker (suggested on Linux!).

For Linux users:

sudo groupadd docker
sudo usermod -aG docker $USER

For Mac users:

sudo dscl . create /Groups/docker
sudo dseditgroup -o edit -a $USER -t user docker

Log out and log back in so that your group membership is re-evaluated.

* You are done. To run Yambo into the container:

docker run -ti --user $(id -u):$(id -g) \
--mount type=bind,source="$(pwd)",target=/tmpdir \
-e OMP_NUM_THREADS=4 \
nicspalla/yambo-gcc_openmp_mkl:latest \
yambo -F yambo.in -J yambo.out

Otherwise (suggested!), copy and paste the code below in a file, i.e called drun.sh:

#!/bin/bash
docker run -ti --user $(id -u):$(id -g) \
--mount type=bind,source="$(pwd)",target=/tmpdir \
-e OMP_NUM_THREADS=4 \
nicspalla/yambo-gcc_openmp_mkl:latest $@

then give the file execute privileges:

chmod +x drun.sh

Move (or copy) this file in the directory where you want to use Yambo and use it as prefix of your Yambo calculation:

./drun.sh yambo -F yambo.in -J yambo.out

If the yambo container is working correctly you should obtain:

./drun.sh yambo

yambo: cannot access CORE database (SAVE/*db1 and/or SAVE/*wf)

>./drun.sh yambo -h

should provide in output the help for yambo usage.

=== Install Yambo ===
If you have some experience with compiling codes, you can [[Download| get the source]] and [[Installation | install]] it. If you never compiled a code, it is better to choose one of the above options as the technical assistance we can offer is limited.

== Tutorials ==

Before starting, [[Get_Tutorial_files_CECAM2021|get the tutorial files]].

=== Thursday 8 April ===
'''14:30 - 17:00 From the DFT ground state to the complete setup of a Many Body calculation using Yambo''' Davide Sangalli (CNR-ISM, Italy), Pedro Melo (University of Liege, Belgium)


* [[First steps: walk through from DFT(standalone)|First steps: Initialization and more ]]
* [[Next steps: RPA calculations (standalone)|Next steps: RPA calculations ]]

=== Friday 9 April ===

'''13:30 - 16:30 A complete tour through GW simulation in a complex material (from the blackboard to numerical computation: convergence, algorithms, parallel usage)''' Daniele Varsano (CNR-NANO, Italy), Andrea Ferretti (CNR-NANO, Italy)

* [[GW hBN Yambo Virtual 2021 version|How to obtain the quasi-particle band structure of a bulk material: h-BN]]

=== Thursday 15 April ===

'''13:30 - 15:00 A guided tour through calculations of spectroscopic properties using the BSE approach''' Fulvio Paleari (CNR-ISM, Italy), Myrta Grüning (Queen's University Belfast, Northern Ireland)

* [[BSE hBN Yambo Virtual 2021 version|How to obtain an optical spectrum]]

== Lectures ==

=== Thursday 8 April ===

'''10:00 to 10:10 - Welcome & Introduction''' Andrea Marini

'''10:10 to 10:30 - Material Science and Yambo, what we can calculate''' Andrea Marini

'''10:40 to 11:00 - Introduction to Many Body Perturbation Theory''' Pedro Melo

'''11:25 to 11:45 - The linear response theory''' Claudio Attaccalite

'''12:00 to 12:20 - From equations to simulations: the hard life of a Materials scientist''' Myrta Grüning

=== Friday 9 April ===

'''10:00 to 10:20 - from ARPES to quasiparticles''' Andrea Ferretti

'''10:30 to 10:50 - The Quasi Particle concept and the GW method''' Andrea Ferretti & Daniele Varsano

'''11:20 to 11:40 - GW implementation and common approximations''' Daniele Varsano

=== Thursday 15 April ===

'''10:00 to 10:20 - Optical properties & excitons''' Maurizia Palummo

'''10:30 to 10:50 - Derivation of the Bethe-Salpeter Equation and main physical concepts''' Claudio Attaccalite

'''11:20 to 11:40 - BSE implementation and common approximations''' Davide Sangalli

=== Friday 16 April ===

GW hBN Yambo Virtual 2021 version

2021-04-06T16:07:05Z

Aferretti: /* 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''.

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 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-06T16:05:24Z

Aferretti: /* 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 ''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

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-06T16:04:45Z

Aferretti: /* 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 ''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 includes also the calculation of the exchange self-energy
(simply, it 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

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 parallel strategies

2020-01-28T16:17:37Z

Aferretti: /* MPI vs OpenMP scaling */

'''This modules contains very general discussions of the parallel environment of Yambo.

In this tutorial we will see how to setup the variables governing the parallel execution of yambo in order to perform efficient calculations in terms of both cpu time and memory to solution. As a test case we will consider the hBN 2D material. Because of its reduced dimensionality, GW calculations turns out to be very delicate. Beside the usual convergence studies with respect to k-points and sums-over-bands, in low dimensional systems a sensible amount of vacuum is required in order to treat the system as isolated, translating into a large number of plane-waves. As for other tutorials, it is important to stress that this tutorial it is meant to illustrate the functionality of the key variables and to run in reasonable time, so it has not the purpose to reach the desired accuracy to reproduce experimental results. Moreover please also note that scaling performance illustrated below may be significantly dependent on the underlying parallel architecture. Nevertheless, general considerations are tentatively drawn in discussing the results.

==Files and Tools==
Database and tools can be downloaded here:

*[http://www.yambo-code.org/educational/tutorials/files/hBN-2D-para.tar.gz hBN-2D-para.tar.gz]


== Getting familiar with yambo in parallel ==

Let's start by copying the tutorial files in the cluster and unzip them in the folder you will run the tutorial.
$ mkdir YAMBO_TUTORIALS
$ cd YAMBO_TUTORIALS
$ cp $path/hBN-2D-para.tar.gz ./
$ tar -zxvf hBN-2D-para.tar.gz
$ cd ./hBN-2D-para/YAMBO
Under the YAMBO folder, together with the SAVE folder, you will see the run.sh script

$ ls
parse_qp.py parse_ytiming.py SAVE

First, run the initialization as usual.
Then you need to generate the input file for a GW run.
$ yambo -g n -p p -F yambo_gw.in
After setting the variables in red, the new input file should look like the following:
$ cat yambo_gw.in

ppa # [R Xp] Plasmon Pole Approximation
gw0 # [R GW] GoWo Quasiparticle energy levels
HF_and_locXC # [R XX] Hartree-Fock Self-energy and Vxc
em1d # [R Xd] Dynamical Inverse Dielectric Matrix
X_Threads= 0 # [OPENMP/X] Number of threads for response functions
DIP_Threads= 0 # [OPENMP/X] Number of threads for dipoles
SE_Threads= 0 # [OPENMP/GW] Number of threads for self-energy
EXXRLvcs= 21817 RL # [XX] Exchange RL components
VXCRLvcs= 21817 RL # [XC] XCpotential RL components
Chimod= "" # [X] IP/Hartree/ALDA/LRC/BSfxc
% BndsRnXp
1 | 300 | # [Xp] Polarization function bands
%
NGsBlkXp= 4 Ry # [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 | 300 | # [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
1| 4| 1| 8|
%

Now you need to create a submission script. here below an example (run.sh) based on the SLURM scheduler. In the case of other schedulers, the header should be updated accordingly.
$ cat run.sh

#!/bin/bash
#SBATCH -N 1
#SBATCH -t 06:00:00
#SBATCH -J test
#SBATCH --partition=<queue name>
#SBATCH --tasks-per-node=1
#SBATCH --cpus-per-task=1

nodes=1
tasks_per_node=1
nthreads=1
ncpu=`echo $nodes $tasks_per_node | awk '{print $1*$2}'`

module purge
module load <needed modules>
module load <more modules>
bindir=<path to yambo bindir>

export OMP_NUM_THREADS=$nthreads

label=MPI${ncpu}_OMP${nthreads}
jdir=run_${label}
cdir=run_${label}.out

filein0=yambo_gw.in
filein=yambo_gw_${label}.in

cp -f $filein0 $filein
cat >> $filein << EOF

DIP_CPU= "1 $ncpu 1" # [PARALLEL] CPUs for each role
DIP_ROLEs= "k c v" # [PARALLEL] CPUs roles (k,c,v)
DIP_Threads= 0 # [OPENMP/X] Number of threads for dipoles
X_CPU= "1 1 1 $ncpu 1" # [PARALLEL] CPUs for each role
X_ROLEs= "q g k c v" # [PARALLEL] CPUs roles (q,g,k,c,v)
X_nCPU_LinAlg_INV= $ncpu # [PARALLEL] CPUs for Linear Algebra
X_Threads= 0 # [OPENMP/X] Number of threads for response functions
SE_CPU= " 1 $ncpu 1" # [PARALLEL] CPUs for each role
SE_ROLEs= "q qp b" # [PARALLEL] CPUs roles (q,qp,b)
SE_Threads= 0

EOF

echo "Running on $ncpu MPI, $nthreads OpenMP threads"
mpirun -np $ncpu $bindir/yambo -F $filein -J $jdir -C $cdir

As soon as you are ready to submit the job.

$ sbatch run.sh

Yambo calculates the GW-qp corrections running on 1 MPI process with a single thread.
As you can see, monitoring the log file produced by yambo, the run takes some time, although
we are using minimal parameters.

The status of the jobs can be monitored via:
$ squeue -u $USER # to inspect the status of jobs
# (hint: make a unix alias, if you like)
$ scancel <jobid> # to delete jobs in the queue

== Pure MPI scaling with default parallelization scheme ==

Meanwhile we can run the code in parallel. Let's use consider the case of a node having 16 cores (you can try to adapt the following discussion to the actual maximum number of
cores/node you have in your system). As a first run, we'll use 16 MPI tasks, still with a single thread.
To this end modify the run.sh script changing
#SBATCH --tasks-per-node=16
#SBATCH --cpus-per-task=1

ntasks_per_node=16
nthreads=1

This time the code should be much faster.
Once the run is over try to run the simulation also on 2, 4, 8 MPI tasks.
Each time, please remember to change both the number of tasks per node both in the header and in the <code>ntasks_per_node</code> variable.
Finally, you can try to produce a scaling plot.

To analyze the data you can use the phyton script parse_ytiming.py run which is provided.

You can use it running
$ ./parse_ytiming.py run*/r-*

You should obtain something like that (but with more columns)
# ncores dip Xo X io_X io_WF Sgm_x Sgm_c (REDUX) WALL_TIME
1 4.7337s 13m39.00s 0.1500s 0.0241s 0.2487s 34.2143s 15m7.00s 0.0000s 29m29s
4 1.6019s 218.7982s 0.0882s 0.0283s 0.2077s 9.3338s 242.4438s 0.0001s 07m54s
8 1.0755s 127.3209s 0.0974s 0.0291s 0.2134s 5.4490s 140.7788s 0.6926s 04m38s
12 0.7510s 89.1649s 0.1015s 0.0299s 0.2068s 4.2961s 109.1227s 0.0007s 03m26s
16 0.7653s 68.2550s 0.1048s 0.0309s 0.2463s 2.9211s 72.6220s 0.2799s 02m27s

Plot the execution time vs the number of MPI tasks
and check (do a log plot) how far you are from the ideal linear scaling.
Below a similar plot produced on a local cluster equipped with two Intel(R) Xeon(R) Silver 4208 CPU @ 2.10GHz processors per node (16 physical cares/node).
[[File:scaling_MPI_corvina.jpg|750px|center]]

'''tips:''' 
* not all runlevels scale in in the same way 
* you should never overload the available number of cores

== Pure OpenMP scaling ==

Next step is instead to check the OpenMP scaling.
Set back
#SBATCH --tasks-per-node=1
#SBATCH --cpus-per-task=16
and now use
ntasks_per_node=1
nthreads=16

Since we are already using 16 threads, we cannot also distribute among MPI tasks, i.e. ncpu will result equal to 1.
Try setting nthreads to 16, 8, 4 and 2 and again to plot the execution time vs the number of threads using the python script.
Again you should be able to produce data similar to the following. In the following we stopped increasing the number of threads up to 8 because of the
specific architecture used in the runs (a dual socket machine with 8 cores/socket).

# ncores threads dip Xo X io_X io_WF Sgm_x Sgm_c WALL_TIME
1 1 4.7337s 13m39.00s 0.1500s 0.0241s 0.2487s 34.2143s 15m7.00s 29m29s
2 2 3.1971s 549.1491s 0.2248s 0.0298s 0.2491s 17.6552s 584.3692s 19m17s
4 4 2.9419s 358.5202s 0.1928s 0.0289s 0.2590s 9.2010s 421.2219s 13m15s
8 8 2.7992s 344.3342s 0.2332s 0.0325s 0.2543s 5.4334s 362.6982s 11m58s

'''tips:''' 
* OpenMP usually shares the memory among threads, but not always 
* you should never overload the available number of cores 
* in principle, we could overload the cores setting more threads than the available total number of cores since a single core allows multi-thread operations

== MPI vs OpenMP scaling ==

Which is scaling better ? MPI or OpenMP?
How is the memory distributed?

Now you can try running simulations with hybrid strategies.
Try for example setting:

#SBATCH --tasks-per-node=8
#SBATCH --cpus-per-task=2

ntasks_per_node= 8
nthreads= 2

We can try to do scaling keeping the total number of threads per node (ntasks_per_node * nthreads) equal to 16.
Parsing the data we will obtain something similar to

# ncores MPI threads dip Xo X io_X io_WF Sgm_x Sgm_c WALL_TIME
16 2 8 3.6816s 386.0552s 0.0856s 0.0268s 0.2163s 18.9077s 530.0875s 15m43s
16 4 4 0.9950s 82.5070s 0.1098s 0.0299s 0.2051s 3.0837s 122.6565s 03m32s
16 8 2 0.8524s 72.6708s 0.0986s 0.0293s 0.2282s 3.0379s 88.1589s 02m48s
16 16 1 0.7653s 68.2550s 0.1048s 0.0309s 0.2463s 2.9211s 72.6220s 02m27s

As you can see here the total CPU time decreases more and more moving the parallelization from the OpenMP to the MPI level.
Sigma_c in particular scales better. Nevertheless, note that the relative performance of the different parallel configurations
may strongly depend on the actual machine you are running on.

However, CPU time is not the only parameter you need to check.
The total memory usage is also very critical since the GW method may have a large memory footprint.
If you have compiled yambo with the flag <code>--enable-memory-profile</code>, the memory usage is tracked and the maximum allocated mem
is printed in the report file, and can be extracted typing:
$ grep "Max memory used" <report_file>

In general yambo can distribute memory when using MPI parallelism (though the actual amount depends on the distribution of MPI tasks across MPI levels).
Nevertheless, some memory replication is still present. In general, within the node OpenMP helps in easing the memory usage. Therefore, in cases where the node memori is
tight, one may consider changing some MPI tasks for OpenMP threads within the node.

Using a hybrid scheme you may also consider running yambo on mode than one node.
To run on two nodes for example you need to set
#SBATCH -N 2

nodes=2
accordingly you can now set
nthreads= 4
This time you will use 32 cores with (16 per node) 4 OpenMP threads and 2*16/4=8 MPI tasks.

'''tips:''' 
* in real life calculations running on n_cores > 100, it is a good idea to adopt a hybrid approach 
* with OpenMP, you cannot exit the single node, with MPI you can

== Advanced: Comparing different parallelization schemes (optional) ==

Up to now we used the default parallelization scheme.
Yambo also allows you to tune the parameters which controls the parallelization scheme.
To this end you can open again the job.sh script and modify the section where the yambo input
variables are set

X_CPU= "1 1 1 $ncpu 1" # [PARALLEL] CPUs for each role
X_ROLEs= "q g k c v" # [PARALLEL] CPUs roles (q,g,k,c,v)
#X_nCPU_LinAlg_INV= $ncpu # [PARALLEL] CPUs for Linear Algebra
X_Threads= 0 # [OPENMP/X] Number of threads for response functions
DIP_Threads= 0 # [OPENMP/X] Number of threads for dipoles
SE_CPU= "1 1 $ncpu" # [PARALLEL] CPUs for each role
SE_ROLEs= "q qp b" # [PARALLEL] CPUs roles (q,qp,b)
SE_Threads= 0

In particular "X_CPU" sets how the MPI Tasks are distributed in the calculation of the response function.
The possibilities are shown in the "X_ROLEs". The same holds for "SE_CPU" and "SE_ROLEs" which control
how MPI Tasks are distributed in the calculation of the response function.

Please try different parallelization schemes and check the performances of Yambo.
In doing so you should also change the jobname in the run.sh script
label=MPI${ncpu}_OMP${nthreads}_scheme1

Using the python script, you can then chenck how speed, memory and load balance between the CPUs are affected.
For more details see also the [[Using_Yambo_in_parallel|Parallel module]]

'''tips: '''
* the product of the numbers entering each variable (i.e. X_CPU and SE_CPU) times the number of threads should always match the total number of cores (unless you want to overload the cores taking advantage of multi-threads) 
* using the X_Threads and SE_Threads variables you can think about setting different Hybrid schemes in between the screening and the self-energy runlevel.
* memory better scales if you parallelize on bands (c v b) 
* parallelization on k-points performs similarly to parallelization on bands, but memory requires more memory 
* parallelization on q-points requires much less communication in between the MPI tasks. It maybe useful if you run on more than one node and the inter-node connection is slow

 
{| 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]] --> [[GW_parallel_strategies|GW Parallel]]
|style="width:35%; text-align:right"|Next: [[Pushing_convergence_in_parallel|GW Convergence]]
|-
|}

GW parallel strategies

2020-01-28T16:17:05Z

Aferretti: /* MPI vs OpenMP scaling */

'''This modules contains very general discussions of the parallel environment of Yambo.

In this tutorial we will see how to setup the variables governing the parallel execution of yambo in order to perform efficient calculations in terms of both cpu time and memory to solution. As a test case we will consider the hBN 2D material. Because of its reduced dimensionality, GW calculations turns out to be very delicate. Beside the usual convergence studies with respect to k-points and sums-over-bands, in low dimensional systems a sensible amount of vacuum is required in order to treat the system as isolated, translating into a large number of plane-waves. As for other tutorials, it is important to stress that this tutorial it is meant to illustrate the functionality of the key variables and to run in reasonable time, so it has not the purpose to reach the desired accuracy to reproduce experimental results. Moreover please also note that scaling performance illustrated below may be significantly dependent on the underlying parallel architecture. Nevertheless, general considerations are tentatively drawn in discussing the results.

==Files and Tools==
Database and tools can be downloaded here:

*[http://www.yambo-code.org/educational/tutorials/files/hBN-2D-para.tar.gz hBN-2D-para.tar.gz]


== Getting familiar with yambo in parallel ==

Let's start by copying the tutorial files in the cluster and unzip them in the folder you will run the tutorial.
$ mkdir YAMBO_TUTORIALS
$ cd YAMBO_TUTORIALS
$ cp $path/hBN-2D-para.tar.gz ./
$ tar -zxvf hBN-2D-para.tar.gz
$ cd ./hBN-2D-para/YAMBO
Under the YAMBO folder, together with the SAVE folder, you will see the run.sh script

$ ls
parse_qp.py parse_ytiming.py SAVE

First, run the initialization as usual.
Then you need to generate the input file for a GW run.
$ yambo -g n -p p -F yambo_gw.in
After setting the variables in red, the new input file should look like the following:
$ cat yambo_gw.in

ppa # [R Xp] Plasmon Pole Approximation
gw0 # [R GW] GoWo Quasiparticle energy levels
HF_and_locXC # [R XX] Hartree-Fock Self-energy and Vxc
em1d # [R Xd] Dynamical Inverse Dielectric Matrix
X_Threads= 0 # [OPENMP/X] Number of threads for response functions
DIP_Threads= 0 # [OPENMP/X] Number of threads for dipoles
SE_Threads= 0 # [OPENMP/GW] Number of threads for self-energy
EXXRLvcs= 21817 RL # [XX] Exchange RL components
VXCRLvcs= 21817 RL # [XC] XCpotential RL components
Chimod= "" # [X] IP/Hartree/ALDA/LRC/BSfxc
% BndsRnXp
1 | 300 | # [Xp] Polarization function bands
%
NGsBlkXp= 4 Ry # [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 | 300 | # [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
1| 4| 1| 8|
%

Now you need to create a submission script. here below an example (run.sh) based on the SLURM scheduler. In the case of other schedulers, the header should be updated accordingly.
$ cat run.sh

#!/bin/bash
#SBATCH -N 1
#SBATCH -t 06:00:00
#SBATCH -J test
#SBATCH --partition=<queue name>
#SBATCH --tasks-per-node=1
#SBATCH --cpus-per-task=1

nodes=1
tasks_per_node=1
nthreads=1
ncpu=`echo $nodes $tasks_per_node | awk '{print $1*$2}'`

module purge
module load <needed modules>
module load <more modules>
bindir=<path to yambo bindir>

export OMP_NUM_THREADS=$nthreads

label=MPI${ncpu}_OMP${nthreads}
jdir=run_${label}
cdir=run_${label}.out

filein0=yambo_gw.in
filein=yambo_gw_${label}.in

cp -f $filein0 $filein
cat >> $filein << EOF

DIP_CPU= "1 $ncpu 1" # [PARALLEL] CPUs for each role
DIP_ROLEs= "k c v" # [PARALLEL] CPUs roles (k,c,v)
DIP_Threads= 0 # [OPENMP/X] Number of threads for dipoles
X_CPU= "1 1 1 $ncpu 1" # [PARALLEL] CPUs for each role
X_ROLEs= "q g k c v" # [PARALLEL] CPUs roles (q,g,k,c,v)
X_nCPU_LinAlg_INV= $ncpu # [PARALLEL] CPUs for Linear Algebra
X_Threads= 0 # [OPENMP/X] Number of threads for response functions
SE_CPU= " 1 $ncpu 1" # [PARALLEL] CPUs for each role
SE_ROLEs= "q qp b" # [PARALLEL] CPUs roles (q,qp,b)
SE_Threads= 0

EOF

echo "Running on $ncpu MPI, $nthreads OpenMP threads"
mpirun -np $ncpu $bindir/yambo -F $filein -J $jdir -C $cdir

As soon as you are ready to submit the job.

$ sbatch run.sh

Yambo calculates the GW-qp corrections running on 1 MPI process with a single thread.
As you can see, monitoring the log file produced by yambo, the run takes some time, although
we are using minimal parameters.

The status of the jobs can be monitored via:
$ squeue -u $USER # to inspect the status of jobs
# (hint: make a unix alias, if you like)
$ scancel <jobid> # to delete jobs in the queue

== Pure MPI scaling with default parallelization scheme ==

Meanwhile we can run the code in parallel. Let's use consider the case of a node having 16 cores (you can try to adapt the following discussion to the actual maximum number of
cores/node you have in your system). As a first run, we'll use 16 MPI tasks, still with a single thread.
To this end modify the run.sh script changing
#SBATCH --tasks-per-node=16
#SBATCH --cpus-per-task=1

ntasks_per_node=16
nthreads=1

This time the code should be much faster.
Once the run is over try to run the simulation also on 2, 4, 8 MPI tasks.
Each time, please remember to change both the number of tasks per node both in the header and in the <code>ntasks_per_node</code> variable.
Finally, you can try to produce a scaling plot.

To analyze the data you can use the phyton script parse_ytiming.py run which is provided.

You can use it running
$ ./parse_ytiming.py run*/r-*

You should obtain something like that (but with more columns)
# ncores dip Xo X io_X io_WF Sgm_x Sgm_c (REDUX) WALL_TIME
1 4.7337s 13m39.00s 0.1500s 0.0241s 0.2487s 34.2143s 15m7.00s 0.0000s 29m29s
4 1.6019s 218.7982s 0.0882s 0.0283s 0.2077s 9.3338s 242.4438s 0.0001s 07m54s
8 1.0755s 127.3209s 0.0974s 0.0291s 0.2134s 5.4490s 140.7788s 0.6926s 04m38s
12 0.7510s 89.1649s 0.1015s 0.0299s 0.2068s 4.2961s 109.1227s 0.0007s 03m26s
16 0.7653s 68.2550s 0.1048s 0.0309s 0.2463s 2.9211s 72.6220s 0.2799s 02m27s

Plot the execution time vs the number of MPI tasks
and check (do a log plot) how far you are from the ideal linear scaling.
Below a similar plot produced on a local cluster equipped with two Intel(R) Xeon(R) Silver 4208 CPU @ 2.10GHz processors per node (16 physical cares/node).
[[File:scaling_MPI_corvina.jpg|750px|center]]

'''tips:''' 
* not all runlevels scale in in the same way 
* you should never overload the available number of cores

== Pure OpenMP scaling ==

Next step is instead to check the OpenMP scaling.
Set back
#SBATCH --tasks-per-node=1
#SBATCH --cpus-per-task=16
and now use
ntasks_per_node=1
nthreads=16

Since we are already using 16 threads, we cannot also distribute among MPI tasks, i.e. ncpu will result equal to 1.
Try setting nthreads to 16, 8, 4 and 2 and again to plot the execution time vs the number of threads using the python script.
Again you should be able to produce data similar to the following. In the following we stopped increasing the number of threads up to 8 because of the
specific architecture used in the runs (a dual socket machine with 8 cores/socket).

# ncores threads dip Xo X io_X io_WF Sgm_x Sgm_c WALL_TIME
1 1 4.7337s 13m39.00s 0.1500s 0.0241s 0.2487s 34.2143s 15m7.00s 29m29s
2 2 3.1971s 549.1491s 0.2248s 0.0298s 0.2491s 17.6552s 584.3692s 19m17s
4 4 2.9419s 358.5202s 0.1928s 0.0289s 0.2590s 9.2010s 421.2219s 13m15s
8 8 2.7992s 344.3342s 0.2332s 0.0325s 0.2543s 5.4334s 362.6982s 11m58s

'''tips:''' 
* OpenMP usually shares the memory among threads, but not always 
* you should never overload the available number of cores 
* in principle, we could overload the cores setting more threads than the available total number of cores since a single core allows multi-thread operations

== MPI vs OpenMP scaling ==

Which is scaling better ? MPI or OpenMP?
How is the memory distributed?

Now you can try running simulations with hybrid strategies.
Try for example setting:

#SBATCH --tasks-per-node=8
#SBATCH --cpus-per-task=2

ntasks_per_node= 8
nthreads= 2

We can try to do scaling keeping the total number of threads per node (ntasks_per_node * nthreads) equal to 16.
Parsing the data we will obtain something similar to

# ncores MPI threads dip Xo X io_X io_WF Sgm_x Sgm_c WALL_TIME
16 2 8 3.6816s 386.0552s 0.0856s 0.0268s 0.2163s 18.9077s 530.0875s 15m43s
16 4 4 0.9950s 82.5070s 0.1098s 0.0299s 0.2051s 3.0837s 122.6565s 03m32s
16 8 2 0.8524s 72.6708s 0.0986s 0.0293s 0.2282s 3.0379s 88.1589s 02m48s
16 16 1 0.7653s 68.2550s 0.1048s 0.0309s 0.2463s 2.9211s 72.6220s 02m27s

As you can see here the total CPU time decreases more and more moving the parallelization from the OpenMP to the MPI level.
Sigma_c in particular scales better. Nevertheless, note that the relative performance of the different parallel configurations
may strongly depend on the actual machine you are running on.

However, CPU time is not the only parameter you need to check.
The total memory usage is also very critical since the GW method may have a large memory footprint.
If you have compiled yambo with the flag <code>--enable-memory-profile</code>, the memory usage is tracked and the maximum allocated mem
is printed in the report file, and can be extracted typing:
$ grep "Max memory used" <report_file>



In general yambo can distribute memory when using MPI parallelism (though the actual amount depends on the distribution of MPI tasks across MPI levels).
Nevertheless, some memory replication is still present. In general, within the node OpenMP helps in easing the memory usage. Therefore, in cases where the node memori is
tight, one may consider changing some MPI tasks for OpenMP threads within the node.

Using a hybrid scheme you may also consider running yambo on mode than one node.
To run on two nodes for example you need to set
#SBATCH -N 2

nodes=2
accordingly you can now set
nthreads= 4
This time you will use 32 cores with (16 per node) 4 OpenMP threads and 2*16/4=8 MPI tasks.

'''tips:''' 
* in real life calculations running on n_cores > 100, it is a good idea to adopt a hybrid approach 
* with OpenMP, you cannot exit the single node, with MPI you can

== Advanced: Comparing different parallelization schemes (optional) ==

Up to now we used the default parallelization scheme.
Yambo also allows you to tune the parameters which controls the parallelization scheme.
To this end you can open again the job.sh script and modify the section where the yambo input
variables are set

X_CPU= "1 1 1 $ncpu 1" # [PARALLEL] CPUs for each role
X_ROLEs= "q g k c v" # [PARALLEL] CPUs roles (q,g,k,c,v)
#X_nCPU_LinAlg_INV= $ncpu # [PARALLEL] CPUs for Linear Algebra
X_Threads= 0 # [OPENMP/X] Number of threads for response functions
DIP_Threads= 0 # [OPENMP/X] Number of threads for dipoles
SE_CPU= "1 1 $ncpu" # [PARALLEL] CPUs for each role
SE_ROLEs= "q qp b" # [PARALLEL] CPUs roles (q,qp,b)
SE_Threads= 0

In particular "X_CPU" sets how the MPI Tasks are distributed in the calculation of the response function.
The possibilities are shown in the "X_ROLEs". The same holds for "SE_CPU" and "SE_ROLEs" which control
how MPI Tasks are distributed in the calculation of the response function.

Please try different parallelization schemes and check the performances of Yambo.
In doing so you should also change the jobname in the run.sh script
label=MPI${ncpu}_OMP${nthreads}_scheme1

Using the python script, you can then chenck how speed, memory and load balance between the CPUs are affected.
For more details see also the [[Using_Yambo_in_parallel|Parallel module]]

'''tips: '''
* the product of the numbers entering each variable (i.e. X_CPU and SE_CPU) times the number of threads should always match the total number of cores (unless you want to overload the cores taking advantage of multi-threads) 
* using the X_Threads and SE_Threads variables you can think about setting different Hybrid schemes in between the screening and the self-energy runlevel.
* memory better scales if you parallelize on bands (c v b) 
* parallelization on k-points performs similarly to parallelization on bands, but memory requires more memory 
* parallelization on q-points requires much less communication in between the MPI tasks. It maybe useful if you run on more than one node and the inter-node connection is slow

 
{| 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]] --> [[GW_parallel_strategies|GW Parallel]]
|style="width:35%; text-align:right"|Next: [[Pushing_convergence_in_parallel|GW Convergence]]
|-
|}

GW parallel strategies

2020-01-28T15:59:45Z

Aferretti: /* MPI vs OpenMP scaling */

'''This modules contains very general discussions of the parallel environment of Yambo.

In this tutorial we will see how to setup the variables governing the parallel execution of yambo in order to perform efficient calculations in terms of both cpu time and memory to solution. As a test case we will consider the hBN 2D material. Because of its reduced dimensionality, GW calculations turns out to be very delicate. Beside the usual convergence studies with respect to k-points and sums-over-bands, in low dimensional systems a sensible amount of vacuum is required in order to treat the system as isolated, translating into a large number of plane-waves. As for other tutorials, it is important to stress that this tutorial it is meant to illustrate the functionality of the key variables and to run in reasonable time, so it has not the purpose to reach the desired accuracy to reproduce experimental results. Moreover please also note that scaling performance illustrated below may be significantly dependent on the underlying parallel architecture. Nevertheless, general considerations are tentatively drawn in discussing the results.

==Files and Tools==
Database and tools can be downloaded here:

*[http://www.yambo-code.org/educational/tutorials/files/hBN-2D-para.tar.gz hBN-2D-para.tar.gz]


== Getting familiar with yambo in parallel ==

Let's start by copying the tutorial files in the cluster and unzip them in the folder you will run the tutorial.
$ mkdir YAMBO_TUTORIALS
$ cd YAMBO_TUTORIALS
$ cp $path/hBN-2D-para.tar.gz ./
$ tar -zxvf hBN-2D-para.tar.gz
$ cd ./hBN-2D-para/YAMBO
Under the YAMBO folder, together with the SAVE folder, you will see the run.sh script

$ ls
parse_qp.py parse_ytiming.py SAVE

First, run the initialization as usual.
Then you need to generate the input file for a GW run.
$ yambo -g n -p p -F yambo_gw.in
After setting the variables in red, the new input file should look like the following:
$ cat yambo_gw.in

ppa # [R Xp] Plasmon Pole Approximation
gw0 # [R GW] GoWo Quasiparticle energy levels
HF_and_locXC # [R XX] Hartree-Fock Self-energy and Vxc
em1d # [R Xd] Dynamical Inverse Dielectric Matrix
X_Threads= 0 # [OPENMP/X] Number of threads for response functions
DIP_Threads= 0 # [OPENMP/X] Number of threads for dipoles
SE_Threads= 0 # [OPENMP/GW] Number of threads for self-energy
EXXRLvcs= 21817 RL # [XX] Exchange RL components
VXCRLvcs= 21817 RL # [XC] XCpotential RL components
Chimod= "" # [X] IP/Hartree/ALDA/LRC/BSfxc
% BndsRnXp
1 | 300 | # [Xp] Polarization function bands
%
NGsBlkXp= 4 Ry # [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 | 300 | # [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
1| 4| 1| 8|
%

Now you need to create a submission script. here below an example (run.sh) based on the SLURM scheduler. In the case of other schedulers, the header should be updated accordingly.
$ cat run.sh

#!/bin/bash
#SBATCH -N 1
#SBATCH -t 06:00:00
#SBATCH -J test
#SBATCH --partition=<queue name>
#SBATCH --tasks-per-node=1
#SBATCH --cpus-per-task=1

nodes=1
tasks_per_node=1
nthreads=1
ncpu=`echo $nodes $tasks_per_node | awk '{print $1*$2}'`

module purge
module load <needed modules>
module load <more modules>
bindir=<path to yambo bindir>

export OMP_NUM_THREADS=$nthreads

label=MPI${ncpu}_OMP${nthreads}
jdir=run_${label}
cdir=run_${label}.out

filein0=yambo_gw.in
filein=yambo_gw_${label}.in

cp -f $filein0 $filein
cat >> $filein << EOF

DIP_CPU= "1 $ncpu 1" # [PARALLEL] CPUs for each role
DIP_ROLEs= "k c v" # [PARALLEL] CPUs roles (k,c,v)
DIP_Threads= 0 # [OPENMP/X] Number of threads for dipoles
X_CPU= "1 1 1 $ncpu 1" # [PARALLEL] CPUs for each role
X_ROLEs= "q g k c v" # [PARALLEL] CPUs roles (q,g,k,c,v)
X_nCPU_LinAlg_INV= $ncpu # [PARALLEL] CPUs for Linear Algebra
X_Threads= 0 # [OPENMP/X] Number of threads for response functions
SE_CPU= " 1 $ncpu 1" # [PARALLEL] CPUs for each role
SE_ROLEs= "q qp b" # [PARALLEL] CPUs roles (q,qp,b)
SE_Threads= 0

EOF

echo "Running on $ncpu MPI, $nthreads OpenMP threads"
mpirun -np $ncpu $bindir/yambo -F $filein -J $jdir -C $cdir

As soon as you are ready to submit the job.

$ sbatch run.sh

Yambo calculates the GW-qp corrections running on 1 MPI process with a single thread.
As you can see, monitoring the log file produced by yambo, the run takes some time, although
we are using minimal parameters.

The status of the jobs can be monitored via:
$ squeue -u $USER # to inspect the status of jobs
# (hint: make a unix alias, if you like)
$ scancel <jobid> # to delete jobs in the queue

== Pure MPI scaling with default parallelization scheme ==

Meanwhile we can run the code in parallel. Let's use consider the case of a node having 16 cores (you can try to adapt the following discussion to the actual maximum number of
cores/node you have in your system). As a first run, we'll use 16 MPI tasks, still with a single thread.
To this end modify the run.sh script changing
#SBATCH --tasks-per-node=16
#SBATCH --cpus-per-task=1

ntasks_per_node=16
nthreads=1

This time the code should be much faster.
Once the run is over try to run the simulation also on 2, 4, 8 MPI tasks.
Each time, please remember to change both the number of tasks per node both in the header and in the <code>ntasks_per_node</code> variable.
Finally, you can try to produce a scaling plot.

To analyze the data you can use the phyton script parse_ytiming.py run which is provided.

You can use it running
$ ./parse_ytiming.py run*/r-*

You should obtain something like that (but with more columns)
# ncores dip Xo X io_X io_WF Sgm_x Sgm_c (REDUX) WALL_TIME
1 4.7337s 13m39.00s 0.1500s 0.0241s 0.2487s 34.2143s 15m7.00s 0.0000s 29m29s
4 1.6019s 218.7982s 0.0882s 0.0283s 0.2077s 9.3338s 242.4438s 0.0001s 07m54s
8 1.0755s 127.3209s 0.0974s 0.0291s 0.2134s 5.4490s 140.7788s 0.6926s 04m38s
12 0.7510s 89.1649s 0.1015s 0.0299s 0.2068s 4.2961s 109.1227s 0.0007s 03m26s
16 0.7653s 68.2550s 0.1048s 0.0309s 0.2463s 2.9211s 72.6220s 0.2799s 02m27s

Plot the execution time vs the number of MPI tasks
and check (do a log plot) how far you are from the ideal linear scaling.
Below a similar plot produced on a local cluster equipped with two Intel(R) Xeon(R) Silver 4208 CPU @ 2.10GHz processors per node (16 physical cares/node).
[[File:scaling_MPI_corvina.jpg|750px|center]]

'''tips:''' 
* not all runlevels scale in in the same way 
* you should never overload the available number of cores

== Pure OpenMP scaling ==

Next step is instead to check the OpenMP scaling.
Set back
#SBATCH --tasks-per-node=1
#SBATCH --cpus-per-task=16
and now use
ntasks_per_node=1
nthreads=16

Since we are already using 16 threads, we cannot also distribute among MPI tasks, i.e. ncpu will result equal to 1.
Try setting nthreads to 16, 8, 4 and 2 and again to plot the execution time vs the number of threads using the python script.
Again you should be able to produce data similar to the following. In the following we stopped increasing the number of threads up to 8 because of the
specific architecture used in the runs (a dual socket machine with 8 cores/socket).

# ncores threads dip Xo X io_X io_WF Sgm_x Sgm_c WALL_TIME
1 1 4.7337s 13m39.00s 0.1500s 0.0241s 0.2487s 34.2143s 15m7.00s 29m29s
2 2 3.1971s 549.1491s 0.2248s 0.0298s 0.2491s 17.6552s 584.3692s 19m17s
4 4 2.9419s 358.5202s 0.1928s 0.0289s 0.2590s 9.2010s 421.2219s 13m15s
8 8 2.7992s 344.3342s 0.2332s 0.0325s 0.2543s 5.4334s 362.6982s 11m58s

'''tips:''' 
* OpenMP usually shares the memory among threads, but not always 
* you should never overload the available number of cores 
* in principle, we could overload the cores setting more threads than the available total number of cores since a single core allows multi-thread operations

== MPI vs OpenMP scaling ==

Which is scaling better ? MPI or OpenMP?
How is the memory distributed?

Now you can try running simulations with hybrid strategies.
Try for example setting:

#SBATCH --tasks-per-node=8
#SBATCH --cpus-per-task=2

ntasks_per_node= 8
nthreads= 2

We can try to do scaling keeping the total number of threads per node (ntasks_per_node * nthreads) equal to 16.
Parsing the data we will obtain something similar to

# ncores MPI threads dip Xo X io_X io_WF Sgm_x Sgm_c WALL_TIME
16 2 8 3.6816s 386.0552s 0.0856s 0.0268s 0.2163s 18.9077s 530.0875s 15m43s
16 4 4 0.9950s 82.5070s 0.1098s 0.0299s 0.2051s 3.0837s 122.6565s 03m32s
16 8 2 0.8524s 72.6708s 0.0986s 0.0293s 0.2282s 3.0379s 88.1589s 02m48s
16 16 1 0.7653s 68.2550s 0.1048s 0.0309s 0.2463s 2.9211s 72.6220s 02m27s

As you can see here the total CPU time decreases more and more moving the parallelization from the OpenMP to the MPI level.
Sigma_c in particular scales better. Nevertheless, note that the relative performance of the different parallel configurations
may strongly depend on the actual machine you are running on.

However, CPU time is not the only parameter you need to check.
The total memory usage is also very critical since the GW method may have a large memory footprint.
If you have compiled yambo with the flag <code>--enable-memory-profile</code>, the memory usage is tracked and the maximum allocated mem
is printed in the report file, and can be extracted typing:
$ grep "Max memory used" <report_file>


As you can see yambo is distributing memory since the single MPI task uses less memory than
the total one needed (you can even compare with the serial case). However, it is not as efficient as
OpenMP in doing so.

Using a hybrid scheme you may also consider running yambo on mode than one node.
To run on two nodes for example you need to set
#SBATCH -N 2

nodes=2
accordingly you can now set
nthreads= 4
This time you will use 32 cores with (16 per node) 4 OpenMP threads and 2*16/4=8 MPI tasks.

'''tips:''' 
* in real life calculations running on n_cores > 100, it is a good idea to adopt a hybrid approach 
* with OpenMP, you cannot exit the single node, with MPI you can

== Advanced: Comparing different parallelization schemes (optional) ==

Up to now we used the default parallelization scheme.
Yambo also allows you to tune the parameters which controls the parallelization scheme.
To this end you can open again the job.sh script and modify the section where the yambo input
variables are set

X_CPU= "1 1 1 $ncpu 1" # [PARALLEL] CPUs for each role
X_ROLEs= "q g k c v" # [PARALLEL] CPUs roles (q,g,k,c,v)
#X_nCPU_LinAlg_INV= $ncpu # [PARALLEL] CPUs for Linear Algebra
X_Threads= 0 # [OPENMP/X] Number of threads for response functions
DIP_Threads= 0 # [OPENMP/X] Number of threads for dipoles
SE_CPU= "1 1 $ncpu" # [PARALLEL] CPUs for each role
SE_ROLEs= "q qp b" # [PARALLEL] CPUs roles (q,qp,b)
SE_Threads= 0

In particular "X_CPU" sets how the MPI Tasks are distributed in the calculation of the response function.
The possibilities are shown in the "X_ROLEs". The same holds for "SE_CPU" and "SE_ROLEs" which control
how MPI Tasks are distributed in the calculation of the response function.

Please try different parallelization schemes and check the performances of Yambo.
In doing so you should also change the jobname in the run.sh script
label=MPI${ncpu}_OMP${nthreads}_scheme1

Using the python script, you can then chenck how speed, memory and load balance between the CPUs are affected.
For more details see also the [[Using_Yambo_in_parallel|Parallel module]]

'''tips: '''
* the product of the numbers entering each variable (i.e. X_CPU and SE_CPU) times the number of threads should always match the total number of cores (unless you want to overload the cores taking advantage of multi-threads) 
* using the X_Threads and SE_Threads variables you can think about setting different Hybrid schemes in between the screening and the self-energy runlevel.
* memory better scales if you parallelize on bands (c v b) 
* parallelization on k-points performs similarly to parallelization on bands, but memory requires more memory 
* parallelization on q-points requires much less communication in between the MPI tasks. It maybe useful if you run on more than one node and the inter-node connection is slow

 
{| 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]] --> [[GW_parallel_strategies|GW Parallel]]
|style="width:35%; text-align:right"|Next: [[Pushing_convergence_in_parallel|GW Convergence]]
|-
|}

GW parallel strategies

2020-01-28T15:58:40Z

Aferretti: /* MPI vs OpenMP scaling */

'''This modules contains very general discussions of the parallel environment of Yambo.

In this tutorial we will see how to setup the variables governing the parallel execution of yambo in order to perform efficient calculations in terms of both cpu time and memory to solution. As a test case we will consider the hBN 2D material. Because of its reduced dimensionality, GW calculations turns out to be very delicate. Beside the usual convergence studies with respect to k-points and sums-over-bands, in low dimensional systems a sensible amount of vacuum is required in order to treat the system as isolated, translating into a large number of plane-waves. As for other tutorials, it is important to stress that this tutorial it is meant to illustrate the functionality of the key variables and to run in reasonable time, so it has not the purpose to reach the desired accuracy to reproduce experimental results. Moreover please also note that scaling performance illustrated below may be significantly dependent on the underlying parallel architecture. Nevertheless, general considerations are tentatively drawn in discussing the results.

==Files and Tools==
Database and tools can be downloaded here:

*[http://www.yambo-code.org/educational/tutorials/files/hBN-2D-para.tar.gz hBN-2D-para.tar.gz]


== Getting familiar with yambo in parallel ==

Let's start by copying the tutorial files in the cluster and unzip them in the folder you will run the tutorial.
$ mkdir YAMBO_TUTORIALS
$ cd YAMBO_TUTORIALS
$ cp $path/hBN-2D-para.tar.gz ./
$ tar -zxvf hBN-2D-para.tar.gz
$ cd ./hBN-2D-para/YAMBO
Under the YAMBO folder, together with the SAVE folder, you will see the run.sh script

$ ls
parse_qp.py parse_ytiming.py SAVE

First, run the initialization as usual.
Then you need to generate the input file for a GW run.
$ yambo -g n -p p -F yambo_gw.in
After setting the variables in red, the new input file should look like the following:
$ cat yambo_gw.in

ppa # [R Xp] Plasmon Pole Approximation
gw0 # [R GW] GoWo Quasiparticle energy levels
HF_and_locXC # [R XX] Hartree-Fock Self-energy and Vxc
em1d # [R Xd] Dynamical Inverse Dielectric Matrix
X_Threads= 0 # [OPENMP/X] Number of threads for response functions
DIP_Threads= 0 # [OPENMP/X] Number of threads for dipoles
SE_Threads= 0 # [OPENMP/GW] Number of threads for self-energy
EXXRLvcs= 21817 RL # [XX] Exchange RL components
VXCRLvcs= 21817 RL # [XC] XCpotential RL components
Chimod= "" # [X] IP/Hartree/ALDA/LRC/BSfxc
% BndsRnXp
1 | 300 | # [Xp] Polarization function bands
%
NGsBlkXp= 4 Ry # [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 | 300 | # [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
1| 4| 1| 8|
%

Now you need to create a submission script. here below an example (run.sh) based on the SLURM scheduler. In the case of other schedulers, the header should be updated accordingly.
$ cat run.sh

#!/bin/bash
#SBATCH -N 1
#SBATCH -t 06:00:00
#SBATCH -J test
#SBATCH --partition=<queue name>
#SBATCH --tasks-per-node=1
#SBATCH --cpus-per-task=1

nodes=1
tasks_per_node=1
nthreads=1
ncpu=`echo $nodes $tasks_per_node | awk '{print $1*$2}'`

module purge
module load <needed modules>
module load <more modules>
bindir=<path to yambo bindir>

export OMP_NUM_THREADS=$nthreads

label=MPI${ncpu}_OMP${nthreads}
jdir=run_${label}
cdir=run_${label}.out

filein0=yambo_gw.in
filein=yambo_gw_${label}.in

cp -f $filein0 $filein
cat >> $filein << EOF

DIP_CPU= "1 $ncpu 1" # [PARALLEL] CPUs for each role
DIP_ROLEs= "k c v" # [PARALLEL] CPUs roles (k,c,v)
DIP_Threads= 0 # [OPENMP/X] Number of threads for dipoles
X_CPU= "1 1 1 $ncpu 1" # [PARALLEL] CPUs for each role
X_ROLEs= "q g k c v" # [PARALLEL] CPUs roles (q,g,k,c,v)
X_nCPU_LinAlg_INV= $ncpu # [PARALLEL] CPUs for Linear Algebra
X_Threads= 0 # [OPENMP/X] Number of threads for response functions
SE_CPU= " 1 $ncpu 1" # [PARALLEL] CPUs for each role
SE_ROLEs= "q qp b" # [PARALLEL] CPUs roles (q,qp,b)
SE_Threads= 0

EOF

echo "Running on $ncpu MPI, $nthreads OpenMP threads"
mpirun -np $ncpu $bindir/yambo -F $filein -J $jdir -C $cdir

As soon as you are ready to submit the job.

$ sbatch run.sh

Yambo calculates the GW-qp corrections running on 1 MPI process with a single thread.
As you can see, monitoring the log file produced by yambo, the run takes some time, although
we are using minimal parameters.

The status of the jobs can be monitored via:
$ squeue -u $USER # to inspect the status of jobs
# (hint: make a unix alias, if you like)
$ scancel <jobid> # to delete jobs in the queue

== Pure MPI scaling with default parallelization scheme ==

Meanwhile we can run the code in parallel. Let's use consider the case of a node having 16 cores (you can try to adapt the following discussion to the actual maximum number of
cores/node you have in your system). As a first run, we'll use 16 MPI tasks, still with a single thread.
To this end modify the run.sh script changing
#SBATCH --tasks-per-node=16
#SBATCH --cpus-per-task=1

ntasks_per_node=16
nthreads=1

This time the code should be much faster.
Once the run is over try to run the simulation also on 2, 4, 8 MPI tasks.
Each time, please remember to change both the number of tasks per node both in the header and in the <code>ntasks_per_node</code> variable.
Finally, you can try to produce a scaling plot.

To analyze the data you can use the phyton script parse_ytiming.py run which is provided.

You can use it running
$ ./parse_ytiming.py run*/r-*

You should obtain something like that (but with more columns)
# ncores dip Xo X io_X io_WF Sgm_x Sgm_c (REDUX) WALL_TIME
1 4.7337s 13m39.00s 0.1500s 0.0241s 0.2487s 34.2143s 15m7.00s 0.0000s 29m29s
4 1.6019s 218.7982s 0.0882s 0.0283s 0.2077s 9.3338s 242.4438s 0.0001s 07m54s
8 1.0755s 127.3209s 0.0974s 0.0291s 0.2134s 5.4490s 140.7788s 0.6926s 04m38s
12 0.7510s 89.1649s 0.1015s 0.0299s 0.2068s 4.2961s 109.1227s 0.0007s 03m26s
16 0.7653s 68.2550s 0.1048s 0.0309s 0.2463s 2.9211s 72.6220s 0.2799s 02m27s

Plot the execution time vs the number of MPI tasks
and check (do a log plot) how far you are from the ideal linear scaling.
Below a similar plot produced on a local cluster equipped with two Intel(R) Xeon(R) Silver 4208 CPU @ 2.10GHz processors per node (16 physical cares/node).
[[File:scaling_MPI_corvina.jpg|750px|center]]

'''tips:''' 
* not all runlevels scale in in the same way 
* you should never overload the available number of cores

== Pure OpenMP scaling ==

Next step is instead to check the OpenMP scaling.
Set back
#SBATCH --tasks-per-node=1
#SBATCH --cpus-per-task=16
and now use
ntasks_per_node=1
nthreads=16

Since we are already using 16 threads, we cannot also distribute among MPI tasks, i.e. ncpu will result equal to 1.
Try setting nthreads to 16, 8, 4 and 2 and again to plot the execution time vs the number of threads using the python script.
Again you should be able to produce data similar to the following. In the following we stopped increasing the number of threads up to 8 because of the
specific architecture used in the runs (a dual socket machine with 8 cores/socket).

# ncores threads dip Xo X io_X io_WF Sgm_x Sgm_c WALL_TIME
1 1 4.7337s 13m39.00s 0.1500s 0.0241s 0.2487s 34.2143s 15m7.00s 29m29s
2 2 3.1971s 549.1491s 0.2248s 0.0298s 0.2491s 17.6552s 584.3692s 19m17s
4 4 2.9419s 358.5202s 0.1928s 0.0289s 0.2590s 9.2010s 421.2219s 13m15s
8 8 2.7992s 344.3342s 0.2332s 0.0325s 0.2543s 5.4334s 362.6982s 11m58s

'''tips:''' 
* OpenMP usually shares the memory among threads, but not always 
* you should never overload the available number of cores 
* in principle, we could overload the cores setting more threads than the available total number of cores since a single core allows multi-thread operations

== MPI vs OpenMP scaling ==

Which is scaling better ? MPI or OpenMP?
How is the memory distributed?

Now you can try running simulations with hybrid strategies.
Try for example setting:

#SBATCH --tasks-per-node=8
#SBATCH --cpus-per-task=2

ntasks_per_node= 8
nthreads= 2

We can try to do scaling keeping the total number of threads per node (ntasks_per_node * nthreads) equal to 16.
Parsing the data we will obtain something similar to

# ncores MPI threads dip Xo X io_X io_WF Sgm_x Sgm_c WALL_TIME
16 2 8 3.6816s 386.0552s 0.0856s 0.0268s 0.2163s 18.9077s 530.0875s 15m43s
16 4 4 0.9950s 82.5070s 0.1098s 0.0299s 0.2051s 3.0837s 122.6565s 03m32s
16 8 2 0.8524s 72.6708s 0.0986s 0.0293s 0.2282s 3.0379s 88.1589s 02m48s
16 16 1 0.7653s 68.2550s 0.1048s 0.0309s 0.2463s 2.9211s 72.6220s 02m27s

As you can see here the total CPU time decreases more and more moving the parallelization from the OpenMP to the MPI level.
Sigma_c in particular scales better. Nevertheless, note that the relative performance of the different parallel configurations
may strongly depend on the actual machine you are running on.

However, CPU time is not the only parameter you need to check.
The total memory usage is also very critical since the GW method may have a large memory footprint.
If you have compiled yambo with the flag <code>--enable-memory-profile</code>, the memory usage is tracked and the maximum allocated mem
is printed in the report file, and can be extracted typing:
$ grep "Max memory used" <report_file>

<--!
If you compare for example the two extreme cases (you can use)
$ grep Gb run_MPI1_OMP*/l* | grep Alloc (use this for the case with only one MPI proc)
$ grep Gb run_MPI*_OMP*/LOG/l*_1 | grep Alloc (use this for the case with more than one MPI proc)

For the case
# ncores MPI threads
16 1 16
<01s> [M 0.119 Gb] Alloc WF ( 0.112)
<03s> [M 0.314 Gb] Alloc WF ( 0.306)
<46s> [M 0.074 Gb] Alloc WF ( 0.056)
<50s> [M 0.321 Gb] Alloc WF ( 0.306)
the numbers reported above refer to the total amount of memory use in the run.

For the case
# ncores MPI threads
16 16 1
<02s> P0001: [M 0.034 Gb] Alloc WF ( 0.026)
<43s> P0001: [M 0.037 Gb] Alloc WF ( 0.019)
<45s> P0001: [M 0.091 Gb] Alloc WF ( 0.076)
the numbers reported above refer to the total amount of memory per MPI task.
Multiplying by 16 you obtain an estimate of the total memory: 0.091*16=1.456 (0.076*16=1.216)
These last two numbers have to be compared with 0.321 (0.306)
-->
As you can see yambo is distributing memory since the single MPI task uses less memory than
the total one needed (you can even compare with the serial case). However, it is not as efficient as
OpenMP in doing so.

Using a hybrid scheme you may also consider running yambo on mode than one node.
To run on two nodes for example you need to set
#SBATCH -N 2

nodes=2
accordingly you can now set
nthreads= 4
This time you will use 32 cores with (16 per node) 4 OpenMP threads and 2*16/4=8 MPI tasks.

'''tips:''' 
* in real life calculations running on n_cores > 100, it is a good idea to adopt a hybrid approach 
* with OpenMP, you cannot exit the single node, with MPI you can

== Advanced: Comparing different parallelization schemes (optional) ==

Up to now we used the default parallelization scheme.
Yambo also allows you to tune the parameters which controls the parallelization scheme.
To this end you can open again the job.sh script and modify the section where the yambo input
variables are set

X_CPU= "1 1 1 $ncpu 1" # [PARALLEL] CPUs for each role
X_ROLEs= "q g k c v" # [PARALLEL] CPUs roles (q,g,k,c,v)
#X_nCPU_LinAlg_INV= $ncpu # [PARALLEL] CPUs for Linear Algebra
X_Threads= 0 # [OPENMP/X] Number of threads for response functions
DIP_Threads= 0 # [OPENMP/X] Number of threads for dipoles
SE_CPU= "1 1 $ncpu" # [PARALLEL] CPUs for each role
SE_ROLEs= "q qp b" # [PARALLEL] CPUs roles (q,qp,b)
SE_Threads= 0

In particular "X_CPU" sets how the MPI Tasks are distributed in the calculation of the response function.
The possibilities are shown in the "X_ROLEs". The same holds for "SE_CPU" and "SE_ROLEs" which control
how MPI Tasks are distributed in the calculation of the response function.

Please try different parallelization schemes and check the performances of Yambo.
In doing so you should also change the jobname in the run.sh script
label=MPI${ncpu}_OMP${nthreads}_scheme1

Using the python script, you can then chenck how speed, memory and load balance between the CPUs are affected.
For more details see also the [[Using_Yambo_in_parallel|Parallel module]]

'''tips: '''
* the product of the numbers entering each variable (i.e. X_CPU and SE_CPU) times the number of threads should always match the total number of cores (unless you want to overload the cores taking advantage of multi-threads) 
* using the X_Threads and SE_Threads variables you can think about setting different Hybrid schemes in between the screening and the self-energy runlevel.
* memory better scales if you parallelize on bands (c v b) 
* parallelization on k-points performs similarly to parallelization on bands, but memory requires more memory 
* parallelization on q-points requires much less communication in between the MPI tasks. It maybe useful if you run on more than one node and the inter-node connection is slow

 
{| 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]] --> [[GW_parallel_strategies|GW Parallel]]
|style="width:35%; text-align:right"|Next: [[Pushing_convergence_in_parallel|GW Convergence]]
|-
|}

GW parallel strategies

2020-01-28T15:18:52Z

Aferretti: /* MPI vs OpenMP scaling */

'''This modules contains very general discussions of the parallel environment of Yambo.

In this tutorial we will see how to setup the variables governing the parallel execution of yambo in order to perform efficient calculations in terms of both cpu time and memory to solution. As a test case we will consider the hBN 2D material. Because of its reduced dimensionality, GW calculations turns out to be very delicate. Beside the usual convergence studies with respect to k-points and sums-over-bands, in low dimensional systems a sensible amount of vacuum is required in order to treat the system as isolated, translating into a large number of plane-waves. As for other tutorials, it is important to stress that this tutorial it is meant to illustrate the functionality of the key variables and to run in reasonable time, so it has not the purpose to reach the desired accuracy to reproduce experimental results. Moreover please also note that scaling performance illustrated below may be significantly dependent on the underlying parallel architecture. Nevertheless, general considerations are tentatively drawn in discussing the results.

==Files and Tools==
Database and tools can be downloaded here:

*[http://www.yambo-code.org/educational/tutorials/files/hBN-2D-para.tar.gz hBN-2D-para.tar.gz]


== Getting familiar with yambo in parallel ==

Let's start by copying the tutorial files in the cluster and unzip them in the folder you will run the tutorial.
$ mkdir YAMBO_TUTORIALS
$ cd YAMBO_TUTORIALS
$ cp $path/hBN-2D-para.tar.gz ./
$ tar -zxvf hBN-2D-para.tar.gz
$ cd ./hBN-2D-para/YAMBO
Under the YAMBO folder, together with the SAVE folder, you will see the run.sh script

$ ls
parse_qp.py parse_ytiming.py SAVE

First, run the initialization as usual.
Then you need to generate the input file for a GW run.
$ yambo -g n -p p -F yambo_gw.in
After setting the variables in red, the new input file should look like the following:
$ cat yambo_gw.in

ppa # [R Xp] Plasmon Pole Approximation
gw0 # [R GW] GoWo Quasiparticle energy levels
HF_and_locXC # [R XX] Hartree-Fock Self-energy and Vxc
em1d # [R Xd] Dynamical Inverse Dielectric Matrix
X_Threads= 0 # [OPENMP/X] Number of threads for response functions
DIP_Threads= 0 # [OPENMP/X] Number of threads for dipoles
SE_Threads= 0 # [OPENMP/GW] Number of threads for self-energy
EXXRLvcs= 21817 RL # [XX] Exchange RL components
VXCRLvcs= 21817 RL # [XC] XCpotential RL components
Chimod= "" # [X] IP/Hartree/ALDA/LRC/BSfxc
% BndsRnXp
1 | 300 | # [Xp] Polarization function bands
%
NGsBlkXp= 4 Ry # [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 | 300 | # [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
1| 4| 1| 8|
%

Now you need to create a submission script. here below an example (run.sh) based on the SLURM scheduler. In the case of other schedulers, the header should be updated accordingly.
$ cat run.sh

#!/bin/bash
#SBATCH -N 1
#SBATCH -t 06:00:00
#SBATCH -J test
#SBATCH --partition=<queue name>
#SBATCH --tasks-per-node=1
#SBATCH --cpus-per-task=1

nodes=1
tasks_per_node=1
nthreads=1
ncpu=`echo $nodes $tasks_per_node | awk '{print $1*$2}'`

module purge
module load <needed modules>
module load <more modules>
bindir=<path to yambo bindir>

export OMP_NUM_THREADS=$nthreads

label=MPI${ncpu}_OMP${nthreads}
jdir=run_${label}
cdir=run_${label}.out

filein0=yambo_gw.in
filein=yambo_gw_${label}.in

cp -f $filein0 $filein
cat >> $filein << EOF

DIP_CPU= "1 $ncpu 1" # [PARALLEL] CPUs for each role
DIP_ROLEs= "k c v" # [PARALLEL] CPUs roles (k,c,v)
DIP_Threads= 0 # [OPENMP/X] Number of threads for dipoles
X_CPU= "1 1 1 $ncpu 1" # [PARALLEL] CPUs for each role
X_ROLEs= "q g k c v" # [PARALLEL] CPUs roles (q,g,k,c,v)
X_nCPU_LinAlg_INV= $ncpu # [PARALLEL] CPUs for Linear Algebra
X_Threads= 0 # [OPENMP/X] Number of threads for response functions
SE_CPU= " 1 $ncpu 1" # [PARALLEL] CPUs for each role
SE_ROLEs= "q qp b" # [PARALLEL] CPUs roles (q,qp,b)
SE_Threads= 0

EOF

echo "Running on $ncpu MPI, $nthreads OpenMP threads"
mpirun -np $ncpu $bindir/yambo -F $filein -J $jdir -C $cdir

As soon as you are ready to submit the job.

$ sbatch run.sh

Yambo calculates the GW-qp corrections running on 1 MPI process with a single thread.
As you can see, monitoring the log file produced by yambo, the run takes some time, although
we are using minimal parameters.

The status of the jobs can be monitored via:
$ squeue -u $USER # to inspect the status of jobs
# (hint: make a unix alias, if you like)
$ scancel <jobid> # to delete jobs in the queue

== Pure MPI scaling with default parallelization scheme ==

Meanwhile we can run the code in parallel. Let's use consider the case of a node having 16 cores (you can try to adapt the following discussion to the actual maximum number of
cores/node you have in your system). As a first run, we'll use 16 MPI tasks, still with a single thread.
To this end modify the run.sh script changing
#SBATCH --tasks-per-node=16
#SBATCH --cpus-per-task=1

ntasks_per_node=16
nthreads=1

This time the code should be much faster.
Once the run is over try to run the simulation also on 2, 4, 8 MPI tasks.
Each time, please remember to change both the number of tasks per node both in the header and in the <code>ntasks_per_node</code> variable.
Finally, you can try to produce a scaling plot.

To analyze the data you can use the phyton script parse_ytiming.py run which is provided.

You can use it running
$ ./parse_ytiming.py run*/r-*

You should obtain something like that (but with more columns)
# ncores dip Xo X io_X io_WF Sgm_x Sgm_c (REDUX) WALL_TIME
1 4.7337s 13m39.00s 0.1500s 0.0241s 0.2487s 34.2143s 15m7.00s 0.0000s 29m29s
4 1.6019s 218.7982s 0.0882s 0.0283s 0.2077s 9.3338s 242.4438s 0.0001s 07m54s
8 1.0755s 127.3209s 0.0974s 0.0291s 0.2134s 5.4490s 140.7788s 0.6926s 04m38s
12 0.7510s 89.1649s 0.1015s 0.0299s 0.2068s 4.2961s 109.1227s 0.0007s 03m26s
16 0.7653s 68.2550s 0.1048s 0.0309s 0.2463s 2.9211s 72.6220s 0.2799s 02m27s

Plot the execution time vs the number of MPI tasks
and check (do a log plot) how far you are from the ideal linear scaling.
Below a similar plot produced on a local cluster equipped with two Intel(R) Xeon(R) Silver 4208 CPU @ 2.10GHz processors per node (16 physical cares/node).
[[File:scaling_MPI_corvina.jpg|750px|center]]

'''tips:''' 
* not all runlevels scale in in the same way 
* you should never overload the available number of cores

== Pure OpenMP scaling ==

Next step is instead to check the OpenMP scaling.
Set back
#SBATCH --tasks-per-node=1
#SBATCH --cpus-per-task=16
and now use
ntasks_per_node=1
nthreads=16

Since we are already using 16 threads, we cannot also distribute among MPI tasks, i.e. ncpu will result equal to 1.
Try setting nthreads to 16, 8, 4 and 2 and again to plot the execution time vs the number of threads using the python script.
Again you should be able to produce data similar to the following. In the following we stopped increasing the number of threads up to 8 because of the
specific architecture used in the runs (a dual socket machine with 8 cores/socket).

# ncores threads dip Xo X io_X io_WF Sgm_x Sgm_c WALL_TIME
1 1 4.7337s 13m39.00s 0.1500s 0.0241s 0.2487s 34.2143s 15m7.00s 29m29s
2 2 3.1971s 549.1491s 0.2248s 0.0298s 0.2491s 17.6552s 584.3692s 19m17s
4 4 2.9419s 358.5202s 0.1928s 0.0289s 0.2590s 9.2010s 421.2219s 13m15s
8 8 2.7992s 344.3342s 0.2332s 0.0325s 0.2543s 5.4334s 362.6982s 11m58s

'''tips:''' 
* OpenMP usually shares the memory among threads, but not always 
* you should never overload the available number of cores 
* in principle, we could overload the cores setting more threads than the available total number of cores since a single core allows multi-thread operations

== MPI vs OpenMP scaling ==

Which is scaling better ? MPI or OpenMP?
How is the memory distributed?

Now you can try running simulations with hybrid strategies.
Try for example setting:

#SBATCH --tasks-per-node=8
#SBATCH --cpus-per-task=2

ntasks_per_node= 8
nthreads= 2

We can try to do scaling keeping the total number of threads per node (ntasks_per_node * nthreads) equal to 16.
Parsing the data we will obtain something similar to

# ncores MPI threads dip Xo X io_X io_WF Sgm_x Sgm_c WALL_TIME
16 2 8 3.6816s 386.0552s 0.0856s 0.0268s 0.2163s 18.9077s 530.0875s 15m43s
16 4 4 0.9950s 82.5070s 0.1098s 0.0299s 0.2051s 3.0837s 122.6565s 03m32s
16 8 2 0.8524s 72.6708s 0.0986s 0.0293s 0.2282s 3.0379s 88.1589s 02m48s
16 16 1 0.7653s 68.2550s 0.1048s 0.0309s 0.2463s 2.9211s 72.6220s 02m27s

As you can see here the total CPU time decreases more and more moving the parallelization from the OpenMP to the MPI level.
Sigma_c in particular scales better. Nevertheless, note that the relative performance of the different parallel configurations
may strongly depend on the actual machine you are running on.

However, CPU time is not the only parameter you need to check.
Also, the total memory usage is important
If you compare for example the two extreme cases (you can use)
$ grep Gb run_MPI1_OMP*/l* | grep Alloc (use this for the case with only one MPI proc)
$ grep Gb run_MPI*_OMP*/LOG/l*_1 | grep Alloc (use this for the case with more than one MPI proc)

For the case
# ncores MPI threads
16 1 16
<01s> [M 0.119 Gb] Alloc WF ( 0.112)
<03s> [M 0.314 Gb] Alloc WF ( 0.306)
<46s> [M 0.074 Gb] Alloc WF ( 0.056)
<50s> [M 0.321 Gb] Alloc WF ( 0.306)
the numbers reported above refer to the total amount of memory use in the run.

For the case
# ncores MPI threads
16 16 1
<02s> P0001: [M 0.034 Gb] Alloc WF ( 0.026)
<43s> P0001: [M 0.037 Gb] Alloc WF ( 0.019)
<45s> P0001: [M 0.091 Gb] Alloc WF ( 0.076)
the numbers reported above refer to the total amount of memory per MPI task.
Multiplying by 16 you obtain an estimate of the total memory: 0.091*16=1.456 (0.076*16=1.216)
These last two numbers have to be compared with 0.321 (0.306)
As you can see yambo is distributing memory since the single MPI task uses less memory than
the total one needed (you can even compare with the serial case). However, it is not as efficient as
OpenMP in doing so.

Using a hybrid scheme you may also consider running yambo on mode than one node.
To run on two nodes for example you need to set
#SBATCH -N 2

nodes=2
accordingly you can now set
nthreads= 4
This time you will use 32 cores with (16 per node) 4 OpenMP threads and 2*16/4=8 MPI tasks.

'''tips:''' 
- in real life calculations running on n_cores > 100, it is a good idea to adopt a hybrid approach 
- with OpenMP, you cannot exit the single node, with MPI you can

== Advanced: Comparing different parallelization schemes (optional) ==

Up to now we used the default parallelization scheme.
Yambo also allows you to tune the parameters which controls the parallelization scheme.
To this end you can open again the job.sh script and modify the section where the yambo input
variables are set

X_CPU= "1 1 1 $ncpu 1" # [PARALLEL] CPUs for each role
X_ROLEs= "q g k c v" # [PARALLEL] CPUs roles (q,g,k,c,v)
#X_nCPU_LinAlg_INV= $ncpu # [PARALLEL] CPUs for Linear Algebra
X_Threads= 0 # [OPENMP/X] Number of threads for response functions
DIP_Threads= 0 # [OPENMP/X] Number of threads for dipoles
SE_CPU= "1 1 $ncpu" # [PARALLEL] CPUs for each role
SE_ROLEs= "q qp b" # [PARALLEL] CPUs roles (q,qp,b)
SE_Threads= 0

In particular "X_CPU" sets how the MPI Tasks are distributed in the calculation of the response function.
The possibilities are shown in the "X_ROLEs". The same holds for "SE_CPU" and "SE_ROLEs" which control
how MPI Tasks are distributed in the calculation of the response function.

Please try different parallelization schemes and check the performances of Yambo.
In doing so you should also change the jobname in the run.sh script
label=MPI${ncpu}_OMP${nthreads}_scheme1

Using the python script, you can then chenck how speed, memory and load balance between the CPUs are affected.
For more details see also the [[Using_Yambo_in_parallel|Parallel module]]

'''tips: '''
* the product of the numbers entering each variable (i.e. X_CPU and SE_CPU) times the number of threads should always match the total number of cores (unless you want to overload the cores taking advantage of multi-threads) 
* using the X_Threads and SE_Threads variables you can think about setting different Hybrid schemes in between the screening and the self-energy runlevel.
* memory better scales if you parallelize on bands (c v b) 
* parallelization on k-points performs similarly to parallelization on bands, but memory requires more memory 
* parallelization on q-points requires much less communication in between the MPI tasks. It maybe useful if you run on more than one node and the inter-node connection is slow

 
{| 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]] --> [[GW_parallel_strategies|GW Parallel]]
|style="width:35%; text-align:right"|Next: [[Pushing_convergence_in_parallel|GW Convergence]]
|-
|}

GW parallel strategies

2020-01-28T14:44:36Z

Aferretti: /* Pure OpenMP scaling */

'''This modules contains very general discussions of the parallel environment of Yambo.

In this tutorial we will see how to setup the variables governing the parallel execution of yambo in order to perform efficient calculations in terms of both cpu time and memory to solution. As a test case we will consider the hBN 2D material. Because of its reduced dimensionality, GW calculations turns out to be very delicate. Beside the usual convergence studies with respect to k-points and sums-over-bands, in low dimensional systems a sensible amount of vacuum is required in order to treat the system as isolated, translating into a large number of plane-waves. As for other tutorials, it is important to stress that this tutorial it is meant to illustrate the functionality of the key variables and to run in reasonable time, so it has not the purpose to reach the desired accuracy to reproduce experimental results. Moreover please also note that scaling performance illustrated below may be significantly dependent on the underlying parallel architecture. Nevertheless, general considerations are tentatively drawn in discussing the results.

==Files and Tools==
Database and tools can be downloaded here:

*[http://www.yambo-code.org/educational/tutorials/files/hBN-2D-para.tar.gz hBN-2D-para.tar.gz]


== Getting familiar with yambo in parallel ==

Let's start by copying the tutorial files in the cluster and unzip them in the folder you will run the tutorial.
$ mkdir YAMBO_TUTORIALS
$ cd YAMBO_TUTORIALS
$ cp $path/hBN-2D-para.tar.gz ./
$ tar -zxvf hBN-2D-para.tar.gz
$ cd ./hBN-2D-para/YAMBO
Under the YAMBO folder, together with the SAVE folder, you will see the run.sh script

$ ls
parse_qp.py parse_ytiming.py SAVE

First, run the initialization as usual.
Then you need to generate the input file for a GW run.
$ yambo -g n -p p -F yambo_gw.in
After setting the variables in red, the new input file should look like the following:
$ cat yambo_gw.in

ppa # [R Xp] Plasmon Pole Approximation
gw0 # [R GW] GoWo Quasiparticle energy levels
HF_and_locXC # [R XX] Hartree-Fock Self-energy and Vxc
em1d # [R Xd] Dynamical Inverse Dielectric Matrix
X_Threads= 0 # [OPENMP/X] Number of threads for response functions
DIP_Threads= 0 # [OPENMP/X] Number of threads for dipoles
SE_Threads= 0 # [OPENMP/GW] Number of threads for self-energy
EXXRLvcs= 21817 RL # [XX] Exchange RL components
VXCRLvcs= 21817 RL # [XC] XCpotential RL components
Chimod= "" # [X] IP/Hartree/ALDA/LRC/BSfxc
% BndsRnXp
1 | 300 | # [Xp] Polarization function bands
%
NGsBlkXp= 4 Ry # [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 | 300 | # [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
1| 4| 1| 8|
%

Now you need to create a submission script. here below an example (run.sh) based on the SLURM scheduler. In the case of other schedulers, the header should be updated accordingly.
$ cat run.sh

#!/bin/bash
#SBATCH -N 1
#SBATCH -t 06:00:00
#SBATCH -J test
#SBATCH --partition=<queue name>
#SBATCH --tasks-per-node=1
#SBATCH --cpus-per-task=1

nodes=1
tasks_per_node=1
nthreads=1
ncpu=`echo $nodes $tasks_per_node | awk '{print $1*$2}'`

module purge
module load <needed modules>
module load <more modules>
bindir=<path to yambo bindir>

export OMP_NUM_THREADS=$nthreads

label=MPI${ncpu}_OMP${nthreads}
jdir=run_${label}
cdir=run_${label}.out

filein0=yambo_gw.in
filein=yambo_gw_${label}.in

cp -f $filein0 $filein
cat >> $filein << EOF

DIP_CPU= "1 $ncpu 1" # [PARALLEL] CPUs for each role
DIP_ROLEs= "k c v" # [PARALLEL] CPUs roles (k,c,v)
DIP_Threads= 0 # [OPENMP/X] Number of threads for dipoles
X_CPU= "1 1 1 $ncpu 1" # [PARALLEL] CPUs for each role
X_ROLEs= "q g k c v" # [PARALLEL] CPUs roles (q,g,k,c,v)
X_nCPU_LinAlg_INV= $ncpu # [PARALLEL] CPUs for Linear Algebra
X_Threads= 0 # [OPENMP/X] Number of threads for response functions
SE_CPU= " 1 $ncpu 1" # [PARALLEL] CPUs for each role
SE_ROLEs= "q qp b" # [PARALLEL] CPUs roles (q,qp,b)
SE_Threads= 0

EOF

echo "Running on $ncpu MPI, $nthreads OpenMP threads"
mpirun -np $ncpu $bindir/yambo -F $filein -J $jdir -C $cdir

As soon as you are ready to submit the job.

$ sbatch run.sh

Yambo calculates the GW-qp corrections running on 1 MPI process with a single thread.
As you can see, monitoring the log file produced by yambo, the run takes some time, although
we are using minimal parameters.

The status of the jobs can be monitored via:
$ squeue -u $USER # to inspect the status of jobs
# (hint: make a unix alias, if you like)
$ scancel <jobid> # to delete jobs in the queue

== Pure MPI scaling with default parallelization scheme ==

Meanwhile we can run the code in parallel. Let's use consider the case of a node having 16 cores (you can try to adapt the following discussion to the actual maximum number of
cores/node you have in your system). As a first run, we'll use 16 MPI tasks, still with a single thread.
To this end modify the run.sh script changing
#SBATCH --tasks-per-node=16
#SBATCH --cpus-per-task=1

ntasks_per_node=16
nthreads=1

This time the code should be much faster.
Once the run is over try to run the simulation also on 2, 4, 8 MPI tasks.
Each time, please remember to change both the number of tasks per node both in the header and in the <code>ntasks_per_node</code> variable.
Finally, you can try to produce a scaling plot.

To analyze the data you can use the phyton script parse_ytiming.py run which is provided.

You can use it running
$ ./parse_ytiming.py run*/r-*

You should obtain something like that (but with more columns)
# ncores dip Xo X io_X io_WF Sgm_x Sgm_c (REDUX) WALL_TIME
1 4.7337s 13m39.00s 0.1500s 0.0241s 0.2487s 34.2143s 15m7.00s 0.0000s 29m29s
4 1.6019s 218.7982s 0.0882s 0.0283s 0.2077s 9.3338s 242.4438s 0.0001s 07m54s
8 1.0755s 127.3209s 0.0974s 0.0291s 0.2134s 5.4490s 140.7788s 0.6926s 04m38s
12 0.7510s 89.1649s 0.1015s 0.0299s 0.2068s 4.2961s 109.1227s 0.0007s 03m26s
16 0.7653s 68.2550s 0.1048s 0.0309s 0.2463s 2.9211s 72.6220s 0.2799s 02m27s

Plot the execution time vs the number of MPI tasks
and check (do a log plot) how far you are from the ideal linear scaling.
Below a similar plot produced on a local cluster equipped with two Intel(R) Xeon(R) Silver 4208 CPU @ 2.10GHz processors per node (16 physical cares/node).
[[File:scaling_MPI_corvina.jpg|750px|center]]

'''tips:''' 
* not all runlevels scale in in the same way 
* you should never overload the available number of cores

== Pure OpenMP scaling ==

Next step is instead to check the OpenMP scaling.
Set back
#SBATCH --tasks-per-node=1
#SBATCH --cpus-per-task=16
and now use
ntasks_per_node=1
nthreads=16

Since we are already using 16 threads, we cannot also distribute among MPI tasks, i.e. ncpu will result equal to 1.
Try setting nthreads to 16, 8, 4 and 2 and again to plot the execution time vs the number of threads using the python script.
Again you should be able to produce data similar to the following. In the following we stopped increasing the number of threads up to 8 because of the
specific architecture used in the runs (a dual socket machine with 8 cores/socket).

# ncores threads dip Xo X io_X io_WF Sgm_x Sgm_c WALL_TIME
1 1 4.7337s 13m39.00s 0.1500s 0.0241s 0.2487s 34.2143s 15m7.00s 29m29s
2 2 3.1971s 549.1491s 0.2248s 0.0298s 0.2491s 17.6552s 584.3692s 19m17s
4 4 2.9419s 358.5202s 0.1928s 0.0289s 0.2590s 9.2010s 421.2219s 13m15s
8 8 2.7992s 344.3342s 0.2332s 0.0325s 0.2543s 5.4334s 362.6982s 11m58s

'''tips:''' 
* OpenMP usually shares the memory among threads, but not always 
* you should never overload the available number of cores 
* in principle, we could overload the cores setting more threads than the available total number of cores since a single core allows multi-thread operations

== MPI vs OpenMP scaling ==

Which is scaling better ? MPI or OpenMP?
How is the memory distributed?

Now you can try running simulations with hybrid strategies.
Try for example setting:

#SBATCH --tasks-per-node=8
#SBATCH --cpus-per-task=2

ntasks_per_node= 8
nthreads= 2

We can try to do scaling keeping the total number of threads per node (ntasks_per_node * nthreads) equal to 16.
Parsing the data we will obtain something similar to

# ncores MPI threads Dipoles Xo X Sgm_x Sgm_c WALL_TIME
16 1 16 1.00s 38.00s 0.00s 2.00s 33.00s 01m25s
16 2 8 2.00s 34.00s 0.00s 1.00s 16.00s 01m06s
16 4 4 0.00s 34.00s 0.00s 1.00s 11.00s 56s
16 8 2 0.00s 33.00s 0.00s 0.00s 9.00s 52s
16 16 1 0.00s 35.00s 0.00s 0.00s 7.00s 54s

As you can see here the total CPU time decreases more and more moving the parallelization from the OpenMP to the MPI level.
Sigma_c in particular scales better. However, the fastest run is not the one with 16 MPI task but the 8 2 configuration
since Xo is faster using a hybrid MPI-OpenMP scheme.

However, CPU time is not the only parameter you need to check.
Also, the total memory usage is important
If you compare for example the two extreme cases (you can use)
$ grep Gb run_MPI1_OMP*/l* | grep Alloc (use this for the case with only one MPI proc)
$ grep Gb run_MPI*_OMP*/LOG/l*_1 | grep Alloc (use this for the case with more than one MPI proc)

For the case
# ncores MPI threads
16 1 16
<01s> [M 0.119 Gb] Alloc WF ( 0.112)
<03s> [M 0.314 Gb] Alloc WF ( 0.306)
<46s> [M 0.074 Gb] Alloc WF ( 0.056)
<50s> [M 0.321 Gb] Alloc WF ( 0.306)
the numbers reported above refer to the total amount of memory use in the run.

For the case
# ncores MPI threads
16 16 1
<02s> P0001: [M 0.034 Gb] Alloc WF ( 0.026)
<43s> P0001: [M 0.037 Gb] Alloc WF ( 0.019)
<45s> P0001: [M 0.091 Gb] Alloc WF ( 0.076)
the numbers reported above refer to the total amount of memory per MPI task.
Multiplying by 16 you obtain an estimate of the total memory: 0.091*16=1.456 (0.076*16=1.216)
These last two numbers have to be compared with 0.321 (0.306)
As you can see yambo is distributing memory since the single MPI task uses less memory than
the total one needed (you can even compare with the serial case). However, it is not as efficient as
OpenMP in doing so.

Using a hybrid scheme you may also consider running yambo on mode than one node.
To run on two nodes for example you need to set
#SBATCH -N 2

nodes=2
accordingly you can now set
nthreads= 4
This time you will use 32 cores with (16 per node) 4 OpenMP threads and 2*16/4=8 MPI tasks.

'''tips:''' 
- in real life calculations running on n_cores > 100, it is a good idea to adopt a hybrid approach 
- with OpenMP, you cannot exit the single node, with MPI you can

== Advanced: Comparing different parallelization schemes (optional) ==

Up to now we used the default parallelization scheme.
Yambo also allows you to tune the parameters which controls the parallelization scheme.
To this end you can open again the job.sh script and modify the section where the yambo input
variables are set

X_CPU= "1 1 1 $ncpu 1" # [PARALLEL] CPUs for each role
X_ROLEs= "q g k c v" # [PARALLEL] CPUs roles (q,g,k,c,v)
#X_nCPU_LinAlg_INV= $ncpu # [PARALLEL] CPUs for Linear Algebra
X_Threads= 0 # [OPENMP/X] Number of threads for response functions
DIP_Threads= 0 # [OPENMP/X] Number of threads for dipoles
SE_CPU= "1 1 $ncpu" # [PARALLEL] CPUs for each role
SE_ROLEs= "q qp b" # [PARALLEL] CPUs roles (q,qp,b)
SE_Threads= 0

In particular "X_CPU" sets how the MPI Tasks are distributed in the calculation of the response function.
The possibilities are shown in the "X_ROLEs". The same holds for "SE_CPU" and "SE_ROLEs" which control
how MPI Tasks are distributed in the calculation of the response function.

Please try different parallelization schemes and check the performances of Yambo.
In doing so you should also change the jobname in the run.sh script
label=MPI${ncpu}_OMP${nthreads}_scheme1

Using the python script, you can then chenck how speed, memory and load balance between the CPUs are affected.
For more details see also the [[Using_Yambo_in_parallel|Parallel module]]

'''tips: '''
* the product of the numbers entering each variable (i.e. X_CPU and SE_CPU) times the number of threads should always match the total number of cores (unless you want to overload the cores taking advantage of multi-threads) 
* using the X_Threads and SE_Threads variables you can think about setting different Hybrid schemes in between the screening and the self-energy runlevel.
* memory better scales if you parallelize on bands (c v b) 
* parallelization on k-points performs similarly to parallelization on bands, but memory requires more memory 
* parallelization on q-points requires much less communication in between the MPI tasks. It maybe useful if you run on more than one node and the inter-node connection is slow

 
{| 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]] --> [[GW_parallel_strategies|GW Parallel]]
|style="width:35%; text-align:right"|Next: [[Pushing_convergence_in_parallel|GW Convergence]]
|-
|}

File:Scaling MPI corvina.jpg

2020-01-28T14:42:47Z

Aferretti: Aferretti uploaded a new version of File:Scaling MPI corvina.jpg

=={{int:filedesc}}==
{{Information
|description={{en|1=Yambo tutorial image, MPI scaling, corvina}}
|date=2020-01-28
|source={{own}}
|author=[[User:Aferretti|Aferretti]]
|permission=
|other versions=
}}

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

This file was uploaded with the UploadWizard extension.

[[Category:Uploaded with UploadWizard]]

GW parallel strategies

2020-01-28T14:35:54Z

Aferretti: /* MPI vs OpenMP scaling */

'''This modules contains very general discussions of the parallel environment of Yambo.

In this tutorial we will see how to setup the variables governing the parallel execution of yambo in order to perform efficient calculations in terms of both cpu time and memory to solution. As a test case we will consider the hBN 2D material. Because of its reduced dimensionality, GW calculations turns out to be very delicate. Beside the usual convergence studies with respect to k-points and sums-over-bands, in low dimensional systems a sensible amount of vacuum is required in order to treat the system as isolated, translating into a large number of plane-waves. As for other tutorials, it is important to stress that this tutorial it is meant to illustrate the functionality of the key variables and to run in reasonable time, so it has not the purpose to reach the desired accuracy to reproduce experimental results. Moreover please also note that scaling performance illustrated below may be significantly dependent on the underlying parallel architecture. Nevertheless, general considerations are tentatively drawn in discussing the results.

==Files and Tools==
Database and tools can be downloaded here:

*[http://www.yambo-code.org/educational/tutorials/files/hBN-2D-para.tar.gz hBN-2D-para.tar.gz]


== Getting familiar with yambo in parallel ==

Let's start by copying the tutorial files in the cluster and unzip them in the folder you will run the tutorial.
$ mkdir YAMBO_TUTORIALS
$ cd YAMBO_TUTORIALS
$ cp $path/hBN-2D-para.tar.gz ./
$ tar -zxvf hBN-2D-para.tar.gz
$ cd ./hBN-2D-para/YAMBO
Under the YAMBO folder, together with the SAVE folder, you will see the run.sh script

$ ls
parse_qp.py parse_ytiming.py SAVE

First, run the initialization as usual.
Then you need to generate the input file for a GW run.
$ yambo -g n -p p -F yambo_gw.in
After setting the variables in red, the new input file should look like the following:
$ cat yambo_gw.in

ppa # [R Xp] Plasmon Pole Approximation
gw0 # [R GW] GoWo Quasiparticle energy levels
HF_and_locXC # [R XX] Hartree-Fock Self-energy and Vxc
em1d # [R Xd] Dynamical Inverse Dielectric Matrix
X_Threads= 0 # [OPENMP/X] Number of threads for response functions
DIP_Threads= 0 # [OPENMP/X] Number of threads for dipoles
SE_Threads= 0 # [OPENMP/GW] Number of threads for self-energy
EXXRLvcs= 21817 RL # [XX] Exchange RL components
VXCRLvcs= 21817 RL # [XC] XCpotential RL components
Chimod= "" # [X] IP/Hartree/ALDA/LRC/BSfxc
% BndsRnXp
1 | 300 | # [Xp] Polarization function bands
%
NGsBlkXp= 4 Ry # [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 | 300 | # [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
1| 4| 1| 8|
%

Now you need to create a submission script. here below an example (run.sh) based on the SLURM scheduler. In the case of other schedulers, the header should be updated accordingly.
$ cat run.sh

#!/bin/bash
#SBATCH -N 1
#SBATCH -t 06:00:00
#SBATCH -J test
#SBATCH --partition=<queue name>
#SBATCH --tasks-per-node=1
#SBATCH --cpus-per-task=1

nodes=1
tasks_per_node=1
nthreads=1
ncpu=`echo $nodes $tasks_per_node | awk '{print $1*$2}'`

module purge
module load <needed modules>
module load <more modules>
bindir=<path to yambo bindir>

export OMP_NUM_THREADS=$nthreads

label=MPI${ncpu}_OMP${nthreads}
jdir=run_${label}
cdir=run_${label}.out

filein0=yambo_gw.in
filein=yambo_gw_${label}.in

cp -f $filein0 $filein
cat >> $filein << EOF

DIP_CPU= "1 $ncpu 1" # [PARALLEL] CPUs for each role
DIP_ROLEs= "k c v" # [PARALLEL] CPUs roles (k,c,v)
DIP_Threads= 0 # [OPENMP/X] Number of threads for dipoles
X_CPU= "1 1 1 $ncpu 1" # [PARALLEL] CPUs for each role
X_ROLEs= "q g k c v" # [PARALLEL] CPUs roles (q,g,k,c,v)
X_nCPU_LinAlg_INV= $ncpu # [PARALLEL] CPUs for Linear Algebra
X_Threads= 0 # [OPENMP/X] Number of threads for response functions
SE_CPU= " 1 $ncpu 1" # [PARALLEL] CPUs for each role
SE_ROLEs= "q qp b" # [PARALLEL] CPUs roles (q,qp,b)
SE_Threads= 0

EOF

echo "Running on $ncpu MPI, $nthreads OpenMP threads"
mpirun -np $ncpu $bindir/yambo -F $filein -J $jdir -C $cdir

As soon as you are ready to submit the job.

$ sbatch run.sh

Yambo calculates the GW-qp corrections running on 1 MPI process with a single thread.
As you can see, monitoring the log file produced by yambo, the run takes some time, although
we are using minimal parameters.

The status of the jobs can be monitored via:
$ squeue -u $USER # to inspect the status of jobs
# (hint: make a unix alias, if you like)
$ scancel <jobid> # to delete jobs in the queue

== Pure MPI scaling with default parallelization scheme ==

Meanwhile we can run the code in parallel. Let's use consider the case of a node having 16 cores (you can try to adapt the following discussion to the actual maximum number of
cores/node you have in your system). As a first run, we'll use 16 MPI tasks, still with a single thread.
To this end modify the run.sh script changing
#SBATCH --tasks-per-node=16
#SBATCH --cpus-per-task=1

ntasks_per_node=16
nthreads=1

This time the code should be much faster.
Once the run is over try to run the simulation also on 2, 4, 8 MPI tasks.
Each time, please remember to change both the number of tasks per node both in the header and in the <code>ntasks_per_node</code> variable.
Finally, you can try to produce a scaling plot.

To analyze the data you can use the phyton script parse_ytiming.py run which is provided.

You can use it running
$ ./parse_ytiming.py run*/r-*

You should obtain something like that (but with more columns)
# ncores dip Xo X io_X io_WF Sgm_x Sgm_c (REDUX) WALL_TIME
1 4.7337s 13m39.00s 0.1500s 0.0241s 0.2487s 34.2143s 15m7.00s 0.0000s 29m29s
4 1.6019s 218.7982s 0.0882s 0.0283s 0.2077s 9.3338s 242.4438s 0.0001s 07m54s
8 1.0755s 127.3209s 0.0974s 0.0291s 0.2134s 5.4490s 140.7788s 0.6926s 04m38s
12 0.7510s 89.1649s 0.1015s 0.0299s 0.2068s 4.2961s 109.1227s 0.0007s 03m26s
16 0.7653s 68.2550s 0.1048s 0.0309s 0.2463s 2.9211s 72.6220s 0.2799s 02m27s

Plot the execution time vs the number of MPI tasks
and check (do a log plot) how far you are from the ideal linear scaling.
Below a similar plot produced on a local cluster equipped with two Intel(R) Xeon(R) Silver 4208 CPU @ 2.10GHz processors per node (16 physical cares/node).
[[File:scaling_MPI_corvina.jpg|750px|center]]

'''tips:''' 
* not all runlevels scale in in the same way 
* you should never overload the available number of cores

== Pure OpenMP scaling ==

Next step is instead to check the OpenMP scaling.
Set back
#SBATCH --tasks-per-node=1
#SBATCH --cpus-per-task=16
and now use
ntasks_per_node=1
nthreads=16

Since we are already using 16 threads, we cannot also distribute among MPI tasks, i.e. ncpu will result equal to 1.
Try setting nthreads to 16, 8, 4 and 2 and again to plot the execution time vs the number of threads using the python script.
Again you should be able to produce data similar to the following

# ncores threads dip Xo X io_X io_WF Sgm_x Sgm_c WALL_TIME
1 1 4.7337s 13m39.00s 0.1500s 0.0241s 0.2487s 34.2143s 15m7.00s 29m29s
2 2 3.1971s 549.1491s 0.2248s 0.0298s 0.2491s 17.6552s 584.3692s 19m17s
4 4 2.9419s 358.5202s 0.1928s 0.0289s 0.2590s 9.2010s 421.2219s 13m15s
8 8 2.7992s 344.3342s 0.2332s 0.0325s 0.2543s 5.4334s 362.6982s 11m58s

'''tips:''' 
* OpenMP usually shares the memory among threads, but not always 
* you should never overload the available number of cores 
* in principle, we could overload the cores setting more threads than the available total number of cores since a single core allows multi-thread operations

== MPI vs OpenMP scaling ==

Which is scaling better ? MPI or OpenMP?
How is the memory distributed?

Now you can try running simulations with hybrid strategies.
Try for example setting:

#SBATCH --tasks-per-node=8
#SBATCH --cpus-per-task=2

ntasks_per_node= 8
nthreads= 2

We can try to do scaling keeping the total number of threads per node (ntasks_per_node * nthreads) equal to 16.
Parsing the data we will obtain something similar to

# ncores MPI threads Dipoles Xo X Sgm_x Sgm_c WALL_TIME
16 1 16 1.00s 38.00s 0.00s 2.00s 33.00s 01m25s
16 2 8 2.00s 34.00s 0.00s 1.00s 16.00s 01m06s
16 4 4 0.00s 34.00s 0.00s 1.00s 11.00s 56s
16 8 2 0.00s 33.00s 0.00s 0.00s 9.00s 52s
16 16 1 0.00s 35.00s 0.00s 0.00s 7.00s 54s

As you can see here the total CPU time decreases more and more moving the parallelization from the OpenMP to the MPI level.
Sigma_c in particular scales better. However, the fastest run is not the one with 16 MPI task but the 8 2 configuration
since Xo is faster using a hybrid MPI-OpenMP scheme.

However, CPU time is not the only parameter you need to check.
Also, the total memory usage is important
If you compare for example the two extreme cases (you can use)
$ grep Gb run_MPI1_OMP*/l* | grep Alloc (use this for the case with only one MPI proc)
$ grep Gb run_MPI*_OMP*/LOG/l*_1 | grep Alloc (use this for the case with more than one MPI proc)

For the case
# ncores MPI threads
16 1 16
<01s> [M 0.119 Gb] Alloc WF ( 0.112)
<03s> [M 0.314 Gb] Alloc WF ( 0.306)
<46s> [M 0.074 Gb] Alloc WF ( 0.056)
<50s> [M 0.321 Gb] Alloc WF ( 0.306)
the numbers reported above refer to the total amount of memory use in the run.

For the case
# ncores MPI threads
16 16 1
<02s> P0001: [M 0.034 Gb] Alloc WF ( 0.026)
<43s> P0001: [M 0.037 Gb] Alloc WF ( 0.019)
<45s> P0001: [M 0.091 Gb] Alloc WF ( 0.076)
the numbers reported above refer to the total amount of memory per MPI task.
Multiplying by 16 you obtain an estimate of the total memory: 0.091*16=1.456 (0.076*16=1.216)
These last two numbers have to be compared with 0.321 (0.306)
As you can see yambo is distributing memory since the single MPI task uses less memory than
the total one needed (you can even compare with the serial case). However, it is not as efficient as
OpenMP in doing so.

Using a hybrid scheme you may also consider running yambo on mode than one node.
To run on two nodes for example you need to set
#SBATCH -N 2

nodes=2
accordingly you can now set
nthreads= 4
This time you will use 32 cores with (16 per node) 4 OpenMP threads and 2*16/4=8 MPI tasks.

'''tips:''' 
- in real life calculations running on n_cores > 100, it is a good idea to adopt a hybrid approach 
- with OpenMP, you cannot exit the single node, with MPI you can

== Advanced: Comparing different parallelization schemes (optional) ==

Up to now we used the default parallelization scheme.
Yambo also allows you to tune the parameters which controls the parallelization scheme.
To this end you can open again the job.sh script and modify the section where the yambo input
variables are set

X_CPU= "1 1 1 $ncpu 1" # [PARALLEL] CPUs for each role
X_ROLEs= "q g k c v" # [PARALLEL] CPUs roles (q,g,k,c,v)
#X_nCPU_LinAlg_INV= $ncpu # [PARALLEL] CPUs for Linear Algebra
X_Threads= 0 # [OPENMP/X] Number of threads for response functions
DIP_Threads= 0 # [OPENMP/X] Number of threads for dipoles
SE_CPU= "1 1 $ncpu" # [PARALLEL] CPUs for each role
SE_ROLEs= "q qp b" # [PARALLEL] CPUs roles (q,qp,b)
SE_Threads= 0

In particular "X_CPU" sets how the MPI Tasks are distributed in the calculation of the response function.
The possibilities are shown in the "X_ROLEs". The same holds for "SE_CPU" and "SE_ROLEs" which control
how MPI Tasks are distributed in the calculation of the response function.

Please try different parallelization schemes and check the performances of Yambo.
In doing so you should also change the jobname in the run.sh script
label=MPI${ncpu}_OMP${nthreads}_scheme1

Using the python script, you can then chenck how speed, memory and load balance between the CPUs are affected.
For more details see also the [[Using_Yambo_in_parallel|Parallel module]]

'''tips: '''
* the product of the numbers entering each variable (i.e. X_CPU and SE_CPU) times the number of threads should always match the total number of cores (unless you want to overload the cores taking advantage of multi-threads) 
* using the X_Threads and SE_Threads variables you can think about setting different Hybrid schemes in between the screening and the self-energy runlevel.
* memory better scales if you parallelize on bands (c v b) 
* parallelization on k-points performs similarly to parallelization on bands, but memory requires more memory 
* parallelization on q-points requires much less communication in between the MPI tasks. It maybe useful if you run on more than one node and the inter-node connection is slow

 
{| 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]] --> [[GW_parallel_strategies|GW Parallel]]
|style="width:35%; text-align:right"|Next: [[Pushing_convergence_in_parallel|GW Convergence]]
|-
|}

GW parallel strategies

2020-01-28T14:35:05Z

Aferretti: /* Pure OpenMP scaling */

'''This modules contains very general discussions of the parallel environment of Yambo.

In this tutorial we will see how to setup the variables governing the parallel execution of yambo in order to perform efficient calculations in terms of both cpu time and memory to solution. As a test case we will consider the hBN 2D material. Because of its reduced dimensionality, GW calculations turns out to be very delicate. Beside the usual convergence studies with respect to k-points and sums-over-bands, in low dimensional systems a sensible amount of vacuum is required in order to treat the system as isolated, translating into a large number of plane-waves. As for other tutorials, it is important to stress that this tutorial it is meant to illustrate the functionality of the key variables and to run in reasonable time, so it has not the purpose to reach the desired accuracy to reproduce experimental results. Moreover please also note that scaling performance illustrated below may be significantly dependent on the underlying parallel architecture. Nevertheless, general considerations are tentatively drawn in discussing the results.

==Files and Tools==
Database and tools can be downloaded here:

*[http://www.yambo-code.org/educational/tutorials/files/hBN-2D-para.tar.gz hBN-2D-para.tar.gz]


== Getting familiar with yambo in parallel ==

Let's start by copying the tutorial files in the cluster and unzip them in the folder you will run the tutorial.
$ mkdir YAMBO_TUTORIALS
$ cd YAMBO_TUTORIALS
$ cp $path/hBN-2D-para.tar.gz ./
$ tar -zxvf hBN-2D-para.tar.gz
$ cd ./hBN-2D-para/YAMBO
Under the YAMBO folder, together with the SAVE folder, you will see the run.sh script

$ ls
parse_qp.py parse_ytiming.py SAVE

First, run the initialization as usual.
Then you need to generate the input file for a GW run.
$ yambo -g n -p p -F yambo_gw.in
After setting the variables in red, the new input file should look like the following:
$ cat yambo_gw.in

ppa # [R Xp] Plasmon Pole Approximation
gw0 # [R GW] GoWo Quasiparticle energy levels
HF_and_locXC # [R XX] Hartree-Fock Self-energy and Vxc
em1d # [R Xd] Dynamical Inverse Dielectric Matrix
X_Threads= 0 # [OPENMP/X] Number of threads for response functions
DIP_Threads= 0 # [OPENMP/X] Number of threads for dipoles
SE_Threads= 0 # [OPENMP/GW] Number of threads for self-energy
EXXRLvcs= 21817 RL # [XX] Exchange RL components
VXCRLvcs= 21817 RL # [XC] XCpotential RL components
Chimod= "" # [X] IP/Hartree/ALDA/LRC/BSfxc
% BndsRnXp
1 | 300 | # [Xp] Polarization function bands
%
NGsBlkXp= 4 Ry # [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 | 300 | # [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
1| 4| 1| 8|
%

Now you need to create a submission script. here below an example (run.sh) based on the SLURM scheduler. In the case of other schedulers, the header should be updated accordingly.
$ cat run.sh

#!/bin/bash
#SBATCH -N 1
#SBATCH -t 06:00:00
#SBATCH -J test
#SBATCH --partition=<queue name>
#SBATCH --tasks-per-node=1
#SBATCH --cpus-per-task=1

nodes=1
tasks_per_node=1
nthreads=1
ncpu=`echo $nodes $tasks_per_node | awk '{print $1*$2}'`

module purge
module load <needed modules>
module load <more modules>
bindir=<path to yambo bindir>

export OMP_NUM_THREADS=$nthreads

label=MPI${ncpu}_OMP${nthreads}
jdir=run_${label}
cdir=run_${label}.out

filein0=yambo_gw.in
filein=yambo_gw_${label}.in

cp -f $filein0 $filein
cat >> $filein << EOF

DIP_CPU= "1 $ncpu 1" # [PARALLEL] CPUs for each role
DIP_ROLEs= "k c v" # [PARALLEL] CPUs roles (k,c,v)
DIP_Threads= 0 # [OPENMP/X] Number of threads for dipoles
X_CPU= "1 1 1 $ncpu 1" # [PARALLEL] CPUs for each role
X_ROLEs= "q g k c v" # [PARALLEL] CPUs roles (q,g,k,c,v)
X_nCPU_LinAlg_INV= $ncpu # [PARALLEL] CPUs for Linear Algebra
X_Threads= 0 # [OPENMP/X] Number of threads for response functions
SE_CPU= " 1 $ncpu 1" # [PARALLEL] CPUs for each role
SE_ROLEs= "q qp b" # [PARALLEL] CPUs roles (q,qp,b)
SE_Threads= 0

EOF

echo "Running on $ncpu MPI, $nthreads OpenMP threads"
mpirun -np $ncpu $bindir/yambo -F $filein -J $jdir -C $cdir

As soon as you are ready to submit the job.

$ sbatch run.sh

Yambo calculates the GW-qp corrections running on 1 MPI process with a single thread.
As you can see, monitoring the log file produced by yambo, the run takes some time, although
we are using minimal parameters.

The status of the jobs can be monitored via:
$ squeue -u $USER # to inspect the status of jobs
# (hint: make a unix alias, if you like)
$ scancel <jobid> # to delete jobs in the queue

== Pure MPI scaling with default parallelization scheme ==

Meanwhile we can run the code in parallel. Let's use consider the case of a node having 16 cores (you can try to adapt the following discussion to the actual maximum number of
cores/node you have in your system). As a first run, we'll use 16 MPI tasks, still with a single thread.
To this end modify the run.sh script changing
#SBATCH --tasks-per-node=16
#SBATCH --cpus-per-task=1

ntasks_per_node=16
nthreads=1

This time the code should be much faster.
Once the run is over try to run the simulation also on 2, 4, 8 MPI tasks.
Each time, please remember to change both the number of tasks per node both in the header and in the <code>ntasks_per_node</code> variable.
Finally, you can try to produce a scaling plot.

To analyze the data you can use the phyton script parse_ytiming.py run which is provided.

You can use it running
$ ./parse_ytiming.py run*/r-*

You should obtain something like that (but with more columns)
# ncores dip Xo X io_X io_WF Sgm_x Sgm_c (REDUX) WALL_TIME
1 4.7337s 13m39.00s 0.1500s 0.0241s 0.2487s 34.2143s 15m7.00s 0.0000s 29m29s
4 1.6019s 218.7982s 0.0882s 0.0283s 0.2077s 9.3338s 242.4438s 0.0001s 07m54s
8 1.0755s 127.3209s 0.0974s 0.0291s 0.2134s 5.4490s 140.7788s 0.6926s 04m38s
12 0.7510s 89.1649s 0.1015s 0.0299s 0.2068s 4.2961s 109.1227s 0.0007s 03m26s
16 0.7653s 68.2550s 0.1048s 0.0309s 0.2463s 2.9211s 72.6220s 0.2799s 02m27s

Plot the execution time vs the number of MPI tasks
and check (do a log plot) how far you are from the ideal linear scaling.
Below a similar plot produced on a local cluster equipped with two Intel(R) Xeon(R) Silver 4208 CPU @ 2.10GHz processors per node (16 physical cares/node).
[[File:scaling_MPI_corvina.jpg|750px|center]]

'''tips:''' 
* not all runlevels scale in in the same way 
* you should never overload the available number of cores

== Pure OpenMP scaling ==

Next step is instead to check the OpenMP scaling.
Set back
#SBATCH --tasks-per-node=1
#SBATCH --cpus-per-task=16
and now use
ntasks_per_node=1
nthreads=16

Since we are already using 16 threads, we cannot also distribute among MPI tasks, i.e. ncpu will result equal to 1.
Try setting nthreads to 16, 8, 4 and 2 and again to plot the execution time vs the number of threads using the python script.
Again you should be able to produce data similar to the following

# ncores threads dip Xo X io_X io_WF Sgm_x Sgm_c WALL_TIME
1 1 4.7337s 13m39.00s 0.1500s 0.0241s 0.2487s 34.2143s 15m7.00s 29m29s
2 2 3.1971s 549.1491s 0.2248s 0.0298s 0.2491s 17.6552s 584.3692s 19m17s
4 4 2.9419s 358.5202s 0.1928s 0.0289s 0.2590s 9.2010s 421.2219s 13m15s
8 8 2.7992s 344.3342s 0.2332s 0.0325s 0.2543s 5.4334s 362.6982s 11m58s

'''tips:''' 
* OpenMP usually shares the memory among threads, but not always 
* you should never overload the available number of cores 
* in principle, we could overload the cores setting more threads than the available total number of cores since a single core allows multi-thread operations

== MPI vs OpenMP scaling ==

Which is scaling better ? MPI or OpenMP?
How is the memory distributed?

Now you can try running simulations with hybrid strategies.
Try for example setting:

#SBATCH --tasks-per-node=8

ntasks_per_node= 8
nthreads= 2

We can try to do scaling keeping the total number of threads per node (ntasks_per_node * nthreads) equal to 16.
Parsing the data we will obtain something similar to

# ncores MPI threads Dipoles Xo X Sgm_x Sgm_c WALL_TIME
16 1 16 1.00s 38.00s 0.00s 2.00s 33.00s 01m25s
16 2 8 2.00s 34.00s 0.00s 1.00s 16.00s 01m06s
16 4 4 0.00s 34.00s 0.00s 1.00s 11.00s 56s
16 8 2 0.00s 33.00s 0.00s 0.00s 9.00s 52s
16 16 1 0.00s 35.00s 0.00s 0.00s 7.00s 54s

As you can see here the total CPU time decreases more and more moving the parallelization from the OpenMP to the MPI level.
Sigma_c in particular scales better. However, the fastest run is not the one with 16 MPI task but the 8 2 configuration
since Xo is faster using a hybrid MPI-OpenMP scheme.

However, CPU time is not the only parameter you need to check.
Also, the total memory usage is important
If you compare for example the two extreme cases (you can use)
$ grep Gb run_MPI1_OMP*/l* | grep Alloc (use this for the case with only one MPI proc)
$ grep Gb run_MPI*_OMP*/LOG/l*_1 | grep Alloc (use this for the case with more than one MPI proc)

For the case
# ncores MPI threads
16 1 16
<01s> [M 0.119 Gb] Alloc WF ( 0.112)
<03s> [M 0.314 Gb] Alloc WF ( 0.306)
<46s> [M 0.074 Gb] Alloc WF ( 0.056)
<50s> [M 0.321 Gb] Alloc WF ( 0.306)
the numbers reported above refer to the total amount of memory use in the run.

For the case
# ncores MPI threads
16 16 1
<02s> P0001: [M 0.034 Gb] Alloc WF ( 0.026)
<43s> P0001: [M 0.037 Gb] Alloc WF ( 0.019)
<45s> P0001: [M 0.091 Gb] Alloc WF ( 0.076)
the numbers reported above refer to the total amount of memory per MPI task.
Multiplying by 16 you obtain an estimate of the total memory: 0.091*16=1.456 (0.076*16=1.216)
These last two numbers have to be compared with 0.321 (0.306)
As you can see yambo is distributing memory since the single MPI task uses less memory than
the total one needed (you can even compare with the serial case). However, it is not as efficient as
OpenMP in doing so.

Using a hybrid scheme you may also consider running yambo on mode than one node.
To run on two nodes for example you need to set
#SBATCH -N 2

nodes=2
accordingly you can now set
nthreads= 4
This time you will use 32 cores with (16 per node) 4 OpenMP threads and 2*16/4=8 MPI tasks.

'''tips:''' 
- in real life calculations running on n_cores > 100, it is a good idea to adopt a hybrid approach 
- with OpenMP, you cannot exit the single node, with MPI you can

== Advanced: Comparing different parallelization schemes (optional) ==

Up to now we used the default parallelization scheme.
Yambo also allows you to tune the parameters which controls the parallelization scheme.
To this end you can open again the job.sh script and modify the section where the yambo input
variables are set

X_CPU= "1 1 1 $ncpu 1" # [PARALLEL] CPUs for each role
X_ROLEs= "q g k c v" # [PARALLEL] CPUs roles (q,g,k,c,v)
#X_nCPU_LinAlg_INV= $ncpu # [PARALLEL] CPUs for Linear Algebra
X_Threads= 0 # [OPENMP/X] Number of threads for response functions
DIP_Threads= 0 # [OPENMP/X] Number of threads for dipoles
SE_CPU= "1 1 $ncpu" # [PARALLEL] CPUs for each role
SE_ROLEs= "q qp b" # [PARALLEL] CPUs roles (q,qp,b)
SE_Threads= 0

In particular "X_CPU" sets how the MPI Tasks are distributed in the calculation of the response function.
The possibilities are shown in the "X_ROLEs". The same holds for "SE_CPU" and "SE_ROLEs" which control
how MPI Tasks are distributed in the calculation of the response function.

Please try different parallelization schemes and check the performances of Yambo.
In doing so you should also change the jobname in the run.sh script
label=MPI${ncpu}_OMP${nthreads}_scheme1

Using the python script, you can then chenck how speed, memory and load balance between the CPUs are affected.
For more details see also the [[Using_Yambo_in_parallel|Parallel module]]

'''tips: '''
* the product of the numbers entering each variable (i.e. X_CPU and SE_CPU) times the number of threads should always match the total number of cores (unless you want to overload the cores taking advantage of multi-threads) 
* using the X_Threads and SE_Threads variables you can think about setting different Hybrid schemes in between the screening and the self-energy runlevel.
* memory better scales if you parallelize on bands (c v b) 
* parallelization on k-points performs similarly to parallelization on bands, but memory requires more memory 
* parallelization on q-points requires much less communication in between the MPI tasks. It maybe useful if you run on more than one node and the inter-node connection is slow

 
{| 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]] --> [[GW_parallel_strategies|GW Parallel]]
|style="width:35%; text-align:right"|Next: [[Pushing_convergence_in_parallel|GW Convergence]]
|-
|}

GW parallel strategies

2020-01-28T14:34:42Z

Aferretti: /* Pure OpenMP scaling */

'''This modules contains very general discussions of the parallel environment of Yambo.

In this tutorial we will see how to setup the variables governing the parallel execution of yambo in order to perform efficient calculations in terms of both cpu time and memory to solution. As a test case we will consider the hBN 2D material. Because of its reduced dimensionality, GW calculations turns out to be very delicate. Beside the usual convergence studies with respect to k-points and sums-over-bands, in low dimensional systems a sensible amount of vacuum is required in order to treat the system as isolated, translating into a large number of plane-waves. As for other tutorials, it is important to stress that this tutorial it is meant to illustrate the functionality of the key variables and to run in reasonable time, so it has not the purpose to reach the desired accuracy to reproduce experimental results. Moreover please also note that scaling performance illustrated below may be significantly dependent on the underlying parallel architecture. Nevertheless, general considerations are tentatively drawn in discussing the results.

==Files and Tools==
Database and tools can be downloaded here:

*[http://www.yambo-code.org/educational/tutorials/files/hBN-2D-para.tar.gz hBN-2D-para.tar.gz]


== Getting familiar with yambo in parallel ==

Let's start by copying the tutorial files in the cluster and unzip them in the folder you will run the tutorial.
$ mkdir YAMBO_TUTORIALS
$ cd YAMBO_TUTORIALS
$ cp $path/hBN-2D-para.tar.gz ./
$ tar -zxvf hBN-2D-para.tar.gz
$ cd ./hBN-2D-para/YAMBO
Under the YAMBO folder, together with the SAVE folder, you will see the run.sh script

$ ls
parse_qp.py parse_ytiming.py SAVE

First, run the initialization as usual.
Then you need to generate the input file for a GW run.
$ yambo -g n -p p -F yambo_gw.in
After setting the variables in red, the new input file should look like the following:
$ cat yambo_gw.in

ppa # [R Xp] Plasmon Pole Approximation
gw0 # [R GW] GoWo Quasiparticle energy levels
HF_and_locXC # [R XX] Hartree-Fock Self-energy and Vxc
em1d # [R Xd] Dynamical Inverse Dielectric Matrix
X_Threads= 0 # [OPENMP/X] Number of threads for response functions
DIP_Threads= 0 # [OPENMP/X] Number of threads for dipoles
SE_Threads= 0 # [OPENMP/GW] Number of threads for self-energy
EXXRLvcs= 21817 RL # [XX] Exchange RL components
VXCRLvcs= 21817 RL # [XC] XCpotential RL components
Chimod= "" # [X] IP/Hartree/ALDA/LRC/BSfxc
% BndsRnXp
1 | 300 | # [Xp] Polarization function bands
%
NGsBlkXp= 4 Ry # [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 | 300 | # [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
1| 4| 1| 8|
%

Now you need to create a submission script. here below an example (run.sh) based on the SLURM scheduler. In the case of other schedulers, the header should be updated accordingly.
$ cat run.sh

#!/bin/bash
#SBATCH -N 1
#SBATCH -t 06:00:00
#SBATCH -J test
#SBATCH --partition=<queue name>
#SBATCH --tasks-per-node=1
#SBATCH --cpus-per-task=1

nodes=1
tasks_per_node=1
nthreads=1
ncpu=`echo $nodes $tasks_per_node | awk '{print $1*$2}'`

module purge
module load <needed modules>
module load <more modules>
bindir=<path to yambo bindir>

export OMP_NUM_THREADS=$nthreads

label=MPI${ncpu}_OMP${nthreads}
jdir=run_${label}
cdir=run_${label}.out

filein0=yambo_gw.in
filein=yambo_gw_${label}.in

cp -f $filein0 $filein
cat >> $filein << EOF

DIP_CPU= "1 $ncpu 1" # [PARALLEL] CPUs for each role
DIP_ROLEs= "k c v" # [PARALLEL] CPUs roles (k,c,v)
DIP_Threads= 0 # [OPENMP/X] Number of threads for dipoles
X_CPU= "1 1 1 $ncpu 1" # [PARALLEL] CPUs for each role
X_ROLEs= "q g k c v" # [PARALLEL] CPUs roles (q,g,k,c,v)
X_nCPU_LinAlg_INV= $ncpu # [PARALLEL] CPUs for Linear Algebra
X_Threads= 0 # [OPENMP/X] Number of threads for response functions
SE_CPU= " 1 $ncpu 1" # [PARALLEL] CPUs for each role
SE_ROLEs= "q qp b" # [PARALLEL] CPUs roles (q,qp,b)
SE_Threads= 0

EOF

echo "Running on $ncpu MPI, $nthreads OpenMP threads"
mpirun -np $ncpu $bindir/yambo -F $filein -J $jdir -C $cdir

As soon as you are ready to submit the job.

$ sbatch run.sh

Yambo calculates the GW-qp corrections running on 1 MPI process with a single thread.
As you can see, monitoring the log file produced by yambo, the run takes some time, although
we are using minimal parameters.

The status of the jobs can be monitored via:
$ squeue -u $USER # to inspect the status of jobs
# (hint: make a unix alias, if you like)
$ scancel <jobid> # to delete jobs in the queue

== Pure MPI scaling with default parallelization scheme ==

Meanwhile we can run the code in parallel. Let's use consider the case of a node having 16 cores (you can try to adapt the following discussion to the actual maximum number of
cores/node you have in your system). As a first run, we'll use 16 MPI tasks, still with a single thread.
To this end modify the run.sh script changing
#SBATCH --tasks-per-node=16
#SBATCH --cpus-per-task=1

ntasks_per_node=16
nthreads=1

This time the code should be much faster.
Once the run is over try to run the simulation also on 2, 4, 8 MPI tasks.
Each time, please remember to change both the number of tasks per node both in the header and in the <code>ntasks_per_node</code> variable.
Finally, you can try to produce a scaling plot.

To analyze the data you can use the phyton script parse_ytiming.py run which is provided.

You can use it running
$ ./parse_ytiming.py run*/r-*

You should obtain something like that (but with more columns)
# ncores dip Xo X io_X io_WF Sgm_x Sgm_c (REDUX) WALL_TIME
1 4.7337s 13m39.00s 0.1500s 0.0241s 0.2487s 34.2143s 15m7.00s 0.0000s 29m29s
4 1.6019s 218.7982s 0.0882s 0.0283s 0.2077s 9.3338s 242.4438s 0.0001s 07m54s
8 1.0755s 127.3209s 0.0974s 0.0291s 0.2134s 5.4490s 140.7788s 0.6926s 04m38s
12 0.7510s 89.1649s 0.1015s 0.0299s 0.2068s 4.2961s 109.1227s 0.0007s 03m26s
16 0.7653s 68.2550s 0.1048s 0.0309s 0.2463s 2.9211s 72.6220s 0.2799s 02m27s

Plot the execution time vs the number of MPI tasks
and check (do a log plot) how far you are from the ideal linear scaling.
Below a similar plot produced on a local cluster equipped with two Intel(R) Xeon(R) Silver 4208 CPU @ 2.10GHz processors per node (16 physical cares/node).
[[File:scaling_MPI_corvina.jpg|750px|center]]

'''tips:''' 
* not all runlevels scale in in the same way 
* you should never overload the available number of cores

== Pure OpenMP scaling ==

Next step is instead to check the OpenMP scaling.
Set back
#SBATCH --tasks-per-node=1
#SBATCH --cpus-per-task=16
and now use
ntasks_per_node=1
nthreads=16

Since we are already using 16 threads, we cannot also distribute among MPI tasks, i.e. ncpu will result equal to 1.
Try setting nthreads to 16, 8, 4 and 2 and again to plot the execution time vs the number of threads using the python script.
Again you should be able to produce data similar to the following

# ncores threads dip Xo X io_X io_WF Sgm_x Sgm_c WALL_TIME
1 1 4.7337s 13m39.00s 0.1500s 0.0241s 0.2487s 34.2143s 15m7.00s 29m29s
2 2 3.1971s 549.1491s 0.2248s 0.0298s 0.2491s 17.6552s 584.3692s 19m17s
4 4 2.9419s 358.5202s 0.1928s 0.0289s 0.2590s 9.2010s 421.2219s 13m15s
8 8 2.7992s 344.3342s 0.2332s 0.0325s 0.2543s 5.4334s 362.6982s 11m58s

'''tips:''' 
* OpenMP usually shares the memory among threads, but not always 
* you should never overload the available number of cores 
* in principle, we could overload the cores setting more threads than the available total number of cores since a single core allows multi-thread operations

== MPI vs OpenMP scaling ==

Which is scaling better ? MPI or OpenMP?
How is the memory distributed?

Now you can try running simulations with hybrid strategies.
Try for example setting:

#SBATCH --tasks-per-node=8

ntasks_per_node= 8
nthreads= 2

We can try to do scaling keeping the total number of threads per node (ntasks_per_node * nthreads) equal to 16.
Parsing the data we will obtain something similar to

# ncores MPI threads Dipoles Xo X Sgm_x Sgm_c WALL_TIME
16 1 16 1.00s 38.00s 0.00s 2.00s 33.00s 01m25s
16 2 8 2.00s 34.00s 0.00s 1.00s 16.00s 01m06s
16 4 4 0.00s 34.00s 0.00s 1.00s 11.00s 56s
16 8 2 0.00s 33.00s 0.00s 0.00s 9.00s 52s
16 16 1 0.00s 35.00s 0.00s 0.00s 7.00s 54s

As you can see here the total CPU time decreases more and more moving the parallelization from the OpenMP to the MPI level.
Sigma_c in particular scales better. However, the fastest run is not the one with 16 MPI task but the 8 2 configuration
since Xo is faster using a hybrid MPI-OpenMP scheme.

However, CPU time is not the only parameter you need to check.
Also, the total memory usage is important
If you compare for example the two extreme cases (you can use)
$ grep Gb run_MPI1_OMP*/l* | grep Alloc (use this for the case with only one MPI proc)
$ grep Gb run_MPI*_OMP*/LOG/l*_1 | grep Alloc (use this for the case with more than one MPI proc)

For the case
# ncores MPI threads
16 1 16
<01s> [M 0.119 Gb] Alloc WF ( 0.112)
<03s> [M 0.314 Gb] Alloc WF ( 0.306)
<46s> [M 0.074 Gb] Alloc WF ( 0.056)
<50s> [M 0.321 Gb] Alloc WF ( 0.306)
the numbers reported above refer to the total amount of memory use in the run.

For the case
# ncores MPI threads
16 16 1
<02s> P0001: [M 0.034 Gb] Alloc WF ( 0.026)
<43s> P0001: [M 0.037 Gb] Alloc WF ( 0.019)
<45s> P0001: [M 0.091 Gb] Alloc WF ( 0.076)
the numbers reported above refer to the total amount of memory per MPI task.
Multiplying by 16 you obtain an estimate of the total memory: 0.091*16=1.456 (0.076*16=1.216)
These last two numbers have to be compared with 0.321 (0.306)
As you can see yambo is distributing memory since the single MPI task uses less memory than
the total one needed (you can even compare with the serial case). However, it is not as efficient as
OpenMP in doing so.

Using a hybrid scheme you may also consider running yambo on mode than one node.
To run on two nodes for example you need to set
#SBATCH -N 2

nodes=2
accordingly you can now set
nthreads= 4
This time you will use 32 cores with (16 per node) 4 OpenMP threads and 2*16/4=8 MPI tasks.

'''tips:''' 
- in real life calculations running on n_cores > 100, it is a good idea to adopt a hybrid approach 
- with OpenMP, you cannot exit the single node, with MPI you can

== Advanced: Comparing different parallelization schemes (optional) ==

Up to now we used the default parallelization scheme.
Yambo also allows you to tune the parameters which controls the parallelization scheme.
To this end you can open again the job.sh script and modify the section where the yambo input
variables are set

X_CPU= "1 1 1 $ncpu 1" # [PARALLEL] CPUs for each role
X_ROLEs= "q g k c v" # [PARALLEL] CPUs roles (q,g,k,c,v)
#X_nCPU_LinAlg_INV= $ncpu # [PARALLEL] CPUs for Linear Algebra
X_Threads= 0 # [OPENMP/X] Number of threads for response functions
DIP_Threads= 0 # [OPENMP/X] Number of threads for dipoles
SE_CPU= "1 1 $ncpu" # [PARALLEL] CPUs for each role
SE_ROLEs= "q qp b" # [PARALLEL] CPUs roles (q,qp,b)
SE_Threads= 0

In particular "X_CPU" sets how the MPI Tasks are distributed in the calculation of the response function.
The possibilities are shown in the "X_ROLEs". The same holds for "SE_CPU" and "SE_ROLEs" which control
how MPI Tasks are distributed in the calculation of the response function.

Please try different parallelization schemes and check the performances of Yambo.
In doing so you should also change the jobname in the run.sh script
label=MPI${ncpu}_OMP${nthreads}_scheme1

Using the python script, you can then chenck how speed, memory and load balance between the CPUs are affected.
For more details see also the [[Using_Yambo_in_parallel|Parallel module]]

'''tips: '''
* the product of the numbers entering each variable (i.e. X_CPU and SE_CPU) times the number of threads should always match the total number of cores (unless you want to overload the cores taking advantage of multi-threads) 
* using the X_Threads and SE_Threads variables you can think about setting different Hybrid schemes in between the screening and the self-energy runlevel.
* memory better scales if you parallelize on bands (c v b) 
* parallelization on k-points performs similarly to parallelization on bands, but memory requires more memory 
* parallelization on q-points requires much less communication in between the MPI tasks. It maybe useful if you run on more than one node and the inter-node connection is slow

 
{| 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]] --> [[GW_parallel_strategies|GW Parallel]]
|style="width:35%; text-align:right"|Next: [[Pushing_convergence_in_parallel|GW Convergence]]
|-
|}

GW parallel strategies

2020-01-28T14:25:52Z

Aferretti: /* Pure MPI scaling with default parallelization scheme */

'''This modules contains very general discussions of the parallel environment of Yambo.

In this tutorial we will see how to setup the variables governing the parallel execution of yambo in order to perform efficient calculations in terms of both cpu time and memory to solution. As a test case we will consider the hBN 2D material. Because of its reduced dimensionality, GW calculations turns out to be very delicate. Beside the usual convergence studies with respect to k-points and sums-over-bands, in low dimensional systems a sensible amount of vacuum is required in order to treat the system as isolated, translating into a large number of plane-waves. As for other tutorials, it is important to stress that this tutorial it is meant to illustrate the functionality of the key variables and to run in reasonable time, so it has not the purpose to reach the desired accuracy to reproduce experimental results. Moreover please also note that scaling performance illustrated below may be significantly dependent on the underlying parallel architecture. Nevertheless, general considerations are tentatively drawn in discussing the results.

==Files and Tools==
Database and tools can be downloaded here:

*[http://www.yambo-code.org/educational/tutorials/files/hBN-2D-para.tar.gz hBN-2D-para.tar.gz]


== Getting familiar with yambo in parallel ==

Let's start by copying the tutorial files in the cluster and unzip them in the folder you will run the tutorial.
$ mkdir YAMBO_TUTORIALS
$ cd YAMBO_TUTORIALS
$ cp $path/hBN-2D-para.tar.gz ./
$ tar -zxvf hBN-2D-para.tar.gz
$ cd ./hBN-2D-para/YAMBO
Under the YAMBO folder, together with the SAVE folder, you will see the run.sh script

$ ls
parse_qp.py parse_ytiming.py SAVE

First, run the initialization as usual.
Then you need to generate the input file for a GW run.
$ yambo -g n -p p -F yambo_gw.in
After setting the variables in red, the new input file should look like the following:
$ cat yambo_gw.in

ppa # [R Xp] Plasmon Pole Approximation
gw0 # [R GW] GoWo Quasiparticle energy levels
HF_and_locXC # [R XX] Hartree-Fock Self-energy and Vxc
em1d # [R Xd] Dynamical Inverse Dielectric Matrix
X_Threads= 0 # [OPENMP/X] Number of threads for response functions
DIP_Threads= 0 # [OPENMP/X] Number of threads for dipoles
SE_Threads= 0 # [OPENMP/GW] Number of threads for self-energy
EXXRLvcs= 21817 RL # [XX] Exchange RL components
VXCRLvcs= 21817 RL # [XC] XCpotential RL components
Chimod= "" # [X] IP/Hartree/ALDA/LRC/BSfxc
% BndsRnXp
1 | 300 | # [Xp] Polarization function bands
%
NGsBlkXp= 4 Ry # [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 | 300 | # [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
1| 4| 1| 8|
%

Now you need to create a submission script. here below an example (run.sh) based on the SLURM scheduler. In the case of other schedulers, the header should be updated accordingly.
$ cat run.sh

#!/bin/bash
#SBATCH -N 1
#SBATCH -t 06:00:00
#SBATCH -J test
#SBATCH --partition=<queue name>
#SBATCH --tasks-per-node=1
#SBATCH --cpus-per-task=1

nodes=1
tasks_per_node=1
nthreads=1
ncpu=`echo $nodes $tasks_per_node | awk '{print $1*$2}'`

module purge
module load <needed modules>
module load <more modules>
bindir=<path to yambo bindir>

export OMP_NUM_THREADS=$nthreads

label=MPI${ncpu}_OMP${nthreads}
jdir=run_${label}
cdir=run_${label}.out

filein0=yambo_gw.in
filein=yambo_gw_${label}.in

cp -f $filein0 $filein
cat >> $filein << EOF

DIP_CPU= "1 $ncpu 1" # [PARALLEL] CPUs for each role
DIP_ROLEs= "k c v" # [PARALLEL] CPUs roles (k,c,v)
DIP_Threads= 0 # [OPENMP/X] Number of threads for dipoles
X_CPU= "1 1 1 $ncpu 1" # [PARALLEL] CPUs for each role
X_ROLEs= "q g k c v" # [PARALLEL] CPUs roles (q,g,k,c,v)
X_nCPU_LinAlg_INV= $ncpu # [PARALLEL] CPUs for Linear Algebra
X_Threads= 0 # [OPENMP/X] Number of threads for response functions
SE_CPU= " 1 $ncpu 1" # [PARALLEL] CPUs for each role
SE_ROLEs= "q qp b" # [PARALLEL] CPUs roles (q,qp,b)
SE_Threads= 0

EOF

echo "Running on $ncpu MPI, $nthreads OpenMP threads"
mpirun -np $ncpu $bindir/yambo -F $filein -J $jdir -C $cdir

As soon as you are ready to submit the job.

$ sbatch run.sh

Yambo calculates the GW-qp corrections running on 1 MPI process with a single thread.
As you can see, monitoring the log file produced by yambo, the run takes some time, although
we are using minimal parameters.

The status of the jobs can be monitored via:
$ squeue -u $USER # to inspect the status of jobs
# (hint: make a unix alias, if you like)
$ scancel <jobid> # to delete jobs in the queue

== Pure MPI scaling with default parallelization scheme ==

Meanwhile we can run the code in parallel. Let's use consider the case of a node having 16 cores (you can try to adapt the following discussion to the actual maximum number of
cores/node you have in your system). As a first run, we'll use 16 MPI tasks, still with a single thread.
To this end modify the run.sh script changing
#SBATCH --tasks-per-node=16
#SBATCH --cpus-per-task=1

ntasks_per_node=16
nthreads=1

This time the code should be much faster.
Once the run is over try to run the simulation also on 2, 4, 8 MPI tasks.
Each time, please remember to change both the number of tasks per node both in the header and in the <code>ntasks_per_node</code> variable.
Finally, you can try to produce a scaling plot.

To analyze the data you can use the phyton script parse_ytiming.py run which is provided.

You can use it running
$ ./parse_ytiming.py run*/r-*

You should obtain something like that (but with more columns)
# ncores dip Xo X io_X io_WF Sgm_x Sgm_c (REDUX) WALL_TIME
1 4.7337s 13m39.00s 0.1500s 0.0241s 0.2487s 34.2143s 15m7.00s 0.0000s 29m29s
4 1.6019s 218.7982s 0.0882s 0.0283s 0.2077s 9.3338s 242.4438s 0.0001s 07m54s
8 1.0755s 127.3209s 0.0974s 0.0291s 0.2134s 5.4490s 140.7788s 0.6926s 04m38s
12 0.7510s 89.1649s 0.1015s 0.0299s 0.2068s 4.2961s 109.1227s 0.0007s 03m26s
16 0.7653s 68.2550s 0.1048s 0.0309s 0.2463s 2.9211s 72.6220s 0.2799s 02m27s

Plot the execution time vs the number of MPI tasks
and check (do a log plot) how far you are from the ideal linear scaling.
Below a similar plot produced on a local cluster equipped with two Intel(R) Xeon(R) Silver 4208 CPU @ 2.10GHz processors per node (16 physical cares/node).
[[File:scaling_MPI_corvina.jpg|750px|center]]

'''tips:''' 
* not all runlevels scale in in the same way 
* you should never overload the available number of cores

== Pure OpenMP scaling ==

Next step is instead to check the OpenMP scaling.
Set back
#SBATCH --tasks-per-node=1
#SBATCH --cpus-per-task=16
and now use
ntasks_per_node=1
nthreads=16

Since we are already using 16 threads, we cannot also distribute among MPI tasks, i.e. ncpu will result equal to 1.
Try setting nthreads to 16, 8, 4 and 2 and again to plot the execution time vs the number of threads using the python script.
Again you should be able to produce a plot similar to the following

[[File:scaling_omp_fermi.jpg|750px|center]]

'''tips:''' 
* OpenMP usually shares the memory among threads, but not always 
* you should never overload the available number of cores 
* in principle, we could overload the cores setting more threads than the available total number of cores since a single core allows multi-thread operations

== MPI vs OpenMP scaling ==

Which is scaling better ? MPI or OpenMP?
How is the memory distributed?

Now you can try running simulations with hybrid strategies.
Try for example setting:

#SBATCH --tasks-per-node=8

ntasks_per_node= 8
nthreads= 2

We can try to do scaling keeping the total number of threads per node (ntasks_per_node * nthreads) equal to 16.
Parsing the data we will obtain something similar to

# ncores MPI threads Dipoles Xo X Sgm_x Sgm_c WALL_TIME
16 1 16 1.00s 38.00s 0.00s 2.00s 33.00s 01m25s
16 2 8 2.00s 34.00s 0.00s 1.00s 16.00s 01m06s
16 4 4 0.00s 34.00s 0.00s 1.00s 11.00s 56s
16 8 2 0.00s 33.00s 0.00s 0.00s 9.00s 52s
16 16 1 0.00s 35.00s 0.00s 0.00s 7.00s 54s

As you can see here the total CPU time decreases more and more moving the parallelization from the OpenMP to the MPI level.
Sigma_c in particular scales better. However, the fastest run is not the one with 16 MPI task but the 8 2 configuration
since Xo is faster using a hybrid MPI-OpenMP scheme.

However, CPU time is not the only parameter you need to check.
Also, the total memory usage is important
If you compare for example the two extreme cases (you can use)
$ grep Gb run_MPI1_OMP*/l* | grep Alloc (use this for the case with only one MPI proc)
$ grep Gb run_MPI*_OMP*/LOG/l*_1 | grep Alloc (use this for the case with more than one MPI proc)

For the case
# ncores MPI threads
16 1 16
<01s> [M 0.119 Gb] Alloc WF ( 0.112)
<03s> [M 0.314 Gb] Alloc WF ( 0.306)
<46s> [M 0.074 Gb] Alloc WF ( 0.056)
<50s> [M 0.321 Gb] Alloc WF ( 0.306)
the numbers reported above refer to the total amount of memory use in the run.

For the case
# ncores MPI threads
16 16 1
<02s> P0001: [M 0.034 Gb] Alloc WF ( 0.026)
<43s> P0001: [M 0.037 Gb] Alloc WF ( 0.019)
<45s> P0001: [M 0.091 Gb] Alloc WF ( 0.076)
the numbers reported above refer to the total amount of memory per MPI task.
Multiplying by 16 you obtain an estimate of the total memory: 0.091*16=1.456 (0.076*16=1.216)
These last two numbers have to be compared with 0.321 (0.306)
As you can see yambo is distributing memory since the single MPI task uses less memory than
the total one needed (you can even compare with the serial case). However, it is not as efficient as
OpenMP in doing so.

Using a hybrid scheme you may also consider running yambo on mode than one node.
To run on two nodes for example you need to set
#SBATCH -N 2

nodes=2
accordingly you can now set
nthreads= 4
This time you will use 32 cores with (16 per node) 4 OpenMP threads and 2*16/4=8 MPI tasks.

'''tips:''' 
- in real life calculations running on n_cores > 100, it is a good idea to adopt a hybrid approach 
- with OpenMP, you cannot exit the single node, with MPI you can

== Advanced: Comparing different parallelization schemes (optional) ==

Up to now we used the default parallelization scheme.
Yambo also allows you to tune the parameters which controls the parallelization scheme.
To this end you can open again the job.sh script and modify the section where the yambo input
variables are set

X_CPU= "1 1 1 $ncpu 1" # [PARALLEL] CPUs for each role
X_ROLEs= "q g k c v" # [PARALLEL] CPUs roles (q,g,k,c,v)
#X_nCPU_LinAlg_INV= $ncpu # [PARALLEL] CPUs for Linear Algebra
X_Threads= 0 # [OPENMP/X] Number of threads for response functions
DIP_Threads= 0 # [OPENMP/X] Number of threads for dipoles
SE_CPU= "1 1 $ncpu" # [PARALLEL] CPUs for each role
SE_ROLEs= "q qp b" # [PARALLEL] CPUs roles (q,qp,b)
SE_Threads= 0

In particular "X_CPU" sets how the MPI Tasks are distributed in the calculation of the response function.
The possibilities are shown in the "X_ROLEs". The same holds for "SE_CPU" and "SE_ROLEs" which control
how MPI Tasks are distributed in the calculation of the response function.

Please try different parallelization schemes and check the performances of Yambo.
In doing so you should also change the jobname in the run.sh script
label=MPI${ncpu}_OMP${nthreads}_scheme1

Using the python script, you can then chenck how speed, memory and load balance between the CPUs are affected.
For more details see also the [[Using_Yambo_in_parallel|Parallel module]]

'''tips: '''
* the product of the numbers entering each variable (i.e. X_CPU and SE_CPU) times the number of threads should always match the total number of cores (unless you want to overload the cores taking advantage of multi-threads) 
* using the X_Threads and SE_Threads variables you can think about setting different Hybrid schemes in between the screening and the self-energy runlevel.
* memory better scales if you parallelize on bands (c v b) 
* parallelization on k-points performs similarly to parallelization on bands, but memory requires more memory 
* parallelization on q-points requires much less communication in between the MPI tasks. It maybe useful if you run on more than one node and the inter-node connection is slow

 
{| 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]] --> [[GW_parallel_strategies|GW Parallel]]
|style="width:35%; text-align:right"|Next: [[Pushing_convergence_in_parallel|GW Convergence]]
|-
|}

File:Scaling MPI corvina.jpg

2020-01-28T14:24:22Z

Aferretti: User created page with UploadWizard

GW parallel strategies

2020-01-28T14:23:17Z

Aferretti: /* Pure MPI scaling with default parallelization scheme */

'''This modules contains very general discussions of the parallel environment of Yambo.

In this tutorial we will see how to setup the variables governing the parallel execution of yambo in order to perform efficient calculations in terms of both cpu time and memory to solution. As a test case we will consider the hBN 2D material. Because of its reduced dimensionality, GW calculations turns out to be very delicate. Beside the usual convergence studies with respect to k-points and sums-over-bands, in low dimensional systems a sensible amount of vacuum is required in order to treat the system as isolated, translating into a large number of plane-waves. As for other tutorials, it is important to stress that this tutorial it is meant to illustrate the functionality of the key variables and to run in reasonable time, so it has not the purpose to reach the desired accuracy to reproduce experimental results. Moreover please also note that scaling performance illustrated below may be significantly dependent on the underlying parallel architecture. Nevertheless, general considerations are tentatively drawn in discussing the results.

==Files and Tools==
Database and tools can be downloaded here:

*[http://www.yambo-code.org/educational/tutorials/files/hBN-2D-para.tar.gz hBN-2D-para.tar.gz]


== Getting familiar with yambo in parallel ==

Let's start by copying the tutorial files in the cluster and unzip them in the folder you will run the tutorial.
$ mkdir YAMBO_TUTORIALS
$ cd YAMBO_TUTORIALS
$ cp $path/hBN-2D-para.tar.gz ./
$ tar -zxvf hBN-2D-para.tar.gz
$ cd ./hBN-2D-para/YAMBO
Under the YAMBO folder, together with the SAVE folder, you will see the run.sh script

$ ls
parse_qp.py parse_ytiming.py SAVE

First, run the initialization as usual.
Then you need to generate the input file for a GW run.
$ yambo -g n -p p -F yambo_gw.in
After setting the variables in red, the new input file should look like the following:
$ cat yambo_gw.in

ppa # [R Xp] Plasmon Pole Approximation
gw0 # [R GW] GoWo Quasiparticle energy levels
HF_and_locXC # [R XX] Hartree-Fock Self-energy and Vxc
em1d # [R Xd] Dynamical Inverse Dielectric Matrix
X_Threads= 0 # [OPENMP/X] Number of threads for response functions
DIP_Threads= 0 # [OPENMP/X] Number of threads for dipoles
SE_Threads= 0 # [OPENMP/GW] Number of threads for self-energy
EXXRLvcs= 21817 RL # [XX] Exchange RL components
VXCRLvcs= 21817 RL # [XC] XCpotential RL components
Chimod= "" # [X] IP/Hartree/ALDA/LRC/BSfxc
% BndsRnXp
1 | 300 | # [Xp] Polarization function bands
%
NGsBlkXp= 4 Ry # [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 | 300 | # [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
1| 4| 1| 8|
%

Now you need to create a submission script. here below an example (run.sh) based on the SLURM scheduler. In the case of other schedulers, the header should be updated accordingly.
$ cat run.sh

#!/bin/bash
#SBATCH -N 1
#SBATCH -t 06:00:00
#SBATCH -J test
#SBATCH --partition=<queue name>
#SBATCH --tasks-per-node=1
#SBATCH --cpus-per-task=1

nodes=1
tasks_per_node=1
nthreads=1
ncpu=`echo $nodes $tasks_per_node | awk '{print $1*$2}'`

module purge
module load <needed modules>
module load <more modules>
bindir=<path to yambo bindir>

export OMP_NUM_THREADS=$nthreads

label=MPI${ncpu}_OMP${nthreads}
jdir=run_${label}
cdir=run_${label}.out

filein0=yambo_gw.in
filein=yambo_gw_${label}.in

cp -f $filein0 $filein
cat >> $filein << EOF

DIP_CPU= "1 $ncpu 1" # [PARALLEL] CPUs for each role
DIP_ROLEs= "k c v" # [PARALLEL] CPUs roles (k,c,v)
DIP_Threads= 0 # [OPENMP/X] Number of threads for dipoles
X_CPU= "1 1 1 $ncpu 1" # [PARALLEL] CPUs for each role
X_ROLEs= "q g k c v" # [PARALLEL] CPUs roles (q,g,k,c,v)
X_nCPU_LinAlg_INV= $ncpu # [PARALLEL] CPUs for Linear Algebra
X_Threads= 0 # [OPENMP/X] Number of threads for response functions
SE_CPU= " 1 $ncpu 1" # [PARALLEL] CPUs for each role
SE_ROLEs= "q qp b" # [PARALLEL] CPUs roles (q,qp,b)
SE_Threads= 0

EOF

echo "Running on $ncpu MPI, $nthreads OpenMP threads"
mpirun -np $ncpu $bindir/yambo -F $filein -J $jdir -C $cdir

As soon as you are ready to submit the job.

$ sbatch run.sh

Yambo calculates the GW-qp corrections running on 1 MPI process with a single thread.
As you can see, monitoring the log file produced by yambo, the run takes some time, although
we are using minimal parameters.

The status of the jobs can be monitored via:
$ squeue -u $USER # to inspect the status of jobs
# (hint: make a unix alias, if you like)
$ scancel <jobid> # to delete jobs in the queue

== Pure MPI scaling with default parallelization scheme ==

Meanwhile we can run the code in parallel. Let's use consider the case of a node having 16 cores (you can try to adapt the following discussion to the actual maximum number of
cores/node you have in your system). As a first run, we'll use 16 MPI tasks, still with a single thread.
To this end modify the run.sh script changing
#SBATCH --tasks-per-node=16
#SBATCH --cpus-per-task=1

ntasks_per_node=16
nthreads=1

This time the code should be much faster.
Once the run is over try to run the simulation also on 2, 4, 8 MPI tasks.
Each time, please remember to change both the number of tasks per node both in the header and in the <code>ntasks_per_node</code> variable.
Finally, you can try to produce a scaling plot.

To analyze the data you can use the phyton script parse_ytiming.py run which is provided.

You can use it running
$ ./parse_ytiming.py run*/r-*

You should obtain something like that (but with more columns)
# ncores dip Xo X io_X io_WF Sgm_x Sgm_c (REDUX) WALL_TIME
1 4.7337s 13m39.00s 0.1500s 0.0241s 0.2487s 34.2143s 15m7.00s 0.0000s 29m29s
4 1.6019s 218.7982s 0.0882s 0.0283s 0.2077s 9.3338s 242.4438s 0.0001s 07m54s
8 1.0755s 127.3209s 0.0974s 0.0291s 0.2134s 5.4490s 140.7788s 0.6926s 04m38s
12 0.7510s 89.1649s 0.1015s 0.0299s 0.2068s 4.2961s 109.1227s 0.0007s 03m26s
16 0.7653s 68.2550s 0.1048s 0.0309s 0.2463s 2.9211s 72.6220s 0.2799s 02m27s

Plot the execution time vs the number of MPI tasks
and check (do a log plot) how far you are from the ideal linear scaling.
Below a similar plot produced on a local cluster equipped with two Intel(R) Xeon(R) Silver 4208 CPU @ 2.10GHz processors per node (16 physical cares/node).
[[File:scaling_mpi_corvina.jpg|750px|center]]

'''tips:''' 
- not all runlevels scale in in the same way 
- you should never overload the available number of cores

== Pure OpenMP scaling ==

Next step is instead to check the OpenMP scaling.
Set back
#SBATCH --tasks-per-node=1
#SBATCH --cpus-per-task=16
and now use
ntasks_per_node=1
nthreads=16

Since we are already using 16 threads, we cannot also distribute among MPI tasks, i.e. ncpu will result equal to 1.
Try setting nthreads to 16, 8, 4 and 2 and again to plot the execution time vs the number of threads using the python script.
Again you should be able to produce a plot similar to the following

[[File:scaling_omp_fermi.jpg|750px|center]]

'''tips:''' 
* OpenMP usually shares the memory among threads, but not always 
* you should never overload the available number of cores 
* in principle, we could overload the cores setting more threads than the available total number of cores since a single core allows multi-thread operations

== MPI vs OpenMP scaling ==

Which is scaling better ? MPI or OpenMP?
How is the memory distributed?

Now you can try running simulations with hybrid strategies.
Try for example setting:

#SBATCH --tasks-per-node=8

ntasks_per_node= 8
nthreads= 2

We can try to do scaling keeping the total number of threads per node (ntasks_per_node * nthreads) equal to 16.
Parsing the data we will obtain something similar to

# ncores MPI threads Dipoles Xo X Sgm_x Sgm_c WALL_TIME
16 1 16 1.00s 38.00s 0.00s 2.00s 33.00s 01m25s
16 2 8 2.00s 34.00s 0.00s 1.00s 16.00s 01m06s
16 4 4 0.00s 34.00s 0.00s 1.00s 11.00s 56s
16 8 2 0.00s 33.00s 0.00s 0.00s 9.00s 52s
16 16 1 0.00s 35.00s 0.00s 0.00s 7.00s 54s

As you can see here the total CPU time decreases more and more moving the parallelization from the OpenMP to the MPI level.
Sigma_c in particular scales better. However, the fastest run is not the one with 16 MPI task but the 8 2 configuration
since Xo is faster using a hybrid MPI-OpenMP scheme.

However, CPU time is not the only parameter you need to check.
Also, the total memory usage is important
If you compare for example the two extreme cases (you can use)
$ grep Gb run_MPI1_OMP*/l* | grep Alloc (use this for the case with only one MPI proc)
$ grep Gb run_MPI*_OMP*/LOG/l*_1 | grep Alloc (use this for the case with more than one MPI proc)

For the case
# ncores MPI threads
16 1 16
<01s> [M 0.119 Gb] Alloc WF ( 0.112)
<03s> [M 0.314 Gb] Alloc WF ( 0.306)
<46s> [M 0.074 Gb] Alloc WF ( 0.056)
<50s> [M 0.321 Gb] Alloc WF ( 0.306)
the numbers reported above refer to the total amount of memory use in the run.

For the case
# ncores MPI threads
16 16 1
<02s> P0001: [M 0.034 Gb] Alloc WF ( 0.026)
<43s> P0001: [M 0.037 Gb] Alloc WF ( 0.019)
<45s> P0001: [M 0.091 Gb] Alloc WF ( 0.076)
the numbers reported above refer to the total amount of memory per MPI task.
Multiplying by 16 you obtain an estimate of the total memory: 0.091*16=1.456 (0.076*16=1.216)
These last two numbers have to be compared with 0.321 (0.306)
As you can see yambo is distributing memory since the single MPI task uses less memory than
the total one needed (you can even compare with the serial case). However, it is not as efficient as
OpenMP in doing so.

Using a hybrid scheme you may also consider running yambo on mode than one node.
To run on two nodes for example you need to set
#SBATCH -N 2

nodes=2
accordingly you can now set
nthreads= 4
This time you will use 32 cores with (16 per node) 4 OpenMP threads and 2*16/4=8 MPI tasks.

'''tips:''' 
- in real life calculations running on n_cores > 100, it is a good idea to adopt a hybrid approach 
- with OpenMP, you cannot exit the single node, with MPI you can

== Advanced: Comparing different parallelization schemes (optional) ==

Up to now we used the default parallelization scheme.
Yambo also allows you to tune the parameters which controls the parallelization scheme.
To this end you can open again the job.sh script and modify the section where the yambo input
variables are set

X_CPU= "1 1 1 $ncpu 1" # [PARALLEL] CPUs for each role
X_ROLEs= "q g k c v" # [PARALLEL] CPUs roles (q,g,k,c,v)
#X_nCPU_LinAlg_INV= $ncpu # [PARALLEL] CPUs for Linear Algebra
X_Threads= 0 # [OPENMP/X] Number of threads for response functions
DIP_Threads= 0 # [OPENMP/X] Number of threads for dipoles
SE_CPU= "1 1 $ncpu" # [PARALLEL] CPUs for each role
SE_ROLEs= "q qp b" # [PARALLEL] CPUs roles (q,qp,b)
SE_Threads= 0

In particular "X_CPU" sets how the MPI Tasks are distributed in the calculation of the response function.
The possibilities are shown in the "X_ROLEs". The same holds for "SE_CPU" and "SE_ROLEs" which control
how MPI Tasks are distributed in the calculation of the response function.

Please try different parallelization schemes and check the performances of Yambo.
In doing so you should also change the jobname in the run.sh script
label=MPI${ncpu}_OMP${nthreads}_scheme1

Using the python script, you can then chenck how speed, memory and load balance between the CPUs are affected.
For more details see also the [[Using_Yambo_in_parallel|Parallel module]]

'''tips: '''
* the product of the numbers entering each variable (i.e. X_CPU and SE_CPU) times the number of threads should always match the total number of cores (unless you want to overload the cores taking advantage of multi-threads) 
* using the X_Threads and SE_Threads variables you can think about setting different Hybrid schemes in between the screening and the self-energy runlevel.
* memory better scales if you parallelize on bands (c v b) 
* parallelization on k-points performs similarly to parallelization on bands, but memory requires more memory 
* parallelization on q-points requires much less communication in between the MPI tasks. It maybe useful if you run on more than one node and the inter-node connection is slow

 
{| 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]] --> [[GW_parallel_strategies|GW Parallel]]
|style="width:35%; text-align:right"|Next: [[Pushing_convergence_in_parallel|GW Convergence]]
|-
|}

GW parallel strategies

2020-01-28T14:19:07Z

Aferretti: /* Pure MPI scaling with default parallelization scheme */

'''This modules contains very general discussions of the parallel environment of Yambo.

In this tutorial we will see how to setup the variables governing the parallel execution of yambo in order to perform efficient calculations in terms of both cpu time and memory to solution. As a test case we will consider the hBN 2D material. Because of its reduced dimensionality, GW calculations turns out to be very delicate. Beside the usual convergence studies with respect to k-points and sums-over-bands, in low dimensional systems a sensible amount of vacuum is required in order to treat the system as isolated, translating into a large number of plane-waves. As for other tutorials, it is important to stress that this tutorial it is meant to illustrate the functionality of the key variables and to run in reasonable time, so it has not the purpose to reach the desired accuracy to reproduce experimental results. Moreover please also note that scaling performance illustrated below may be significantly dependent on the underlying parallel architecture. Nevertheless, general considerations are tentatively drawn in discussing the results.

==Files and Tools==
Database and tools can be downloaded here:

*[http://www.yambo-code.org/educational/tutorials/files/hBN-2D-para.tar.gz hBN-2D-para.tar.gz]


== Getting familiar with yambo in parallel ==

Let's start by copying the tutorial files in the cluster and unzip them in the folder you will run the tutorial.
$ mkdir YAMBO_TUTORIALS
$ cd YAMBO_TUTORIALS
$ cp $path/hBN-2D-para.tar.gz ./
$ tar -zxvf hBN-2D-para.tar.gz
$ cd ./hBN-2D-para/YAMBO
Under the YAMBO folder, together with the SAVE folder, you will see the run.sh script

$ ls
parse_qp.py parse_ytiming.py SAVE

First, run the initialization as usual.
Then you need to generate the input file for a GW run.
$ yambo -g n -p p -F yambo_gw.in
After setting the variables in red, the new input file should look like the following:
$ cat yambo_gw.in

ppa # [R Xp] Plasmon Pole Approximation
gw0 # [R GW] GoWo Quasiparticle energy levels
HF_and_locXC # [R XX] Hartree-Fock Self-energy and Vxc
em1d # [R Xd] Dynamical Inverse Dielectric Matrix
X_Threads= 0 # [OPENMP/X] Number of threads for response functions
DIP_Threads= 0 # [OPENMP/X] Number of threads for dipoles
SE_Threads= 0 # [OPENMP/GW] Number of threads for self-energy
EXXRLvcs= 21817 RL # [XX] Exchange RL components
VXCRLvcs= 21817 RL # [XC] XCpotential RL components
Chimod= "" # [X] IP/Hartree/ALDA/LRC/BSfxc
% BndsRnXp
1 | 300 | # [Xp] Polarization function bands
%
NGsBlkXp= 4 Ry # [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 | 300 | # [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
1| 4| 1| 8|
%

Now you need to create a submission script. here below an example (run.sh) based on the SLURM scheduler. In the case of other schedulers, the header should be updated accordingly.
$ cat run.sh

#!/bin/bash
#SBATCH -N 1
#SBATCH -t 06:00:00
#SBATCH -J test
#SBATCH --partition=<queue name>
#SBATCH --tasks-per-node=1
#SBATCH --cpus-per-task=1

nodes=1
tasks_per_node=1
nthreads=1
ncpu=`echo $nodes $tasks_per_node | awk '{print $1*$2}'`

module purge
module load <needed modules>
module load <more modules>
bindir=<path to yambo bindir>

export OMP_NUM_THREADS=$nthreads

label=MPI${ncpu}_OMP${nthreads}
jdir=run_${label}
cdir=run_${label}.out

filein0=yambo_gw.in
filein=yambo_gw_${label}.in

cp -f $filein0 $filein
cat >> $filein << EOF

DIP_CPU= "1 $ncpu 1" # [PARALLEL] CPUs for each role
DIP_ROLEs= "k c v" # [PARALLEL] CPUs roles (k,c,v)
DIP_Threads= 0 # [OPENMP/X] Number of threads for dipoles
X_CPU= "1 1 1 $ncpu 1" # [PARALLEL] CPUs for each role
X_ROLEs= "q g k c v" # [PARALLEL] CPUs roles (q,g,k,c,v)
X_nCPU_LinAlg_INV= $ncpu # [PARALLEL] CPUs for Linear Algebra
X_Threads= 0 # [OPENMP/X] Number of threads for response functions
SE_CPU= " 1 $ncpu 1" # [PARALLEL] CPUs for each role
SE_ROLEs= "q qp b" # [PARALLEL] CPUs roles (q,qp,b)
SE_Threads= 0

EOF

echo "Running on $ncpu MPI, $nthreads OpenMP threads"
mpirun -np $ncpu $bindir/yambo -F $filein -J $jdir -C $cdir

As soon as you are ready to submit the job.

$ sbatch run.sh

Yambo calculates the GW-qp corrections running on 1 MPI process with a single thread.
As you can see, monitoring the log file produced by yambo, the run takes some time, although
we are using minimal parameters.

The status of the jobs can be monitored via:
$ squeue -u $USER # to inspect the status of jobs
# (hint: make a unix alias, if you like)
$ scancel <jobid> # to delete jobs in the queue

== Pure MPI scaling with default parallelization scheme ==

Meanwhile we can run the code in parallel. Let's use consider the case of a node having 16 cores (you can try to adapt the following discussion to the actual maximum number of
cores/node you have in your system). As a first run, we'll use 16 MPI tasks, still with a single thread.
To this end modify the run.sh script changing
#SBATCH --tasks-per-node=16
#SBATCH --cpus-per-task=1

ntasks_per_node=16
nthreads=1

This time the code should be much faster.
Once the run is over try to run the simulation also on 2, 4, 8 MPI tasks.
Each time, please remember to change both the number of tasks per node both in the header and in the <code>ntasks_per_node</code> variable.
Finally, you can try to produce a scaling plot.

To analyze the data you can use the phyton script parse_ytiming.py run which is provided.

You can use it running
$ ./parse_ytiming.py run*/r-*

You should obtain something like that (but with more columns)
# ncores dip Xo X io_X io_WF Sgm_x Sgm_c (REDUX) WALL_TIME
1 4.7337s 13m39.00s 0.1500s 0.0241s 0.2487s 34.2143s 15m7.00s 0.0000s 29m29s
4 1.6019s 218.7982s 0.0882s 0.0283s 0.2077s 9.3338s 242.4438s 0.0001s 07m54s
8 1.0755s 127.3209s 0.0974s 0.0291s 0.2134s 5.4490s 140.7788s 0.6926s 04m38s
12 0.7510s 89.1649s 0.1015s 0.0299s 0.2068s 4.2961s 109.1227s 0.0007s 03m26s
16 0.7653s 68.2550s 0.1048s 0.0309s 0.2463s 2.9211s 72.6220s 0.2799s 02m27s

Plot the execution time vs the number of MPI tasks
and check (do a log plot) how far you are from the ideal linear scaling.
Below a similar plot performed on Fermi
[[File:scaling_mpi_fermi.jpg|750px|center]]

'''tips:''' 
- not all runlevels scale in in the same way 
- you should never overload the available number of cores

== Pure OpenMP scaling ==

Next step is instead to check the OpenMP scaling.
Set back
#SBATCH --tasks-per-node=1
#SBATCH --cpus-per-task=16
and now use
ntasks_per_node=1
nthreads=16

Since we are already using 16 threads, we cannot also distribute among MPI tasks, i.e. ncpu will result equal to 1.
Try setting nthreads to 16, 8, 4 and 2 and again to plot the execution time vs the number of threads using the python script.
Again you should be able to produce a plot similar to the following

[[File:scaling_omp_fermi.jpg|750px|center]]

'''tips:''' 
* OpenMP usually shares the memory among threads, but not always 
* you should never overload the available number of cores 
* in principle, we could overload the cores setting more threads than the available total number of cores since a single core allows multi-thread operations

== MPI vs OpenMP scaling ==

Which is scaling better ? MPI or OpenMP?
How is the memory distributed?

Now you can try running simulations with hybrid strategies.
Try for example setting:

#SBATCH --tasks-per-node=8

ntasks_per_node= 8
nthreads= 2

We can try to do scaling keeping the total number of threads per node (ntasks_per_node * nthreads) equal to 16.
Parsing the data we will obtain something similar to

# ncores MPI threads Dipoles Xo X Sgm_x Sgm_c WALL_TIME
16 1 16 1.00s 38.00s 0.00s 2.00s 33.00s 01m25s
16 2 8 2.00s 34.00s 0.00s 1.00s 16.00s 01m06s
16 4 4 0.00s 34.00s 0.00s 1.00s 11.00s 56s
16 8 2 0.00s 33.00s 0.00s 0.00s 9.00s 52s
16 16 1 0.00s 35.00s 0.00s 0.00s 7.00s 54s

As you can see here the total CPU time decreases more and more moving the parallelization from the OpenMP to the MPI level.
Sigma_c in particular scales better. However, the fastest run is not the one with 16 MPI task but the 8 2 configuration
since Xo is faster using a hybrid MPI-OpenMP scheme.

However, CPU time is not the only parameter you need to check.
Also, the total memory usage is important
If you compare for example the two extreme cases (you can use)
$ grep Gb run_MPI1_OMP*/l* | grep Alloc (use this for the case with only one MPI proc)
$ grep Gb run_MPI*_OMP*/LOG/l*_1 | grep Alloc (use this for the case with more than one MPI proc)

For the case
# ncores MPI threads
16 1 16
<01s> [M 0.119 Gb] Alloc WF ( 0.112)
<03s> [M 0.314 Gb] Alloc WF ( 0.306)
<46s> [M 0.074 Gb] Alloc WF ( 0.056)
<50s> [M 0.321 Gb] Alloc WF ( 0.306)
the numbers reported above refer to the total amount of memory use in the run.

For the case
# ncores MPI threads
16 16 1
<02s> P0001: [M 0.034 Gb] Alloc WF ( 0.026)
<43s> P0001: [M 0.037 Gb] Alloc WF ( 0.019)
<45s> P0001: [M 0.091 Gb] Alloc WF ( 0.076)
the numbers reported above refer to the total amount of memory per MPI task.
Multiplying by 16 you obtain an estimate of the total memory: 0.091*16=1.456 (0.076*16=1.216)
These last two numbers have to be compared with 0.321 (0.306)
As you can see yambo is distributing memory since the single MPI task uses less memory than
the total one needed (you can even compare with the serial case). However, it is not as efficient as
OpenMP in doing so.

Using a hybrid scheme you may also consider running yambo on mode than one node.
To run on two nodes for example you need to set
#SBATCH -N 2

nodes=2
accordingly you can now set
nthreads= 4
This time you will use 32 cores with (16 per node) 4 OpenMP threads and 2*16/4=8 MPI tasks.

'''tips:''' 
- in real life calculations running on n_cores > 100, it is a good idea to adopt a hybrid approach 
- with OpenMP, you cannot exit the single node, with MPI you can

== Advanced: Comparing different parallelization schemes (optional) ==

Up to now we used the default parallelization scheme.
Yambo also allows you to tune the parameters which controls the parallelization scheme.
To this end you can open again the job.sh script and modify the section where the yambo input
variables are set

X_CPU= "1 1 1 $ncpu 1" # [PARALLEL] CPUs for each role
X_ROLEs= "q g k c v" # [PARALLEL] CPUs roles (q,g,k,c,v)
#X_nCPU_LinAlg_INV= $ncpu # [PARALLEL] CPUs for Linear Algebra
X_Threads= 0 # [OPENMP/X] Number of threads for response functions
DIP_Threads= 0 # [OPENMP/X] Number of threads for dipoles
SE_CPU= "1 1 $ncpu" # [PARALLEL] CPUs for each role
SE_ROLEs= "q qp b" # [PARALLEL] CPUs roles (q,qp,b)
SE_Threads= 0

In particular "X_CPU" sets how the MPI Tasks are distributed in the calculation of the response function.
The possibilities are shown in the "X_ROLEs". The same holds for "SE_CPU" and "SE_ROLEs" which control
how MPI Tasks are distributed in the calculation of the response function.

Please try different parallelization schemes and check the performances of Yambo.
In doing so you should also change the jobname in the run.sh script
label=MPI${ncpu}_OMP${nthreads}_scheme1

Using the python script, you can then chenck how speed, memory and load balance between the CPUs are affected.
For more details see also the [[Using_Yambo_in_parallel|Parallel module]]

'''tips: '''
* the product of the numbers entering each variable (i.e. X_CPU and SE_CPU) times the number of threads should always match the total number of cores (unless you want to overload the cores taking advantage of multi-threads) 
* using the X_Threads and SE_Threads variables you can think about setting different Hybrid schemes in between the screening and the self-energy runlevel.
* memory better scales if you parallelize on bands (c v b) 
* parallelization on k-points performs similarly to parallelization on bands, but memory requires more memory 
* parallelization on q-points requires much less communication in between the MPI tasks. It maybe useful if you run on more than one node and the inter-node connection is slow

 
{| 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]] --> [[GW_parallel_strategies|GW Parallel]]
|style="width:35%; text-align:right"|Next: [[Pushing_convergence_in_parallel|GW Convergence]]
|-
|}

GW parallel strategies

2020-01-28T14:18:31Z

Aferretti: /* Pure MPI scaling with default parallelization scheme */

'''This modules contains very general discussions of the parallel environment of Yambo.

In this tutorial we will see how to setup the variables governing the parallel execution of yambo in order to perform efficient calculations in terms of both cpu time and memory to solution. As a test case we will consider the hBN 2D material. Because of its reduced dimensionality, GW calculations turns out to be very delicate. Beside the usual convergence studies with respect to k-points and sums-over-bands, in low dimensional systems a sensible amount of vacuum is required in order to treat the system as isolated, translating into a large number of plane-waves. As for other tutorials, it is important to stress that this tutorial it is meant to illustrate the functionality of the key variables and to run in reasonable time, so it has not the purpose to reach the desired accuracy to reproduce experimental results. Moreover please also note that scaling performance illustrated below may be significantly dependent on the underlying parallel architecture. Nevertheless, general considerations are tentatively drawn in discussing the results.

==Files and Tools==
Database and tools can be downloaded here:

*[http://www.yambo-code.org/educational/tutorials/files/hBN-2D-para.tar.gz hBN-2D-para.tar.gz]


== Getting familiar with yambo in parallel ==

Let's start by copying the tutorial files in the cluster and unzip them in the folder you will run the tutorial.
$ mkdir YAMBO_TUTORIALS
$ cd YAMBO_TUTORIALS
$ cp $path/hBN-2D-para.tar.gz ./
$ tar -zxvf hBN-2D-para.tar.gz
$ cd ./hBN-2D-para/YAMBO
Under the YAMBO folder, together with the SAVE folder, you will see the run.sh script

$ ls
parse_qp.py parse_ytiming.py SAVE

First, run the initialization as usual.
Then you need to generate the input file for a GW run.
$ yambo -g n -p p -F yambo_gw.in
After setting the variables in red, the new input file should look like the following:
$ cat yambo_gw.in

ppa # [R Xp] Plasmon Pole Approximation
gw0 # [R GW] GoWo Quasiparticle energy levels
HF_and_locXC # [R XX] Hartree-Fock Self-energy and Vxc
em1d # [R Xd] Dynamical Inverse Dielectric Matrix
X_Threads= 0 # [OPENMP/X] Number of threads for response functions
DIP_Threads= 0 # [OPENMP/X] Number of threads for dipoles
SE_Threads= 0 # [OPENMP/GW] Number of threads for self-energy
EXXRLvcs= 21817 RL # [XX] Exchange RL components
VXCRLvcs= 21817 RL # [XC] XCpotential RL components
Chimod= "" # [X] IP/Hartree/ALDA/LRC/BSfxc
% BndsRnXp
1 | 300 | # [Xp] Polarization function bands
%
NGsBlkXp= 4 Ry # [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 | 300 | # [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
1| 4| 1| 8|
%

Now you need to create a submission script. here below an example (run.sh) based on the SLURM scheduler. In the case of other schedulers, the header should be updated accordingly.
$ cat run.sh

#!/bin/bash
#SBATCH -N 1
#SBATCH -t 06:00:00
#SBATCH -J test
#SBATCH --partition=<queue name>
#SBATCH --tasks-per-node=1
#SBATCH --cpus-per-task=1

nodes=1
tasks_per_node=1
nthreads=1
ncpu=`echo $nodes $tasks_per_node | awk '{print $1*$2}'`

module purge
module load <needed modules>
module load <more modules>
bindir=<path to yambo bindir>

export OMP_NUM_THREADS=$nthreads

label=MPI${ncpu}_OMP${nthreads}
jdir=run_${label}
cdir=run_${label}.out

filein0=yambo_gw.in
filein=yambo_gw_${label}.in

cp -f $filein0 $filein
cat >> $filein << EOF

DIP_CPU= "1 $ncpu 1" # [PARALLEL] CPUs for each role
DIP_ROLEs= "k c v" # [PARALLEL] CPUs roles (k,c,v)
DIP_Threads= 0 # [OPENMP/X] Number of threads for dipoles
X_CPU= "1 1 1 $ncpu 1" # [PARALLEL] CPUs for each role
X_ROLEs= "q g k c v" # [PARALLEL] CPUs roles (q,g,k,c,v)
X_nCPU_LinAlg_INV= $ncpu # [PARALLEL] CPUs for Linear Algebra
X_Threads= 0 # [OPENMP/X] Number of threads for response functions
SE_CPU= " 1 $ncpu 1" # [PARALLEL] CPUs for each role
SE_ROLEs= "q qp b" # [PARALLEL] CPUs roles (q,qp,b)
SE_Threads= 0

EOF

echo "Running on $ncpu MPI, $nthreads OpenMP threads"
mpirun -np $ncpu $bindir/yambo -F $filein -J $jdir -C $cdir

As soon as you are ready to submit the job.

$ sbatch run.sh

Yambo calculates the GW-qp corrections running on 1 MPI process with a single thread.
As you can see, monitoring the log file produced by yambo, the run takes some time, although
we are using minimal parameters.

The status of the jobs can be monitored via:
$ squeue -u $USER # to inspect the status of jobs
# (hint: make a unix alias, if you like)
$ scancel <jobid> # to delete jobs in the queue

== Pure MPI scaling with default parallelization scheme ==

Meanwhile we can run the code in parallel. Let's use consider the case of a node having 16 cores (you can try to adapt the following discussion to the actual maximum number of
cores/node you have in your system). As a first run, we'll use 16 MPI tasks, still with a single thread.
To this end modify the run.sh script changing
#SBATCH --tasks-per-node=16
#SBATCH --cpus-per-task=1

ntasks_per_node=16
nthreads=1

This time the code should be much faster.
Once the run is over try to run the simulation also on 2, 4, 8 MPI tasks.
Each time, please remember to change both the number of tasks per node both in the header and in the <code>ntasks_per_node</code> variable.
Finally, you can try to produce a scaling plot.

To analyze the data you can use the phyton script parse_ytiming.py run which is provided.

You can use it running
$ ./parse_ytiming.py run*/r-*

You should obtain something like that (but with more columns)
# ncores dip Xo X io_X io_WF Sgm_x Sgm_c (REDUX) WALL_TIME
1 4.7337s 13m39.00s 0.1500s 0.0241s 0.2487s 34.2143s 15m7.00s 0.0000s 29m29s
4 1.6019s 218.7982s 0.0882s 0.0283s 0.2077s 9.3338s 242.4438s 0.0001s 07m54s
8 1.0755s 127.3209s 0.0974s 0.0291s 0.2134s 5.4490s 140.7788s 0.6926s 04m38s
12 0.7510s 89.1649s 0.1015s 0.0299s 0.2068s 4.2961s 109.1227s 0.0007s 03m26s
16 0.7653s 68.2550s 0.1048s 0.0309s 0.2463s 2.9211s 72.6220s 0.2799s 02m27s

Plot the execution time vs the number of MPI tasks
and check (do a log plot) how far you are from the ideal linear scaling.
Below a similar plot performed on Fermi
[[File:scaling_mpi_fermi.jpg|750px|center]]

'''tips:''' 
- not all runlevels scale in in the same way 
- you should never overload the available number of cores

== Pure OpenMP scaling ==

Next step is instead to check the OpenMP scaling.
Set back
#SBATCH --tasks-per-node=1
#SBATCH --cpus-per-task=16
and now use
ntasks_per_node=1
nthreads=16

Since we are already using 16 threads, we cannot also distribute among MPI tasks, i.e. ncpu will result equal to 1.
Try setting nthreads to 16, 8, 4 and 2 and again to plot the execution time vs the number of threads using the python script.
Again you should be able to produce a plot similar to the following

[[File:scaling_omp_fermi.jpg|750px|center]]

'''tips:''' 
* OpenMP usually shares the memory among threads, but not always 
* you should never overload the available number of cores 
* in principle, we could overload the cores setting more threads than the available total number of cores since a single core allows multi-thread operations

== MPI vs OpenMP scaling ==

Which is scaling better ? MPI or OpenMP?
How is the memory distributed?

Now you can try running simulations with hybrid strategies.
Try for example setting:

#SBATCH --tasks-per-node=8

ntasks_per_node= 8
nthreads= 2

We can try to do scaling keeping the total number of threads per node (ntasks_per_node * nthreads) equal to 16.
Parsing the data we will obtain something similar to

# ncores MPI threads Dipoles Xo X Sgm_x Sgm_c WALL_TIME
16 1 16 1.00s 38.00s 0.00s 2.00s 33.00s 01m25s
16 2 8 2.00s 34.00s 0.00s 1.00s 16.00s 01m06s
16 4 4 0.00s 34.00s 0.00s 1.00s 11.00s 56s
16 8 2 0.00s 33.00s 0.00s 0.00s 9.00s 52s
16 16 1 0.00s 35.00s 0.00s 0.00s 7.00s 54s

As you can see here the total CPU time decreases more and more moving the parallelization from the OpenMP to the MPI level.
Sigma_c in particular scales better. However, the fastest run is not the one with 16 MPI task but the 8 2 configuration
since Xo is faster using a hybrid MPI-OpenMP scheme.

However, CPU time is not the only parameter you need to check.
Also, the total memory usage is important
If you compare for example the two extreme cases (you can use)
$ grep Gb run_MPI1_OMP*/l* | grep Alloc (use this for the case with only one MPI proc)
$ grep Gb run_MPI*_OMP*/LOG/l*_1 | grep Alloc (use this for the case with more than one MPI proc)

For the case
# ncores MPI threads
16 1 16
<01s> [M 0.119 Gb] Alloc WF ( 0.112)
<03s> [M 0.314 Gb] Alloc WF ( 0.306)
<46s> [M 0.074 Gb] Alloc WF ( 0.056)
<50s> [M 0.321 Gb] Alloc WF ( 0.306)
the numbers reported above refer to the total amount of memory use in the run.

For the case
# ncores MPI threads
16 16 1
<02s> P0001: [M 0.034 Gb] Alloc WF ( 0.026)
<43s> P0001: [M 0.037 Gb] Alloc WF ( 0.019)
<45s> P0001: [M 0.091 Gb] Alloc WF ( 0.076)
the numbers reported above refer to the total amount of memory per MPI task.
Multiplying by 16 you obtain an estimate of the total memory: 0.091*16=1.456 (0.076*16=1.216)
These last two numbers have to be compared with 0.321 (0.306)
As you can see yambo is distributing memory since the single MPI task uses less memory than
the total one needed (you can even compare with the serial case). However, it is not as efficient as
OpenMP in doing so.

Using a hybrid scheme you may also consider running yambo on mode than one node.
To run on two nodes for example you need to set
#SBATCH -N 2

nodes=2
accordingly you can now set
nthreads= 4
This time you will use 32 cores with (16 per node) 4 OpenMP threads and 2*16/4=8 MPI tasks.

'''tips:''' 
- in real life calculations running on n_cores > 100, it is a good idea to adopt a hybrid approach 
- with OpenMP, you cannot exit the single node, with MPI you can

== Advanced: Comparing different parallelization schemes (optional) ==

Up to now we used the default parallelization scheme.
Yambo also allows you to tune the parameters which controls the parallelization scheme.
To this end you can open again the job.sh script and modify the section where the yambo input
variables are set

X_CPU= "1 1 1 $ncpu 1" # [PARALLEL] CPUs for each role
X_ROLEs= "q g k c v" # [PARALLEL] CPUs roles (q,g,k,c,v)
#X_nCPU_LinAlg_INV= $ncpu # [PARALLEL] CPUs for Linear Algebra
X_Threads= 0 # [OPENMP/X] Number of threads for response functions
DIP_Threads= 0 # [OPENMP/X] Number of threads for dipoles
SE_CPU= "1 1 $ncpu" # [PARALLEL] CPUs for each role
SE_ROLEs= "q qp b" # [PARALLEL] CPUs roles (q,qp,b)
SE_Threads= 0

In particular "X_CPU" sets how the MPI Tasks are distributed in the calculation of the response function.
The possibilities are shown in the "X_ROLEs". The same holds for "SE_CPU" and "SE_ROLEs" which control
how MPI Tasks are distributed in the calculation of the response function.

Please try different parallelization schemes and check the performances of Yambo.
In doing so you should also change the jobname in the run.sh script
label=MPI${ncpu}_OMP${nthreads}_scheme1

Using the python script, you can then chenck how speed, memory and load balance between the CPUs are affected.
For more details see also the [[Using_Yambo_in_parallel|Parallel module]]

'''tips: '''
* the product of the numbers entering each variable (i.e. X_CPU and SE_CPU) times the number of threads should always match the total number of cores (unless you want to overload the cores taking advantage of multi-threads) 
* using the X_Threads and SE_Threads variables you can think about setting different Hybrid schemes in between the screening and the self-energy runlevel.
* memory better scales if you parallelize on bands (c v b) 
* parallelization on k-points performs similarly to parallelization on bands, but memory requires more memory 
* parallelization on q-points requires much less communication in between the MPI tasks. It maybe useful if you run on more than one node and the inter-node connection is slow

 
{| 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]] --> [[GW_parallel_strategies|GW Parallel]]
|style="width:35%; text-align:right"|Next: [[Pushing_convergence_in_parallel|GW Convergence]]
|-
|}