1. Input file format

1.1. 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] 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]. The Kleinmann-Bylander approximation was later made more systematic by Hamann [H89, H13]. 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] 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 double-zeta 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 Kohn-Sham 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 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.

1.4. 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.

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

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

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 non-zero 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.

Table 1.8.1 RESCU calculations.

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	self-consistent	Compute the Mulliken populations.
phonon		Compute the dynamical matrix (and possibly BS, DOS) using finite-displacements.
potential	self-consistent	Compute various real space potentials (e.g. \(v_H\), \(v_{xc}\)).
relaxation		Compute the equilibrium atomic positions.
self-consistent		Compute the ground state density.
wannier	self-consistent	Compute maximally localized Wannier functions.
wannier-bs	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 8-atom silicon supercell.

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\)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).

Table 1.10.1 Units keywords.

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 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                 = 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.

1.11. Command line options

When executing RESCU, modes and options can be specified using the flags listed in Table 1.11.1.

Table 1.11.1 RESCU run time parameters and options.

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.
–dry-run	-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.
–no-finalize	-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.
–show-structure	-s	read the input file following the –show-structure 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 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

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 Table 1.12.1.

Table 1.12.1 Keywords modifiable at run time via rescu_runtime.input.

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

[H89]

D. R. Hamann. Generalized norm-conserving pseudopotentials. In: Phys. Rev. B 40 (5 Aug. 1989), pp. 2980–2987.

[H13]

D. R. Hamann. Optimized norm-conserving Vanderbilt pseudopotentials. In: Phys. Rev. B 88 (8 Aug. 2013), p. 085117.

[HSC79]

D. R. Hamann, M. Schlüter, and C. Chiang. Norm-Conserving Pseudopotentials. Phys. Rev. Lett. 43 (20 Nov. 1979), pp. 1494–1497.

[KB82]

Leonard Kleinman and D. M. Bylander. Efficacious Form for Model Pseudopotentials. In: Phys. Rev. Lett. 48 (20 May 1982), pp. 1425–1428.

[LFC82]

Steven G. Louie, Sverre Froyen, and Marvin L. Cohen. Nonlinear ionic pseudopotentials in spin-density-functional calculations. In: Phys. Rev. B 26 (4 Aug. 1982), pp. 1738–1742.

[SAGG02]

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. Journal of Physics: Condensed Matter 14.11 (2002), p. 2745.

[TM91]

N. Troullier and José Luriaas Martins. Efficient pseudopotentials for plane-wave calculations. In: Phys. Rev. B 43 (3 Jan. 1991), pp. 1993–2006.