1. Input file format
1.1. Pseudopotentials
RESCU solves the KohnSham 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 solidstate 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. Normconserving pseudopotentials (NCPS) [HSC79] satisfy the condition that the norm of the pseudowavefunctions 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 pseudowavefunction 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 semilocal pseudopotentials, which means that they are local in the radial direction but nonlocal 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 semilocal NCPS [KB82]. The KleinmannBylander approximation was later made more systematic by Hamann [H89, H13]. It is those generalized normconserving pseudopotentials (GNCPS) that RESCU uses to describe the atoms.
RESCU was developed using the pseudopotentials from the Nanoacademic database. The database contains tested localdensity approximation (LDA) pseudopotentials from most atoms below radon. The pseudopotentials are generated from Dirac equation solutions using the TroullierMartins [TM91] scheme. Some pseudopotentials include partial core charge generated from either the Louie [LFC82] 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.
1.2. 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 doublezeta polarized NAO has been generated following the schema of Soler et al. [SAGG02]. 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 KohnSham equation on a real space grid.
1.3. 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 cutoff for the NAO.aoprec
precision of the NAO basis set. It can be ‘SZ’, ‘DZ’ and ‘all’ for singlezeta, doublezeta and higherzeta 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 cutoff for the pseudopotential projectors.vnlNcutoff
principal quantum number cutoff 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.
1.4. Pseudopotentials database
By default, RESCU will look for pseudopotentials in rescux.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 rescux.x.x/PotentialData
.
You can list all pseudopotentials using the basis
flag.
1.5. 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 realspace 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.
1.6. 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 KohnSham states or the effective potential entering the
KohnSham 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
.
1.7. 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\)3 array and [1,2;3,4;5,6]
is a 3\(\times\)2 array. Boolean may be entered as false
or
true
. Otherwise, zero is treated as false and any nonzero number is
treated as true.
1.8. 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 Table 1.8.1.
Calc. types 
Dependency 
Description 

bandstructure 
selfconsistent 
Compute a line bandstructure. 
bandunfolding 
selfconsistent 
Compute the spectral function for a bandstructure. 
density 
selfconsistent 
Compute the real space density. 
dos 
selfconsistent 
Compute the density of states (and possibly LDOS, PDOS). 
dfptdielectric 
selfconsistent 
Compute the dielectric tensor using DFPT. 
dfptoptic 
dfptdielectric, dfptphonon 
Compute various optical properties (e.g. permittitivity) using DFPT. 
dfptphonon 
selfconsistent 
Compute the dynamical matrix using DFPT. 
dfptphononbs 
dfptphonon 
Compute the phonon band structure using DFPT. 
dfptphonondos 
dfptphonon 
Compute the phonon density of states using DFPT. 
dfptraman 
dfptdielectric, dfptphonon 
Compute the Raman tensor using DFPT. 
force 
selfconsistent 
Compute the atomic forces. 
mulliken 
selfconsistent 
Compute the Mulliken populations. 
phonon 
Compute the dynamical matrix (and possibly BS, DOS) using finitedisplacements. 

potential 
selfconsistent 
Compute various real space potentials (e.g. \(v_H\), \(v_{xc}\)). 
relaxation 
Compute the equilibrium atomic positions. 

selfconsistent 
Compute the ground state density. 

wannier 
selfconsistent 
Compute maximally localized Wannier functions. 
wannierbs 
wannier 
Compute the Wannier Hamiltonian band structure. 
1.9. 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 8atom silicon supercell.
info.calculationType = 'selfconsistent'
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 selfconsistent as it is here, the KohnSham equation is solved selfconsistently and the equilibrium groundstate 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 MATfile which contains the rest of the results (e.g. total energy, KohnSham 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\)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
rescu i si_real_scf
The input flag tells RESCU to read the input file si_real_scf.
1.10. 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
units.energy = 'eV'
and the length unit to Angstrom with
units.length = 'Angstrom'
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 Table 1.10.1
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 
units.length 
Defines length units 
units.kpoint.sigma 
Smearing parameter units 
Units are converted to atomic when RESCU reads the input files. When executing RESCU, you’ll see, for example
## INFO ##
RESCU version (path) = TAG_RESCU_VERSION_TAG [2.6.0] (/homes/jsmith/rescu)
Calculation type = selfconsistent
## PARALLEL ##
Number of processes = 48
Parallel config (smi,gpu,kpara) = (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.
1.11. Command line options
When executing RESCU, modes and options can be specified using the flags listed in Table 1.11.1.
Flags 
Short 
Description 

–basis 
display a periodic table with links to copy pseudopotentials files. 

–convert 
convert input files (POSCAR) to XYZ format for RESCU to read. 

–dryrun 
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. 
–gpu 
use GPUs to accelerate the calculation. 

–help 
RESCU’s help. 

–input 
i 
read the input file following the –input flag. 
–mat2txt 
reprint certain results in plain text (e.g. BS, DOS, density, potential). 

–mpi 
use MPI to parallelize the calculation. 

–nofinalize 
n 
don’t call MPI_Finalize upon completing the calculation. This allows to execute multiple time without exiting MATLAB. 
–parameter 
displays documentation and search parameters. 

–plot 
p 
plot the band structure or DOS contained in the file following the –plot flag. 
–profile 
save a profile of the calculation. 

–showstructure 
s 
read the input file following the –showstructure flag and produces a plot of the structure. 
–smi 
use MPI, BLACS and ScaLAPACK to parallelize the calculation. 
When executing RESCU, run time parameters and options can be specified using the flags listed in Table 1.11.1. Most command line parameters are related to parallelization and plotting.
1.12. 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 selfconsistent
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 selfconsistent 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 selfconsistent 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 selfconsistent
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 MPIprocesses).
For example, if you typed in
mpiexec mapby 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 Table 1.12.1.
Max num iterations 

Save auxiliary wavefunc. 

Save density 

Save lcao 

Save lcao Hamiltonian 

Save partial weights 

Save potential 

Save kin. energy density 

Save wavefunctions 

Save density matrix (R) 

Save densitymatrix (k) 

Set time limit 

D. R. Hamann. Generalized normconserving pseudopotentials. In: Phys. Rev. B 40 (5 Aug. 1989), pp. 2980–2987.
D. R. Hamann. Optimized normconserving Vanderbilt pseudopotentials. In: Phys. Rev. B 88 (8 Aug. 2013), p. 085117.
D. R. Hamann, M. Schlüter, and C. Chiang. NormConserving Pseudopotentials. Phys. Rev. Lett. 43 (20 Nov. 1979), pp. 1494–1497.
Leonard Kleinman and D. M. Bylander. Efficacious Form for Model Pseudopotentials. In: Phys. Rev. Lett. 48 (20 May 1982), pp. 1425–1428.
Steven G. Louie, Sverre Froyen, and Marvin L. Cohen. Nonlinear ionic pseudopotentials in spindensityfunctional calculations. In: Phys. Rev. B 26 (4 Aug. 1982), pp. 1738–1742.
José M Soler, Emilio Artacho, Julian D Gale, Alberto Garcı́a, Javier Junquera, Pablo Ordejón, and Daniel SánchezPortal. The SIESTA method for ab initio order N materials simulation. Journal of Physics: Condensed Matter 14.11 (2002), p. 2745.
N. Troullier and José Luriaas Martins. Efficient pseudopotentials for planewave calculations. In: Phys. Rev. B 43 (3 Jan. 1991), pp. 1993–2006.