The reader is supposed to be familiar with the LAPW basis set. This section is intended as a short recapitulation and to define the notation used in the manual.
The LAPW method relies on a partitioning of space into non-overlapping MT spheres centered at the atomic nuclei and the interstitial region. The basis functions are defined differently in the two regions, plane waves in the interstitial and numerical functions in the spheres, consisting of a radial part :math:`{u_{lp}^a(r)}` (:math:`{a}` is the atomic index) and the spherical harmonics :math:`{Y_{lm}(\hat{\mathbf{r}})}`. :math:`{p}` is an index to distinguish different types of radial functions: :math:`{u_{l0}^a=u_l^a}`, :math:`{\,u_{l1}^a=\dot{u}_l^a=\partial u_l^a/\partial\epsilon}`, :math:`{\,u_{lp}^a=u_l^{a,\mathrm{LO}},\,p\ge 2}`, where we have used the usual notation of LAPW. Augmented plane waves are formed by matching linear combinations of the :math:`{u}` and :math:`{\dot{u}}` to the interstitial plane waves, forming the standard LAPW basis set. Local orbitals :math:`{u^\mathrm{LO}}` can be used to extend the basis set, to enable the description of semicore and high-lying conduction states. The plane waves and the angular part of the MT functions can be converged straightforwardly with the reciprocal cutoff radius :math:`{g_\mathrm{max}}` and the maximal l quantum number :math:`{l_\mathrm{max}}`, respectively, whereas the radial part of the MT functions is more difficult to converge.
The LAPW method relies on a partitioning of space into non-overlapping MT spheres centered at the atomic nuclei and the interstitial region.
The basis functions are defined differently in the two regions, plane waves in the interstitial and numerical functions in the spheres,
consisting of a radial part :math:`{u_{lp}^a(r)}` (:math:`{a}` is the atomic index) and the spherical harmonics :math:`{Y_{lm}(\hat{\mathbf{r}})}`.
:math:`{p}` is an index to distinguish different types of radial functions: :math:`{u_{l0}^a=u_l^a}`,
where we have used the usual notation of LAPW. Augmented plane waves are formed by matching linear combinations of the
:math:`{u}` and :math:`{\dot{u}}` to the interstitial plane waves, forming the standard LAPW basis set.
Local orbitals :math:`{u^\mathrm{LO}}` can be used to extend the basis set, to enable the description of semicore and high-lying conduction states.
The plane waves and the angular part of the MT functions can be converged straightforwardly
with the reciprocal cutoff radius :math:`{g_\mathrm{max}}` and the maximal l quantum number :math:`{l_\mathrm{max}}`, respectively,
whereas the radial part of the MT functions is more difficult to improve systematically, but it is possible, see [Comput. Phys. Commun. 184, 2670 (2013)].
MTACCUR
--------
(*) The accuracy of the radial MT basis can be analyzed with the keyword ``MTACCUR e1 e2``, which gives the MT representation error [Phys. Rev. B 83, 081101] in the energy range between ``e1`` and ``e2``. (If unspecified, ``e1`` and ``e2`` are chosen automatically.) The results are written to the output files ``spex.mt.t`` where ``t`` is the atom type index, or ``spex.mt.s.t`` with the spin index ``s(=1 or 2)`` for spin-polarized calculations. The files contain sets of data for all l quantum numbers, which can be plotted separately with gnuplot (e.g., ``plot "spex.mt.1" i 3`` for :math:`{l=3}`).
(*) The accuracy of the radial MT basis can be analyzed with the keyword ``MTACCUR`` followed by two numbers :math:`e_1` and :math:`e_2`.
Spex then calculates the MT representation error
[Phys. Rev. B 83, 081101] in the energy range between :math:`e_1` and :math:`e_2`.
(If unspecified, upper and lower bounds are chosen automatically.)
The results are written to the output files ``spex.mt.t`` where t is the atom type index, or ``spex.mt.s.t`` with the spin index s(=1 or 2) for spin-polarized calculations. The files contain sets of data for all l quantum numbers, which can be plotted separately with "gnuplot" (e.g., ``plot "spex.mt.1" i 3`` for :math:`{l=3}`).
.. list-table:: Examples
:widths: 24 100
* - ``MTACCUR -1 2``
- Calculate MT representation error between -1 and 2 Hartree.
* - ``MTACCUR``
- Automatic energy range.
.. _mpb:
Mixed product basis
===================
The methods implemented in Spex distinguish themselves from conventional DFT with local or semilocal functionals by the fact that individual two-particle scattering processes are described explicitly. In such processes, the state of an incoming particle and the state that it scatters into form products of wavefunctions. Many of the physical quantities, such as the Coulomb interaction, the polarization function, and the dielectric function, become matrices when represented in a suitable product basis. In the context of the FLAPW method, the mixed product basis is an optimal choice. It consists of two separate sets of functions that are defined only in one of the spatial regions, while being zero in the other, the first is defined by products of the LAPW MT functions and the second by interstitial plane waves. (The products of plane waves are plane waves again.) The corresponding parameters are defined in the section ``MBASIS`` of the input file.
The methods implemented in Spex distinguish themselves from conventional DFT with local or semilocal functionals by the fact that individual two-particle scattering processes are described explicitly. In such processes, the state of an incoming particle and the state that it scatters into form products of wavefunctions. Many of the physical quantities, such as the Coulomb interaction, the polarization function, and the dielectric function, become matrices when represented in a suitable product basis. In the context of the FLAPW method, the mixed product basis is an optimal choice. It consists of two separate sets of functions that are defined only in one of the spatial regions, while being zero in the other, the first is defined by products of the LAPW MT functions and the second by interstitial plane waves. (The products of plane waves are plane waves again.) The corresponding parameters are defined in the section ``MBASIS`` of the input file.
GCUT (MBASIS)
---------------
If :math:`{N}` is the number of LAPW basis functions, one would naively expect the number of product functions to be roughly :math:`{N^2}`. In the case of the interstitial plane waves, this is not so, since, with a cutoff :math:`{g_\mathrm{max}}`, the maximum momentum of the product would be :math:`{2g_\mathrm{max}}`, leading to :math:`{8N}` as the number of product plane waves. Fortunately, it turns out that the basis size can be much smaller in practice. Therefore, we introduce a reciprocal cutoff radius :math:`{G_\mathrm{max}}` for the interstitial plane waves and find that, instead of :math:`{G_\mathrm{max}=2g_\mathrm{max}}`, good convergence is achieved already with :math:`{G_\mathrm{max}=0.75g_\mathrm{max}}`, the default value. The parameter :math:`{G_\mathrm{max}}` can be set to a different value with the keyword ``GCUT`` in the section ``MBASIS`` of the input file.
- Use a reciprocal cutoff radius of 2.9 Bohr\ :sup:`-1` for the product plane waves.
.. _lcut:
LCUT (MBASIS)
LCUT (MBASIS)
--------------
The MT functions are constructed from the products :math:`{u_{lp}^a(r)Y_{lm}(\hat{\mathbf{r}})u_{l'p'}^a(r)Y_{l'm'}(\hat{\mathbf{r}})}`. (Obviously, the atom index :math:`{a}` must be indentical.) The product of spherical harmonics exands into a linear combination of :math:`{Y_{LM}(\hat{\mathbf{r}})}` with :math:`{L=|l-l'|,...,l+l'}` and :math:`{|M|\le L}`. In principle, this leads to a cutoff of :math:`{2l_\mathrm{max}}` for the products, but, as with the plane waves, one can afford to use a much smaller cutoff parameter in practice. We use :math:`{L_\mathrm{max}=l_\mathrm{max}/2}` as the default. The corresponding keyword in the input file is called ``LCUT``.
The MT functions are constructed from the products :math:`{u_{lp}^a(r)Y_{lm}(\hat{\mathbf{r}})u_{l'p'}^a(r)Y_{l'm'}(\hat{\mathbf{r}})}`. (Obviously, the atom index :math:`{a}` must be identical.) The product of spherical harmonics expands into a linear combination of :math:`{Y_{LM}(\hat{\mathbf{r}})}` with :math:`{L=|l-l'|,...,l+l'}` and :math:`{|M|\le L}`. In principle, this leads to a cutoff of :math:`{2l_\mathrm{max}}` for the products, but, as with the plane waves, one can afford to use a much smaller cutoff parameter in practice. We use :math:`{L_\mathrm{max}=l_\mathrm{max}/2}` as the default. The corresponding keyword in the input file is called ``LCUT``.
.. list-table:: Example
:widths: 16 100
* - ``LCUT 5 4``
- Use l cutoffs of 5 and 4 for two atom types in the system.
SELECT (MBASIS)
----------------
In the LAPW basis, the matching conditions at the MT boundaries require large :math:`{l}` cutoff radii, typically around :math:`{l=10}`, giving a correspondingly large number of radial functions. Not all of these functions must be considered in the product basis set. The keyword ``SELECT`` enables a specific choice of the radial functions. When specified, an entry for each atom type is required. The default is ``l;l+1`` with ``l`` being the ``LCUT``. The best way to describe the syntax of ``SELECT`` is with examples:
The LOs are selected by series of 1s and 0s. If there are many LOs, a definition like ``0000111`` can be abbreviated to ``4031`` (four times ``0``, three times ``1``). It is important to note that the wave-function products that must be represented consist mostly of occupied-unoccupied pairs. So, the first set of parameters before the semicolon refers to the occupied state, the set after the semicolon refers to the unoccupied state.
In the LAPW basis, the matching conditions at the MT boundaries require large l cutoff values, typically around :math:`{l=10}`, giving a correspondingly large number of radial functions. Not all of these functions must be considered in the product basis set. The keyword ``SELECT`` enables a specific choice of the radial functions. When specified, an entry for each atom type is required.
The best way to describe the syntax of ``SELECT`` is with examples:
.. list-table:: Examples
:widths: 50 100
* - ``SELECT 2;3``
- Use products of :math:`{u_{lp} u_{l'p'}}` with :math:`{l\le 2}` and :math:`{l'\le 3}` for :math:`{p=0}` (so-called :math:`{u}`) and no function of :math:`{p=1}` (so-called :math:`{\dot{u}}`).
* - ``SELECT 2,1;3,2``
- Same as before but also include the :math:`{\dot{u}}` functions with :math:`{l\le 1}` and :math:`{l'\le 2}`.
* - ``SELECT 2,,1100;3,,1111``
- Same as first line but also include the local orbitals :math:`{p\ge 2}`, which are selected (deselected) by "1" ("0"): here, the first two and all four LOs, respectively. The default behavior is to include semicore LOs but to exclude the ones at higher energies.
* - ``SELECT 2,1,1100;3,2,1111``
- Same as second line with the LOs.
The LOs are selected by series of 1s and 0s. If there are many LOs, a definition like ``0000111``
can be abbreviated by ``4031`` (four times ``0``, three times ``1``).
One of the most important quantities to be calculated in *GW* calculations (and related methods)
which describe the coupling of a propagating particle to an interaction line. Often, the two states with
:math:`n` and :math:`n'` are occupied and unoccupied, respectively.
In this sense, the first set of ``SELECT`` parameters before the semicolon refers to the occupied states,
the set after the semicolon refers to the unoccupied states.
For :math:`l=2` with :math:`2l` or :math:`2l+1` being the l cutoff specified by ``LCUT``, the default
would be ``2;3``.
TOL (MBASIS)
------------------
(*) The set of MT products selected by ``SELECT`` can still be highly linearly dependent. Therefore, in a subsequent optimization step one diagonalizes the MT overlap matrix and retains only those eigenfunctions whose eigenvalues exceed a predefined tolerance value. This tolerance is 0.0001 by default and can be changed with the keyword ``TOL`` in the input file.
- Remove linear dependencies that fall below a tolerance of 0.00001 (see text).
OPTIMIZE (MBASIS)
-----------------
The mixed product basis can still be quite large. In the calculation of the screened interaction, each matrix element, when represented in the basis of Coulomb eigenfunctions, is multiplied by :math:`{\sqrt{v_\mu v_\nu}}` with the Coulomb eigenvalues :math:`{\{v_\mu\}}`. This gives an opportunity for reducing the basis-set size further by introducing a Coulomb cutoff :math:`{v_\mathrm{min}}`. The reduced basis set is then used for the polarization function, the dielectric function, and the screened interaction. The parameter :math:`{v_\mathrm{min}}` can be specified after the keyword ``OPTIMIZE MB`` in three ways: first, as a "pseudo" reciprocal cutoff radius :math:`{\sqrt{4\pi/v_\mathrm{min}}}` (which derives from the plane-wave Coulomb eigenvalues :math:`{v_\mathbf{G}=4\pi/G^2}`), second, directly as the parameter :math:`{v_\mathrm{min}}` by using a negative real number, and, finally, as the number of basis functions that should be retained when given as an integer. The so-defined basis functions are mathematically close to plane waves. For testing purposes, one can also enforce the usage of plane waves (or rather projections onto plane waves) with the keyword ``OPTIMIZE PW``, in which case the Coulomb matrix is known analytically. No optimization of the basis is applied, if ``OPTIMIZE`` is omitted.
In summary, there are a number of parameters that influence the accuracy of the basis set. Whenever a new physical system is investigated, it is recommendable to converge the basis set for that system. The parameters to consider in this respect are ``GCUT``, ``LCUT``, ``SELECT``, and ``OPTIMIZE``.
Despite the favorable convergence behavior of the mixed product basis,
it can still be quite large. In the calculation of the screened interaction, each matrix element, when represented in the basis of Coulomb eigenfunctions, is multiplied by :math:`{\sqrt{v_\mu v_\nu}}` with the Coulomb eigenvalues :math:`{\{v_\mu\}}`. This gives an opportunity for reducing the basis-set size further by introducing a Coulomb eigenvalue threshold :math:`{v_\mathrm{min}}`. The reduced basis set is then used for the polarization function, the dielectric function, and the screened interaction. The parameter :math:`{v_\mathrm{min}}` can be specified after the keyword ``OPTIMIZE MB`` in three ways: first, as a "pseudo" reciprocal cutoff radius :math:`{\sqrt{4\pi/v_\mathrm{min}}}` (which derives from the plane-wave Coulomb eigenvalues :math:`{v_\mathbf{G}=4\pi/G^2}`), second, directly as the parameter :math:`{v_\mathrm{min}}` by using a negative real number, and, finally, as the number of basis functions that should be retained when given as an integer. The so-defined basis functions are mathematically close to plane waves. For testing purposes, one can also enforce the usage of plane waves (or rather projections onto plane waves) with the keyword ``OPTIMIZE PW``, in which case the Coulomb matrix is known analytically. No optimization of the basis is applied, if ``OPTIMIZE`` is omitted.
.. list-table:: Examples
:widths: 34 100
* - ``OPTIMIZE MB 4.0``
- Optimize the mixed product basis by removing eigenfunctions with eigenvalues below :math:`4\pi/4.0^2`.
* - ``OPTIMIZE MB -0.05``
- Optimize the mixed product basis by removing eigenfunctions with eigenvalues below 0.05.
* - ``OPTIMIZE MB 80``
- Retain only the eigenfunctions with the 80 largest eigenvalues.
* - ``OPTIMIZE PW 4.5``
- Use projected plane waves with the cutoff 4.5 Bohr\ :sup:`-1` (for testing only, can be quite slow).
In summary, there are a number of parameters that influence the accuracy of the basis set. Whenever a new physical system is investigated, it is recommendable to converge the basis set for that system. The parameters to consider in this respect are ``GCUT``, ``LCUT``, ``SELECT``, and ``OPTIMIZE``.
Finally, we show a section ``MBASIS`` for a system with three atom types as an example
...
...
@@ -117,7 +143,7 @@ NOAPW (MBASIS)
ADDBAS (MBASIS)
------------------
(*) This keyword augments the mixed product basis by the radial :math:`{u_{lp}}` functions, the :math:`{l}` and :math:`{p}` parameters are according to first part of the ``SELECT`` definition. This improves the basis convergence for COHSEX calculations.
(*) This keyword augments the mixed product basis by the radial :math:`{u_{lp}}` functions, the :math:`{l}` and :math:`{p}` parameters are according to the first part of the ``SELECT`` definition. This improves the basis convergence for COHSEX calculations.
CHKPROD (MBASIS)
-----------------
...
...
@@ -125,38 +151,199 @@ CHKPROD (MBASIS)
WFADJUST (MBASIS)
------------------
(**) 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.)
(**) 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 memory.)
FFT (WFPROD)
--------------
When the interaction potential is represented in the mixed product basis, the coupling to the single-particle states involve projections of the form
The calculation of these projections can be quite expensive. Therefore, there are a number of keywords that can be used for acceleration. Most of them are, by now, somewhat obsolete. An important keyword, though, is ``FFT`` in the section ``WFPROD`` of the input file. When used, the interstitial terms are evaluated using Fast Fourier Transformations (FFTs), i.e., by transforming into real space (where the convolutions turn into products), instead of by explicit convolutions in reciprocal space. For small systems the latter is faster, but for large systems it is recommendable to use FFTs because of a better scaling with system size. A run with FFTs can be made to yield results identical to the explicit summation. This requires an FFT reciprocal cutoff radius of :math:`{2G_\mathrm{max}+g_\mathrm{max}}`, which can be achieved by setting ``FFT EXACT``, but such a calculation is quite costly. It is, therefore, advisable to use smaller cutoff radii, thereby sacrificing a bit of accuracy but speeding up the computations a lot. If given without an argument, Spex will use 2/3 of the above *exact* cutoff. One can also specify a cutoff by a real-valued argument explicitly, good compromises between accuracy and speed are values between 6 and 8 Bohr'^-1^'.
The calculation of these projections can be quite expensive. Therefore, there are a number of keywords that can be used for acceleration.
Most of them are, by now, somewhat obsolete. An important keyword, though, is ``FFT`` in the section ``WFPROD`` of the input file.
When used, the interstitial terms are evaluated using Fast Fourier Transformations (FFTs), i.e., by transforming into real space
(where the convolutions turn into products), instead of by explicit convolutions in reciprocal space.
For small systems the latter is faster, but for large systems it is recommendable to use FFTs because of a better scaling with system size.
A run with FFTs can be made to yield results identical to the explicit summation. This requires an FFT reciprocal cutoff radius of :math:`{2g_\mathrm{max}+G_\mathrm{max}}`, which can be achieved by setting ``FFT EXACT``, but such a calculation is quite costly. It is, therefore, advisable to use smaller cutoff radii, thereby sacrificing a bit of accuracy but speeding up the computations a lot. If given without an argument, Spex will use 2/3 of the above *exact* cutoff. One can also specify a cutoff by a real-valued argument explicitly, good compromises between accuracy and speed are values between 6 and 8 Bohr\ :sup:`-1`.
.. list-table:: Examples
:widths: 18 100
* - ``FFT 6``
- Use FFTs with the cutoff 6 Bohr\ :sup:`-1`.
* - ``FFT``
- Use the default cutoff :math:`{\frac{2}{3}(2g_\mathrm{max}+G_\mathrm{max})}`.
* - ``FFT EXACT``
- Use the exact cutoff :math:`{2g_\mathrm{max}+G_\mathrm{max}}`.
APPROXPW (WFPROD)
------------------
(**) Since version 02.03 the interstitial part of the projections is calculated exactly, leading to favorable 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. (Only included for testing.)
(**) Since version 02.03 the interstitial part of the projections is calculated exactly, leading to favorable convergence with respect to ``GCUT``. However, the exact evaluation takes considerably more time. If ``APPROXPW`` is set, the old and approximate way of calculating the products is used instead. (Only included for testing.)
LCUT MTTHR (MBASIS)
--------------------
(**) The MT part of the projections can be accelerated as well with the keywords ``LCUT`` and ``MTTHR`` in the section ``WFPROD``. (Note the other unrelated :ref:`lcut` keyword in ``MBASIS``.) The first can be used to restrict the l cutoff of the wave functions (only for the projections), one l cutoff for each atom type. The second is a threshold value below which wave-function coefficients are neglected. By default, the two options are unused.
LCUT and MTTHR (WFPROD)
------------------------
(**) The MT part of the projections can be accelerated as well using the the keywords ``LCUT`` and ``MTTHR``
in the section ``WFPROD``. (The keyword ``LCUT`` should not be confused with the keyword of the same name
in the section ``MBASIS``, :numref:`lcut`.) The first can be used to restrict the l cutoff of the wavefunctions (only for the projections), one l cutoff for each atom type. The second is a threshold value below which wave-function coefficients are neglected. By default, the two options are unused.
MINCPW (MBASIS)
MINCPW (WFPROD)
----------------
(**) The keyword ``MINCPW`` modifies the plane-wave 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``.
(**) The keyword ``MINCPW`` modifies the plane-wave 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``.
.. _wannier:
Wannier orbitals
=============================
...
.. note:: For Wannier functions to be available, the Spex configure script for compilation has to be run with the option ``--with-wan``. See :numref:`installation`.
For many features of the Spex code, Wannier functions are required: Wannier interpolation, spin-wave calculations,
*GT* self-energy, Hubbard *U* parameter.
Wannier functions are constructed by a linear combination of single-particle states.
They can be viewed as Fourier
transforms of the Bloch states. While Bloch states have a definite k vector and are delocalized over real space,
the Wannier functions are localized at specific atomic sites and delocalized in k space.
.. warning:: This section discusses several settings that are common for all calculations. Some of them are explained in more detail in later sections.
This section discusses several settings that are common for all calculations. Some of them are explained in more detail in later chapters.
General Settings
=================
MEM
-----------
Calculations based on many-body perturbation theory are costly, not only in terms of computation time but also in terms of memory. Since the problem sizes (e.g., number of atoms) are thus effectively restricted by the memory hardware of the computer, the latter constitutes in some ways a more serious limit than the computation time the user can afford to invest. Therefore, an upper limit for the memory that Spex is allowed to use can be defined with the keyword MEM x with x in MB. The default is MEM 1000. In parallel Spex, x is the upper limit per node. If possible, Spex will divide the work load into packets in such a way that the memory usage stays below the limit. (Actually, Spex might use a bit more memory than specified.)
Calculations based on many-body perturbation theory are costly, not only in terms of computation time but also in terms of memory. Since the problem sizes (e.g., number of atoms) are thus effectively restricted by the memory hardware of the computer, the latter constitutes in some ways a more serious limit than the computation time the user can afford to invest. Therefore, an upper limit for the memory that Spex is allowed to use can be defined with the keyword ``MEM x`` with x in MB. The default is ``MEM 1000``.
In parallel Spex, the value would correspond to the upper limit per node. If possible, Spex will divide the work load into packets in such a way that the memory usage stays below the limit. (Actually, Spex might use a bit more memory than specified.)
.. list-table:: Example
:widths: 16 100
* - ``MEM 2000``
- Restrict memory usage to 2GB (Default: 1GB).
.. _job:
JOB
--------
Each Spex run needs a job definition, which defines what Spex should do, e.g., ``JOB GW 1:(1-5)`` for a ``GW`` calculation of the specified set of bands. The available jobs are
Each Spex run needs a job definition, which defines what Spex should do, e.g., ``JOB GW 1:(1-5)`` for a *GW* calculation of the specified set of bands. The available jobs are
@@ -41,43 +44,47 @@ Each Spex run needs a job definition, which defines what Spex should do, e.g., `
Details of these jobs are explained in subsequent sections. The job definition must not be omitted but may be empty: ``JOB``, in which case Spex will just read the wavefunctions and energies, perform some checks and some elemental calculations (e.g., Wannier interpolation), and stop. In principle, Spex supports multiple jobs such as ``JOB GW 1:(1-5) DIELEC 1:{0:1,0.01}``. This feature is, however, seldom used and is not guaranteed to work correctly in all versions.
There are only two keywords that may not be omitted from the input file. The first is ``JOB``, the second ``BZ``, which defines the k-point set for the sampling of the Brillouin zone. The keyword requires four integer arguments, BZ l m n, defining an lxmxn k-point set. If the keyword ``WRTKPT`` is set (or, alternatively, with the command line option ``spex -w``), Spex uses the ``BZ`` definition to construct the irreducible wedge of the k-point set and writes the respective list of k points to a file, which is then read by the DFT code.
- Subsequently, calculate the screened interaction on a frequency mesh.
* - ``JOB``
- Just perform some checks and stop.
.. _WRTKPT:
BZ and WRTKPT
--------------
There are only two keywords that must not be omitted from the input file. The first is ``JOB``, the second ``BZ``, which defines the k-point set for the sampling of the Brillouin zone. The keyword requires four integer arguments, ``BZ l m n``, defining an :math:`l\times m\times n` k-point set. If the keyword ``WRTKPT`` is set (or, alternatively, with the command line option ``spex -w``), Spex uses the ``BZ`` definition to construct the irreducible wedge of the k-point set and writes the respective list of k points to a file, which is then read by the DFT code.
.. list-table:: Example
:widths: 16 100
* - ``BZ 8 4 2``.
- Define a :math:`8\times 4\times 2` k-point sampling.
RESTART
--------
This is an important keyword. It enables (a) continuing a calculation that has, for some reason, stopped or crashed and (b) reusing data of a previous calculation. If specified, Spex will store intermediate results in a file or read them if the particular data is already present in the file. Even if RESTART was not specified in the first run, Spex might still be able to reuse data from a previous run with ``RESTART 2``. (This option usually gives less freedom for a change of parameters. ``RESTART 1`` and RESTART are equivalent.) It depends on the particular job definition whether ``RESTART`` and/or ``RESTART 2`` are available and how they work. See below for details.
This is an important keyword. It enables (a) continuing a calculation that has, for some reason, stopped or crashed and (b) reusing data of a previous calculation. If specified, Spex will store intermediate results in a file or read them if the particular data is already present in the file. Even if ``RESTART`` was not specified in the first run, Spex might still be able to reuse data from a previous run with ``RESTART 2``. (This option usually gives less freedom for a change of parameters. ``RESTART 1`` and ``RESTART`` are equivalent.) It depends on the particular job definition whether ``RESTART`` and/or ``RESTART 2`` are available and how they work. See below for details.
.. list-table:: Examples
:widths: 18 100
* - ``RESTART``
- Read/write restart file.
* - ``RESTART 2``
- Try to reuse data from standard output files.
STOREIBZ
---------
Spex reads wavefunctions and energies as a first step. In general, these have to be stored for all k vectors in the set (e.g., for all 64 points of a 4x4x4 set), filling up a lot of memory. This can be restricted to the irreducible zone (only eight points in the example) with the keyword ``STOREIBZ``. Spex then regenerates the wavefunctions on equivalent k points on the fly. This might slow down the calculation but is more economical with computer memory.
Spex reads wavefunctions and energies as a first step. In general, these have to be stored for all k vectors in the set (e.g., for all 64 points of a :math:`4\times 4\times 4` set), filling up a lot of memory. This can be restricted to the irreducible zone (only eight points in the example) with the keyword ``STOREIBZ``. Spex then regenerates the wavefunctions on equivalent k points on the fly. This might slow down the calculation but is more economical with computer memory.
.. note:: ``--enable-load`` (*) Another possibility to reduce the memory consumption is to reconfigure (and recompile) the code with the option --enable-load (or recompile with the flag -DLOAD in the Makefile). With this option, Spex stores the wavefunctions in memory only temporarily and rereads them from harddisc whenever they are needed. Obviously, this requires a fast harddisc and network connection. The HDF5 library is used for the data transfer. There is no possibility to set the option in the input file because it strongly affects the way the wavefunction data is handled in the code.
--enable-load
-----------------
(*) Another possibility to reduce the memory consumption is to reconfigure (and recompile) the code with the option ``--enable-load`` (or recompile with the flag ``-DLOAD`` in the Makefile). With this option, Spex stores the wavefunctions in memory only temporarily and rereads them from harddisc whenever they are needed. Obviously, this requires a fast harddisc and network connection. The HDF5 library is used for the data transfer. There is no possibility to set the option in the input file because it strongly affects the way the wavefunction data is handled in the code.
Input data
===========
...
...
@@ -87,78 +94,129 @@ Spex needs data from a previous self-consistent solution of a mean-field system
NBAND
-----
The Green function involves a summation over electronic bands, as do the polarization function and the self-energy. The convergence with respect to the number of bands is a very important aspect in calculations based on many-body perturbation theory. The keyword NBAND n sets the number of bands to n. Obviously, n must not be larger than the number of bands provided by the input data. It should be noted that the actual number of bands can differ from n and also from k point to k point because Spex makes sure that degenerate subspaces are not cut in order to avoid symmetry breaking. If n is a real number (i.e., if it contains a decimal point: 3.0), it is interpreted as the maximal band energy. Then, all bands up to this energy are included. This is helpful if one wants to use a single parameter for calculations with differently sized unit cells. For example, when the unit cell doubles, one would have to include twice as many bands to reach the same accuracy, while the maximal band energy practically remains unchanged. If NBAND is unset, all available bands are used.
The Green function involves a summation over electronic bands, as do the polarization function [Eq. :eq:`eqP`] and the self-energy. The convergence with respect to the number of bands is a very important aspect in calculations based on many-body perturbation theory. The keyword ``NBAND n`` sets the number of bands to n. Obviously, n must not be larger than the number of bands provided by the input data. It should be noted that the actual number of bands can differ from n and also from k point to k point because Spex makes sure that degenerate subspaces are not cut in order to avoid symmetry breaking. If n is a real number (i.e., if it contains a decimal point: ``3.0``), it is interpreted as the maximal band energy. Then, all bands up to this energy are included. This is helpful if one wants to use a single parameter for calculations with differently sized unit cells. For example, when the unit cell doubles, one would have to include twice as many bands to reach the same accuracy, while the maximal band energy (practically) remains unchanged. If ``NBAND`` is unset, all available bands are used.
(*) The set of wavefunctions read from harddisc can be checked in terms of their orthonormality and continuity (mismatch) at the muffin-tin (MT) boundary with the keywords CHKOLAP and CHKMISM, respectively. The former test gives a value for the deviation from exact orthonormality. The smaller the value, the better the condition of orthonormality is fulfilled. If the deviation is too large, the program stops. The second keyword yields for each k point the average and maximal MT mismatch of the wavefunctions. If any of these tests yield too large errors, there could be a problem with the read-in process or with the data written by the DFT code. The developers should be informed in this case.
By default, Spex averages over the SOC-splitted states. For example, the two states 2p\ :sup:`1/2` and the four states 2p\ :sup:`3/2` are
averaged to give the six quasi-non-relativistic states of the 2p shell (or the three spin-up 2p states and the three spin-down 2p states
in the case of spin polarization). Then, all core states of a given shell have the same energy and the same radial form of the wavefunction. The averaging procedure
can be avoided by specifying ``CORESOC``. The SOC-splitted states and the different energies and wavefunctions are then retained and taken
into account in the calculations of the self-energy, polarization function, et cetera. In the case of spin polarization, the Weiss field gives
rise to further lifting of degeneracies. Spex calculates the respective new splittings, energies, and wavefunctions.
For reference, the core-state energies are written to the output file. Usually, the effect of ``CORESOC`` is numerically small, but it
still might play an important role for *GW* calculations in the case of very small band gaps.
CHKMISM and CHKOLAP
--------------------
(*) The set of wavefunctions read from harddisc can be checked in terms of their orthonormality and continuity (mismatch) at the muffin-tin (MT) boundary with the keywords ``CHKOLAP`` and ``CHKMISM``, respectively. The former test gives a value for the deviation from exact orthonormality. The smaller the value, the better the condition of orthonormality is fulfilled. If the deviation is too large, the program stops.
The second keyword yields, for each k point, the average and maximal MT mismatch of the wavefunctions. If any of these tests yield too large errors, there could be a problem with the read-in process or with the data written by the DFT code. The developers should be informed in this case.
MTACCUR
-------
(*) The LAPW method relies on a partitioning of space into MT spheres and the interstitial region. The basis functions are defined differently in the two regions, interstitial plane waves in the latter and numerical functions in the spheres with radial parts :math:`{u(r)}, {\dot{u}(r)=\partial u(r)/\partial\epsilon}`, :math:`{u^\mathrm{LO}(r)}` and spherical harmonics :math:`{Y_{lm}(\hat{\mathbf{r}})}` The plane waves and the angular part of the MT functions can be converged straightforwardly with the reciprocal cutoff radius :math:`{g_\mathrm{max}}` and the maximal l quantum number :math:`{l_\mathrm{max}}`, respectively, whereas the radial part of the MT functions is not converged as easily. The standard LAPW basis is restricted to the functions :math:`{u}` and :math:`{\dot{u}}`. Local orbitals :math:`{u^\mathrm{LO}}` can be used to extend the basis set, to enable the description of semicore and high-lying conduction states. The accuracy of the radial MT basis can be analyzed with the keyword MTACCUR e1 e2 which gives the MT representation error [Phys. Rev. B 83, 081101] in the energy range between e1 and e2. (If unspecified, e1 and e2 are chosen automatically.) The results are written to the output files spex.mt.t where t is the atom type index, or spex.mt.s.t with the spin index s(=1 or 2) for spin-polarized calculations. The files contain sets of data for all l quantum numbers, which can be plotted separately with gnuplot (e.g., plot "spex.mt.1" i 3 for :math:`{l=3}`)
The plane waves and the angular part of the MT functions can be converged straightforwardly with the reciprocal cutoff radius :math:`{g_\mathrm{max}}`
and the maximal l quantum number :math:`{l_\mathrm{max}}`, respectively, whereas the radial part of the MT functions is not converged as easily.
The standard LAPW basis is restricted to the functions :math:`{u}` and :math:`{\dot{u}}`. Local orbitals :math:`{u^\mathrm{LO}}`
can be used to extend the basis set, to enable the description of semicore and high-lying conduction states.
The accuracy of the radial MT basis can be analyzed with the keyword ``MTACCUR e1 e2`` which gives the MT representation error [Phys. Rev. B 83, 081101]
in the energy range between e1 and e2. (If unspecified, e1 and e2 are chosen automatically.) The results are written to the output files "spex.mt.t"
where t is the atom type index, or "spex.mt.s.t" with the spin index s(=1 or 2) for spin-polarized calculations.
The files contain sets of data for all l quantum numbers, which can be plotted separately with gnuplot (e.g., ``plot "spex.mt.1" i 3`` for :math:`{l=3}`)
.. list-table:: Examples
:widths: 24 100
* - ``MTACCUR -1 2``
- Calculate MT representation error between -1 and 2 Hartree.
* - ``MTACCUR``
- Automatic energy range.
BANDINFO
---------
(*) This keyword lets Spex analyze the orbital character of the wavefunctions. The results are given, first,
in the form of a table in the output file containing the orbital decomposition for each eigenstate and,
second, as projected density-of-states (DOS) plots in the files "spex.dos.NNN" (where NNN is a three-digit running index).
As the table can be very large, there is a possibility to choose the atom type index at whose spheres the analysis is to be performed.
