tutorials.rst 71.3 KB
Newer Older
1 2 3 4 5
.. _tutorials:

===================
Tutorials
===================
6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24
In this section, we provide detailed tutorials for the main features of the Spex code.

GW calculations
===============
The Spex code was started as a pure GW code. The GW approach remains the main computational method implemented in the code.

One-shot approach
-----------------
A simple input file for a one-shot GW calculation for bulk silicon was already presented in :ref:`getting_started`. The following, equivalent input file is even more minimalistic.

.. code-block:: bash

  BZ 4 4 4
  JOB GW 1:(1,2,5) 7:(1,3,5) 3:(1-3,5)

It only contains the two essential keywords that any Spex input file must contain: ``BZ`` and ``JOB``, specifying, respectively, the k mesh for the Brillouin-zone sampling and the requested type of calculation. Here, we calculate quasiparticle corrections for the bands (1,2,5) of the first, (1,3,5) of the seventh, and (1,2,3,5) of the third k point. The band indices are defined according to the ordering in the mean-field input data. In the example, we have left out some band indices because of energy degeneracy. For example, bands 3 and 4 (of the first k point) are degenerate with band 2.

In the case of magnetic systems, the quasiparticle energies for both spins are calculated by default. Alternatively, one can choose the spin index by using u (spin up) or d (spin down), e.g., ``JOB GW 1:u(1,2,5) 1:d(1,2,5)`` is identical to ``JOB GW 1:(1,2,5)``.

anoop chandran's avatar
anoop chandran committed
25 26
.. _kpt:

27 28
KPT 
----
29
The k-points follow an internal ordering: first the irreducible parent k points, then the remaining equivalent k points. A list of the irreducible k-vectors is written to the output file. In the present example, there are eight irreducible k points and 64 k points in total. All 64 k-point indices can be used in the job definition. We have chosen the ones from the irreducible set. They correspond to the :math:`{\Gamma}` (index 1), X (index 7), and L point (index 3). Clearly, for a different k-point set, e.g., 8x8x8, the k-point indices would change (except for the index 1, which always corresponds to the :math:`{\Gamma}` point). Therefore, there is the possibility of defining k-point labels with 
30 31 32 33 34

``KPT X=1/2*(0,1,1) L=1/2*(0,0,1)``
or 
``KPT X=[1,0,0] L=1/2*[1,1,-1]``

35
The labels must be single (upper- or lower-case) characters. The two definitions are equivalent. The first gives the k vectors in internal coordinates, i.e., in the basis of the reciprocal basis vector, the second in cartesian coordinates in units of :math:`{2\pi/a}`  with the lattice constant a . In the case of the fcc lattice of silicon, the lattice basis vectors are :math:`{a_1=a(011)/2}` , :math:`a_2=a(101)/2` , and :math:`a_3=a(110)/2` . The reciprocal basis vectors are thus :math:`{b_1=2\pi/a(-111)}` et cetera. For the X point, e.g., one then gets :math:`{(a_2+a_3)/2=2\pi/a(100)}` . In order for the cartesian coordinates (square brackets) to be interpreted correctly, Spex must obviously know the lattice constant a. (In Fleur, the lattice constant is taken to be the global scaling factor for the lattice vectors.) The so-defined k points must be elements of the k mesh defined by ``BZ``. We will later discuss how points outside the k mesh can be considered using the special label +. With the k labels, the above job definition can be written as ``JOB GW 1:(1,2,5) X:(1,3,5) L:(1-3,5)`` as in the input file described in :ref:`getting_started` There are two more special k-point labels: ``IBZ`` and ``BZ`` (e.g., ``JOB GW IBZ:(1,2,5)``) stand for all k points in the irreducible and the full k set, respectively. (The label ``BZ`` is included for completeness but is not needed in practice.) The ``IBZ`` label is helpful when a self-consistent GW calculation is to be performed, which requires the self-energy to be calculated for the whole irreducible Brillouin zone.
36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59

The quasiparticle energies are written to standard output in tabular form::

    Bd     vxc    sigmax    sigmac         Z        KS        HF          GW lin/dir
    1 -12.15897 -19.20415   6.60649   0.65146  -6.19011 -13.23529  -6.36401   0.73681
                            1.05993  -0.10556                      -6.36806   0.72704
    2 -13.30408 -14.45814   0.69809   0.76876   5.77669   4.62263   5.42615   0.00070
                            0.00039  -0.00088                       5.42695   0.00081
    5 -11.49631  -7.27160  -3.86726   0.76385   8.34013  12.56485   8.61313  -0.00731
                           -0.00708  -0.00533                       8.61239  -0.00749

The columns are

* ``Bd``  band index,
* ``vxc`` expectation value of the exchange-correlation potential :math:`v^{xc}`, e.g., -12.15897 eV, 
* ``sigmax``  expectation value of the exchange self-energy :math:`\sum^x`, e.g., -19.20415 eV, 
* ``sigmac``  expectation value of the correlation self-energy :math:`\sum^c`, e.g., (6.60649+1.05993i) eV (note that the self-energy is complex), 
* ``Z`` renormalization factor Z, e.g., (0.65146-0.10556i) eV, 
* ``KS``  mean-field energy eigenvalue (e.g., from the previous KS-DFT calculation), e.g., -6.19011 eV, 
* ``HF``  Hartree-Fock value (one-shot), e.g., -13.23529 eV, 
* ``GW``  GW quasiparticle values, e.g., (-6.36401+0.73681i ) eV (linearized solution) and (-6.36806+0.72704i ) eV (direct solution). 

The two GW values for the quasiparticle energy follow two common methods to approximately solve the quasiparticle equation

Anoop Chandran's avatar
Anoop Chandran committed
60 61 62
.. math::
  \displaystyle\left\{-\frac{\nabla}{2}+v^\mathrm{ext}(\mathbf{r})+v^\mathrm{H}(\mathbf{r})\right\}\psi_{\mathbf{k}n}(\mathbf{r})+\int \Sigma^\mathrm{xc}(\mathbf{r},\mathbf{r}';E_{\mathbf{k}n})\psi_{\mathbf{k}n}(\mathbf{r}')d^3 r=E_{\mathbf{k}n}\psi_{\mathbf{k}n}(\mathbf{r})
  :label: qpeq
63 64 65

where :math:`{v^\mathrm{ext}}`, :math:`{v^\mathrm{H}}`, :math:`{\Sigma^\mathrm{xc}}`, :math:`{\psi_{\mathbf{k}n}}`, :math:`{E_{\mathbf{k}n})}` are the external and Hartree potential, the ``GW`` self-energy, and the quasiparticle wavefunction and energy, respectively. Taking the difference :math:`{\Sigma^\mathrm{xc}-v^\mathrm{xc}}` as a small perturbation, we can write the quasiparticle energy as a correction on the mean-field eigenvalue

Anoop Chandran's avatar
Anoop Chandran committed
66 67 68
.. math::
  \displaystyle E_{\mathbf{k}n}=\epsilon_{\mathbf{k}n}+\langle\phi_{\mathbf{k}n}|\Sigma^\mathrm{xc}(E_{\mathbf{k}n})-v^\mathrm{xc}|\phi_{\mathbf{k}n}\rangle\approx\epsilon_{\mathbf{k}n}+Z_{\mathbf{k}n}\langle\phi_{\mathbf{k}n}|\Sigma^\mathrm{xc}(\epsilon_{\mathbf{k}n})-v^\mathrm{xc}|\phi_{\mathbf{k}n}\rangle
  :label: qppert
69

Anoop Chandran's avatar
Anoop Chandran committed
70
with the single-particle wavefunction :math:`{\phi_{\mathbf{k}n}}` and the frequency-independent potential :math:`{v^{\mathrm{xc}}}`, which in the case of a KS solution would correspond to the local exchange-correlation potential; the nonlocal Hartree-Fock exchange potential and the *hermitianized* self-energy of QSGW (see below) are other examples. :math:`{Z_{\mathbf{k}n}=[1-\partial\Sigma^{\mathrm{xc}}/\partial\omega(\epsilon_{\mathbf{k}n})]^{-1}}` is called the renormalization factor. The two expressions on the right-hand side correspond to the "linearized" and "direct" (iterative) solutions given in the output. The direct solution takes into account the non-linearity of the quasiparticle equation and is thus considered the more accurate result. However, there is usually only little difference between the two values.
71 72
Up to this point, the job syntax for Hartree Fock (``JOB HF``), PBE0 (``JOB PBE0``), screened exchange (``JOB SX``), COHSEX (``JOB COSX``), and ''GT'' (``JOB GT`` and ``JOB GWT``) calculations is identical to the one of ``GW`` calculations, e.g., ``JOB HF FULL X:(1-10)``. Except the latter (``GT``), all of these methods are mean-field approaches, so one only gets one single-particle energy (instead of a ''linearized'' and a ''direct'' solution) for each band.

anoop chandran's avatar
anoop chandran committed
73 74
.. _spectral:

75 76 77 78 79
SPECTRAL (SENERGY) 
------------------

(*) It should be pointed out that the quasiparticle energies given in the output rely on the quasiparticle approximation. The more fundamental equation, as it were, is the Dyson equation

Anoop Chandran's avatar
Anoop Chandran committed
80 81
.. math::
 \displaystyle G(\omega)=G_0(\omega)+G_0(\omega)[\Sigma^{\mathrm{xc}}(\omega)-v^{\mathrm{xc}}]G(\omega)
82

Anoop Chandran's avatar
Anoop Chandran committed
83
which links the interacting Green function {$G$} to the non-interacting KS one :math:`{G_0}` and which, in principle, requires the self-energy to be known on the complete :math:`{\omega}` axis. The spectral function measured in photoelectron spectroscopy is directly related to the Green function by
84

Anoop Chandran's avatar
Anoop Chandran committed
85 86
.. math:: 
  A(\mathbf{k},\omega)=\pi^{-1}\,\text{sgn}(\omega-\epsilon_\mathrm{F})\,\,\text{tr}\left\{\text{Im}[\omega I-H^\mathrm{KS}(\mathbf{k})-\Sigma^{\mathrm{xc}}(\mathbf{k},\omega)]^{-1}\right\}\,,
87 88 89 90 91 92 93 94 95

where the trace (tr) is over the eigenstates and :math:`{\epsilon_\mathrm{F}}` is the Fermi energy. The spectral function can be evaluated using the line

``SPECTRAL``

in the section ``SENERGY`` of the input file. This option does not require the ``FULL`` keyword. Optionally, one can define a frequency mesh by
the keyword ``SPECTRAL`` in the section ``SENERGY``, in the examples below from -10 eV to 1 eV in steps of 0.01 eV. If there is no explicit mesh, Spex chooses one automatically. The spectral function is then written to the file "spectral", one block of data for each k point given in the job definition. There is another optional parameter given at the end of the line (second example below), which can be used to bound the imaginary part of the self-energy and, thus, the quasiparticle peak widths from below by this value (unset if not given). This can be helpful in the case of very sharp quasiparticle peaks that are otherwise hard to catch with the frequency mesh.


Anoop Chandran's avatar
Anoop Chandran committed
96 97 98 99 100 101 102
+----------+---------------------------------------+-----------------------------------------------------------------+
| Examples | ``SPECTRAL {-10eV:1eV,0.01eV}``       | | Write spectral function :math:`{\text{Im}G(\omega)}` on the   |
|          |                                       | | specified frequency mesh to the file "spectral".              |
+----------+---------------------------------------+-----------------------------------------------------------------+
|          | ``SPECTRAL {-10eV:1eV,0.01eV} 0.002`` | | Bound imaginary part from below by 0.02, preventing           |
|          |                                       | | peak widths to become too small to be plotted.                |
+----------+---------------------------------------+-----------------------------------------------------------------+
103 104 105 106 107

Alhough ``GW`` calculations can be readily performed with the default settings, the user should be familiar to some degree with the details of the computation and how he/she can influence each step of the program run. Also note that the default settings might work well for one physical system but be unsuitable for another. 

The ``GW`` self-energy 

Anoop Chandran's avatar
Anoop Chandran committed
108 109
.. math:: \displaystyle\Sigma^{\mathrm{xc}}(\mathbf{r},\mathbf{r}';\omega)=\frac{i}{2\pi}\int_{-\infty}^\infty G(\mathbf{r},\mathbf{r}';\omega+\omega')\,W(\mathbf{r},\mathbf{r}';\omega')e^{i\eta\omega'}\,d\omega'\,.
 :label: selfene 
110 111 112

can be understood as a scattering potential that contains the exact exchange potential and correlation effects through the inclusion of ''W'', the dynamically screened interaction, which incorporates the screening of the many-electron system into an effective dynamical potential, obtained from the dielectric function :math:`{\varepsilon}` through

Anoop Chandran's avatar
Anoop Chandran committed
113 114
.. math:: 
  \displaystyle W(\mathbf{r},\mathbf{r}';\omega)=\int \varepsilon^{-1}(\mathbf{r},\mathbf{r}'';\omega) v(\mathbf{r}'',\mathbf{r}')\,d^3 r''\,.
115 116 117 118 119

This integral equation turns into a matrix equation 

:math:`{\displaystyle W_{\mu\nu}(\mathbf{k},\omega)=\sum_\eta \varepsilon^{-1}_{\mu\eta}(\mathbf{k},\omega)v_{\eta\nu}(\mathbf{k})}` 

anoop chandran's avatar
anoop chandran committed
120
if the quantities  :math:`{W}`, :math:`{\varepsilon}`, and :math:`{v}` ; are represented in the :ref:`mbp`, which thus has to be converged properly. The dielectric function, in turn, describes the change of the internal potential through screening processes and is related to the polarization matrix by :math:`{\varepsilon(\mathbf{k},\omega)=1-P(\mathbf{k},\omega)v(\mathbf{k})}` in matrix notation. The polarization function is one of the main quantities in the ``GW`` scheme. Its evaluation is described in the section :ref:`polar`. 
121

122
The self-energy can be written as the sum of two terms, the first of which is the exact non-local exchange potential of Hartree-Fock theory, the remainder can be interpreted as a correlation self-energy and has the mathematical form of the equation :eq:`selfene` with :math:`{W(\omega)}` replaced by :math:`{W^\mathrm{c}(\omega)=W(\omega)-v}`. The frequency integration is carried out analytically for the exchange part (by summing over the residues). The correlation part is more complex to evaluate because of the frequency dependence of the interaction. (Fast electrons experience a different potential than slow electrons.)
123 124 125 126 127

There are several ways to represent the self-energy as a function of frequency. The default method is ``analytic continuation``, in which the screened interaction and the self-energy are evaluated on a mesh of purely imaginary frequencies. The self-energy is then analytically continued to the complete complex frequency plane (:math:`{\Sigma^\mathrm{xc}(i\omega)\rightarrow\Sigma^\mathrm{xc}(z)}`, :math:`{\omega\in\cal{R}}`, :math:`{z\in\cal{C}}`). This has several advantages over the usage of the real frequency axis. First, :math:`{W(\omega)}` is a hermitian (or real-symmetric) matrix if :math:`{\omega}` is purely imaginary. Second, ``W`` and :math:`{\Sigma^{\mathrm{xc}}}` show a lot of structure along the real axis, whereas they are much smoother on the imaginary axis, thereby making it easier to sample and interpolate these functions. Third, after the analytic continuation the self-energy is known, in principle, as an analytic function on the complete complex plane. And fourth, the method requires only few parameters and is, therefore, easy to handle. The main disadvantage lies is the badly controlled extrapolation of the Pade approximants, which can sometimes produce "outlier values", with a potential adverse effect on the accuracy and reliability of the method. Therefore, there is a more sophisticated but also more complex method called ``contour integration``, in which the frequency convolution is performed explicitly, yielding the self-energy directly for selected frequencies on the real axis. In this method, we also mostly integrate along the imaginary frequency axis.

MESH (SENERGY)
--------------
Anoop Chandran's avatar
Anoop Chandran committed
128
All methods employ a mesh of purely imaginary frequencies, which extends from 0 to some maximal :math:`{i\omega_\mathrm{max}}`. The number of mesh points :math:`{N}` and the maximal frequency must be provided as parameters, for example ``MESH 10 10.0``, which is the default. The mesh is defined by :math:`{i\omega_n=i\omega_\mathrm{max}f_n/f_N}` with :math:`{f_n=\{(N-1)/[0.9(n-1)]-1\}^{-1}}`, :math:`{n=1,2,...}`. It is fine for small :math:`{\omega}`, where the quantities have a lot of structure, and coarse for large :math:`{\omega}`. Sometimes it is helpful to make the mesh even finer for small :math:`{\omega}`. This is possible by specifying, for example, ``10+3``, which would yield three, two, and one extra equidistant frequencies in the ranges [:math:`{\omega_1,\omega_2}`], [:math:`{\omega_2,\omega_3}`], and [:math:`{\omega_3,\omega_4}`], respectively. If the second argument is defined negative (:math:`{-\omega_\mathrm{max}}`), then :math:`{f_n=\{N/(n-1)-1\}^{-1}}`. The latter definition is rarely used. One can also employ a user-defined mesh provided in a file (one frequency per line, comments ``#...`` are allowed).
129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144

+----------+--------------------+--------------------------------------------------------------------------------------------------+
| Examples | ``MESH 12 15.0``   | Use a mesh containing twelve frequencies for [0,i15] htr                                         |
+----------+--------------------+--------------------------------------------------------------------------------------------------+
|          | ``MESH 12+2 15.0`` | | Add points at low frequencies, two (one) between :math:`{\omega_1}` and :math:`{\omega_2}`     |
|          |                    | | (:math:`{\omega_2}`  and :math:`{\omega_3}` )                                                  |
+----------+--------------------+--------------------------------------------------------------------------------------------------+
|          | ``MESH 12 -15.0``  | Use alternative mesh definition.                                                                 |
+----------+--------------------+--------------------------------------------------------------------------------------------------+
|          | ``MESH mesh.dat``  | Read frequency mesh from file "mesh.dat"                                                         |
+----------+--------------------+--------------------------------------------------------------------------------------------------+

CONTINUE (SENERGY)
-------------------
The keyword ``CONTINUE`` in the section ``SENERGY`` chooses the analytic continuation method. It can have optional parameters. If given without parameters (or if not specified at all), Pade approximants are used. An integer number, such as ``CONTINUE 2``, lets Spex perform a fit to an n-pole function (here, n=2) with the Newton method. The latter approach is somewhat obsolete by now and recommended only for test calculations. The argument can have additional flags +c*. Any combination is possible. They are explained in the examples.

Anoop Chandran's avatar
Anoop Chandran committed
145 146 147 148 149 150 151 152 153 154 155 156 157
+----------+-----------------+-----------------------------------------------------------------------------------------+
| Examples | ``CONTINUE``    | Use Pade approximants (Default).                                                        |
+----------+-----------------+-----------------------------------------------------------------------------------------+
|          | ``CONTINUE 2``  | Fit to the two-pole function :math:`{a_1/(\omega-b_1)+a_2/(\omega-b_2)}`                |
+----------+-----------------+-----------------------------------------------------------------------------------------+
|          | ``CONTINUE 2+`` | Include a constant in the fit function :math:`{a_1/(\omega-b_1)+a_2/(\omega-b_2)+c}`    |
+----------+-----------------+-----------------------------------------------------------------------------------------+
|          | ``CONTINUE 2c`` | | Take constraints (continuity of value and gradient at :math:`{\omega=0}`)             |
|          |                 | | into account when fitting                                                             |
+----------+-----------------+-----------------------------------------------------------------------------------------+
|          | ``CONTINUE 2*`` | | Allow parameters :math:`{b_i}` with positive imaginary parts                          |
|          |                 | | (should be negative) to contribute. (Default with Pade method.)                       |
+----------+-----------------+-----------------------------------------------------------------------------------------+
158 159 160 161 162 163 164 165

The second method is ``contour integration``, in which the frequency integration is performed explicitly, however not along the real frequency axis but on a deformed integration contour that avoids the real frequency axis as well as possible. This integration contour starts from :math:`{-\infty}`, describes an infinite quarter circle to :math:`{-i\infty}`, then runs along the imaginary frequency axis to :math:`{i\infty}`, and finishes, again with an infinite quarter circle, to :math:`{\infty}`. The two quarter circles do not contribute to the integral (because the integrand behaves as :math:`{\propto \omega^{-2}}`). Furthermore, depending on the frequency argument :math:`{\omega}` of the self-energy, one has to add a few residues coming from the poles of the Green function in the interval [:math:`{0,\omega-\epsilon_\mathrm{F}}`] if :math:`{\omega>\epsilon_\mathrm{F}}` and [:math:`{\epsilon_\mathrm{F}-\omega,0}`] otherwise, which requires the correlation screened interaction :math:`{W^\mathrm{c}(\omega)}` to be evaluated on this interval of the real axis. As a consequence, the calculations are more demanding in terms of computational complexity and cost (time and memory). Also, contour integration requires additional input parameters and is therefore somewhat more difficult to apply. However, the results are more accurate. In particular, they are not affected by the "ill-definedness" of the analytic continuation. 

CONTOUR (SENERGY)
-----------------
The corresponding keyword is called ``CONTOUR`` and belongs to the section ``SENERGY``. Obviously, ``CONTOUR`` and ``CONTINUE`` must not be given at the same time. The keyword ``CONTOUR`` expects two arguments. The first defines the frequencies :math:`{\omega}`, for which the self-energy :math:`{\Sigma^\mathrm{xc}(\omega)}` is to be evaluated. At least, two frequencies are needed to approximate the self-energy as a linear function in :math:`{\omega}` and, thus, to calculate the ''linearized'' solution of the quasiparticle equation (see above). For this, a single value suffices (example ``0.01``), with which the self-energy for a state :math:`{\mathbf{k}n}` is evaluated at two frequencies (:math:`{\epsilon_{\mathbf{k}n}-0.01}` and :math:`{\epsilon_{\mathbf{k}n}+0.01}`). The more accurate ''direct'' solution is only available if we specify a range of frequencies for the self-energy instead of a single number. This is possible by an argument such as :math:`{-0.1:0.15,0.01}`. Here, the range of values is relative to :math:`{\epsilon_{\mathbf{k}n}}`. Note that the range is flipped (to :math:`{-0.15:0.1,0.01}` in the example) for occupied states :math:`{\mathbf{k}n}` to reflect the fact that occupied and unoccupied states tend to shift in opposite directions by the renormalization. One can also specify an absolute frequency mesh by [:math:`{...}`], i.e., relative to the Fermi energy. This is mandatory for ``FULL`` calculations. It is sometimes a bit inconvenient to determine suitable values for the upper and lower bound of [:math:`{...}`]. 
Therefore, Spex allows the usage of wildcards for one of the boundaries or both (see below). The second argument to ``CONTOUR`` gives the increment of the (equidistant) real-frequency mesh for :math:`{W(\omega')}`. The lower and upper boundaries of this mesh are predetermined already by the first argument. As a third method, Spex also allows to omit the second argument altogether. Then, it uses a ''hybrid'' method where the screened interaction is analytically continued from the imaginary (where it has to be known for the integral along this axis, see above) to the real axis, thereby obviating the need of calculating and storing ''W'' on a real-frequency mesh. The disadvantage is that the badly controlled Pade extrapolation introduces an element of randomness (also see keyword ``SMOOTH`` below). Our experience so far is that the ''hybrid'' method is in-between the two other methods in terms of both computational cost and numerical accuracy.

Anoop Chandran's avatar
Anoop Chandran committed
166 167 168 169 170 171 172 173 174 175 176 177 178 179
+----------+------------------------------------+--------------------------------------------------------------------------------------------------------------------+
| Examples | ``CONTOUR 0.01 0.005``             | | Use contour integration to obtain the two                                                                        |
|          |                                    | | values :math:`{\Sigma^\mathrm{xc}(\epsilon\pm 0.01)}`, giving :math:`{\Sigma^\mathrm{xc}}` as a linear           |
|          |                                    | | function.                                                                                                        |
+----------+------------------------------------+--------------------------------------------------------------------------------------------------------------------+
|          | ``CONTOUR {-0.1:0.15,0.01} 0.005`` | | Calculate :math:`{\Sigma^\mathrm{xc}(\omega)}` on a frequency mesh relative to                                   |
|          |                                    | | the KS energy :math:`{\epsilon}`.                                                                                |
+----------+------------------------------------+--------------------------------------------------------------------------------------------------------------------+
|          | ``CONTOUR [{*:*,0.01}] 0.005``     | | Use an absolute frequency mesh                                                                                   |
|          |                                    | | (relative to the Fermi energy) instead.                                                                          |
|          |                                    | | Wildcards are used for the upper and lower bounds.                                                               |
+----------+------------------------------------+--------------------------------------------------------------------------------------------------------------------+
|          | ``CONTOUR [{*:*,0.01}]``           | Use ``hybrid`` method.                                                                                             |
+----------+------------------------------------+--------------------------------------------------------------------------------------------------------------------+
180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204

``FREQINT`` (``SENERGY``)
(*) Independently of whether :math:`{\Sigma^\mathrm{xc}(i\omega_n)}` (``CONTINUE``) or :math:`{\Sigma^\mathrm{xc}(\omega_n)}` (``CONTOUR``) is evaluated, an important step in the calculation of the self-energy is to perform the frequency convolution :math:`{\int_{-\infty}^\infty G(z+i\omega')W(i\omega')d\omega'}` with :math:`{z=i\omega}` or :math:`{z=\omega}`. For this frequency integration, we interpolate ``W`` and then perform the convolution with the Green function analytically. The keyword ``FREQINT`` determines how the interpolation should be done. It can take two values, ``SPLINE`` and ``PADE`` for spline [after the transformation :math:`{\omega\rightarrow \omega/(1+\omega)}`] and Pade interpolation. The default is ``SPLINE``. In the case of ``GT`` calculations, there is a similar frequency integration with the ``T`` matrix replacing ``W``. There, the default is ``PADE``.

+----------+--------------------+---------------------------------------------------------------------+
| Examples | ``FREQINT SPLINE`` | | Use spline interpolation for ``W`` (or ``T``) in the frequency    | 
|          |                    | | convolution :math:`{G\cdot W}` (:math:`{G\cdot T}`).              |
+----------+--------------------+---------------------------------------------------------------------+
|          | ``FREQINT PADE``   | Use Pade interpolation.                                             |
+----------+--------------------+---------------------------------------------------------------------+


SMOOTH (SENERGY)
-----------------
(*) We have already mentioned that the Pade approximation can lead to spurious features in the extrapolated or interpolated quantity, e.g., the self-energy or the screened interaction (also see ``FREQINT``), if one of the Pade poles happen to lie close to the real (or imaginary) frequency axis. To avoid such unphysical results, we can make use of an averaging procedure where, for each set of values, :math:`{\{\Sigma^\mathrm{xc}(i\omega_n)\}}` or :math:`{\{W(i\omega_n)\}}`, we evaluate a large number of Pade approximants with randomly shifted frequency points according to :math:`{\omega_n\rightarrow\omega_n(1+10^{-7}r_n)}` with random numbers :math:`{r\in[-0.5,0.5]}` and average over them. This simple but effective way to smoothen the functions is activated with the keyword ``SMOOTH`` in section ``SENERGY``. It can have up to two arguments, giving the number of Pade approximants to average over, the first for the self-energy, the second for the screened interaction or the ``T`` matrix in the case of ``GT`` calculations (``FREQINT PADE``). Smoothening is usually unnecessary for ``GW`` calculations but is helpful in the case of the ``GT`` approach. By default, no smoothening is applied. Note that this feature leads to a small degree of randomness in the results.

+----------+--------------------+----------------------------------------------------------------------+
| Examples | ``SMOOTH 500``     | Average over 500 Pade approximants to smoothen the self-energy.      |
+----------+--------------------+----------------------------------------------------------------------+
|          | ``SMOOTH 500 250`` | | In addition, average over 250 approximants to                      |
|          |                    | | smoothen ``W`` (or the ``T`` matrix). (Requires ``FREQINT PADE``.) |
+----------+--------------------+----------------------------------------------------------------------+

NOZERO (SENERGY)
----------------
anoop chandran's avatar
anoop chandran committed
205
Both the exchange (HF) and the correlation self-energy contain terms of the form :math:`{\langle...\rangle\langle...\rangle I(\mathbf{k})}` with :math:`{I=v}` and :math:`{I=W}`, respectively. The quantities :math:`{\langle...\rangle}` are the projections discussed in the section :ref:`mbp` and behave as :math:`{\propto k}` in the long-wavelength limit :math:`{k\rightarrow 0}`. The prefactor is obtained from :math:`{k.p}` perturbation theory. Multiplying with :math:`{I\propto k^{-2}}` gives rise to zero-order terms involving that prefactor. These zero-order terms (which only appear at the :math:`{\Gamma}`; point) can improve the k-point convergence. However, in the case of systems with small band gaps, the zero-order terms can become unnaturally large (because the integrand is strongly varying in the neighborhood of k=0 in these systems), impeding a favourable convergence with respect to the k-point sampling. Therefore, the keyword ``NOZERO`` in section ``SENERGY`` allows the zero-order terms to be neglected. They are included by default.
206 207 208

ALIGNVXC (SENERGY)
------------------
209
(*) The equation :eq:`qpeq` depends explicitly on the mean-field starting point through the eigensolutions :math:`{\{\phi_{\mathbf{k}n}\}}`. This dependence is more obvious in the equation :eq:`qppert` quasiparticle equation, which contains the exchange-correlation potential explicitly. Thus, a constant shift :math:`{v^\mathrm{xc}\rightarrow v^\mathrm{xc}+\Delta}` will not only shift the quasiparticle energies as a whole (as it would the KS energies) but also individually so that energy differences (e.g., the quasiparticle band gap) can depend on this constant shift. (Again, this is different from the KS gap, which would not be affected.) The underlying reason is that quasiparticle energies represent total-energy differences (between the ``N`` and the ``N``:math:`{\pm}` 1 particle system) and are thus defined as absolute energies, which depend individually on the "energy zero" set by :math:`{v^\mathrm{xc}}`. One can utilize this dependence to simulate the self-consistency condition that the input and output ionization potentials (valence-band maximum) be identical; in other words, the ionization potential should not change by the quasiparticle renormalization. The keyword ``ALIGNVXC`` in section ``SENERGY`` enforces this condition. To this end, the valence-band maximum should be included in the job definition. (Spex uses the highest occupied one among the states defined after ``JOB`` for the correction.) One can also specify the shift explicitly as a real-valued argument after ``ALIGNVXC``.
210 211 212

+----------+--------------------+---------------------------------------------------------------------------------+
| Examples | ``ALIGNVXC``       | | Align exchange-correlation potential in such a way that the                   |
Anoop Chandran's avatar
Anoop Chandran committed
213 214
|          |                    | | ionization potential remains unchanged by the quasiparticle                   |
|          |                    | | correction.                                                                   |
215
+----------+--------------------+---------------------------------------------------------------------------------+
Anoop Chandran's avatar
Anoop Chandran committed
216 217
|          | ``ALIGNVXC 0.2eV`` | | Apply a constant positive shift of 0.2 eV to the                              |
|          |                    | | exchange-correlation potential.                                               |
218 219 220 221 222
+----------+--------------------+---------------------------------------------------------------------------------+


VXC (SENERGY)
--------------
223
(*) The matrix elements of the exchange-correlation potential are needed in the solution of the equation :eq:`qppert`. By default, these matrix elements are taken from the input data provided by the DFT code (e.g., in the file "vxcfull" written by Fleur). Alternatively, Spex can calculate the matrix using the potentials from the input data. (This is required for PBE0.) For that, the keyword ``VXC`` in section ``SENERGY`` can take the arguments ``READ`` and ``CALC``.
224 225 226 227 228 229 230 231 232 233

+----------+--------------+-----------------------------------------------------------------+
| Examples | ``VXC READ`` | Read :math:`{v^\mathrm{xc}}` expectation values from harddisc.  |
+----------+--------------+-----------------------------------------------------------------+
|          | ``VXC CALC`` | | Calculate :math:`{v^\mathrm{xc}}` expectation values          |
|          |              | | using the xc potential defined in stars and lattice harmonics.|
+----------+--------------+-----------------------------------------------------------------+

RESTART
---------
234
Spex can reuse data from a previous ``GW`` run that has finished successfully, crashed, or has been stopped by the user. A ``GW`` calculation consists mainly of a loop over the irreducible k points. For each k point, Spex (a) calculates the matrix ``W``(``'k``') and (b) updates the self-energy matrix (or expectation values) :math:`{\Sigma^{xc}}` with the contribution of the current k point (and its symmetry-equivalent k points). After completion of step (b), the current self-energy is always written to the (binary) files "spex.sigx" and "spex.sigc". If the ``RESTART`` option is specified (independently of its argument), Spex also writes the matrix ``W(k)`` (in addition to some other data) to the (HDF5) file "spex.cor" unless it is already present in that file. If it is present, the corresponding data is read instead of being calculated. In this way, the keyword ``RESTART`` enables reusage of the calculated ``W(k)`` from a previous run. The matrix ``W(k)`` does not depend on the k points and band indices defined after ``JOB``. So, these parameters can be changed before a run with ``RESTART``, in which the ``W`` data is then reused. For example, band structures can be calculated efficiently in this way (see below). Especially for long calculations, it is recommended to use the ``RESTART`` option. Spex can also restart a calculation using self-energy data contained in "spex.sigx" and "spex.sigc". To this end, an argument is added: ``RESTART 2``. Spex then starts with the k point, at which the calculation was interrupted before. In contrast to "spex.cor", the files "spex.sigx" and "spex.sigc" do depend on the job definition, which must therefore ``not`` be changed before a run with ``RESTART 2``. However, there are few parameters (see below) that may be changed before a rerun with ``RESTART 2``. These concern details of solving the quasiparticle equation, which follows after completion of the self-energy calculation. The following logical table gives an overview.
235

Anoop Chandran's avatar
Anoop Chandran committed
236 237 238 239 240 241 242 243 244
+---------------+--------------+-----------------+
|               | ``spex.cor`` | ``spex.sigx/c`` |
+===============+==============+=================+
| --            | --           | write           |
+---------------+--------------+-----------------+
| ``RESTART``   | read-write   | write           |
+---------------+--------------+-----------------+
| ``RESTART 2`` | read-write   | read-write      |
+---------------+--------------+-----------------+
245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276

The different rules for "spex.cor" and "spex.sigx/c" are motivated by the facts that (a) the file "spex.cor" is much bigger than "spex.sigx/c" (so, writing of "spex.cor" to harddisc should not be the default), (b) the files "spex.sigx/c" include the updated self-energy (requiring more computation than for ``W``, thus representing "more valuable" data).

There are other (binary) files that are written during a program run and that may be reused later. The ones relevant for ``GW`` (same rules as for "spex.cor") are

* ``spex.mb``: contains MT part of product basis,
* ``spex.ccou``: contains ``contracted`` screened interaction (i.e., summed over ``'k``'); this contraction is needed for the self-energy core contribution (``CORES``), ``COSX``, and ``IBC``,
* ``spex.core``: contains core contribution to ``W`` (keyword ``CORES``).

The ``RESTART`` option can be exploited to customize the calculations. For example, it is possible to perform a self-consistent QS ``GW`` while keeping ``W`` fixed to the LDA level throughout the iterations. (The screened interaction is then always read from "spex.cor" and the MT product basis from "spex.mb".) As another example, when ``CORES`` is used, the MT product basis additionally contains products of core states with LAPW basis functions. To avoid that, one can run a calculation without ``CORES`` first (which can be stopped just after the product basis is written to "spex.mb"), followed by a calculation with ``RESTART``. The product basis is then read from "spex.mb" (excluding the core-basis products) instead of being constructed anew.

As already mentioned above, when preliminary data is read from one of the restart files, changing input parameters might conflict with the data in the files. Spex tries to detect such conflicts. In case of conflict, Spex either stops the calculation ("spex.cor") or recalculates the data and overwrites the files ("spex.sigx/c"). It is, however, not guaranteed that Spex can detect all possible conflicts. So, care has to be taken if parameters are changed in calculations with ``RESTART``.

The following is a (incomplete) list of parameters that may be changed for a calculation with ``RESTART 2``, in which the files "spex.sigx/c" are read: ``ALIGNVXC``, ``VXC``, ``SPECTRAL``, ``SMOOTH``, ``CONTINUE``, ``WRITE``, all of section ``WANNIER`` (e.g., for Wannier interpolation).
In the case of ``RESTART 1`` (or ``RESTART``) (i.e, when "spex.cor" is to be read), one may change most parameters except: ``MESH``, 2nd argument of ``CONTOUR``, ``JOB`` types (most cases). Many changes of parameters will be overridden with values from the restart files (e.g., parameters in the section ``MBASIS`` by data from the file "spex.mb"). Other changed parameters might affect only the self-energy but not the ``W``, for example, ``NBAND``. (The latter allows to check the band convergence of ``W`` and :math:`{\Sigma^{xc}}`, separately.) Again, this can be used efficiently to customize a calculation.

+----------+---------------+-------------------------------------------------------------------------+
| Examples | ``RESTART``   | | Spex tries to read the screened interaction ``W``                     |
|          |               | | (and other data) from the file "spex.cor".                            |
|          |               | | If the required data does not exist, the calculation proceeds         | 
|          |               | | normally and appends ``W`` to the file (reusable in a later restart). |
+----------+---------------+-------------------------------------------------------------------------+
|          | ``RESTART 1`` | | Same as ``RESTART``.                                                  |
+----------+---------------+-------------------------------------------------------------------------+
|          | ``RESTART 2`` | | Implies ``RESTART``. Spex reads the self-energy from the              |
|          |               | | files "spex.sigx" and "spex.sigc" if they exist. If not, the          |
|          |               | | calculation proceeds normally.                                        |
+----------+---------------+-------------------------------------------------------------------------+


GW band structures
-------------------
277 278
In this section, three ways of calculating ``GW`` band structures are discussed.

anoop chandran's avatar
anoop chandran committed
279
* Using the :ref:`kpath` label (single Spex run)
280
* With :ref:`kptadd` additional :math:`q` points (multiple Spex run)
281
* Wannier interpolation (single --; but long --; Spex run).
282 283 284

The calculation of a ``GW`` band structure is not as straightforward as in the case of KS-DFT, where the local nature of the effective potential (e.g., LDA or GGA) allows the KS Hamiltonian to be diagonalized independently for each q point along a q-point path. The ``GW`` self-energy, on the other hand, is non-local. As a consequence, its evaluation involves a convolution in reciprocal space :math:`{\Sigma^\mathrm{xc}(\mathbf{q})=i\sum_\mathbf{q}G(\mathbf{q+k})W(-\mathbf{k})}` (in simplified notation), requiring summations over the full Brillouin zone for any arbitrarily chosen :math:`q` point. So, in addition to :math:`q`, one would need to include all shifted points :math:`q+k`, too, where :math:`k` stands for the k points defined in ``BZ``.

anoop chandran's avatar
anoop chandran committed
285 286 287
If we restrict ourselves to the set of k points defined in ``BZ``, the band structure along a certain high-symmetry line (e.g., :math:`{\Gamma-X}`) can consist only of the few k points that happen to lie on this line. Sometimes this is already sufficient. For example, if the ``GW`` renormalization affects the band dispersion only little, then a few points along the high-symmetry line are enough to shift/modify the KS bands accordingly and produce, in this way, a quasiparticle band structure. Such a calculation can be performed in a single Spex run.

.. _kpath:
288 289 290

KPTPATH
--------
291
As an example, we want to plot a band structure for the path from L over :math:`{\Gamma}`; to :math:`X` for our Si example. In principle, we would have to identify all k-point indices along this path and set the job definition accordingly, but Spex can do this for you. The k-point path can be defined with a line ``KPTPATH (L,1,X)``. In the :ref:`job` job definition, one can then use the special label ``PATH`` to address the corresponding list of k points, e.g., ``JOB GW PATH:(1-10)``. Spex will automatically choose the k points that lie on the path defined by ``KPTPATH`` and calculate the ``GW`` quasiparticle energies. As usual, the results are written to the Spex :ref:`spex.out` file. The data can be extracted from the output file with the spex.extr utility: ``spex.extr g -b spex.out > bandstr`` (assuming that the output has been piped into the file "spex.out"). The file "bandstr" then contains a plottable list of xy values (momentum/energy) for each quasiparticle band. However, in most cases the band structure will not be smooth enough because of the small number of k points. One solution is, as already mentioned, to modify a KS band structure. Another possibility is to interpolate the energies with splines; the spex.extr utility has this capability. Finally, one could simply use much denser k-point sets, but this would entail very expensive calculations. 
292 293 294 295 296 297 298 299 300 301

+-----------+------------------------+------------------------------------------------------------+
| Examples  | ``KPTPATH (L,1,X)``    | | Define k-point path from L over the                      | 
|           |                        | | :math:`\Gamma`; point (k index is always 1) to X.        |
|           |                        | | The labels L and X must be defined with [[#KPT|``KPT``]] |
+-----------+------------------------+------------------------------------------------------------+
|           | ``JOB GW PATH:(1-10)`` | | Run ``GW`` calculation for the first ten bands at all    |
|           |                        | | k points defined by ``KPTPATH``.                         |
+-----------+------------------------+------------------------------------------------------------+

anoop chandran's avatar
anoop chandran committed
302
.. _kptadd:
303 304 305

KPT +=...
---------
306
This section explains an extension to the keyword :ref:`kpt` (already described before), which will later enable the calculation of smooth band structures. The extension allows adding arbitrary q points, one at a time, allowing one to investigate the quasiparticle spectrum at momenta that are not element of the original k-point set (defined by ``BZ``). For example, in Si the conduction-band minimum is not at a high-symmetry k point but at around 3/4 along the line :math:`{\Gamma - X}`. This particular q point can be defined using the special k label "+" by ``+=[0,0,0.75]`` (alternatively, ``+=3/8*(1,1,0)`` in internal coordinates) after the keyword :ref:`kpt`. As explained above, each additional point :math:`q` must be accompanied with all shifted points :math:`q+k`. So, before running Spex, we must let the DFT code generate the wavefunctions and energies at the shifted k-point set ``'q+k``'. This is done in the usual way by creating the k-point file :ref:`wrtkpt` or ``-w`` flag) and running the DFT code. (In the case of Fleur, the shifted k points are appended to the list in the file "kpts".) The additional q point can be addressed in the job definition with the special ``+`` label, e.g., ``JOB GW 1:(1-5) +:(1-5)``, which will yield the bands 1-5 for the Γ point and the additional :math:`q`. The energy difference between the fourth state at Γ and the fifth state at :math:`q` yields the fundamental ``GW`` gap.
307 308 309 310 311 312 313 314 315 316 317


+----------+-------------------------+---------------------------------------------------------------------+
| Examples | ``KPT +=1/7*[1,0,0]``   | | Define special k point at 1/7 along the line :math:`{\Gamma--X}`  | 
|          |                         | | (here, the X point in x direction) of an fcc structure.           |
+----------+-------------------------+---------------------------------------------------------------------+
|          | ``KPT +=1/14*(0,1,1)``  | | The same in internal coordinates.                                 |
+----------+-------------------------+---------------------------------------------------------------------+
|          | ``JOB GW +:(1-10)``     | | Run ``GW`` calculation for the states 1-10 at the added q point.  |
+----------+-------------------------+---------------------------------------------------------------------+

318
The possibility of adding arbitrary q points enables the calculation of smooth band structures. To this end, a ``GW`` run (together with the generation of the eigenstates with the DFT code) has to be performed for each q point in a list of q points that make up a path in the Brillouin zone, e.g., from :math:`{\Gamma}`; to :math:`X`. This list is defined with the keyword ``KPTPATH`` as explained above. Fortunately, the screened interaction has to be calculated only once and can be reused for the other points. For this, the keyword ``RESTART`` should be given in the input file. Of course, we also need a job definition, such as ``JOB GW +:(1-10)``. Here, only the additional q point should be specified. (It would be difficult to extract the data for the band structure plot otherwise.) Now, running Spex with ``KPTPATH`` defined in the input file and :ref:`wrtkpt` (or with the option ``-w``) creates two files, containing the usual list of k points (Fleur: "kpts") and the list of q points (Fleur: "qpts"). For each of the q points, we would have to run, in this order, Spex, Fleur, and Spex again. To simplify this task, there is a shell script called "spex.band". This shell script performs all the necessary steps automatically (it uses the same environment variables as `selfc.sh` and produces, for each q point, one output file named ``spex_???.out`` (where ``???`` is a three-digit counting index, or more digits if ``???>999``). 
319 320 321

From these files the band-structure data is extracted with ``spex.extr g -b spex_???.out > bandstr``. The data is written to the file ``bandstr``. The band structure can then be plotted with xmgrace or gnuplot. If you extract the band-structure data, instead, with ``spex.extr g -b -c spex_??.out > bandstr``, you get an additional column, which contains the imaginary parts of the quasiparticle energies. These imaginary parts are proportional to the line width and inversely proportional to the excitation lifetime. The line widths can be plotted together with the band structure in gnuplot with ``plot "bandstr" using 1:2:(10*abs(3)) with points ps var``. You will see that the bands get wider the further they are away from the Fermi energy.

322
As a third alternative, we can use Wannier interpolation to interpolate between the few ``'k``' points of the original k mesh. The construction of Wannier orbitals is explained in a :ref:`wannier`. Here, we use a minimalistic definition for demonstration purposes. We have to modify and add some lines to ``spex.inp``:
323 324 325 326 327 328 329 330 331 332 333 334

.. code-block:: bash

  JOB GW IBZ:(1-4)
  SECTION WANNIER
    ORBITALS 1 4 (sp3)
    MAXIMIZE
    INTERPOL
  END
    
Please also remove the entry ``+=[0,0,0.75]`` from the ``KPT`` line. The first line lets SPEX calculate quasiparticle energies in the whole irreducible Brillouin zone (IBZ). (The Wannier interpolation can be understood as a back-and-forth Fourier transformation with a real-space truncation of matrix elements in-between. The Fourier transformation from momentum to real space involves the band energies in the whole BZ.) The other lines define a set of maximally localized Wannier functions (MLWFs) of bonding :math:`sp^3` hybrid orbitals. These four hybrid orbitals are generated from the four lowest valence bands (first two arguments after ``ORBITALS``). Running Spex will construct the MLWFs and use them to interpolate the band structure. The band structure data is written to the files "bands0" for the KS energies and "bands1" for the ``GW`` quasiparticle energies and can be plotted with xmgrace or gnuplot. The file "bands1" has one data column more than "bands0". This additional column contains the interpolated imaginary parts of the quasiparticle energies. You can plot the band structure together with the variable line thickness as described above.

335
Wannier interpolation can also be used in conjunction with the keyword :ref:`spectral`. The interpolated spectral function is written to the file "spectralw" or, if the system is spin-dependent, to the files "spectralw1" and "spectralw2" for spin up and spin down, respectively.
336

337 338 339

Beyond perturbative GW and QSGW
-------------------------------
340
One can also go beyond the perturbative solution of the equation :eq:`qpeq` and solve it by iterative diagonalization in the basis of the single-particle states. This requires the full self-energy matrix including off-diagonal elements to be calculated. The respective line in the input file would read
341 342 343 344 345 346 347 348 349 350
``JOB GW FULL 1:(1-10) X:(1-10) L:(1-10)`` giving the self-energy as 10x10 matrices at the Γ, X, and L points. (In principle, it is also possible to have a band definition like ``(1-5,9,10)``, which would yield a 7x7 matrix. Degenerate states, not included in the definition, are automatically included.) In ``FULL`` calculations, the Spex code uses irreducible representations (irreps) to speed up the calculation. As a result, the bands are grouped in terms of these irreps (called "blocks") in the output. For example, in the example below (for the X point) the block is composed of the bands 3, 4, 9, and 10. If a block contains only a single band or a single subgroup of degenerate states, the full solution is omitted because it would be identical to the perturbative (diagonal) solution. The full solutions are tabulated in the output::

  Bd        KS      olap        HF      olap        GW
   3   2.92306   0.99971   0.12683   0.99985   2.50496  -0.06006
   4   2.92306   0.99971   0.12683   0.99985   2.50496  -0.06006
   9  16.77136   0.99732  23.25660   0.99962  16.97051  -0.30294
  10  16.77136   0.99732  23.25660   0.99962  16.97051  -0.30294

``HF`` are the Hartree-Fock values (from diagonalization). They are ``'not``' ordered according to energy but related to the KS states with a condition of maximal overlap (also making sure that there is a one-to-one correspondence). The overlap is given on the left. The full ``GW`` energies are related to the KS states as well. This is due to the fact that the quasiparticle equation is non-linear in energy and must, therefore, be solved iteratively for each quasiparticle state. The iterations are started with the KS energy :math:`{\epsilon_{\mathbf{k}n}}` of that state, giving :math:`{H^\mathrm{KS}+\Sigma^\mathrm{xc}(\epsilon_{\mathbf{k}n})-v^\mathrm{xc}}` as the (complex) quasiparticle Hamiltonian. The diagonalization then yields a spectrum of states, of which the one with the largest overlap is picked for the next iteration. In the first few iterations, the off-diagonal elements are switched on adiabatically to alleviate a smooth convergence. The overlap of the final quasiparticle wave function with the original KS state is given, too. Although, this approach usually yields well-defined quasiparticle solutions, it cannot be ruled out that the iterative procedure, when started at two different energies, might result in the same quasiparticle energy. This can happen especially for high-lying states, which do not have a well-defined quasiparticle character anymore.

351
If the job definition contains ``FULL`` and IBZ, the full ``GW`` self-energy matrix is evaluated for the whole IBZ, which enables self-consistent calculations in the framework of the ``quasiparticle self-consistent GW`` (QSGW) approach. In this approach, one creates a mean-field system from the ``GW`` self-energy whose single-particle energies are as close as possible to the quasiparticle energies. This mean-field system is subsequently solved to self-consistency in a DFT code. The resulting solution can then serve as a starting point for a new one-shot ``GW`` calculation, which constitutes the second iteration and so on until the quasiparticle energies are converged. The construction of the mean-field system is, to some extent, arbitrary. We use the following definition, which is slightly modified from the original work [PRL 93, 126406]:
352

Anoop Chandran's avatar
Anoop Chandran committed
353 354
.. math::
  \displaystyle A_{\mathbf{k}nn}=Z_{\mathbf{k}n}^{-1} \langle \phi_{\mathbf{k}n} | \Sigma^\mathrm{xc}(\epsilon_{\mathbf{k}n}) | \phi_{\mathbf{k}n} \rangle
355 356 357

for diagonal elements and

Anoop Chandran's avatar
Anoop Chandran committed
358 359
.. math:: 
  \displaystyle A_{\mathbf{k}nn'}=\langle \phi_{\mathbf{k}n} | \Sigma^\mathrm{xc}(\epsilon_{\mathbf{k}n})+\Sigma^\mathrm{xc}(\epsilon_{\mathbf{k}n'}) | \phi_{\mathbf{k}n'} \rangle
360

Anoop Chandran's avatar
Anoop Chandran committed
361
for off-diagonal elements. The *hermitianized* QSGW operator is then obtained from :math:`{\Sigma^\mathrm{xc,H}=(A+A^\dagger)/2}`. The difference to the original definition is the inclusion of the renormalization factor to better reproduce the ``GW`` quasiparticle energies. The *hermitianized* matrix, or rather the difference :math:`{\Sigma^{\mathrm{xc,H}}-v^\mathrm{xc}}`, is written to the file "spex.qsgw", which is later read by the DFT code. In Fleur, the following steps are required:
362

Anoop Chandran's avatar
Anoop Chandran committed
363
* ``rm fleur.qsgw`` - remove any previous version of the *hermitianized* matrix.
364 365 366 367 368 369 370
* ``rm broyd*`` - remove Broyden information about previous iterations because this information is inconsistent with the new Hamiltonian (the SCF calculation does not converge otherwise).
* Set ``gw=3`` in the Fleur input file.
* Run Fleur.
    Fleur translates the file "spex.qsgw" (in basis of eigenstates) to a file "fleur.qsgw" (in LAPW basis). Then, a SCF run is performed where instead of the KS Hamiltonian :math:`{H^\mathrm{KS}}` the Hamiltonian :math:`{H^\mathrm{KS}+(\Sigma^{\mathrm{xc,H}}-v^\mathrm{xc})}` is employed. After the run finishes, the ``gw=2`` step has to be performed:
* Set ``gw=2`` in the Fleur input file.
* Run Fleur.

371
Apart from the usual output data for a ``GW`` calculation, Fleur writes, in addition, the file "qsgw", which contains the matrix elements of :math:`{\Sigma^{\mathrm{xc,H}}-v^\mathrm{xc}}` in the basis of the new eigenstates. The file "qsgw" is later read by Spex to subtract correctly the double counting. Of course, doing these steps manually is tedious and also error-prone. Therefore, we provide the shell script ``spex.selfc``, which performs the steps needed for a self-consistent calculation automatically. For example, ``spex.selfc 5`` will run five iterations. The shell script assumes that Spex and Fleur are run with ``spex.x`` and ``fleur.x``, respectively. Environment variables can be used to change this:
372 373 374 375 376 377 378 379 380

* ``SPEX_EXEC`` - Spex executable,
* ``FLEUR_EXEC`` - Fleur executable,
* ``SPEX_QUEUE`` - Queue command for parallel execution of Spex (e.g., ``mpiexec -np 20``),
* ``FLEUR_QUEUE`` - Same for Fleur,
* ``QUEUE`` - Default queue command to be used for Spex and Fleur.

The job types ``HF``, ``PBE0``, ``SX``, and ``COSX`` also allow ``FULL`` in the definition, i.e., a full matrix is evaluated, enabling a self-consistent calculation in the same way as QSGW (see above). The file names used are the same: ``spex.qsgw``, ``fleur.qsgw``, ``qsgw``, even though it might actually be a HF calculation. The job ``GT`` (also ``GWT``) does not allow for self-consistency at the moment.

381 382 383 384

GW with MPI
-------------

385 386 387 388 389 390 391 392
RESTART...
----------

MPIBLK
---------

MPISYM
--------
393

anoop chandran's avatar
anoop chandran committed
394 395
.. _polar:

396 397
Polarization function
=====================
398 399
The polarization function gives the linear change in the electronic density of a non-interacting system with respect to changes in the effective potential. It is, thus, a fundamental quantity in the calculation of screening properties of a many-electron systems. For example, the dielectric function, instrumental in the calculation of spectroscopic quantities (e.g. EELS) and the screened interaction needed in ``GW``, is related to the polarization matrix through :math:`{\varepsilon(\mathbf{k},\omega)=1-P(\mathbf{k},\omega)v(\mathbf{k})}`, here given in matrix notation. The corresponding explicit formula for matrix elements of ``P`` in the mixed product basis is

Anoop Chandran's avatar
Anoop Chandran committed
400 401 402
.. math::
  \scriptstyle P_{\mu\nu}(\mathbf{k},\omega)=2\sum_{\mathbf{q}}^{\mathrm{BZ}}\sum_{n}^{\mathrm{occ}}\sum_{n'}^{\mathrm{unocc}}\langle M_{\mathbf{k}\mu} \phi_{\mathbf{q}n} | \phi_{\mathbf{k+q}n'} \rangle\langle \phi_{\mathbf{k+q}n'} | \phi_{\mathbf{q}n} M_{\mathbf{k}\nu} \rangle \cdot\left(\frac{1}{\omega+\epsilon_{\mathbf{q}n}-\epsilon_{\mathbf{q}+\mathbf{k}n'}+i\eta}-\frac{1}{\omega-\epsilon_{\mathbf{q}n}+\epsilon_{\mathbf{q}+\mathbf{k}n'}-i\eta}\right) =\int_{-\infty}^\infty \frac{S_{\mu\nu}(\mathbf{k},\omega')}{\omega-\omega'+i\eta\mathrm{sgn}(\omega')}d\omega'\,.
  :label: eqP
403 404 405

We have implicitly defined the spectral function ``S`` in the last equation, an explicit expression for which is basically given by the formula in the middle with the :math:`{1/(\omega...)}` replaced by :math:`{\delta(\omega...)}`. (Technically, the :math:`{M_{\mathbf{k}\mu}(\mathbf{r})}` form the eigenbasis of the Coulomb matrix, so they are linear combinations of the mixed product basis functions.)

406
The expression for equation :eq:`eqP` involves an infinite band summation over :math:`{n'}`. In practice, this summation is truncated by the number of bands (keyword `nbabd`, which thus becomes an important convergence parameter. The self-energy contains an infinite band summation as well.
407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428

In principle, the k summation is infinite, too: In an infinite crystal, there are infinitely many k points, and the k summation formally turns into a k integration. In practice, of course, there can only by a discreet sampling of the Brillouin zone. The tetrahedron method enables a geometrical interpolation between the explicit k points and, thus, an approximate k integration. Therefore, the tetrahedron method is the default and recommended method. However, there are two other implemented methods: Simple summation over the k-point mesh (see ``HILBERT NONE``) and the Gaussian method (see ``GAUSS``).

TETRAF (SUSCEP)
-----------------
(*) In rare cases, especially for very large k-point sets, the determination of the tetrahedron weights (Timing 'wghts') can become computationally expensive. This is because Spex calculates tetrahedron weights for all k points by default, which makes it possible to average over equivalent k points, thereby avoiding a (slight) symmetry breaking connected with the spatial form of the tetrahedra. (The tetrahedra are not unique!) One can disable this averaging by setting ``TETRAF`` in the section ``SUSCEP``. If set, tetrahedron weights are only calculated for the irreducible part of the BZ. This accelerates the calculation of the weights but introduces slight deviations due to symmetry breaking.

WGHTTHR (WFPROD)
-----------------
(*) In both tetrahedron and Gaussian method, integration weights are calculated to perform the k summation. To be more precise, an integration weight is calculated for each virtual transition, i.e., for each combination of band index pair (occ-nocc) and k point. One can reduce the number of terms by introducing a threshold value below which the respective weight is neglected. The corresponding keyword is ``WGHTTHR`` in the section ``SUSCEP``. The default value is :math:`{10^{-10}}`. It is usually not necessary to change this value in practice.

GAUSS
-------
(*) The Gaussian method is included mostly for testing. It does not only affect  the polarization function but also all other k summations (such as for the Hartree-Fock exchange potential and the determination of the Fermi energy). Therefore, ``GAUSS`` is a global keyword. It effectively replaces each single-particle eigenvalue by a Gaussian function with a certain width so that the density of states becomes a smooth function. In the calculation of the polarization function, one additionally needs a finite width for the Fermi edge. The keyword ``GAUSS`` needs the two width parameters as arguments given as real positive values. The advantage of the Gaussian method is its relative mathematical simplicity compared to the tetrahedron method and, in particular, that the Gaussian method cannot give rise to symmetry breaking. 

+---------+----------------------+---------------------------------------------------------+
| Example | ``GAUSS 0.001 0.01`` | | Use Gaussian k-integration method with                | 
|         |                      | | widths 0.001 and 0.01 htr. (Mostly used for testing.) |
+---------+----------------------+---------------------------------------------------------+

HILBERT (SUSCEP)
----------------
429
The most important keyword in the calculation of the polarization function is ``HILBERT``, which defines a (Hilbert) mesh for the frequency integration in equation :eq:`eqP`. (The old keyword ``FSPEC`` still works but is deprecated.) The Hilbert mesh, used in conjunction with the tetrahedron and the Gaussian method, extends from the lowest (roughly the band gap) to the highest virtual electron transition energy. (Note that the spectral function is symmetric :math:`{S(\omega)=S(-\omega)}`, which makes a mapping to :math:`{\int_0^\infty...}` possible.) The lower and upper bounds are, thus, predetermined by the input data. As the spectral function usually shows more variation at low energies (also, these energies are more important from a perturbation theory point of view), we employ an exponential mesh, which is dense at low and coarse at high energies. Two parameters are necessary to define the Hilbert mesh :math:`{\{w_i\}}`, for example, the first step size :math:`{\omega_2-\omega_1}` and the stretching factor :math:`{a=(\omega_{i+1}-\omega_i)/(\omega_i-\omega_{i-1})}`. These two parameters are accepted as real-valued arguments (example: ``HILBERT 0.01 1.04``). However, with this definition it is not straightforward to increase the density of the mesh without changing the exponential form of the mesh. Therefore, it is recommended to use a different definition, namely using an integer as first argument (without a period!) and a real number as second (example: ``HILBERT 30 40.0``; the second argument is always interpreted as real-valued, so ``HILBERT 30 40`` is equivalent). The first argument gives the number of mesh points between 0 and 5 htr and the second argument is the "accumulated" stretching factor at 5 htr, i.e., by what factor the step size at 5 htr has increased from :math:`{\omega_2-\omega_1}`. (The reason for defining an arbitrary but fixed energy of 5 htr is that modifying the energy range, e.g., by changing ``NBAND``, then leaves the form of the Hilbert mesh unchanged.) In this way, increasing the first argument makes the mesh denser but does not affect the exponential form of the mesh, which, in turn, is governed by the second argument. So, there are two possible definitions (distinguished by whether the first argument has a period or not). For convenience, Spex always writes the equivalent parameters of the other definition to the output. By default, Spex uses a Hilbert mesh defined by ``HILBERT 50 30.0`` for band-gap materials and ``HILBERT 150 50.0`` for metals, unless a spectral frequency mesh is defined (e.g., ``DIELEC {0:1,0.01}``), in which case Spex adjusts the Hilbert mesh to this frequency mesh. An idea of how well a given Hilbert mesh resolves the spectral function can be got by specifying ``WRITE INFO`` in the input file. Then, a file "spex.sf.nnn" (where nnn is a three-digit counting index) is written for each k point, and it contains the spectral function for the head element of ``P`` on the Hilbert mesh as plottable data. One can also define ``HILBERT NONE`` as a special option, which implements the k summation as simple sums over the k points without interpolation or broadening. ``HILBERT NONE`` is only available if the polarization function is to be calculated for purely imaginary frequencies (including zero).
430 431 432 433 434 435 436 437

+----------+------------------------+----------------------------------------------------------------------------------------+
| Examples | ``HILBERT NONE``       | Simple summation over k points.                                                        |
+----------+------------------------+----------------------------------------------------------------------------------------+
|          | ``HILBERT 50 30.0``    | | Use Hilbert mesh with fifty frequencies (between 0 and 5 htr)                        |
|          |                        | | and an accumulated stretching factor of 30 at 5 htr.                                 |
+----------+------------------------+----------------------------------------------------------------------------------------+
|          | ``HILBERT 0.01 1.05``  | | Use Hilbert mesh with a first step size of :math:`{\omega_2-\omega_1=}` 0.01 htr     | 
Anoop Chandran's avatar
Anoop Chandran committed
438 439
|          |                        | | and a stretching factor of :math:`{a=1.05}`.                                         |
|          |                        | | (First argument is real-valued.)                                                     |
440 441 442 443
+----------+------------------------+----------------------------------------------------------------------------------------+

MULTDIFF (SUSCEP)
-------------------
444
(*) In the limit :math:`{k\rightarrow 0}`, the projections in the numerator of equation :eq:`eqP` approach linearly to zero. However, when calculating the dielectric function, one has to multiply with :math:`{\sqrt{4\pi}/k}` (square root of Coulomb matrix) in this limit. So, the first order of :math:`{\langle e^{i\mathbf{kr}} \phi_{\mathbf{q}n} | \phi_{\mathbf{k+q}n'} \rangle}` (corresponding to :math:`{\mu=1}`) in :math:`k` becomes relevant. Using k·p perturbation theory, one can show that the linear term is proportional to :math:`{(\epsilon_{\mathbf{q}n'}-\epsilon_{\mathbf{q}n})^{-1}}`. This can lead to numerical problems if the two energies are very close to each other. Therefore, when treating the :math:`{\Gamma}`; point (k=0), Spex multiplies the linear term with this energy difference, resulting in smooth and non-divergent values, and takes the energy difference into account by replacing :math:`{S(\omega)\rightarrow S(\omega)/\omega}` in the equation :eq:`eqP` frequency integration, thereby avoiding the numerical difficulties. (As an alternative, the energy differences can also be incorporated into the integration weights, which is arguably even more stable numerically, see option ``INT`` below.) By default, Spex does that only for k=0. The behavior can be changed with the keyword ``MULTDIFF`` in the section ``SUSCEP``.
445 446 447 448 449 450 451 452 453

+-------------------+--------------------+------------------------------------------------------------------------------+
| Examples          | ``MULTDIFF OFF``   | Never separate (divergent) energy difference.                                |
+-------------------+--------------------+------------------------------------------------------------------------------+
|                   | ``MULTDIFF ON``    | Always separate energy difference (i.e., for all k points).                  |
+-------------------+--------------------+------------------------------------------------------------------------------+
|                   | ``MULTDIFF INT``   | | Use default behavior (separate for k=0, do not for k≠0)                 |
|                   |                    | | but stick energy difference into integration weights.a                     |
+-------------------+--------------------+------------------------------------------------------------------------------+
Anoop Chandran's avatar
Anoop Chandran committed
454 455
|                   | ``MULTDIFF INTON`` | | Always separate energy difference by sticking them into                    |
|                   |                    | | integration weights.                                                       |
456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473
+-------------------+--------------------+------------------------------------------------------------------------------+

PLASMA (SUSCEP)
---------------
(*) In the case of metals, the polarization function contains an additional term, the so-called Drude term, which gives rise to metallic screening (diverging static dielectric constant, short-range static ``W``). The Drude term stems from virtual intraband transitions across the Fermi surface. It can be formulated with the square of the plasma frequency, which in turn is evaluated by an integration over the Fermi surface. The Drude term can
be treated analytically and, as long as the Fermi surface is sufficiently big, it normally does not pose a numerical problem. However, a very small Fermi surface eventually leads to a very sharp "Drude peak" in the ``GW`` self-energy, impeding a straight-forward numerical solution of the non-linear quasiparticle equation. One could also say that, while the Drude term is actually treated correctly, it gets too much weight because of the coarseness of the k-point mesh. It is, therefore, sometimes helpful to modify the plasma frequency. This is possible with the keyword ``PLASMA``. Its argument replaces the plasma frequency calculated by the code. Setting ``PLASMA 0`` switches the Drude term off altogether. Of course, ``PLASMA 0`` would also disable metallic screening, which might be unphysical. Therefore, there is a special option, ``PLASMA METAL``, which scales the head element of :math:`{W(\mathbf{k},\omega)}` in the limit :math:`{k\rightarrow 0}` to enforce metallic screening. This latter option can be helpful, for example, in the case of semimetallic systems with a tiny Fermi surface.

+----------+------------------+----------------------------------------------------+
| Examples | ``PLASMA 1.5eV`` | Set plasma frequency manually to 1.5 eV.           |
+----------+------------------+----------------------------------------------------+
|          | ``PLASMA 0``     | Set plasma frequency to zero. Disables Drude term. |
+----------+------------------+----------------------------------------------------+
|          | ``PLASMA METAL`` | | Disable Drude term but enforce metallic          |
|          |                  | | screening by scaling the head element of ``W``.  |
+----------+------------------+----------------------------------------------------+

DISORDER (SUSCEP)
-------------------
474
(*) Mathematically, the parameter :math:`{\eta}` in :eq:`eqP` is a positive infinitesimal ensuring the correct time order of the response quantity. Spex effectively treats it as an infinitesimally small positive parameter. Sometimes, however, it can be useful to use a finite value for :math:`{\eta}`, e.g., to simulate disorder in a material. This is possible with the keyword ``DISORDER`` in the section ``SUSCEP``. Note that the keyword has rarely been used so far.
475

476 477 478
+---------+-------------------+----------------------------------------------------+
| Example | ``DISORDER 1000`` | Use a finite value :math:`{\eta=1/(2\cdot 1000)}`. |
+---------+-------------------+----------------------------------------------------+