# Input file format {#sec:inputformat}

## Pseudopotentials

RESCU solves the Kohn-Sham equation within the pseudopotential
approximation. The idea behind this approximation is to replace the
singular Coulomb potential of an ion by a smooth potential which
reproduces the electronic spectrum in a given energy range. For the
purposes of solid-state physics, it is often possible to neglect the
core electron states which seldom participate in low energy physics and
chemistry. The pseudopotential approximation thus aims at describing the
valence electrons as accurately as possible.

Various flavours of pseudopotentials exist. Norm-conserving
pseudopotentials (NCPS) [\[HSC79\]](#HSC79){.citation} satisfy the
condition that the norm of the pseudo-wavefunctions within the core
region is equal to the norm of the real wavefunction inside the core
region. This guarantees that the logarithmic derivative of the
pseudo-wavefunction at the surface of the core region reproduces the
logarithmic derivative of the real wavefunction at the surface of the
core region. The relation also holds of the energy derivative of the
logarithmic derivative which in turns guarantees a good transferability
of the pseudopotential. NCPS were originally designed as semi-local
pseudopotentials, which means that they are local in the radial
direction but non-local in the angular directions. The accuracy and
transferability of the NCPS thus came at a substantial computational
cost. Kleinmann and Bylander later designed a fully separable
approximation to the semi-local NCPS [\[KB82\]](#KB82){.citation}. The
Kleinmann-Bylander approximation was later made more systematic by
Hamann \[[H89](#H89){.citation}, [H13](#H13){.citation}\]. It is those
generalized norm-conserving pseudopotentials (GNCPS) that RESCU uses to
describe the atoms.

RESCU was developed using the pseudopotentials from the Nanoacademic
database. The database contains tested local-density approximation (LDA)
pseudopotentials from most atoms below radon. The pseudopotentials are
generated from Dirac equation solutions using the Troullier-Martins
[\[TM91\]](#TM91){.citation} scheme. Some pseudopotentials include
partial core charge generated from either the Louie
[\[LFC82\]](#LFC82){.citation} or Martins scheme. The pseudopotential
database has been used to solve many research problems, but the
pseudopotentials will not perform in all situations. The Nanoacademic
Nanobase code can be used to generate new pseudopotentials. It is also
possible to use any separable pseudopotential written in the Nanobase
format.

## Numerical atomic orbitals

The ability to perform calculations using either numerical atomic
orbitals (NAO) or a real space grid is a key feature of RESCU. In
particular, it can switch between frameworks between or during
calculations. The Nanoacademic pseudopotential database thus includes
tested and optimized NAO generated by Nanobase for each element. A set
of double-zeta polarized NAO has been generated following the schema of
Soler *et al.* [\[SAGG02\]](#SAGG02){.citation}. Again, better NAO basis
sets may be generated using Nanobase, but RESCU offers the possibility
to escape the constraints imposed by NAO and solve the Kohn-Sham
equation on a real space grid.

## Element

When defining a system, each atom points to a given element. An element
is a structure comprising the following fields:

-   `species` a string containing a label for the element. It is
    typically the periodic table symbol for the atom species. There may
    be many element structures describing the same atom species in which
    case they cannot all have the same label. This may happen when, for
    example, surface atoms are described using a different basis than
    the bulk atoms in a slab calculation.
-   `path` path to the pseudopotential file containing the description
    of the element.
-   `aoLcutoff` angular momentum cut-off for the NAO.
-   `aoprec` precision of the NAO basis set. It can be 'SZ', 'DZ' and
    'all' for single-zeta, double-zeta and higher-zeta bases
    respectively.
-   `valence` number of valence electrons associated with the element.
    This number is usually set such that the atom is neutral, but it
    does not have to be.
-   `vnlLcutoff` angular momentum cut-off for the pseudopotential
    projectors.
-   `vnlNcutoff` principal quantum number cut-off for the
    pseudopotential projectors.

If an xyz file is passed to RESCU, the species fields will be selected
automatically from the leftmost column. If an xyz file is passed to
RESCU and the species field is still given by the user, the labels must
match those in the xyz file.

## Pseudopotentials database

By default, RESCU will look for pseudopotentials in
`rescu-x.x.x/PotentialData`. If the directory doesn\'t exist, you may
create it and put pseudopotential files in there. If you define a
species called, say, `C`, then RESCU will look for `C_AtomicData.mat` in
there. Same for any periodic table symbol. If you would like to locate
your pseudopotentials elsewhere, or have several pseudopotential
databases, you can point RESCU to any of them by setting the
`RESCU_PSEUDO` environment variable. If `RESCU_PSEUDO` is set, it has
precedence over the default `rescu-x.x.x/PotentialData`. You can list
all pseudopotentials using the `--basis` flag.

## Geometry

The emergent properties of molecules and solids depend on their atomic
arrangement. The coordinates of the atoms can be passed to RESCU as an
array or a path to an xyz file. Being a real-space based code, RESCU can
enforce various boundary conditions. The user may choose between
infinite wall Dirichlet boundary conditions and periodic boundary
conditions. Periodic boundary conditions are suitable for many purposes
(even molecular systems), but the administrator of the RESCU project may
be contacted if other types of boundary conditions are required.

## Simulation parameters

Once the atoms and their arrangement are specified, the simulation
parameters must be specified. Some parameters control the accuracy of
the simulation. For instance, the energy cutoff or grid resolution, and
the Brillouin zone sampling are increased until the results' variations
are below a target threshold. Some parameters govern the algorithms that
compute the Kohn-Sham states or the effective potential entering the
Kohn-Sham Hamiltonian. Yet other parameters allow to enforce certain
symmetries, use certain functionals, tune parallelization or choose the
calculation framework. Most parameters have a default value which may
depend on other parameters. A list of all input parameters and their
description can be found in `$RESCUROOT/doc/inputDescription.m`; a
similar list for output variables is found in
`$RESCUROOT/doc/outputDescription.m`.

## Input syntax

The input file are written in the MATLAB syntax, but it is not necessary
to be familiar with MATLAB to generate an input file. The inputs are set
in the following way: `keywork = value;`. For example, the element
vector described above would be set as: `atom.element = [1;2];`. The
semicolon indicates the end of the statement as in C. Strings are
defined using single quotes. For arrays, columns can be separated by
whitespace or commas and rows are separated by semicolons. For instance,
`[1 2 3; 4 5 6]` is a 2$\times$`<!-- -->`{=html}3 array and
`[1,2;3,4;5,6]` is a 3$\times$`<!-- -->`{=html}2 array. Boolean may be
entered as `false` or `true`. Otherwise, zero is treated as false and
any non-zero number is treated as true.

## Calculation type

RESCU can perform various types of calculations. This is specified using
the all important keyword `info.calculationType`. The allowed values are
summarized in `tab:calctype`{.interpreted-text role="numref"}.

  Calc. types                            Dependency                     Description
  -------------------------------------- ------------------------------ -------------------------------------------------------------------------------------------------------------------------------------------
  band-structure                         self-consistent                Compute a *line* band-structure.
  band-unfolding                         self-consistent                Compute the spectral function for a band-structure.
  density                                self-consistent                Compute the real space density.
  dos                                    self-consistent                Compute the density of states (and possibly LDOS, PDOS).
  dfpt-dielectric                        self-consistent                Compute the dielectric tensor using DFPT.
  dfpt-optic                             dfpt-dielectric, dfpt-phonon   Compute various optical properties (e.g. permittitivity) using DFPT.
  dfpt-phonon                            self-consistent                Compute the dynamical matrix using DFPT.
  dfpt-phonon-bs                         dfpt-phonon                    Compute the phonon band structure using DFPT.
  dfpt-phonon-dos                        dfpt-phonon                    Compute the phonon density of states using DFPT.
  dfpt-raman                             dfpt-dielectric, dfpt-phonon   Compute the Raman tensor using DFPT.
  force                                  self-consistent                Compute the atomic forces.
  mulliken phonon                        self-consistent                Compute the Mulliken populations. Compute the dynamical matrix (and possibly BS, DOS) using finite-displacements.
  potential relaxation self-consistent   self-consistent                Compute various real space potentials (e.g. $v_H$, $v_{xc}$). Compute the equilibrium atomic positions. Compute the ground state density.
  wannier                                self-consistent                Compute maximally localized Wannier functions.
  wannier-bs                             wannier                        Compute the Wannier Hamiltonian band structure.

  : RESCU calculations.

## Example: bulk Si cubic cell

We close this section with the following simple example. This is the
input file for a $\Gamma$-point calculation of an 8-atom silicon
supercell.

``` matlab
info.calculationType = 'self-consistent'
info.savepath = './results/si_real_scf';
element(1).species = 'Si';
element(1).path = './Si_TM_LDA.mat';
atom.xyz = 10.2104 * ...
   [[     0         0         0]
    [     0    0.5000    0.5000]
    [0.5000         0    0.5000]
    [0.5000    0.5000         0]
    [0.2500    0.2500    0.2500]
    [0.2500    0.7500    0.7500]
    [0.7500    0.2500    0.7500]
    [0.7500    0.7500    0.2500]];
atom.element = ones(8,1);
domain.latvec = 10.2104*diag([1,1,1]); 
domain.lowres = 2/3;
functional.list = {'XC_LDA_X','XC_LDA_C_PW'};
```

We now comment briefly on each keyword.

-   `info.calculationType` is a string determining the nature of the
    calculation. If it is set to self-consistent as it is here, the
    Kohn-Sham equation is solved self-consistently and the equilibrium
    ground-state density is saved upon completion of the calculation;
-   `info.savepath` is a string containing the path to the results file.
    RESCU uses two files to save the data. One file is an HDF5 file
    which contains all the distributed arrays (e.g. density, kinetic
    energy density, wavefunctions) and the other file is a MAT-file
    which contains the rest of the results (e.g. total energy, Kohn-Sham
    energies, forces). In the present example, the files
    `./results/si_real_scf.h5` and `./results/si_real_scf.mat` will be
    created;
-   `element(1).species` is a string containing the label of element(1).
    In the present example, there is only one element, such that the
    suffix (1) is unnecessary. In general, there might be element(2),
    element(3) and so on. The element is labeled 'Si' in accordance with
    the periodic table symbol;
-   `element(1).path` is a string containing the path to the
    pseudopotential file associated with element(1);
-   `atom.xyz` is an array containing the atom Cartesian coordinates.
    The coordinates of the atoms in a cubic diamond lattice are given
    above;
-   `atom.element` is an array containing the element number associated
    with each atom. All eight atoms are element(1);
-   `domain.latvec` is an array containing three lattice row vectors.
    diag(\[1,1,1\]) is short for a 3$\times$`<!-- -->`{=html}3 identity
    matrix. `aa*diag([1,1,1])` is thus short for
    `[aa 0 0;0 aa 0;0 0 aa]`. The vectors must be row vectors;
-   `domain.lowres` is a number defining the grid resolution in Bohr
    radii. If the number does not evenly divide the grid along one
    dimension, RESCU will increase the resolution;
-   `functional.list` cell array of strings containing the names of the
    functionals included in the DFT calculation; we use Perdew and
    Wang's expression for the LDA correlation functional.

RESCU is executed as follows

``` shell
rescu -i si_real_scf
```

The input flag tells RESCU to read the input file si_real_scf.

## Units

RESCU works with two unit systems:

-   atomic: Ha and Bohr
-   *extended* SI: eV and $\mathring{\text{A}}$

All input units are atomic by default. It is possible to set the energy
unit to **eV** with

``` matlab
units.energy = 'eV'
```

and the length unit to **Angstrom** with

``` matlab
units.length = 'Angstrom'
```

:::: note
::: title
Note
:::

1 Bohr = 0.52917721067 Angstrom 1 Hartree = 27.21138602 eV
::::

A few keywords allow a more precise control for some key quantities.
They are listed in `tab:unitskey`{.interpreted-text role="numref"} More
specific keywords (e.g. `units.dos.range`) have precedence over general
ones (e.g. `units.energy`).

  Keywords                       Definitions
  ------------------------------ ----------------------------------------
  units.atom.xyz                 Atomic coordinates units
  units.domain.latvec            Lattice vectors units
  units.dos.range                DOS range units
  units.dos.resolution           DOS resolution units
  units.energy                   Default energy units
  units.element.CoulombEnergyU   Keyword `element.CoulombEnergyU` units
  units.length                   Defines length units
  units.kpoint.sigma             Smearing parameter units

  : Units keywords.

Units are converted to atomic when RESCU reads the input files. When
executing RESCU, you\'ll see, for example

``` shell
## INFO ##
RESCU version (path)             = TAG_RESCU_VERSION_TAG [2.6.0] (/homes/jsmith/rescu)
Calculation type                 = self-consistent
## PARALLEL ##
Number of processes              = 48
Parallel config (smi,gpu,k-para) = (1,0,0)
## PSEUDOPOTENTIAL ##
Pseudopotential for Sb           = /homes/jsmith/nano_pp/Sb/Sb_DZP.mat
## BASIS ##
Calculation basis                = REAL
## DOMAIN ##
Lattice vectors (Bohr)           = [8.857e+00,0.000e+00,0.000e+00]
                                   [-4.429e+00,7.671e+00,0.000e+00]
                                   [0.000e+00,0.000e+00,2.321e+01]
```

where the lattice vectors are shown in Bohr. All output quantities are
in atomic units, unless otherwise specified.

## Command line options

When executing RESCU, modes and options can be specified using the flags
listed in `tab:flags`{.interpreted-text role="numref"}.

  Flags                         Short   Description
  ----------------------------- ------- ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
  \--basis \--convert                   display a periodic table with links to copy pseudopotentials files. convert input files (POSCAR) to XYZ format for RESCU to read.
  \--dry-run \--gpu \--help     -d      read the input and performs the initialization procedure but doesn't perform the calculation. This allows verifying that the input is correct and the calculation can in principle proceed. use GPUs to accelerate the calculation. RESCU\'s help.
  \--input \--mat2txt \--mpi    -i      read the input file following the \--input flag. reprint certain results in plain text (e.g. BS, DOS, density, potential). use MPI to parallelize the calculation.
  \--no-finalize \--parameter   -n      don't call MPI_Finalize upon completing the calculation. This allows to execute multiple time without exiting MATLAB. displays documentation and search parameters.
  \--plot \--profile            -p      plot the band structure or DOS contained in the file following the \--plot flag. save a profile of the calculation.
  \--show-structure \--smi      -s      read the input file following the \--show-structure flag and produces a plot of the structure. use MPI, BLACS and ScaLAPACK to parallelize the calculation.

  : RESCU run time parameters and options.

When executing RESCU, run time parameters and options can be specified
using the flags listed in `tab:flags`{.interpreted-text role="numref"}.
Most command line parameters are related to parallelization and
plotting.

## Run time interaction

In certain cases, one could also want to modify keyword values at run
time.

For example, suppose that RESCU is performing a `self-consistent`
calculation of a system comprising 7000 atoms. You can tell your
calculation is progressing, but it appears that RESCU will terminate
after reaching the maximal number of self-consistent iterations without
reaching the preset tolerance. However, RESCU could achieve the
tolerance, if only you could increase the keyword
`option.maxSCFiteration` by 10 or 15. This is achieved by creating
`rescu_runtime.input` in the execution directory and writing in it, for
example, `option.maxSCFiteration = 200` like you would in a typical
input file. RESCU reads `rescu_runtime.input` at the beginning of each
self-consistent loop, and hence it will update the value of
`option.maxSCFiteration` to `200` the next time it reaches the top of
the loop.

Another situation which may arise is the following. You estimated the
calculation should take less than a day base on your experience. You
thus reserved some cores for 24 hours on the university cluster.
Unfortunately, the system is not converging as fast as you expected and
your session is about to be terminated before anything gets saved. You
can avoid restarting from scratch by setting or updating the value of
`option.timeLimit` to `1` in `rescu_runtime.input` (or any value under
24 since the keyword has units of hours, but 1 guarantees that RESCU
will save and terminate as soon as possible). The keyword tells RESCU
when to stop calculating and start saving its current state to disk (in
the location given by `info.savepath`; this may require a lot of disk
space for large scale systems). Note that this option is only available
for `self-consistent` calculations at the moment. To restart a
calculation, simply respawn RESCU in exactly the same way as you did the
first time (in particular, use the same number of MPI-processes). For
example, if you typed in

``` shell
mpiexec --map-by ppr:16:node:pe=4 rescu -i O3Sn1Sr1_scf.input
```

to initiate the calculation the first time, type the same command to
restart it (same directory, same input file, etc.).

The complete list of keywords that are modifiable at run time are listed
in `tab:runtime`{.interpreted-text role="numref"}.

  -------------------------- -----------------------------
  Max num iterations         `option.maxSCFiteration`
  Save auxiliary wavefunc.   `option.saveAuxWaveFun`
  Save density               `option.saveDensity`
  Save lcao                  `option.saveLCAO`
  Save lcao Hamiltonian      `option.saveLcaoHam`
  Save partial weights       `option.savePartialWeights`
  Save potential             `option.savePotential`
  Save kin. energy density   `option.saveTau`
  Save wavefunctions         `option.saveWavefunction`
  Save density matrix (R)    `option.saveDensityMatrix`
  Save densitymatrix (k)     `option.saveDensityMatrixK`
  Set time limit             `option.timeLimit`
  -------------------------- -----------------------------

  : Keywords modifiable at run time via `rescu_runtime.input`.

::: {#citations}

[H13]{#H13 .citation-label}

:   D. R. Hamann.
    `Optimized norm-conserving Vanderbilt pseudopotentials. <10.1103/PhysRevB.88.085117>`{.interpreted-text
    role="doi"} In: Phys. Rev. B 88 (8 Aug. 2013), p. 085117.

[H89]{#H89 .citation-label}

:   D. R. Hamann.
    `Generalized norm-conserving pseudopotentials. <10.1103/PhysRevB.40.2980>`{.interpreted-text
    role="doi"} In: Phys. Rev. B 40 (5 Aug. 1989), pp. 2980--2987.

[HSC79]{#HSC79 .citation-label}

:   D. R. Hamann, M. Schlüter, and C. Chiang.
    `Norm-Conserving Pseudopotentials. <10.1103/PhysRevLett.43.1494>`{.interpreted-text
    role="doi"} Phys. Rev. Lett. 43 (20 Nov. 1979), pp. 1494--1497.

[KB82]{#KB82 .citation-label}

:   Leonard Kleinman and D. M. Bylander.
    `Efficacious Form for Model Pseudopotentials. <10.1103/PhysRevLett.48.1425>`{.interpreted-text
    role="doi"} In: Phys. Rev. Lett. 48 (20 May 1982), pp. 1425--1428.

[LFC82]{#LFC82 .citation-label}

:   Steven G. Louie, Sverre Froyen, and Marvin L. Cohen.
    `Nonlinear ionic pseudopotentials in spin-density-functional calculations. <10.1103/PhysRevB.26.1738>`{.interpreted-text
    role="doi"} In: Phys. Rev. B 26 (4 Aug. 1982), pp. 1738--1742.

[SAGG02]{#SAGG02 .citation-label}

:   José M Soler, Emilio Artacho, Julian D Gale, Alberto Garcı́a, Javier
    Junquera, Pablo Ordejón, and Daniel Sánchez-Portal.
    `The SIESTA method for ab initio order- N materials simulation. <10.1088/0953-8984/14/11/302>`{.interpreted-text
    role="doi"} Journal of Physics: Condensed Matter 14.11 (2002), p.
    2745.

[TM91]{#TM91 .citation-label}

:   N. Troullier and José Luriaas Martins.
    `Efficient pseudopotentials for plane-wave calculations. <10.1103/PhysRevB.43.1993>`{.interpreted-text
    role="doi"} In: Phys. Rev. B 43 (3 Jan. 1991), pp. 1993--2006.
:::
