Tutorials: Difference between revisions

From The Yambo Project
Jump to navigation Jump to search
mNo edit summary
 
(26 intermediate revisions by 4 users not shown)
Line 1: Line 1:
If you are starting out with Yambo, or even an experienced user, we recommend that you complete the following tutorials before trying to use Yambo for your system.
The tutorials are meant to give some introductory background to the key concepts behind Yambo. Practical topics such as convergence are also discussed.  
The tutorials are meant to give some introductory background to the key concepts behind Yambo. Practical topics such as convergence are also discussed.  
Nonetheless, users are invited to first read and study the [[lectures|background material]] in order to get familiar with the fundamental physical quantities.
Nonetheless, users are invited to first read and study the [[lectures|background material]] in order to get familiar with the fundamental physical quantities.
We recommend that you complete the tutorials before trying to use Yambo for your system.


Two kinds of tutorials are provided: '''stand-alone''' and '''modular'''. In addition you must have a working environment where both Yambo (and eventually QE) are installed.
You must have a working environment where both Yambo and Yambopy (and eventually QE or abinit) are installed.
 
If you are starting out with Yambo, we suggest to follow [[Setting up Yambo|this page]] with a detailed explanation about how to set up all you need for running the tutorials.
== Setting up Yambo (and eventually QE)  ==
To be able to follow the school you need a running version of the yambo/QE code.
 
There are several different ways to prepare a working environment.
 
=== Virtual Machine(s) ===
The easiest way is to access to a virtual machine which contains both (i) yambo/QE and (ii) the tutorials.
 
You can do it in one of two ways:
* Virtual machine via [[ICTP cloud|ICTP cloud]] If the schools you are attending provided an ICTP virtual machine this is the preferred option. It works through internet connection inside a browser.
* Install the [[Yambo_Virtual_Machine|yambo virtual machine]] on your laptop / desktop. This requires Oracle virtual box. Pre-download of the Virtual machine. No internet connection needed.
<!--
URL of the machine : https://ins45100.ictp.it/
READ-ONLY PASSWORD for TUTOR (ictptutor) access:
NairibiTutor
READ-WRITE password for PARTICIPANT's (ictpuser) access:
NairobiUser
-->
 
=== User installation  ===
You can also setup the yambo code on your on laptop / desktop using different methods.
 
As far as the Yambo source is concerned you can:
* Install [[Yambo via Docker|Yambo via Docker]]
* [[download|Download]] and [[Installation|install]] yambo on your laptop / desktop (requires a linux machine).
* Install yambo on your laptop/desktop/cluster [https://github.com/nicspalla/my-repo via Spack].
* Install using  Anaconda.
 
=== Yambo User Installation with Anaconda ===
It is possible to install Yambo (up to v5.0.4) and Quantum-ESPRESSO via conda-forge (a conda channel/repository):
To setup Anaconda, please start from installing [https://www.anaconda.com/products/distribution#Downloads Anaconda] or [https://docs.conda.io/en/latest/miniconda.html Miniconda].
 
Then we suggest to create a conda environment and activate it:
conda create --name yambopy -c conda-forge
conda activate yambopy
Then you can install the prerequisites and the two codes:
conda install numpy scipy netcdf4 matplotlib pyyaml lxml pandas
conda install yambo
conda install qe
 
==Setting up Yambopy==
 
===Quick installation===
 
A quick way to start using Yambopy is described here.
 
* Make sure that you are using Python 3 and that you have the following python packages: <code>numpy</code>, <code>scipy</code>, <code>matplotlib</code>, <code>netCDF4</code>, <code>lxml</code>, <code>pyyaml</code>. Optionally, you may want to have abipy [[https://abinit.github.io/abipy/index.html]] installed for band structure interpolations.
 
* Go to a directory of your choice and clone yambopy from the git repository
 
git clone https://github.com/yambo-code/yambopy.git
 
If you don't want to use git, you may download a tarball from the git repository instead.
 
* Enter into the yambopy folder and install
 
cd yambopy
sudo python setup.py install
 
If you don't have administrative privileges (for example on a computing cluster), type instead
 
cd yambopy
python setup.py install --user
 
===Installing dependencies with Anaconda===
We suggest installing yambopy using Anaconda [[https://www.anaconda.com/products/distribution]] to manage the various python packages.
 
In this case, you can follow these steps.
 
First, install the required dependencies:
conda install numpy scipy netcdf4 lxml pyyaml
 
Then we create a conda environment based on python 3.6 (this is to ensure compatibility with abipy if we want to install it later on):
conda create --name NAME_ENV python=3.6
Here choose <code>NAME_ENV</code> as you want, e.g. <code>yenv</code>.
 
Now, we install abipy and its dependency pymatgen using <code>pip</code>. Here make sure that you are using the <code>pip</code> version provided by Anaconda and not your system version.
 
pip install pymatgen
pip install abipy
 
Finally, we are ready to install yambopy:
 
git clone https://github.com/yambo-code/yambopy.git
 
(or download and extract tarball) and follow the steps outlined in the quick installation section.
 
Now enter into the yambopy folder and install
 
cd yambopy
sudo python setup.py install
 
If you don't have administrative privileges (for example on a computing cluster), type instead
 
cd yambopy
python setup.py install --user
 
===Frequent issues===
When running the installation you may get a <code>SyntaxError</code> related to utf-8 encoding or it may complain that module <code>setuptools</code> is not installed even though it is. In this case, it means that the <code>sudo</code> command is not preserving the correct <code>PATH</code> for your python executable.
 
Solve the problem by running the installation step as
 
sudo /your/path/to/python setup.py install
or
sudo env PATH=$PATH python setup.py install
 
This applies only to the installation step and not to subsequent yambopy use.
 
== Tutorial files ==
The tutorial CORE databases can be obtained
 
* from the [[Yambo_Virtual_Machine|Yambo Virtual Machine]]
* from the Yambo web-page
* from the Yambo GIT tutorial repository
 
=== From the Yambo Virtual Machine (VM)  ===
If you are using the VM, a recent version of the tutorial files is provided.Follow these [[Yambo_Virtual_Machine#Updating_the_Yambo_tutorial_files| instructions]] to update the tutorial files to the most recent version.
 
=== From the Yambo website ===
If you are using your own installation or the docker, the files needed to run the tutorials can be downloaded from the lists below.
 
After downloading the tar.gz files just unpack them in '''the YAMBO_TUTORIALS''' folder. For example
$ mkdir YAMBO_TUTORIALS
$ mv hBN.tar.gz YAMBO_TUTORIALS
$ cd YAMBO_TUTORIALS
$ tar -xvfz hBN.tar.gz
$ ls YAMBO_TUTORIALS
  hBN
 
====Files needed for modular tutorials====
All of the following should be downloaded prior to following the modular tutorials:
 
{| class="wikitable"
|-
! Tutorial !! File(s)
|-
| rowspan="4"| hBN || [https://media.yambo-code.eu/educational/tutorials/files/hBN.tar.gz hBN.tar.gz]
|-
| [https://media.yambo-code.eu/educational/tutorials/files/hBN-convergence-kpoints.tar.gz hBN-convergence-kpoints.tar.gz]
|-
| [https://media.yambo-code.eu/educational/tutorials/files/hBN-2D.tar.gz hBN-2D.tar.gz]
|-
| [https://media.yambo-code.eu/educational/tutorials/files/hBN-2D-para.tar.gz hBN-2D-para.tar.gz]
|-
|}
 
====Files needed for stand-alone tutorials====
At the start of each tutorial you will be told which specific file needs to be downloaded:
 
{| class="wikitable"
|-
! Tutorial !! File(s)
|-
| rowspan="2"| Silicon || [https://media.yambo-code.eu/educational/tutorials/files/Silicon.tar.gz Silicon.tar.gz]
|-
|[https://media.yambo-code.eu/educational/tutorials/files/Silicon_Electron-Phonon.tar.gz Silicon_Electron-Phonon.tar.gz]
|-
| LiF || [https://media.yambo-code.eu/educational/tutorials/files/LiF.tar.gz LiF.tar.gz]
|-
| Aluminum || [https://media.yambo-code.eu/educational/tutorials/files/Aluminum.tar.gz Aluminum.tar.gz]
|-
| GaSb || [https://media.yambo-code.eu/educational/tutorials/files/GaSb.tar.gz GaSb.tar.gz]
|-
| AlAs || [https://media.yambo-code.eu/educational/tutorials/files/AlAs.tar.gz AlAs.tar.gz]
|-
| Hydrogen_Chain || [https://media.yambo-code.eu/educational/tutorials/files/Hydrogen_Chain.tar.gz Hydrogen_Chain.tar.gz]
|-
|}
 
=== From the Git Tutorial Repository (advanced users) ===
If you are using your own installation or the docker, the [https://github.com/yambo-code/tutorials tutorials repository] contains the updated tutorials CORE databases. To use it
$ git clone https://github.com/yambo-code/tutorials.git YAMBO_TUTORIALS
$ cd YAMBO_TUTORIALS
$ ./setup.pl -install
 
== Stand-alone tutorials ==
These tutorials are self-contained and cover a variety of mixed topics, both physical and methodological. They are designed to be followed from start to finish in one page and do not require previous knowledge of yambo. Each tutorial requires download of a specific core database, and typically they cover a specific physical system (like bulk GaSb or a hydrogen chain). Ground state input files and pseudopotentials are provided. Output files are also provided for reference.
 
These tutorials can be accessed directly from this page of from the side bar. They include different kind of subjects:
 
'''Warning''': These tutorials were prepared using previous version of the Yambo code: some command lines, variables, reports and outputs can be  slightly different from the last version of the code.  Scripts for parsing output cannot work anymore and should be edited to work with the new outputs. New command lines can be accessed typing <code>yambo -h </code>
 
=== Basic ===
* [[LiF|Linear Response in 3D. Excitons at work]]
* [[Silicon|GW convergence]]
<!--
* [[Si_Surface|Linear Response in 2D]]
* [[Si_wire|Linear Response in 1D]]
* [[H2|Linear Response in 0D]]
-->
=== Post Processing ===
* [[Yambo Post Processing (ypp)]]
* [https://www.yambo-code.org/wiki/index.php?title=First_steps_in_Yambopy First Steps in YamboPy]
* [https://www.yambo-code.org/wiki/index.php?title=Yambopy_tutorial:_band_structures Yambopy tutorial: band structures]
* [https://www.yambo-code.org/wiki/index.php?title=Yambopy_tutorial:_Yambo_databases Yambopy tutorial: Yambo databases]
 
=== Advanced ===
* [[Hydrogen chain|TDDFT Failure and long range correlations]]
* [[Linear response from real time simulations]]
 
==== GW and Quasi-particles ====
* [[Real_Axis_and_Lifetimes|Real Axis and Lifetimes]]
* [[Self-consistent GW on eigenvalues only]]
* [[GW tutorial on HPC]]
 
==== Electron phonon coupling ====
* [[Electron Phonon Coupling|Electron Phonon Coupling]]
* [[Optical properties at finite temperature]]
* [[Phonon-assisted luminescence by finite atomic displacements]]
* [[Exciton-phonon coupling and luminescence]]
 
==== Non linear response ====
* [http://www.attaccalite.com/lumen/linear_response.html Linear response using Dynamical Berry phase]
* [[Real time approach to non-linear response]]
* [[Correlation effects in the non-linear response]]
* [http://www.attaccalite.com/lumen/thg_in_silicon.html Third Harmonic Generation]
* [http://www.attaccalite.com/lumen/spin_orbit.html Spin-orbit coupling and non-linear response]
* [[Two-photon absorption]]
* [[Pump and Probe]]
* [[Parallelization for non-linear response calculations]]
 
==== Developing Yambo ====
* [[How to create a new project in Yambo]]
* [[How to create a new ypp interface]]
* [[Some hints on github]]
<!--
* [[SOC|Spin-Orbit Coupling MBPT]]
* [[Kerr|Kerr]]
* [[Real_Time|Real-Time]]
-->
 
<!-- For each TUTORIAL (Solid_LiF, Solid_Al, ...) , therefore, you can download the ground state files (zip archive named TUTORIAL_ground_state.zip) and generate the Yambo databases from your own by running abinit/PWscf and a2y/p2y. In this case the Yambo input and reference files are contained in the zip file (TUTORIAL_reference_files.zip). Alternatively, if (and only if) you have compiled yambo with the NetCDF support you can directly download the zip files containing the Yambo core databases (TUTORIAL_NETCDF_databases_and_reference_files.zip). These are generated using the NetCDF interface in order to be readable in any platform.
After you have downloaded the tutorial zip files and unziped them you should have now a tutorial tree:
localhost:> ls
YAMBO_TUTORIALS/
localhost:> ls  YAMBO_TUTORIALS/
COPYING  Fantastic_Dimensions/  Hydrogen_Chain/  README  Solid_LiF/ Solid_Al/ SiH4/ ...
In each folder you will find an Abinit or Pwscf subfolder in case you have downloaded the ground state zip files and the YAMBO subfolder. The tutorials start by entering the YAMBO subfolder and followinf the informations provided in the tutorial documentation.  -->
 
== Modular tutorials ==
These tutorials are designed to provide a deeper understanding of specific yambo tasks and runlevels. They are designed to avoid repetition of common procedures and physical concepts. As such, they make use of the same physical systems: bulk hexagonal boron nitride ''hBN'' and a hBN sheet ''hBN-2D''.
 
'''Warning''': These tutorials were prepared using previous version of the Yambo code: some command lines, variables, reports and outputs can be  slightly different from the last version of the code.  Scripts for parsing output cannot work anymore and should be edited to work with the new outputs. New command lines can be accessed typing <code>yambo -h </code>
 
====Introduction====
* [[First steps: a walk through from DFT to optical properties]]
====Quasiparticles in the GW approximation====
* [[How to obtain the quasi-particle band structure of a bulk material: h-BN]]
====Using Yambo in Parallel====
This modules contains very general discussions of the parallel environment of Yambo. Still the actual run of the code is specific to the CECAM cluster. If you want to run these modules just replace the parallel queue instructions with simple MPI commands.
 
* [[GW_parallel_strategies|Parallel GW (CECAM specific)]]: strategies for running Yambo in parallel
[[GW_parallel_strategies_CECAM]]
* [[Pushing_convergence_in_parallel|GW convergence (CECAM specific)]]: use Yambo in parallel to converge a GW calculation for a layer of hBN (hBN-2D)
 
====Excitons and the Bethe-Salpeter Equation====
* [[How to obtain an optical spectrum|Calculating optical spectra including excitonic effects: a step-by-step guide]]
* [[How to choose the input parameters|Obtaining a converged optical spectrum]]
* [[How to treat low dimensional systems|Many-body effects in low-dimensional systems: numerical issues and remedies]]
* [[How to analyse excitons|Analysis of excitonic spectra in a 2D material]]
<!--* [[Two particle excitations]] (try to bypass this page) : Learn how to set up and run calculations to obtain and analyze an optical absorption spectrum of bulk and low dimension materials by using the Bethe-Salpeter equation-->
 
====Yambopy====
* [[First steps in Yambopy]]
* [[GW tutorial. Convergence and approximations (BN)]]
* [[Bethe-Salpeter equation tutorial. Optical absorption (BN)]]
* [[Yambopy tutorial: band structures | Database and plotting tutorial for quantum espresso: qepy]]
* [[Yambopy tutorial: Yambo databases | Database and plotting tutorial for yambo: yambopy ]]
 
<!--
====Real-time simulations====
* [[Breaking of symmetries]]
* [[Independent-Particle Approximation Dynamics. Delta Pulse]]
* [[Post-processing. Optical Response]]
-->
=== Modules ===
Alternatively, users can learn more about a specific runlevel or task by looking at the individual '''[[Modules|documentation modules]]'''. These provide a focus on the input parameters, run time behaviour, and underlying physics. Although they can be followed separately, non-experts are urged to follow them as part of the more structured tutorials given above.


<!--
In the left main menu you can access the different Tutorials sections:
== <span id="Schools"></span>Schools ==
* [[Tutorials_download|Download information]]
* [[ICTP2020]]
* [[Tutorials_standalone|Stand-alone tutorials]]
* [[CECAM VIRTUAL 2021]]
* [[Tutorials_modular|Modular tutorials]] and corresponding [[Modules|Modules]]
* [https://www.yambo-code.org/wiki/index.php?title=ICTP_2022 ICTP2022]
* [https://enccs.github.io/max-coe-workshop/day5-tutorials/ More tutorials in Markdown]
-->

Latest revision as of 15:36, 31 October 2024

The tutorials are meant to give some introductory background to the key concepts behind Yambo. Practical topics such as convergence are also discussed. Nonetheless, users are invited to first read and study the background material in order to get familiar with the fundamental physical quantities. We recommend that you complete the tutorials before trying to use Yambo for your system.

You must have a working environment where both Yambo and Yambopy (and eventually QE or abinit) are installed. If you are starting out with Yambo, we suggest to follow this page with a detailed explanation about how to set up all you need for running the tutorials.

In the left main menu you can access the different Tutorials sections:

Retrieved from "https://wiki.yambo-code.eu/wiki/index.php?title=Tutorials&oldid=8115"