.. _keyword_reference:
========================
Keyword Reference
========================
This document gives a reference of available keywords in the input file ``spex.inp``. The syntax of the input file is as follows.
* The file ``spex.inp`` does not use a fixed format, and the keywords may be given in any order.
* Each keyword is given on one line together with its parameters following it and may be given only once.
* All keywords (and section names) are in capital letters.
* Everything after a ``#`` sign is interpreted as a comment. Empty lines are allowed.
* Lines are only interpreted up to the 80th column. Line continuation is possible using a single backslash ``\`` at the end of the previous line.
* Some keywords are only defined inside sections. A section starts with ``SECTION sectionname`` and ends with ``END``.
In the following the keywords are listed and explained alphabetically and for each section separately. If there is no default value, the keyword must be given. **Experimental, badly tested, and obsolete keywords as well as keywords for testing are shown in round brackets.**
.. warning:: The list can be partly out of date or obsolete.
Global Keywords
-----------------
(``ALIGNBD``): Aligns the degenerate states on the unshifted k-point set (see ``KPT +=...``) to the states on the shifted k points. Corresponding transformation matrices are written to the file ``spex.abd`` or read from it if it exists. Normally used to calculate response quantities of metals for small k vectors, e.g., in order to test the expansion around the point '''k=0'''. (Default false)
``BANDINFO``: Prints information about bands: weight of s,p,d,f,g character of each state, (P)DOS plot in separate file (``spex.dos.NNN``), square integral of wave-function products. (Default false)
(``BANDOMIT (bands) ABC``): Omits bands defined in ``bands`` in exchange (``A=1``), susceptibility (``B=1``), and/or correlation self-energy (``C=1``). (Otherwise ``A=0`` etc.) (Default none)
``BZ k l m``: Defines a k-point set ``k``x``l``x``m``.
``CHKMISM``: Checks the mismatch of the DFT wave functions at the MT spheres. (Default false)
``DIPOLE``: Calculates dipole moments for all direct (optical) transitions. (Default false)
``CHKOLAP``: Checks the overlap of the DFT wave functions. (Default false)
(``CORES cores``): Includes core states into the calculation of the susceptibility and self-energy. The core states are defined separately for each atom type as a list in brackets, e.g., ``(4f,5s,5p)``. Empty lists ``()`` are allowed. (Default none)
``CORESOC``: Treats core states as { j,m_j } Dirac spinors. Otherwise, the Dirac states are averaged in each { l,m } channel. (Default false)
(``GAUSS x y``): Use Gauss integration with widths ``x`` and ``y`` instead of tetrahedron integration. Only for debugging. (Default false)
(``IBC n``): Uses the incomplete-basis-set correction (IBC). Experimental! (Default false)
(``ITERATE opt e``): Constructs a (``opt=NR``: non-relativistic, ``opt=SR``: scalar-relativistic, ``opt=FR``: fully relativistic, i.e., including SOC) LAPW(+LO) Hamiltonian from the converged DFT potential and calculates wave functions and energies from it, which are then used in the calculation. This spares you the last DFT run. The parameter ``e`` is the lower energy bound for the electron states. The calculation is fairly slow. (Default none)
``JOB job1 job2 ...``: Defines what Spex should do. Consult the :ref:`tutorials` for details.
``KPT label1 label2 ...``: Defines labels (single characters) for k points. Consult the :ref:`tutorials` for details. (Default none)
``KPTPATH (A,B,C,...)``: Comma-separated list of k points that defines a k-point path. Spex automatically determines all k points (according to the ``BZ`` definition) that lie on the path. The path can be used (e.g., in the ``JOB`` definition) with ``PATH``. If Wannier functions are defined, Spex performs a Wannier interpolation along this path. (default none)
``MEM m``: Restricts the memory usage to ``m`` MB (per node). (Does not work exactly. The code actually needs more memory.) (Default 200)
``MTACCUR emin emax``: Writes plots for the MT representation error in the energy range {``emin``,``emax``} to the files ``spex.mt.NNN``. (Default none)
``NBAND n``: Restricts the number of bands to ``n`` bands or, if ``n`` is a real number, to all bands with energies below that value. (:comment All bands that are not treated explicitly can be taken into account in an approximate way by placing them at a fixed energy above all other energies. For example with ``NBAND 100+5`` this energy would lie 5 ha above the maximum energy (see PRB 78, 085125). :) (Default all bands)
(``PLUSSOC``): Adds spin-orbit coupling to the input data in second variation. (Default false)
``RESTART``: Enables to continue an older calculation (e.g., if the latter has crashed). Intermediate results are written to files (``spex.mb`` - Mixed product basis, ``spex.cou(s)`` - Coulomb matrix, ``spex.cor`` - Dielectric function, ``spex.spc`` - (e.g.) polarization function, ``spex.uwan`` - Wannier U matrices, ``spex.kolap`` - Overlap matrices for Wannier construction) or read from the files if they exist. With ``RESTART SIG``, Spex reads the self-energy from the files ``spex.sigx`` and ``spex.sigc``, which are always written in ``GW/HF FULL`` calculations. (Default false)
``STOREIBZ``: Wave functions are only stored in the IBZ rather than in the full BZ. This decreases the memory demand considerably but slows down the calculation somewhat because wave functions must be regenerated when needed. (Default false)
``WRITE q1 q2 ...``: Tells Spex to write the head element of the specified quantities ``q1/2=`` ``SUSCEP``, ``DIELEC`` or ``SCREEN`` to a file. Optionally a job number can be specified in brackets, as in ``WRITE SUSCEP(2)``. If one of these quantities are explicitly defined in the job definition, they are automatically written to files. With ``q1=INFO``, Spex writes preliminary results to several output files. Consult the :ref:`tutorials` for details. (Default none)
``WRTKPT``: Tells Spex to write out the k-point set and exit. (Default false)
Section ``MBASIS``
-------------------
``ADDBAS``: Augments mixed basis by the radial {u} functions (according to first part of SELECT entry). This improves the basis convergence for COHSEX calculations. (Default false)
``CHKPROD``: Checks the accuracy of the MT product basis. (Default false)
``GCUT G``: G cutoff for the IPWs of the mixed basis.
``LCUT l``: l cutoffs (one for each atom type) for the mixed basis.
``NOAPW``: Switches off construction of "product APWs", which are continuous at the MT sphere boundary. (Default false)
``OPTIMIZE``: Optimize mixed basis for correlation self-energy. Consult the :ref:`tutorials` for details. (Default none)
``SELECT l1,l3,lo1;l2,l4,lo2``: Selection of the MT radial functions from which the mixed basis is constructed. Consult the :ref:`tutorials` for details.
``TOL t``: Tolerance value for the removal of linear dependencies from the MT part of the mixed basis. (Default 0.0001)
(``WFADJUST``): Removes wavefunction coefficients belonging to radial functions that are not used to construct the MT product basis. (Currently the coefficients are actually not removed from the memory.) (Default false)
Section ``COULOMB``
--------------------
``CHKCOUL``: Performs checks on the Coulomb matrix: (1) Project on plane waves and see whether we get :math:`{v_{\mathbf{GG'}}=4\pi \delta_{\mathbf{GG'}}/ |\mathbf{k+G}|^2 }`, (2) compare largest eigenvalue of Coulomb matrix to :math:`{4\pi / k^2}`. (Default false)
(``CUTZERO``): Removes linear dependencies in the overlap matrix of the mixed basis. Otherwise, in the case of a large ``GCUT`` the diagonalization of the Coulomb matrix might fail due to numerical rounding errors in LAPACK. (Default false)
``LEXP``: l cutoff for the expansion of plane waves inside MT spheres. (Default 14)
``NOSTORE``: The default is to precalculate and keep the Coulomb matrices for all k points in memory. With this keyword the matrices are calculated whenever they are needed. This reduces the memory demand but somewhat slows down the calculation. Unless ``APPROXPW`` is chosen, this also applies to the overlap-correction matrix. (Only affects HF and QP calculations.) (Default false)
(``STEPRAD K``): Uses the Fourier transform of the step function as an alternative to the Rayleigh expansion for representing the IPWs and prints the resulting difference. The parameter ``K`` is the corresponding reciprocal cutoff radius. Only for testing. (Default none)
(``TSTCOUL``): Similar to ``CHKCOUL`` but regenerates MT part of the mixed basis from spherical Bessel functions and stops after the test. (Default false)
Section ``WFPROD``
-------------------
(``APPROXPW``): Since version 02.03 the plane-wave part of the wave-function products are calculated exactly leading to much better convergence with respect to ``GCUT``. However, the exact evaluation takes considerably more time. If ``APPROXPW`` is set, the old and approximate calculation of the products is used instead. (Default false)
``LCUT l``:Optional l cutoffs (one for each atom type) for the wave functions in the calculation of the products. (Default none)
``MTTHR d``: Threshold value below which wave-function coefficients are neglected. (1E-10 is a safe choice.) (Default 0)
(``MINCPW n``): Modifies the IPW wave-function coefficients such that their absolute values become as small as possible. This reduces the error in the evaluation of the wave-function products arising from the finite G cutoff and leads to better convergence with respect to ``GCUT`` and smoother band structures, when ``APPROXPW`` is used. The coefficients can be modified, because the set of IPWs is overcomplete. If set, the eigenvectors of the overlap matrix with the ``n`` smallest eigenvalues are used for this modification. Note that it only makes sense to use this together with ``APPROXPW``. (Default 0)
``FFT gcut``: Employs Fast Fourier transformation for the calculation of the plane-wave part of the wave-function products. Scales much better with system size than the direct (default) evaluation. Requires a reciprocal cutoff ``gcut``. The exact limit is :math:`gcut=GCUT{+2k_{\mathrm{max}}}`, where :math:`{k_{\mathrm{max}}}` is the PW cutoff of the DFT calculation, but much lower cutoffs are enough; try with ``gcut=8`` for example. If no ``gcut`` is given, Spex uses the exact limit. (Default none)
Section ``SUSCEP``
------------------
``DISORDER`` :math:`{\tau}`: Replaces the infinitesimal :math:`{i\eta}` by the finite frequency :math:`{i/2\tau}` in the response function. (Default none)
(``FSPEC N x``): Deprecated keyword. Use ``HILBERT`` instead. (Default none)
``HILBERT d x``: Defines the exponential frequency mesh for the Hilbert transformation in one of two ways: (1) ``d`` is the difference between the first (set at the band gap value or zero) mesh point :math:`{\omega_1}` and the second mesh point :math:`{\omega_2}`, and :math:`x` is the factor :math:`{x=(\omega_{i+1}-\omega_i)/(\omega_i-\omega_{i-1})}`; (2) if ``d`` is an integer, it is interpreted as the number of mesh points in the range :math:`{{\omega_1}..5 htr}`, and ``x`` is interpreted as the stretching factor "acquired at 5 htr", i.e., :math:`{x^{1/N}}` is the corresponding factor defined in (1). (Default 0.01 1)
:comment Alternatively, the first argument ``N`` can be a real number in which case it is interpreted as the first nonzero mesh point. Latest version: A negative second argument means the stretching factor that is reached after {N} points, i.e., :math:`{x^N}`. (Default 30 1.05):)
``HUBBARD file``: Calculates Hubbard parameters. If the optional filename ``file`` is given, the Hubbard parameters are read from (written to) ``file`` if it exists (does not exist). (Default false)
``MULTDIFF ON`` or ``OFF``: If set "ON" (and ``MB/PW=`` is used), the BZ integrand in the calculation of the head and wing elements of the polarization function (not for the magnetic susceptibility) is multiplied by KS energy differences. (The integration weights are correspondingly adjusted.) For a small (or zero) '''k''' vector this leads to better numerics (because the integrand is exactly inversely proportional to the KS energy differences in the case '''k=0'''). (Default ``ON `` for '''k=0''', ``OFF`` else)
``PLASMA p``: Sets the plasma frequency at ``p``. ``p=METAL``: use metallic screening. (Default none)
(``TETRAF``): If set, tetrahedron weights are only calculated in the (extended) irreducible part of the BZ. This accelerates the calculation of the weights considerably but introduces slight deviations due to symmetry breaking. (Default false)
``WGHTTHR w``: Sets a threshold value for the (tetrahedron) weights. All transition with weights below ``w`` are neglected. (Default :math:`{10^{-10}}`)
Section ``SENERGY``
----------------------
(``ALIGNVXC``): Aligns chemical potential to quasiparticle state of highest occupied state. (Default false)
``CONTINUE (n)``: If the optional (and now somewhat obsolete) parameter ``n`` is not given, a pade continuation is used. Otherwise, ``n`` specifies the number of poles used in the fit function for the analytic continuation of the self-energy. The fitting procedure can be influenced further by adding single characters to ``n``; character "``c``": employ additional constraints (i.e., integrability of the self-energy and continuity of its derivative at {\omega=0}), "``+``": add a constant to the fit function as a parameter, "``*``": allow poles above the real frequency axis. (Default Pade)
``CONTOUR D d``: Specifies contour integration for the evaluation of the self-energy. The first argument ``D``, if it is a number, defines the interval for the numerical derivative :math:`{d/d\epsilon \Sigma(\epsilon) = [\Sigma(\epsilon+D)-\Sigma(\epsilon-D)]/(2D)}` where :math:`{\epsilon}` is the corresponding KS energy. It can also be defined as a range, e.g. ``{-0.5..0.5,0.01}`` or ``[{-0.5..0.5,0.01}]``, which defines an equidistant mesh (relative to the Kohn-Sham energy or in absolute energies, the latter is the only viable definition for a ``GW FULL`` calculation) on which the self-energy is evaluated and which is used to solve the nonlinear quasiparticle equation (neglecting off-diagonal elements). The second argument ``d`` defines the step size of an equidistant mesh for the screened interaction. If ``d`` is omitted, a Pade continuation is used for the screened interaction (Keywords ``CONTINUE`` and ``CONTOUR`` are mutually exclusive.) (Default none)
``FREQINT SPLINE/PADE``: Algorithm for frequency integration in :math:`{\int G(\omega+\omega')W(\omega')d\omega'}`: the screened interaction is interpolated with a splines or with a Pade approximation. (Default SPLINE)
``LFRAC l``: l cutoff for the treatment of the anisotropy at the point :math:`{k=0}`. For isotropic systems ``l=1`` is enough. (Default 1)
``MESH n x``: Defines the imaginary frequency mesh where ``n`` is the number of points and ``x`` the frequency of the last point. Instead, one can also specify a file that contains the frequency mesh as a list with ``MESH filename``. (Default 10 10.0)
``NOZERO``: Neglect zero order terms in the self-energy coming from combinations of divergent terms math:`{1/k}` and math:`{1/k^2}` in the (bare or screened) interaction with linear and quadratic terms of the other quantities. This is necessary to converge the k-point sampling for materials with small band gaps. (Default false)
``RPAENE``: Calculate RPA correlation energy "on the fly". (Default false)
``VXC READ/CALC``: Specifies whether the vxc matrix elements are calculated or read from the file ``vxcfull``. (Default READ)
.. note:: ``IMAGTIME``: Since version 02.00 the correlation self-energy is evaluated by a direct frequency convolution of {G} and {W} rather than a multiplication in imaginary time. With the keyword ``IMAGTIME`` the latter (older) algorithm can still be used. (In some cases the old algorithm is considerably faster.) (Default false) :)
Section ``WANNIER``
--------------------
``FROZEN e``: Use frozen energy window. Lower bound is defined automatically, upper bound can be defined with the optional parameter ``e``. If ``e`` is not given, Spex guesses a reasonable value. (Default false)
``MAXIMIZE``: Use maximally localized Wannier functions instead of the first-guess ones. (Default false)
``ORBITALS (..) (..) ..``: Defines the orbitals for the first guess. Round brackets ``()`` for atoms, square brackets ``[]`` for atom types. In the brackets, one can use ;-separated lists of s,p,d,f,px,py,pz,dxy,dyz,dxz,dz2,dx2y2,t2g,eg,fz3,fxz2,fyz2,fzxy,fxyz,fxxy,fyxy,sp,sp2,sp3,sp3d,sp3d2. Euler angles can be specified with, e.g., ``sp,120,0,0``. (Default none)
``RSITE latvec``: Calculate off-site Hubbard interaction parameters (in addition to the on-site ones) with ``latvec`` being a lattice vector, e.g., ``(0,0,1)`` or several lattice vectors, e.g., ``(0,0,1) (0,0,3)`` or ``(0,0,1)-(0,0,3)`` or ``(0,1..2,1..3)``. The latter two define a list of lattice vectors: (0,0,1), (0,0,2), (0,0,3) and (0,1,1), (0,2,1), (0,1,2), (0,2,2), (0,1,3), (0,2,3), respectively. (Default none)
(``UREAD``): Wannier U matrix elements are read from the Fleur output file. (Default false)
(``WSCALE s``): Scaling factor ``s`` for the screened Coulomb interaction for spin-wave calculations. ``s`` can be a range ...... to be completed! (Default none)