Input file generation¶

In this tutorial you will learn how to select tasks, generate and modify input files, and control the runtime behavior by using Yambo’s command-line interface.

Requirements

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

Command-line interface¶

Yambo generates its own input files: you just tell the code what you want to calculate by launching yambo along with one or more options. You can access the full list of options like this:

$ yambo -h

yambo -h output

 ___ __  _____  __ __  _____   _____ 
|   Y  ||  _  ||  Y  ||  _  \ |  _  |
|   |  ||. |  ||.    ||. |  / |. |  |
 \   _/ |. _  ||.\ / ||. _  \ |. |  |
  |: |  |: |  ||: |  ||: |   \|: |  |
  |::|  |:.|:.||:.|:.||::.   /|::.  |
  `--"  `-- --"`-- --"`-----" `-----"
 'A shiny pot of fun and happiness [C.D.Hogan]' 

 This is      : yambo
 Version      : 5.3.0 Revision 23927 Hash 1730222ea 
 Configuration: MPI+GPU+CUDA+CUDAF+OpenMP+SLK+SLEPC+HDF5_MPI_IO 

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

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

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

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

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

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

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

 Total Energy:
 -acfdt                           :ACFDT Total Energy

 Utilites:
 -Quiet           (-Q)            :Quiet input file creation
 -fatlog                          :Verbose (fatter) log(s)
 -expuser                         :Assume experienced user
 -DBlist          (-D)            :Databases properties
 -walltime             <int>      :Walltime (more with -h walltime)
 -memory               <int>      :Memory (more with -h memory)
 -slktest                         :ScaLapacK test
 -gputest                         :GPU test

 YAMBO developers group (http://www.yambo-code.eu)

v4.5 (or older)

$ yambo -H

The options can be split into two sets:

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

Lowercase and uppercase options can be used together.

Runlevel selection¶

First of all, you would like to specify which kind of simulation you want to perform and generate an input file with the first set of options. By default, when generating the input file, Yambo will launch the vi editor. Editor choice can be changed at configuration (before compilation). Alternatively you can use the -Q option to skip the automatic editing (do this if you are not familiar with vi).

Important

Remember that for the input file generation to properly work you should first initialize the SAVE folder.

Let’s see an example:

$ yambo -hf -Q

yambo: input file yambo.in created

$ vim yambo.in #(use your favourite editing tool)

v4.5 (or older)

$ yambo -x -Q

yambo: input file yambo.in created

$ vim yambo.in #(use your favourite editing tool)

Multiple options can be used together to activate various tasks or runlevels (in some cases this is actually a necessity). For instance, to generate an input file to calculate optical spectra including local field effects (Hartree approximation), do

$ yambo -optics c -kernel hartree

If you inspect the generated input file you can see that these options switch on

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
[...]

To perform a Hartree-Fock and GW calculation using a plasmon-pole approximation, do

$ yambo -hf -gw0 p -dyson n

which switches on

HF_and_locXC                     # [R] Hartree-Fock
gw0                              # [R] GW approximation
ppa                              # [R][Xp] Plasmon Pole Approximation for the Screened Interaction
el_el_corr                       # [R] Electron-Electron Correlation
dyson                            # [R] Dyson Equation solver
em1d                             # [R][X] Dynamically Screened Interaction

Note

The previous command is equivalent to

$ yambo -hf -gw0 r -dyson n -X p

Tip

You can also use short options to simplify the command. For example

$ yambo -hf -gw0 r -dyson n -X p

is the same as

$ yambo -x -p r -g n -d p

Changing input parameters¶

Yambo reads various parameters from existing database files and/or input files and uses them to suggest values or ranges.

Let’s illustrate this by generating the input file for a Hartree-Fock calculation.

$ yambo -hf

In the generated input file you should find:

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

Now set the value of EXXRLvcs to 1000 RL, save the file the and generate again the input for the Hartree-Fock calculation with yambo -hf (or yambo -x) as before. You will find that the value has changed to

EXXRLvcs= 1009             RL    # [XX] Exchange    RL components

This indicates that Yambo has read the new input value (1000 G-vectors), checked the database of G-vector shells (SAVE/ndb.gops), and changed the input value to one that fits a completely closed shell.

Last, remember that Yambo variables can be expressed in different units. In this case, RL can be replaced by an energy unit like Ry, eV, Ha, etc. Energy units are generally better as they are independent of the cell size.

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

Managing Yambo calculations¶

Uppercase options modify some of the code’s default settings. They can be used when launching the code but also when generating input files, and they are necessary to use Yambo productively.

Let’s have a look again to the available options:

$ yambo -h

v4.5 (or older)

$ yambo -H

The use of the option is briefly explained in the comment on the side. For example:

$ yambo -F yambo.in_HF -x : Make a Hartree-Fock input file called yambo.in_HF
$ yambo -D : Summarize the content of the databases in the SAVE folder
$ yambo -I ../ : Run the code, using a SAVE folder in a directory one level up (../)
$ yambo -C MyTest : Run the code, putting all report, log and output files inside a folder MyTest
$ yambo -O MyData : Run the code, putting all the generated databases inside a folder MyData.

Verbosity¶

Yambo uses a lot of input variables, many of which can be left at their default values.

To keep input files short and manageable, only a few variables appear by default in the input file. More advanced variables can be switched on by using the -V (verbosity) option. These are grouped according to the type of variable. For instance, -V RL switches on variables related to G-vector summations, and -V io switches on options related to I/O control.

For example:

$ yambo -optics c -V RL swithces on FFTGvecs
$ yambo -optics c -V io switches on StdoHash, DBsIOoff, DBsFRAGpm, WFbuffIO

Warning

Unfortunately, -V options must be invoked and changed one at a time.

When you are more expert, you may go straight to -V all, which turns on all possible variables. However note that yambo -o c -V all alone adds an extra 30 variables to the input file, which can be confusing: use it with care.

Job script label¶

The best way to keep track of different runs using different parameters is through the -J flag. This inserts a label in all output and report files, and creates a new folder containing any new databases (i.e. they are not written in the core SAVE folder).

To see how this works try

$ yambo -J 1Ry -V RL -hf -F yambo_hf.in

and set

FFTGvecs = 1 Ry
EXXGvecs = 1 Ry

Then run the calculation using the -J option like this

$ yambo -J 1Ry -F yambo_hf.in

When the calculation is done you can see that the corresponding files and directories have been labeled with 1Ry:

$ ls -d *1Ry*
1Ry  l-1Ry_HF_and_locXC  o-1Ry.hf  r-1Ry_HF_and_locXC
$ ls 1Ry/
ndb.HF_and_locXC

Important

This feature is extremely useful when running convergence tests, trying out different parameters, etc.

Remember that the -J option tells Yambo to look into folders for existing and compatible databases, which are read if found.

You can also put multiple lables after the -J option, for example -J lab1,lab2,lab3: in this case Yambo will look for compatible databases starting from lab1 and continuing in the order in which labels are provided; new databases will be printed in the first directory (again lab1).

Caution

You can also combine the -J option with the -O option.

 yambo -J lab1 -O lab2

In this case Yambo will look for compatible databases in lab1, but new databases will be written in lab2/lab1.

However keep in mind that the -O option does not add any label to the output files.

Finally, try to use Yambo command line options to print a report of the properties of all databases (including ndb.HF_and_locXC). Which options do you need?

See the answer

The options are -D and -J 1Ry:

$ yambo -D -J 1Ry

which in this case gives

[RD./SAVE//ns.db1]--------------------------------------------------------------
 Bands                                            :  100
 K-points                                         :  14
 G-vectors                                        :   8029 [RL space]
 Components                                       :  1016 [wavefunctions]
 Symmetries                                       :  24 [spatial+T-reV]
 Spinor components                                :  1
 Spin polarizations                               :  1
 Temperature                                      :  0.000000 [eV]
 Electrons                                        :  16.00000
 WF G-vectors                                     :  1477
 Max atoms/species                                :  2
 No. of atom species                              :  2
 Magnetic symmetries                              : no
- S/N 003471 ---------------------------------------------- v.04.01.02 r.14024 -
[RD./SAVE//ns.wf]---------------------------------------------------------------
 Fragmentation                                    : yes
 Bands in each block                              :  100
 Blocks                                           :  1
- S/N 003471 ---------------------------------------------- v.04.04.00 r.16920 -
[RD./SAVE//ndb.kindx]-----------------------------------------------------------
 Fragmentation                                    : no
 Polarization last K ( bz)                        :   72
 Polarization last K (ibz)                        :  14
 QP states                                        :   1  14
 X grid is uniform                                : yes
 Grids (string)                                   :  X S
 Grids (int-vector)                               :  1  0  0  1
- S/N 003471 ---------------------------------------------- v.05.03.00 r.23927 -
[RD./1Ry//ndb.HF_and_locXC]-----------------------------------------------------
 Brillouin Zone Q/K grids (IBZ/BZ)                :   14   72   14   72
 RL vectors                                       :   5 [WF]
 Fragmentation                                    : no
 Electronic Temperature                           :  0.000000 [K]
 Bosonic    Temperature                           :  0.000000 [K]
 Green`s function   wavefunctions                 : Slater exchange(X)+Perdew & Zunger(C)
 Total number of QP states                        :  1400
 Exchange RL vectors                              :   5
 Exchange summation bands                         :   8
 RIM RL components                                : 0
 RIM random points                                : 0
- S/N 003471 ---------------------------------------------- v.05.03.00 r.23927 -
[RD./SAVE//ns.kb_pp_pwscf]------------------------------------------------------
 Fragmentation                                    : yes
- S/N 003471 ---------------------------------------------- v.04.01.02 r.14024 -