Yambo 2016
Introduction
YAMBO implements Many-Body Perturbation Theory (MBPT) methods (such as GW and BSE) and Time-Dependent Density Functional Theory (TDDFT), which allows for accurate prediction of fundamental properties as band gaps of semiconductors, band alignments, defect quasi-particle energies, optics and out-of-equilibrium properties of materials. ¹
Installed version(s)
The following versions are installed and currently available on environment hpc-env/8.3:
- Yambo/5.0.2-intel-2019b
Loading / Using Yambo
To load the desired version of the module, use the module load command, e.g.
module load hpc-env/8.3 module load Yambo
Always remember: this command is case sensitive!
After loading the Yambo module, yambo and its associated executables (a2y, c2y, p2y, ypp) can be called from within every directory. But since the software package was installed with intel MPI to ensure parallel computing, you must call the desired executables with mpirun -np <threads> <executable> , for example like this:
mpirun -np 4 yambo
Start Working with Yambo: Quick Tutorial
Our installed module version of Yambo on CARL differs slightly in how to call the specific commands. For this reason, you can find a shortened and slightly modified tutorial which is based on the wiki pages Bulk material: h-BN and Initialization from the yambo tutorial wiki.
On our tutorial version, we will focus on the commands and output files, and not much about the scientific substance of the results. If you want to know more about that we highly recommend visiting the wiki pages that this tutorial is based on.
Bulk material: h-BN
Prerequisites
We will use the following modules, executables and files:
- PWSCF input files and pseudopotentials for hBN bulk
- the modules QuantumESPRESSO/6.6-intel-2019b and Yambo/5.0.2-intel-2019b on hpc-env/8.3
- pw.x executable, version 5.0 or later
- p2y and yambo executables
DFT calculations
Firstly, create a test folder and get the test files for this tutorial:
mkdir $HOME/yambo_test && cd $HOME/yambo_test wget http://www.yambo-code.org/educational/tutorials/files/hBN.tar.gz tar xvf hBN.tar.gz
Load the modules and cd into the untarred directory
ml hpc-env/8.3 ml QuantumESPRESSO/6.6-intel-2019b # It must be this version, not the 6.7 version based on intel-iompi. Otherwise, you will run into MPI errors ml Yambo/5.0.2-intel-2019b cd hBN/PWSCF
Now, run the SCF calculation to generate the ground-state charge density, occupations, Fermi level, and so on. For this step, we need the executable pw.x which is part of QuantumESPRESSO and not callable from only the Yambo module. Also, since QuantumESPRESSO and Yambo are built on MPI, you always have to call the executables with mpirun
mpirun pw.x < hBN_scf.in > hBN_scf.out # can take up to 1 minute
Next run a non-SCF calculation to generate a set of Kohn-Sham eigenvalues and eigenvectors for both occupied and unoccupied states (100 bands):
mpirun -np 4 pw.x < hBN_nscf.in > hBN_nscf.out # this step can be parallelized, here with 4 threads (-np 4)
Here we use a 6x6x2 grid giving 14 k-points, but denser grids should be used for checking convergence of Yambo runs.
Note the presence of the following flags in the input file:
wf_collect=.true. force_symmorphic=.true. diago_thr_init=5.0e-6, diago_full_acc=.true.
which are needed for generating the Yambo databases accurately. Full explanations of these variables are given on the quantum-ESPRESSO input variables page.
After these two runs, you should have a hBN.save directory:
$ ls hBN.save B.pz-vbc.UPF N.pz-vbc.UPF wfc12.hdf5 wfc1.hdf5 wfc4.hdf5 wfc7.hdf5 charge-density.hdf5 wfc10.hdf5 wfc13.hdf5 wfc2.hdf5 wfc5.hdf5 wfc8.hdf5 data-file-schema.xml wfc11.hdf5 wfc14.hdf5 wfc3.hdf5 wfc6.hdf5 wfc9.hdf5
Conversion to Yambo format
The PWscf bBN.save output is converted to the Yambo format using the p2y executable (pwscf to yambo), found in the yambo bin directory ($EBROOTYAMBO/bin - callable from everywhere). Enter hBN.save and launch p2y:
cd hBN.save mpirun p2y
This output repeats some information about the system and generates a SAVE directory
ls SAVE ns.db1 ns.wf ns.kb_pp_pwscf ns.wf_fragments_1_1 ... ns.kb_pp_pwscf_fragment_1 ...
These files, with an n prefix, indicate that they are in netCDF format, and thus not human readable. However, they are perfectly transferable across different architectures. You can check that the databases contain the information you expect by launching Yambo using the -D option:
mpirun yambo -D
Initialization
For Yambo to initialize, you must be at the directory containing the SAVE folder, and not inside the SAVE folder. The error output yambo: cannot access CORE database (SAVE/*db1 and/or SAVE/*wf) mostly will tell you, that you are currently not inside the right directory.
But since we created the SAVE folder at the steps above, you are probably at the right place and can directly call yambo:
mpirun -np4 yambo ## you can parallelize the process, but this is not mandatory
There is now r_setup_02 In the case of parallel runs, CPU-dependent log files will appear inside a LOG folder, e.g.
ls LOG l_p2y_CPU_1 l_p2y_CPU_13 l_p2y_CPU_17 ...
Run-time output
This is typically written to standard output (on screen) and tracks the progress of the run in real time:
<---> [01] MPI/OPENMP structure, Files & I/O Directories <---> [02] CORE Variables Setup <---> [02.01] Unit cells <---> [02.02] Symmetries <---> [02.03] Reciprocal space <---> Shells finder |########################################| [100%] --(E) --(X) <---> [02.04] K-grid lattice <---> Grid dimensions : 6 6 2 <---> [02.05] Energies & Occupations <---> [03] Transferred momenta grid and indexing <---> BZ -> IBZ reduction |########################################| [100%] --(E) --(X) <---> [03.01] X indexes <---> X [eval] |########################################| [100%] --(E) --(X) <---> X[REDUX] |########################################| [100%] --(E) --(X) <---> [03.01.01] Sigma indexes <---> Sigma [eval] |########################################| [100%] --(E) --(X) <---> Sigma[REDUX] |########################################| [100%] --(E) --(X) <---> [04] Timing Overview <---> [05] Memory Overview <---> [06] Game Over & Game summary
Specific runlevels are indicated with numeric labels like [02.02]. The hashes (#) indicate the progress of the run in Wall Clock time, indicating the elapsed (E) and expected (X) time to complete a runlevel, and the percentage of the task complete.
New core databases
New databases appear in the SAVE folder:
ls SAVE ns.db1 ns.wf ns.kb_pp_pwscf ndb.gops ndb.kindx ns.wf_fragments_1_1 ... ns.kb_pp_pwscf_fragment_1 ...
These contain information about the G-vector shells and k/q-point meshes as defined by the DFT calculation.
In general: a database called ns.xxx is a static database, generated once by p2y, while databases called ndb.xxx are dynamically generated while you use yambo.
TIP: if you launch yambo, but it does not seem to do anything, check that these files are present.
Report File
A report file r_setup is generated in the run directory. This mostly reports information about the ground state system as defined by the DFT run, but also adds information about the band gaps, occupations, shells of G-vectors, IBZ/BZ grids, the CPU structure (for parallel runs), and so on. More about this can be found at the original tutorial
Different Ways of Running Yambo
We just run Yambo interactively.
Let's try to re-run the setup with the command
nohup mpirun yambo & ls l_setup nohup.out r_setup r_setup_01 SAVE
If Yambo is launched using a script, or as a background process, or in parallel, this output will appear in a log file prefixed by the letter l, in this case as l_setup. If this log file already exists from a previous run, it will not be overwritten. Instead, a new file will be created with an incrementing numerical label, e.g. l_setup_01, l_setup_02, etc. This applies to all files created by Yambo. Here we see that l_setup was created for the first time, but r_setup already existed from the previous run, so now we have r_setup_01 If you check the differences between the two you will notice that in the second run yambo is reading the previously created ndb.kindx in place of re-computing the indexes. Indeed the output inside l_setup does not show the timing for X and Sigma
Cite Yambo
The yambo team kindly asks everyone who uses yambo to cite their work about yambo as well, which we think is a very supportable request for reasons of scientific fairness.
Their quote:
"Cite us
It is scientifically fair to cite the two following articles in any publication based on results obtained with Yambo
- Many-body perturbation theory calculations using the yambo code, Davide Sangalli and Andrea Ferretti and Henrique Miranda and Claudio Attaccalite and Ivan Marri and Elena Cannuccia and Pedro Miguel Melo and Margherita Marsili and Fulvio Paleari and Antimo Marrazzo and Gianluca Prandini and Pietro Bonf\`a and Michael O Atambo and Fabio Affinito and Maurizia Palummo and Alejandro Molina Sanchez and Conor Hogan and Myrta Gr\xFCning and Daniele Varsano and Andrea Marini, Journal of Physics: Condensed Matter 31, 325902 (2019).
- Yambo: an ab initio tool for excited state calculations, Andrea Marini, Conor Hogan, Myrta Grüning, Daniele Varsano, Comp. Phys. Comm. 144, 180 (2009).
Check the Yambo researcher ID page for citation information." ²
Documentation
The developers created a very elaborate wiki including tutorials for learning and using Yambo. You can find the wiki entry page here.
You can find the software's main page here
