Database initialization¶

In this tutorial you will learn how to initialize the databases in the SAVE folder generated by p2y.

Requirements

hBN folder: download and extract hBN.tar.gz from the Tutorial files page
the SAVE folder (already present in hBN/YAMBO)
yambo executable

In this example we will use hBN. After you have downloaded the required files, move to the hBN folder:

$ cd hBN/
$ ls
COPYING  PWSCF  README.tutorials  YAMBO

Initialization¶

Important

Every Yambo run must start with this step.

First go to where the SAVE directory is located, in this case

$ cd YAMBO
$ ls
GW_QP_database  SAVE

From here, simply run yambo to initialize the databases:

$ yambo

Warning

Do not run yambo from inside the SAVE folder. If you do this you get the following error:

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

Tip

In general, if you get this message it means that you are trying to launch yambo from the wrong place.

Specific runlevels are indicated with numeric labels like [02.02]. The hashes (#) indicate progress of the run in wall clock time, indicating the elapsed (E) and expected (X) time to complete a runlevel, and the completed percentage of the task.

New core databases¶

After the initialization step new databases appear in the SAVE folder:

$ ls SAVE
ndb.gops ndb.kindx
ns.db1 ns.wf ns.kb_pp_pwscf ns.kb_pp_pwscf_fragment_1 ns.wf_fragments_10_1 ...

These highlighted databases contain information about the G-vector shells and k/q-point meshes as defined by the DFT calculation. If these databases are already present launching yambo (to initialize the SAVE) won’t do anything.

Tip

In general a database called ns.* is a static database (generated once by p2y) while databases called ndb.* are dynamically generated while you use yambo.

The initialization 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.

Important

A report file is generated after every run of yambo. You should always inspect the report file for errors and warnings.

Some points of note:

Reciprocal space

[02.03] Reciprocal space
========================

Full and reduced cutoff:   43799.5      79818.4    [mHa]

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

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

K-grid lattice

[02.04] K-grid lattice
======================

Compatible Grid is   : 3D
Base K vectors       :  K_min[ 1 ]  K_min[ 2 ]  K_min[ 3 ]
K_min[ 1 ] :  0.000000 -0.166667  0.000000 [rlu]
K_min[ 2 ] :  0.166667    -0.932573E-8   0.00000    [rlu]
K_min[ 3 ] :  0.000000  0.000000 -0.500000 [rlu]
Grid dimensions      :   6   6   2
K lattice UC volume  :  0.014689 [a.u.]

IBZ K-points                                      :  14
BZ  K-points                                      :   72

K/Q-points units:
rlu = crystal or reduced units; cc = cartesian coordinates; iku = interal k-units

K [ 1]         [rlu]:  0.000000  0.000000  0.000000
       WF components:   997
...

There are 72 k-points in the full BZ, generated using symmetry from the 14 k-points in our user-defined grid.

Energies & Occupations

[02.05] Energies & Occupations
==============================

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

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

The system is insulating (8 filled, 92 empty bands) with an indirect band gap of 3.87 eV. The minimum and maximum direct and indirect gaps are indicated.

Yambo recalculates again the Fermi level (close to the value of 5.06 of the PWscf SCF calculation). From here on, however, the Fermi level is set to zero, and other eigenvalues are shifted accordingly.

Warning

You can specify a value for the temperature in the setup if you generate an input file for the initialization using

$ yambo -i -V all

and modify the ElecTemp variable.

This is useful to get the same Fermi level and possibly the same electronic occupations of the DFT calculation (provided that you used a Fermi-Dirac smearing function), which may be relevant especially for metals.

Also keep in mind that the value of the temperature might affect the exciton binding energy.

Caution

Yambo always uses the default values for the temperature (0 for insulators and room temperature for metals) unless otherwise specified in the input of each calculation.

Report and log files¶

If you launch yambo interactively, the calculation log will be printed on screen.

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.

We can see this behaviour if we run the initialization again:

$ ls
GW_QP_database  SAVE  r_setup
$ yambo

If you check the differences between the log from before and this one 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. You may also see this from the report file:

$ grep 'SAVE//ndb.kindx' r_setup*
r_setup:   [WR./SAVE//ndb.kindx]-----------------------------------------------------------
r_setup_01: [RD./SAVE//ndb.kindx]-----------------------------------------------------------

In the first run the database ndb.kindx was written (WR./SAVE//ndb.kindx) whereas in the second run it was read (RD./SAVE//ndb.kindx).

Important

Remember that Yambo always reads compatible databases when they are available. This saves a lot of time and resources (especially for heavy calculations), but it may be tricky because – as you will learn from other tutorials – if you change an input variable but provide a previous database this will be read and the results will be the same as if you didn’t change the variable at all.

Thus always check report files to see what Yambo is reading and what it is computing.

Tip

The report file always ends with a copy of the input file with the values of the input variables that were actually used in the calculation.

Finally, in the case of parallel runs CPU-dependent log files will be printed inside a LOG folder. For example:

$ ls
SAVE l_setup r_setup
$ mpirun -np 4 yambo 
$ ls
SAVE LOG l_setup r_setup r_setup_01
$ ls LOG
l_setup_CPU_1   l_setup_CPU_2  l_setup_CPU_3  l_setup_CPU_4