Input file generation and command line options

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

Note: This is for yambo 4.5 (or before). For yambo 5.0 please follow this link Input file generation and command line options (5.0)

Command-line options are divided into uppercase and lowercase options:

• Lowercase: select tasks, generate input files, and (by default) launch a file editor
• Uppercase: modify Yambo's default settings, at run time and when generating input files

Lowercase and uppercase options can be used together.

Prerequisites

Previous modules

• Initialization for bulk hBN

You will need:

• The SAVE databases for bulk hBN
• The yambo executable

Input file generator

First, move to the appropriate folder and initialize the Yambo databases if you haven't already done so.

$ cd YAMBO_TUTORIALS/hBN/YAMBO
$ yambo                    (initialize)

Yambo generates its own input files: you just tell the code what you want to calculate by launching Yambo along with one or more lowercase options.

Allowed options

To see the list of runlevels and options, run yambo -h or better,

$ yambo -H
This is yambo 4.4.0 rev.148
A shiny pot of fun and happiness [C.D.Hogan] 
-h		:Short Help
-H		:Long Help
-J <opt>	:Job string identifier
-V <opt>	:Input file verbosity[opt=RL,kpt,sc,qp,io,gen,resp,all,par]
-F <opt>	:Input file
-I <opt>	:Core I/O directory
-O <opt>	:Additional I/O directory
-C <opt>	:Communications I/O directory
-D		:DataBases properties
-W <opt>	:Wall Time limitation (1d2h30m format)
-Q		:Don't launch the text editor
-E <opt>	:Environment Parallel Variables file
-M		:Switch-off MPI support (serial run)
-N		:Switch-off OpenMP support (single thread run)
-i		:Initialization
-o <opt>	:Optics [opt=(c)hi is (G)-space / (b)se is (eh)-space ]
-k <opt>	:Kernel [opt=hartree/alda/lrc/hf/sex](hf/sex only eh-space; lrc only G-space)
-y <opt>	:BSE solver [opt=h/d/s/(p/f)i](h)aydock/(d)iagonalization/(i)nversion
-r		:Coulomb potential
-x		:Hartree-Fock Self-energy and local XC
-d		:Dynamical Inverse Dielectric Matrix
-b		:Static Inverse Dielectric Matrix
-p <opt>	:GW approximations [opt=(p)PA/(c)HOSEX]
-g <opt>	:Dyson Equation solver[opt=(n)ewton/(s)ecant/(g)reen]
-l		:GoWo Quasiparticle lifetimes
-a		:ACFDT Total Energy
-s		:ScaLapacK test

Any time you launch Yambo with a lowercase option, Yambo will generate the appropriate input file (default name: yambo.in) and launch the vi editor.

Editor choice can be changed at configure; alternatively you can use the -Q run time option to skip the automatic editing (do this if you are not familiar with vi!):

$ yambo -x -Q
yambo: input file yambo.in created
$ emacs yambo.in     or your favourite editing tool

Combining options

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 for optical spectra including local field effects (Hartree approximation), do (and then exit)

$ yambo -o c -k hartree       which switches on:
optics                       # [R OPT] Optics
chi                          # [R CHI] Dyson equation for Chi.
Chimod= "Hartree"            # [X] IP/Hartree/ALDA/LRC/BSfxc

To perform a Hartree-Fock and GW calculation using a plasmon-pole approximation, do (and then exit):

$ yambo -x -g n -p p        which switches on:
HF_and_locXC                 # [R XX] Hartree-Fock Self-energy and Vxc
gw0                          # [R GW] GoWo Quasiparticle energy levels
ppa                          # [R Xp] Plasmon Pole Approximation
em1d                         # [R Xd] Dynamical Inverse Dielectric Matrix      

Each runlevel activates its own list of variables and flags.

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

Inside the generated input file you should find:

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

The QPkrange variable (follow the link for a "detailed" explanation for any variable) suggests a range of k-points (1 to 14) and bands (1 to 100) based on what it finds in the core database SAVE/ns.db1, i.e. as defined by the DFT code.
Leave that variable alone, and instead modify the previous variable to EXXRLvcs= 1000 RL

Save the file, and now generate the input a second time with yambo -x. You will see:

 EXXRLvcs=  1009        RL

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, note 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. Technical information is available on the Variables page.

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.

Uppercase options

Uppercase options modify some of the code's default settings. They can be used when launching the code but also when generating input files.

Allowed options

To see the list of options, again do:

$ yambo -H
Tool: yambo 4.1.2 rev.14024
Description: A shiny pot of fun and happiness [C.D.Hogan] 
-J <opt>	:Job string identifier
-V <opt>	:Input file verbosity
                [opt=RL,kpt,sc,qp,io,gen,resp,all,par]
-F <opt>	:Input file
-I <opt>	:Core I/O directory
-O <opt>	:Additional I/O directory
-C <opt>	:Communications I/O directory
-D		:DataBases properties
-W <opt>	:Wall Time limitation (1d2h30m format)
-Q		:Don't launch the text editor
-M		:Switch-off MPI support (serial run)
-N		:Switch-off OpenMP support (single thread run)
[Lower case options]

Command line options are extremely important to master if you want to use yambo productively. Often, the meaning is clear from the help menu:

$ 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, plot files inside a folder MyTest

Other options deserve a closer look.

Verbosity

Yambo uses many 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 inout 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. Try:

$ yambo -o c -V RL       switches on:
FFTGvecs=  3951        RL    # [FFT] Plane-waves

$ yambo -o c -V io       switches on:
StdoHash=  40                # [IO] Live-timing Hashes
DBsIOoff= "none"             # [IO] Space-separated list of DB with NO I/O. DB= ...
DBsFRAGpm= "none"            # [IO] Space-separated list of +DB to be FRAG and ...
#WFbuffIO                    # [IO] Wave-functions buffered I/O

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 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). Try:

$ yambo -J 1Ry -V RL -x        and modify to
FFTGvecs = 1 Ry
EXXGvecs = 1 Ry
$ yambo -J 1Ry           Run the code
$ ls
yambo.in SAVE  
o-1Ry.hf r-1Ry_HF_and_locXC 1Ry 1Ry/ndb.HF_and_locXC

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

Exercise: use yambo to report the properties of all database files (including ndb.HF_and_locXC)

Prev: Initialization

Now: Tutorials Home --> First steps --> Input file generation and command line options

Next: Back to First steps