@@ -9,17 +9,6 @@ This section discusses several settings that are common for all calculations. So

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, 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

...

...

@@ -66,6 +55,25 @@ There are only two keywords that must not be omitted from the input file. The fi

* - ``BZ 8 4 2``.

- Define a :math:`8\times 4\times 2` k-point sampling.

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, 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).

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 :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.

--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.

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.

...

...

@@ -77,14 +85,6 @@ This is an important keyword. It enables (a) continuing a calculation that has,

- 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 :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.

--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.

Although the Spex executable can have different names (e.g., "spex.inv", "spex.noinv"),

we assume that "spex" is the name of the executable in the following.

(This can be achieved by using the caller utility, see the file "INSTALL".)

(This can be achieved by using the caller utility, see :numref:`installation`.)

.. note:: Paragraphs discussing advanced options are preceded with (*), and the ones about obsolete, unmaintained, or experimental options are marked with (**). You can safely skip the paragraphs marked with (*) and (**) at first reading.

@@ -500,7 +500,26 @@ in this way, a quasiparticle band structure. Such a calculation can be performed

KPTPATH

--------

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 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 output 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.

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 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 output 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.

The keyword ``KPTPATH`` can also be used for the other two methods to calculate a band structure (see :numref:`KPTadd` and :numref:`INTERPOL_GW`).

In these methods, one is not restricted to the k points of the k set and can define k-point paths with arbitrary step sizes. To this end, an integer

argument can be specified at the end of the k-path definition. For example, ``KPTPATH (L,1,X),50`` would give a k path with a step size of (roughly)

:math:`2\pi/(50\sqrt[3]{\Omega})`. The k-points given (L, :math:`\Gamma`, and X in the example) must lie on the path. The actual step size is adjusted

accordingly. Here, :math:`\Omega` is the unit-cell volume, so :math:`8\pi^3/\Omega` is the volume of the Brillouin zone and

:math:`2\pi/\sqrt[3]{\Omega}` the average reciprocal lattice constant.

Larger integer arguments give denser k meshes. The default is 20 for

the method explained in :numref:`KPTadd` and 100 for the one in :numref:`INTERPOL_GW`.

.. list-table:: Examples

:widths: 36 100

...

...

@@ -509,6 +528,8 @@ As an example, we want to plot a band structure for the path from L over :math:`

- 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``.

* - ``JOB GW PATH:(1-10)``

- Run *GW* calculation for the first ten bands at all k points defined by ``KPTPATH``.

* - ``KPTPATH (1,N),100``

- Define k-point path from :math:`\Gamma` to N and use step size of :math:`2\pi/(100\sqrt[3]{\Omega})`.

.. _KPTadd:

...

...

@@ -573,7 +594,8 @@ see the Gnuplot manual.)

INTERPOL

---------

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 :numref:`wannier`. Here, we use a minimalistic definition for demonstration purposes. We have to modify and add some lines to ``spex.inp``:

The construction of Wannier orbitals is explained in :numref:`wannier`. Here, we use a minimalistic definition for demonstration purposes.

We have to modify and add some lines to ``spex.inp``:

.. code-block:: bash

...

...

@@ -588,9 +610,18 @@ Please also remove the entry ``+=[0,0,0.75]`` from the ``KPT`` line. The first l

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 section ``WANNIER`` defines a set of maximally localized Wannier functions (MLWFs) of bonding sp\ :sup:`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.

The section ``WANNIER`` defines a set of maximally localized Wannier functions (MLWFs) of bonding sp\ :sup:`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 with the line thickness scaled by the imaginary part in the same way as described before.

The band structure is calculated along the k-point path defined by ``KPTPATH`` (:numref:`KPTPATH`). By default, Spex uses a step

size of (roughly) :math:`2\pi/(100\sqrt[3]{\Omega})`. Alternatively, one can specify a file after ``INTERPOL``, e.g., ``INTERPOL qpts``.

The k-point path is then taken from that file. (The file structure is the same as of "kpts" or "qpts".)

Wannier interpolation can also be used in conjunction with the keyword ``SPECTRAL`` (:numref:`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 the spin up and spin down channels, respectively. These files

...

...

@@ -824,8 +855,8 @@ reciprocal value (for example, in "gnuplot": ``plot "dielecR" using 1:(imag(1/($

In the same way, other quantities can be calculated: the polarization function with ``SUSCEP`` (written to the file "suscep"), the renormalized polarization

function (:math:`R=P+PvR`) with ``SUSCEPR`` (written to the file "suscepR"; "suscep" is also written), the screened interaction with

``SCREEN`` (written to the file "screen"). In the former case (``SUSCEP``), one can also specify spin indices. For example,

``JOB SUSCEP X:ud{0:1,0.001}`` restricts the the polarization function to virtual up\ :math:`\rightarrow`\ down transitions.

``SCREEN`` (written to the file "screen"). In the first case (``SUSCEP``), one can also specify spin indices. For example,

``JOB SUSCEP X:ud{0:1,0.001}`` restricts the polarization function to virtual up\ :math:`\rightarrow`\ down transitions.

Other valid spin labels are ``uu``, ``dd``, ``du``, and ``+`` (spin summed, default).

By default, only the head element is written to the output files. More elements can be written using, e.g.,

...

...

@@ -836,14 +867,14 @@ The special ``+`` k-point label can be used as well (e.g., ``JOB SUSCEP +:{0..50

"spex.band" to prepare a whole list of spectra for a series of Bloch vectors on a high-symmetry line. As explained in

:numref:`KPTadd` for the file "spectral", the script appends a three-digit counting index to the name of the output file

("suscep" in the present example, which is thus renamed to "suscep001", "suscep002", ...). The data can then be compiled

into a single file using the spex.extr utility. (See :numref:`KPTadd` for details).

into a single file using the "spex.extr" utility. (See :numref:`KPTadd` for details).

Total xc energies

==================

Spex can calculate total exchange and/or correlation energies of the many-electron system. The total exchange energy is defined

Spex can calculate total exchange and correlation energies of the many-electron system. The total exchange energy is defined