Commit 73876f19 authored by Christoph Friedrich's avatar Christoph Friedrich

Added "spex.x", new treatment of KPTPATH, and possibility of running INTERPOL with a file.

parent c62a2dd2
......@@ -205,7 +205,7 @@ The mathematical definition is
.. math::
\displaystyle w_{\mathbf{R}n}(\mathbf{r}) = \frac{1}{N} \sum_\mathbf{k} e^{-i\mathbf{kR}}
\sum_m U_{\mathbf{k}m,n} \varphi_{\mathbf{k}m}(\mathbf{r})
\sum_m U_{\mathbf{k}m,n} \phi_{\mathbf{k}m}(\mathbf{r})
:label: wannier
with the lattice vector :math:`\mathbf{R}` (the Wannier orbital is localized in the respective unit cell),
......@@ -272,7 +272,7 @@ symmetry in this case) is rotated.
The so-generated Wannier function are *first-guess* Wannier functions. To be more precise,
the expansion coefficients :math:`U_{\mathbf{k}n,m}` are obtained from projecting the Bloch functions
:math:`\varphi_{\mathbf{k}n}` onto localized functions with the chosen orbital character. Then, an
:math:`\phi_{\mathbf{k}n}` onto localized functions with the chosen orbital character. Then, an
orthonormalization procedure is applied to make the Wannier set orthonormal. For many purposes, the
resulting set of Wannier functions is already usable. However, it is not yet maximally localized.
The following keyword enforces maximal localization with Wannier90 (using the Wannier90 library),
......
......@@ -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.
Input data
===========
......
......@@ -25,10 +25,11 @@ project = 'Spex'
copyright = u'2019, PGI, Forschungszentrum J\u00fclich, Germany'
author = ''
spexversion = open('version').read()
# The short X.Y version
version = '0.0.1'
version = spexversion
# The full version, including alpha/beta/rc tags
release = open('version').read()
release = spexversion
# -- General configuration ---------------------------------------------------
......
......@@ -6,7 +6,7 @@ General information
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.
......
......@@ -51,4 +51,32 @@ The compilation creates the executables
which may be installed with ``make install``. Installation is optional. See the file "INSTALL" for details.
The reason for having two executables, one for systems with inversion symmetry and the other for systems without, is that many quantities
(such as the Coulomb matrix, the screened interaction on the imaginary axis, the exchange self-energy, etc.) can be declared in the code
as real-valued instead of complex-valued arrays in the case of inversion symmetry, which speeds up the computation considerably.
(The floating-point multiplication of complex numbers are about eight times slower than the multiplication of real numbers.)
For the sake of code clarity, it is then advantageous to have two executables.
The user can call "spex.inv" or "spex.noinv" directly or use the caller utility "spex.x". The caller utility simply returns the
name of the executable that should be used for the present system ("spex.inv" or "spex.noinv") and prepends the path. (It is assumed that
all executables reside in the same directory.) This allows the proper executable to be called generally by ```spex.x``` (all shells) or
``$(spex.x)`` (BASH). The shell calls "spex.x", which returns the executable's name, and then immediately runs that executable.
For convenience, you can add the line::
alias spex='$(spex.x)'
(BASH) or::
alias spex '`spex.x`'
(other shells) to your shell config file (".bashrc" or similar). Spex is then called simply by::
$ spex
and the parallelized version by::
$ mpiexec -np 8 spex
as an example.
......@@ -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
by the HF expression
.. math:: E^\mathrm{x}=\frac{1}{2} \sum_{\mathbf{k}n} \sum_{\mathbf{k}'n'} \iint \frac{ \varphi^*_{\mathbf{k}n}(\mathbf{r}) \varphi_{\mathbf{k}'n'}(\mathbf{r}) \varphi^*_{\mathbf{k}'n'}(\mathbf{r}') \varphi_{\mathbf{k}n}(\mathbf{r'}) } { \mathbf{r}-\mathbf{r}' } d^3r\,d^3r'\,.
.. math:: E^\mathrm{x}=\frac{1}{2} \sum_{\mathbf{k}n} \sum_{\mathbf{k}'n'} \iint \frac{ \phi^*_{\mathbf{k}n}(\mathbf{r}) \phi_{\mathbf{k}'n'}(\mathbf{r}) \phi^*_{\mathbf{k}'n'}(\mathbf{r}') \phi_{\mathbf{k}n}(\mathbf{r'}) } { \mathbf{r}-\mathbf{r}' } d^3r\,d^3r'\,.
:label: hfene
The corresponding job is called ``HFENE``. Internally, it works very much like a HF calculation. So, all parameters pertaining to ``HF``
......@@ -925,7 +956,7 @@ to project this interaction potential onto the set of local Wannier functions de
(:numref:`wannier`). The resulting interaction matrix elements
.. math::
V_{n_1n_2,n_3n_4}(\omega) = <n_1 n_2|V(\omega)|n_3 n_4> = \iint w_{n_1}^*(\mathbf{r}) w_{n_3}(\mathbf{r}) V(\mathbf{r},\mathbf{r}';\omega) w_{n_2}^*(\mathbf{r}') w_{n_4}^*(\mathbf{r}') d^3r d^3r'
V_{n_1n_2,n_3n_4}(\omega) = \langle n_1 n_2|V(\omega)|n_3 n_4\rangle = \iint w_{n_1}^*(\mathbf{r}) w_{n_3}(\mathbf{r}) V(\mathbf{r},\mathbf{r}';\omega) w_{n_2}^*(\mathbf{r}') w_{n_4}^*(\mathbf{r}') d^3r d^3r'
:label: screenwdef
are written to the file "spex.cou" for the bare interaction (:math:`V=v`) and the screened interaction
......@@ -1024,5 +1055,5 @@ in which the reference mean-field system is modified in such a way that each sta
the subspace or completely outside (corresponding to probabilities 1 or 0). This method can be used by specifying ``DISENTGL``
in the section ``WANNIER``.
.. note:: Using this keyword actually modifies the mean-field system! (The keyword has not been tested thoroughly yet.)
.. warning:: Using this keyword actually modifies the mean-field system! (The keyword has not been tested thoroughly yet.)
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment