(input-file-generation-tutorial-target)= # 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. ```{admonition} Requirements - `hBN` folder: download and extract `hBN.tar.gz` from the [Tutorial files](#tutorial-files-target) page - the `SAVE` folder (present in `hBN/YAMBO`) **already** [**initialized**](#database-initialization-tutorial-target) - `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: ``````{tab-set} `````{tab-item} v5 ````{code-block} none $ yambo -h ```` ````{dropdown} yambo -h output ```{literalinclude} snippets/yambo-h_v5.txt :language: none ``` ```` ````` `````{tab-item} v4.5 (or older) ````{code-block} none $ yambo -H ```` ````{dropdown} yambo -H output ```{literalinclude} snippets/yambo-h_v4.txt :language: none ``` ```` ````` `````` 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: ``````{tab-set} `````{tab-item} v5 ````{code-block} none $ yambo -hf -Q yambo: input file yambo.in created $ vim yambo.in #(use your favourite editing tool) ```` ````{dropdown} yambo.in content ```{literalinclude} snippets/yambo-hf_v5.txt :language: none ``` ```` ````` `````{tab-item} v4.5 (or older) ````{code-block} none $ yambo -x -Q yambo: input file yambo.in created $ vim yambo.in #(use your favourite editing tool) ```` %````{dropdown} yambo -H output %```{literalinclude} snippets/yambo-h_v4.txt %:language: none %``` %```` ````` `````` 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 ```{code-block} none $ yambo -optics c -kernel hartree ``` If you inspect the generated input file you can see that these options switch on ```{code-block} none 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 ```{code-block} none $ yambo -hf -gw0 p -dyson n ``` which switches on ```{code-block} none 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 ```{code-block} none $ yambo -hf -gw0 r -dyson n -X p ``` ```` ````{tip} :class: dropdown You can also use short options to simplify the command. For example ```{code-block} none $ yambo -hf -gw0 r -dyson n -X p ``` is the same as ```{code-block} none $ 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. ```{code-block} none $ yambo -hf ``` In the generated input file you should find: ```{code-block} none 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 ```{code-block} none 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. ```{seealso} The complete list and description of variables is provided at the dedicated [Input file variables page](#input-file-variables-target). ``` ## 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: ``````{tab-set} `````{tab-item} v5 ````{code-block} none $ yambo -h ```` ````{dropdown} yambo -h (uppercase options) ```{literalinclude} snippets/yambo-h_uppercase_v5.txt :language: none ``` ```` ````` `````{tab-item} v4.5 (or older) ````{code-block} none $ yambo -H ```` ````{dropdown} yambo -H (uppercase options) ```{literalinclude} snippets/yambo-h_uppercase_v4.txt :language: none ``` ```` ````` `````` 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 ```{code-block} $ 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 ```{code-block} none $ 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`: ```{code-block} none $ 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} :class: dropdown You can also combine the `-J` option with the `-O` option. ```{code} 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? ````{dropdown} See the answer The options are `-D` and `-J 1Ry`: ```{code-block} none $ yambo -D -J 1Ry ``` which in this case gives ```{code-block} none [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 - ``` ````