25.2.15 Keywords for Module `riper`

riper shares most of the relevant keywords of the dscf and ridft modules. The $dft data group (see 25.2.10) and auxiliary basis sets defined using the keyword $jbas are always required.

For periodic calculations two additional keywords are necessary:

$periodic n

Specifies the number of periodic directions: $n = 3$ for a 3D periodic bulk solid, $n = 2$ for a 2D periodic surface slab and $n = 1$ for a 1D periodic system. The default value is $0$ for a molecular system.

$cell

Specifies the unit cell parameters. The number of cell parameters depends on the periodicity of the system:

For 3D periodic systems six unit cell parameters $|$a$|$, $|$b$|$, $|$c$|$, $\alpha$, $\beta$ and $\gamma$ need to be provided. Here, $|$a$|$, $|$b$|$ and $|$c$|$ are lengths of the appropriate cell vectors, $\alpha$ is the angle between vectors $\textbf{b}$ and $\textbf{c}$, $\beta$ is the angle between vectors $\textbf{a}$ and $\textbf{c}$, and $\gamma$ is the angle between vectors $\textbf{a}$ and $\textbf{b}$. riper assumes that the cell vectors $\textbf{a}$ and $\textbf{b}$ are aligned along the $x$ axis and on the $xy$ plane, respectively.

For 2D periodic systems three surface cell parameters $|$a$|$, $|$b$|$ and $\gamma$ have to be provided. Here, $|$a$|$ and $|$b$|$ are lengths of the appropriate cell vectors and $\gamma$ is the angle between $\textbf{a}$ and $\textbf{b}$. riper assumes that the cell vectors $\textbf{a}$ and $\textbf{b}$ are aligned along the $x$ axis and on the $xy$ plane, respectively.

For 1D periodic systems only one parameter specifying the length of the unit cell has to be provided. riper assumes that periodic direction is along the $x$ axis.

$lattice

Alternatively, lattice vectors can be provided. The number of cell parameters depends on the periodicity of the system:

For 3D periodic systems three (three-dimensional) lattice vectors need to be provided.

For 2D periodic systems two (two-dimensional) lattice vectors have to be provided. riper assumes that the lattice vectors are aligned on the $xy$ plane.

For 1D periodic systems only one parameter specifying the length of the lattice vector has to be provided. riper assumes that periodic direction is along the $x$ axis.

Optionally, for periodic systems a $\mathbf{k}$ points mesh can be specified:

$kpoints

nkpoints $n_1$ $n_2$ $n_3$

Specifies components along each reciprocal lattice vector of a $\Gamma$ centered mesh of $\mathbf{k}$ points. In 3D periodic systems each $\mathbf{k}$ point is defined by its components $k_1$, $k_2$ and $k_3$ along the reciprocal lattice vectors $\mathbf{b}_1$, $\mathbf{b}_2$ and $\mathbf{b}_3$ as

\[\begin{equation} \mathbf{k} = k_1\mathbf{b}_1 + k_2\mathbf{b}_2 + k_3\mathbf{b}_3 \;\text{.} \end{equation}\](25.1)

For 2D periodic systems $k_3 = 0$. In case of 1D periodicity $k_3 = 0$ and $k_2 = 0$. The three components $k_j$ $(j = 1, 2, 3)$ of $\mathbf{k}$ are given as

\[\begin{equation} k_j = \frac{i}{n_j} \text{ with } i = -\frac{n_j-1}{2},-\frac{n_j-1}{2} + 1,\dots,\frac{n_j-1}{2}-1,\frac{n_j-1}{2} \;\text{.} \end{equation}\](25.2)

with $n_j$ $(j = 1, 2, 3)$ as integer numbers.

For 3D periodic systems $n_1$, $n_2$ and $n_3$ have to be specified. The component $n_3$ can be omitted for 2D periodic systems. In case of 1D periodicity only the $n_1$ has to be specified.

In addition, the options kptlines and recipr within the $kpoints group can be used to obtain band structure plots:

kptlines: Specifies the number of reciprocal space lines for band structure plots.
recipr: Specifies lines in the reciprocal space using three real numbers defining the start point of the line and three real numbers defining its end point. Finally, the number of $\textbf{k}$ points along the line is given as an integer number.

In the following example band energies are calculated along four lines, as specified by the keyword kptlines 4. Each line definition starts in a new line with the keyword recipr, followed by three real numbers defining the start point of the line and three real numbers defining its end point. Finally, the number of $\textbf{k}$ points along the line is given as an integer number. Thus, the first line starts at the point (0.500 0.500 0.500), ends at (0.000 0.000 0.000) and contains 40 $\textbf{k}$ points.

$kpoints
  kptlines 4
  recipr 0.500 0.500 0.500 0.000 0.000 0.000 40
  recipr 0.000 0.000 0.000 0.500 0.500 0.000 40
  recipr 0.500 0.500 0.000 0.746 0.373 0.373 40
  recipr 0.746 0.373 0.373 0.000 0.000 0.000 40

The calculated band structure is written to the file bands.xyz. Each line of the file contains five real numbers: the coordinates $k_1$, $k_2$ and $k_3$ of the $\textbf{k}$ point, its length $|k|$ and the corresponding band energy $\epsilon_{n\mathbf{k}}$.

Keywords within the section $riper can be used to control precision and parameters of algorithms implemented in riper. If the $riper group is absent, the following default values are used:

$riper
  # general keywords
  thrints    1.0d-12
  lenonly    off
  lchgprj    on  (for periodic systems)
  lchgprj    off (for molecular systems)
  northol    5
  pqmatdiag  off
  pqsingtol  1.0d-8  
  # CFMM control options
  lmaxmom    20
  nctrgt     10 (for periodic systems)
  nctrgt     1  (for molecular systems)
  wsicl      3.0
  epsbext    1.0d-9
  locmult    on  (for periodic systems)
  locmult    off (for molecular systems)
  locmomadd  2
  # LMIDF control options
  lpcg       on
  lcfmmpcg   on
  lmxmompcg  20
  pcgtol     1.0d-9
  pcgtyp     sp
  # Gaussian smearing options 
  sigma      0.0d0  
  desnue     0.0d0
  # SCF control options
  ldiis      on
  mxitdiis   4 (for DFT)
  mxitdiis   5 (for HF)
  # Hybrid functional options
  itrunc     2
  inttolk    23.0

The following options are available:

# general keywords
thrints: Threshold for integrals neglect and for differential overlap when screening basis functions pairs. Probably never needs to be changed.
lenonly: Flag for energy calculation only, no gradients.
lchgprj: If set to on charge projection of the auxiliary electron density [214] is performed for molecular systems during calculation of the Coulomb term. The charge projection constraints the charge of auxiliary density exactly to the number of electrons in the system. It is required for periodic systems, otherwise the Coulomb energy would be infinitely large. For molecular systems charge projection leads to a slight increase of the RI fitting error. It may be useful in some cases but we have so far not identified any.
northol: Forces orthonormalization of orbital coefficients every northol SCF iteration.
pqmatdiag: If set to on full diagonalization of the Coulomb metric matrix [214] is performed and used to solve density fitting equations. When diffuse auxiliary basis functions are used the default Cholesky decomposition of the Coulomb metric matrix may fail due to small negative eigenvalues. In this case the slower method based on a full diagonalization of the metric matrix is necessary.
pqsingtol: If pqmatdiag is used pqsingtol sets threshold for neglect of small eigenvalues of the Coulomb metric matrix.
# CFMM control options
lmaxmom: Maximum $l$-moment of multipole expansions used for calculation of the Coulomb term. The default value hardly ever needs to be changed.
nctrgt: Target number of charge distributions per lowest level box of the octree [204]. The default value hardly ever needs to be changed.
wsicl: Sets the well-separateness criterion [204]. Octree boxes with centers separated more than sum of their lengths times $0.5\times$wsicl are considered as well-separated. The default hardly ever needs to be changed. wsicl makes sense only for values $\geq 2.0$. For wsicl $\leq 3.0$ increasing lmaxmom may be necessary for reasonable accuracy.
epsbext: Precision parameter used to determine basis function extents [204].
locmult: If set to on, an additional acceleration method employing local multipole expansions is used. For periodic systems this leads to a significant speedup of calculations, especially for small unit cells and/or diffuse basis functions. Default value is off and on for molecular and periodic systems, respectively.
locmomadd: For locmult set to on the order of local multipole expansions is increased by locmomadd. The default value probably never needs to be changed.
# LMIDF control options
lpcg: If set to on the low-memory iterative density fitting (LMIDF) scheme is used for solving the RI equations [208] using the preconditioned conjugate gradient (PCG) method. It is implemented for molecular systems only. Default value is off.
lcfmmpcg: If lpcg is used, lcfmmpcg specifies whether the CFMM is applied for evaluation of the matrix-vector products needed for the PCG solver. Not employing CFMM speeds up the calculations but significantly increases memory demand since the full Coulomb metric matrix has to be stored. Default value is on.
lmxmompcg: Maximum $l$-moment of multipole expansions for calculations of Coulomb interactions within the PCG algorithm. It should be set to the same or larger value than lmaxmom.
pcgtol: Sets the threshold parameter controlling accuracy of the PCG solver (see [208] for details). Default value is $1.0 \cdot 10^{-9}$. For lower-precision calculations it can be set to $1.0 \cdot 10^{-8}$ but values larger than $1.0 \cdot 10^{-7}$ are not allowed as these lead to large errors in Coulomb energies and occasionally to SCF convergence problems.
pcgtyp char: char = at, ss or sp
Specifies the type of preconditioner used in the PCG algorithm. Three types of preconditioners are implemented and are defined explicitly in Sec. 7. The sp preconditioner is a default one performing consistently the best among the preconditioners considered. The at preconditioner is less efficient in decreasing the number of CG iterations needed for convergence. However, it has negligible memory requirements and more favorable scaling properties, albeit with a large prefactor. The ss preconditioner represents a middle ground between the sp and at preconditioners both in terms of the efficiency and memory requirements.
# Gaussian smearing options
sigma: Width of the Gaussian smearing in hartree. See ref. [216] for more information. Note, that [216] uses eV as the unit for the width of the Gaussian smearing.
desnue: Specifying desnue along with sigma forces occupancy leading to the number of unpaired electrons equal to desnue.
# SCF control options
ldiis: If set to on DIIS (Direct Inversion in the Iterative Subspace) acceleration is used in SCF iterations. Default value is on. Set to off to disable DIIS.
mxitdiis: Maximum number of SCF iterations to be included in the DIIS procedure. Default value is 4 for DFT calculations and 5 for Hartree-Fock calculations. Must be larger than 0 if ldiis is on.
# Hybrid functional options
itrunc: Truncation method for periodic Hartree-Fock exchange: 1 for TCI (Truncated Coulomb Interaction), 2 for MIC (Minimum Image Convention). Default value is 2.
inttolk: Threshold exponent for four-center exchange integrals. Exchange integrals smaller than $\exp(-\texttt{inttolk})$ are neglected. Default value is 23.0. Smaller values increase speed but reduce accuracy.

Keywords within the section $pointvalper can be used to evaluate quantities (electron density/molecular orbitals) for visualization on grid points:

$pointvalper fmt=plt
     dens
     orbs 2
     k 3 2 1 a 1 i
     k 0 0 0 b 2 r
     nimg 2 2 1
     npts 100 100 100
     eps 5.0
     ngrdpbx 50
     full

The following options are available:

fmt: Specifies output format. Currently .plt, .cub, .xyz and .upt extensions are supported (see 7.3.8).
dens: If present, total (and spin for UHF) density is calculated.
orbs: Specifies the number of plotted orbitals. For further details see subsection 7.3.8.
nimg: Number of unit cell images n1, n2 and n3 in the periodic directions a, b and c, respectively, for which plot data is generated.
npts: Number of grid points n1, n2 and n3 along each periodic direction. If not specified, value 100 is used for each n.
eps: Specifies the distance real in bohr around the system for which plot grid is generated in aperiodic directions. Default value is 5 bohr.
ngrdpbx: Number of grid points stored in one octree box during density calculations. Default value is 50. For very large systems or high resolution it may be necessary to increase this parameter to avoid memory allocation problems.
full: Only valid for plt output format. This format uses orthogonal grids. Therefore, for non-orthogonal unit cells grid data is generated for a rectangular box that contains the supercell (unit cell and its periodic images). By default, the values at grid points outside of the supercell are set to zero. For strongly non-orthogonal systems this may lead to large files. The option full switches off the zeroing of values on grid points outside the supercell.

To calculate a simulated density of states (DOS) keyword $dosper is necessary:

$dosper width=real emin=real emax=real scal=real npt=integer

The following options are available:

width: The width of each Gaussian, default value is 0.01 a.u.
emin,enmax: Lower/upper bounds for energy in DOS calculation.
scal: Scaling factor for DOS (total and s-, p-, ... contributions).
npt: Resolution (number of points).

Keywords within the section $rttddft can be used to specify the parameters for RT-TDDFT. Example:

$rttddft
  magnus 2
  scf off
  time 1000.0d0
  tstep 0.1d0
  min energy = 0.013d0
  max energy = 0.5d0
  energy step 0.001d0

The options are explained below.

magnus: Can take values 2 or 4. "2" for second order Magnus expansion and "4" for fourth order Magnus expansion. Default value is 2.
scf: if on, then SCF procedure is used for the time integration. If off
then Predictor-Corrector scheme is used instead.
iterlim: Max SCF cycles if scf is on. Default value is 15.
time: Specifies the evolution time in au. (1 au$=$ 0.02419 fs)
tstep: The time step for the time evolution in au. 0.1 au is usually a good starting point.
print step: Specifies the number of steps $n$ after which the dipole moments and energies are printed out if requested. Default value is 100. That means the quantities are printed out at every 100 steps. To have all the information for post processing, a value of 1 is recommended.
damping: Only valid for absorption spectrum calculation. It is the factor gamma in the equation to calculate the complex polarizability tensor. Default value is 0.004 au. Recommended values in the range of 0.003 au to 0.005 au.
min energy: Only valid for absorption spectrum calculation. Specifies the minimum value of the energy range used to perform the Fourier transform from time to frequency space. Units: au. Default value is 0.15 au.
max energy: Only valid for absorption spectrum calculation. Specifies the maximum value of the energy range used to perform the Fourier transform from time to frequency space. Units: au. Default value is 0.625 au.
energy step: Only valid for absorption spectrum calculation. Specifies the step value or energy interval dE at which to sample the energy values for Fourier transform and absorption spectrum plotting. Units: au. Default value is 0.005 au.

Keywords within the section $electric field can be used to specify the parameters for electric field. To specify a Gaussian electric field pulse use

$electric field
  amplitude x=2.0E-5 y=2.0E-5 z=2.0E-5
  gaussian tzero=3.0 width=0.2

Options are explained below.

amplitude x y z: Cartesian components of the amplitude of the Gaussian pulse (in Electric field au).
gaussian: Sets the electric field type to Gaussian.
tzero: Position of Gaussian pulse maximum (in time au).
width: Width of Gaussian pulse (in time au).

25.2.15 Keywords for Module riper

25.2.15 Keywords for Module `riper`