25.2.19 Keywords for Module `escf`

TDHF and TDDFT calculations

To perform an escf calculation converged molecular orbitals from a HF, DFT or RIDFT calculation are needed. The HF, DFT or RIDFT method is chosen according to the $dft or $ridft keywords, specified above. It is recommended to use well-converged orbitals, specifying $scfconv 7 and $denconv 1d-7 for the ground-state calculation. The input for an escf calculation can be conveniently generated using the ex menu in define, see Section 4.

During an escf run, a system-independent formatted logfile will be constructed for each IRREP. It can be re-used in subsequent calculations (restart or extension of eigenspace or of $rpaconv). An escf run can be interrupted by typing “touch stop” in the working directory.

In an escf run one of the following properties can be calculated: (please note the ’or’ in the text, do only one thing at a time.)

1. RPA and time-dependent DFT singlet or triplet or spin-unrestricted excitation energies (HF+RI(DFT))

$scfinstab rpas: or
$scfinstab rpat: or
$scfinstab urpa

2. TDA (for HF: CI singles) singlet or triplet or spin-unrestricted or spin-flip excitation energies (HF+RI(DFT))

$scfinstab ciss: or
$scfinstab cist: or
$scfinstab ucis: or
$scfinstab spinflip

3. Two-component TDDFT/TDA excitation energies of Kramers-restricted closed-shell systems

$scfinstab soghf: or
$scfinstab tdasoghf

4. Eigenvalues of singlet or triplet or non-real stability matrices (HF+RI(DFT), RHF) or complex stability matrices (HF+RI(DFT), Kramers-GHF)

$scfinstab singlet: or
$scfinstab triplet: or
$scfinstab non-real: or
$scfinstab complex

5. Static polarizability and rotatory dispersion tensors (HF+(RI)DFT, RHF+UHF)

$scfinstab polly

6. Dynamic polarizability and rotatory dispersion tensors (HF+(RI)DFT, RHF+ UHF)

$scfinstab dynpol unit
list of frequencies

where unit can be eV, nm, rcm; default is a.u. (Hartree). For example, to calculate dynamic polarizabilities at 590 nm and 400 i nm (i is the imaginary unit):

$scfinstab dynpol nm
  590
  400 i

The number and symmetry labels of the excited states to be calculated is controlled by the data group $soes. Example:

$soes
b1g  17
eu   23
t2g  all

will yield the 17 lowest excitations in IRREP b1g, the 23 lowest excitations in IRREP eu, and all excitations in IRREP t2g. Specify $soes alln; to calculate the n first excitations in all IRREPS. If n is not specified, all excitations in all IRREPS will be obtained. Both static and dynamic polarizabilites can be calculated with (local) all-electron relativistic methods including the picture-change correction of the corresponding dipole moment in one and two-component calculations. The picture-change correction is invoked by the keyword $pcc and the two-component framework by $soghf.

Adding $damped_response will trigger a damped response calculations at the give frequencies. Example:

$damped_response 0.25 eV

The damping factor must additionaly be specified in eV, cm-1 or nm.

7. Two-photon absorption

$scfinstab twophoton rpas: or
$scfinstab twophoton urpa: or
$scfinstab twophoton ciss: or
$scfinstab twophoton ucis

8. Nuclear spin-spin coupling constants

The data group $ncoupling can be set using the ncoup section in define. A sample input might look like this:

$ncoupling
  fc sd pso dso nofcsdcross     or
  simple                        or
  fromfile
  reduced
  thr=0.1
$nucsel 1,3,5-8
$nucsel2 "c","h"

You can specify the contributions to be calculated by indicating the appropriate abbreviation. If both fc and sd are specified, the FC/SD cross term is calculated, unless manually switched off.

The simple method only calculates the FC and FC/SD cross terms, thus yielding the most important contributions to the isotropic and anisotropic part. Be warned that this might yield qualitatively wrong results in some cases! This method is quite fast because only response equations for the FC term are solved. However, this means that it is incompatible with $nucsel2.

If the option fromfile is set, SSCCs from the data group $coupling_reduced from a previous calculation are used. This option can be used to obtain SSCC for a different isotope without redoing the expensive part of the calculation.

If none of the keywords mentioned above is given, all terms (equivalent to fc sd pso dso) are calculated.

In a two-component calculation, fc, sd, and pso shall always be used together and nofcsdcross is not permissible. The simple method is likewise not allowed. If the DSO term is to be computed by picture-change correction, it needs to be activated here and $pcc needs to be set.

By default, the output is multiplied by the gyromagnetic ratios, yielding $J$ in Hertz. With reduced, the reduced coupling constants $K$ are printed in units of $10^{19}\,\text{T}^2/\text{J}$. The content of $coupling_reduced is not influenced by this setting.

In the final output, couplings where both the isotropic and the anisotropic part are smaller than the threshold thr (in Hertz or $10^{19}\,\text{T}^2/\text{J}$, default: 0.1) will not be printed.

You can specify for which atoms coupling constants shall be calculated by the data groups $nucsel and $nucsel2. As shown above, the syntax is either a list of atomic indices or of element symbols. The default is to calculate all atoms. Response equations (the most expensive step) are solved for the atoms in $nucsel and right-hand side integrals are calculated for atoms in any of the data groups. This means that a coupling tensor is obtained if at least one of the partner is in $nucsel. Notice that the very same data group $nucsel is used by the module mpshift.

It is furthermore recommended to set $rpaconv to at least 6.

The file referenced in $coupling_reduced (default file name: coupling.reduced) is suitable for automated post-processing. It consists of the atomic indices, $J^{\text{iso}}$, $\gamma_K \cdot \gamma_L$, and the nine elements of the matrix $\tilde{K} = J/\gamma_K \gamma_L$ (see eqs. 17.4 and 17.3 for an explanation of these quantities). The gyromagnetic ratios $\gamma_K$ are given in $10^7 \,\text{rad}\,\text{s}^{-1}\,\text{T}^{-1}$. All couplings with $K \ge L$ (ignoring $nucsel and thr) are printed.

general keywords

$rpacor n: The maximum amount of core memory to be allocated for the storage of trial vectors is restricted to n MB. If the memory needed exceeds the threshold given by $rpacor, a multiple pass algorithm will be used. However, especially for large cases, this will increase computation time significantly. The default is 200 MB.
$spectrum unit: The calculated excitation energies and corresponding oscillator strengths are appended to a file named ’spectrum’. Possible values of unit are eV, nm and cm$^{-1}$ or rcm. If no unit is specified, excitation energies are given in a.u.
$cdspectrum unit: The calculated excitation energies and corresponding rotatory strengths are appended to a file named ’cdspectrum’. unit can have the same values as in $spectrum.
$start vector generation e: Flag for generation of UHF start MOs in a triplet instability calculation. The option will become effective only if there are triplet instabilities in the totally symmetric IRREP. The optional real number e specifies the approximate second order energy change in a.u. (default: 0.1).
$velocity gauge: Enables calculation of dipole polarizability/rotatory dispersion in the velocity gauge. Active only for pure DFT (no HF exchange).
: Enable calculation of oscillator and rotatory strength sum rules at frequencies specified by list of frequencies in unit unit (see $scfinstab dynpol). Note that the sums will be taken only over the states specified in $soes.
$rpaconv n: The vectors are considered as converged if the Euclidean residual norm is less than $10^{-n}$. Larger values of n lead to higher accuracy. The default is a residual norm less than $10^{-5}$. For SSCCs, it is recommended to increase $n$ to 6.
$escfiterlimit n: Sets the upper limit for the number of Davidson Iterations to n. Default is $n=25$.
$escfnoxc: Disable the DFT XC kernel contribution (on the grid). Required for the TDDFT-as/TDDFT-ris approaches, see Section 8.4.18.

GW Keywords

$gw

The main keyword that switches on a $GW$ calculation using full spectral representations. This keyword will perform a standard $G_0W_0$ calculation with default values for the other flags.

$rigw

The main keyword that switches on a $GW$ calculation using analytic continuation of the self-energy from imaginary to real space.

There are several options which can be added to the $gw or $rigw keyword. The recommended settings for a quick $G_0W_0$ run are:

Full quasiparticle spectrum using spectral representations:

$gw 
  rpa
  eta 0.001

HOMO-LUMO gap using analytic continuation:

$rigw 
  rpa
  ips+1
  gap

Orbital 3-6 using contour deformation and iterative solution of the QP equation:

$rigw 
  rpa
  eta 0.001
  contour start=3 end=6
  qpeiter 10

With the optional entries:

rpa

Default: false (not set). If added as option pure rpa response function is calculated. If not added, the TDDFT response function is calculated and used to screen the coulomb interaction. In combination with $rigw this keyword is mandatory, with $gw it should also always be set and only be deactivated by experts. The gw menu in define always sets this as default.

  qpeiter <integer>

Default: 0. Switches between linearized quasiparticle equation for 0 and iterate quasiparticle equation for > 0. eta is changed from 0.2 to the supplied value to obtain smooth convergence during the iteration. Only with $gw.

gw0

Default: false (not set). A GW$_0$ calculation is performed instead of $G_0W_0$. The number of GW$_0$ iterations performed is set by qpeiter.

    evgw

Default: false (not set). An eigenvalue-only selfconsistent GW calculation is performed instead of $G_0W_0$.

    scgw

Default: false (not set). A quasiparticle selfconsistent GW calculation is performed instead of $G_0W_0$. Only with $gw and not compatible with two-component calculations.

    offpq <real>

Default: 0.03. Infinitesimal complex energy shift in Fock-matrix contribution of self-energy in scGW calculation. Only in combination with scgw keyword, ignored otherwise.

    fdamp <real>

Default: 0.3. Damping of new Fock-matrix in scGW calculation. Only in combination with scgw keyword, ignored otherwise.

    unlimitz

Default: false (not set). In linearized $G_0W_0$ the linearization Factor Z is allowed to take any value instead of values between 0.5 - 1.0. Ignored if calculation is not a linearized $G_0W_0$ calculation.

    fixz

Default: false (not set). In linearized $G_0W_0$ the linearization Factor Z is fixed to 1.0. Ignored if calculation is not a linearized $G_0W_0$ calculation.

    csf <integer>

Default: false (not set). Calculate self-energy on an energy grid for the specified orbital. Results are saved on file.

  nl <integer>

Default: n$_{occ}$+5. Number of orbitals to print gw results for. It is set to the number of occupied orbitals + 5 if set smaller than the number of occupied orbitals.

  eta <real>

Default: 0.001. Infinitesimal complex energy shift $\eta$. Negative value switches to calculating at that value but extrapolating to 0 in linear approximation. Note that $\eta^2$ is subsequently used internally.

  output <filename>

Default: qpenergies.dat. Output filename for the quasiparticle energies.

For $rigw there are some special keywords that control the cost and efficiency of the module. The defaults chosen by define (or escfitself) are suitable for most systems. They were selected rather to be rather tight to yield reliable results without much knowledge of the system.

gap

Default: not set. Only the HOMO and LUMO quasiparticle states are calculated, all other orbitals are shifted by the HOMO-LUMO gap. In conjunction with the "ips+<integer>" keyword the N highest occupied and N lowest unoccupied states are calculated, making $rigw calculations feasible for many systems.

  ips+ <integer>

Default: not set. When $rigw is set then the the quasiparticle states of all occupied + the N lowest virtual orbitals are calculated. Only with $rigw, ignored with $gw.

  contour start=<integer> end=<integer> spin=<integer>

Default: not set. start, end and spin are optional and may be defined in arbitrary order. start defines the starting point for the orbital range and end the ending of the orbital range to be treated with RI-CD-$GW$. If neither start nor end are defined then the definition from the ips+ and gap keywords is used. In open shell systems spin=1 calculates the self-energy only for alpha shells, spin=2 for alpha and beta shells. For closed shell or any 2c calculation spin=1 is always the correct option and does not need to be set by the user.

  npade <integer>

Default: 128. Number of Pade approximants used in the $rigw module for RI-AC-$GW$. Recommended to be the same as npoints in a dual-grid ansatz. Due to numerical instabilities not more than 256 Pade approximants should be used!

  npoints <integer>

Default: 128. Number of imaginary frequency integration points used in the $rigw module for RI-AC-$GW$, RI-AC-$GW$ and RPA energies. Recommended to be the same as npade in a dual-grid ansatz in RI-AC-$GW$.

  rpoints <integer>

Default: 16. Number of pseudo Fermi-levels in RI-AC-$GW$ calculation. Not used if "contour" keyword is present.

  rshift <real>

Default: 0.3 eV. Initial shift for first Fermi level when RI-AC-$GW$ is used in eV. For insulators 0.3 is recommended, for lower gap systems (< 3-4 eV HOMO-LUMO gap) 0.2 is recommended. Not used if "contour" keyword is present.

  width <real>

Default: rshift. stepwidth between subsequent Fermi levels when RI-AC-$GW$ is used in eV. Recommended to be set such that e$_{HOMO} + rshift + rpoints*width < e_{LUMO}$. Usually values from 0.05-0.20 eV are reasonable if the given condition is fulfilled. Not used if "contour" keyword is present.

  fscdgrd

Default: not set. Approximative RI-CD-$GW$ variant, employing a frequency-sampling strategy for the calculation of the required residues.

  thrs1 <real>

Default: 1.361 eV. Threshold for selection of frequency grid based on absolute differences in frequency-sampled RI-CD-$GW$. Used only if fscdgrd is set.

  thrs2 <real>

Default: 0.001 (0.1%). Threshold for selection of frequency grid based on relative energy differences in frequency-sampled RI-CD-$GW$. Used only if fscdgrd is set.

BSE Keywords

$bse

The main keyword that switches on a BSE calculation. Provided that the response function is calculated setting this keyword will perform a standard BSE calculation with default values for the other flags.

$cbse

The main keyword that switches on a correlation augmented BSE (=cBSE) calculation. A cBSE calculation with default values for the other flags will be performed.

The following optional entries can be added to the $bse or $cbse keyword:

  noqpa
  noqpw

Default: Not set. If set, the matrices ${\bf A}$ and ${\bf W}$, respectively, are constructed using KS/HF orbital energies instead of GW quasi-particles energies. if $cbse is used noqpw is set automatically.

  file <filename>

Default: qpenergies.dat. This option defines the file name of GW quasi-particle energies which are read in.

  iterative

Default: Not set. Compute the auxiliary matrix for the static screened interaction iteratively instead of by Cholesky decomposition.

  thrconv <real>

Default: 1.0d-12. Threshold for convergence in case of the iterative computation of the static screened interaction.

  iterlim <integer>

Default: 100. Maximum number of iterations in case of the iterative computation of the static screened interaction.

$keep_fxc

Default: not set. Appears outside of the $bse data group. It adds the correlation part of the underlying XC Kernel to the BSE response. Automatically set if $cbse is set.

25.2.19 Keywords for Module escf

TDHF and TDDFT calculations

general keywords

GW Keywords

BSE Keywords

25.2.19 Keywords for Module `escf`