Skip to content

GitLab

S
spex-docs
Commit c249f54e authored by Christoph Friedrich's avatar Christoph Friedrich
Browse files
Options

Merge branch 'master' into 'master' 

All Known Issues with Latex, tables and equations are fixed

See merge request !2
parents 895e6d5b e509d34b
Expand all Hide whitespace changes
Inline Side-by-side
Showing with 154 additions and 549 deletions
.gitignore
View file @ c249f54e
build
_static
_templates
.gitlab-ci.yml
README.rst
View file @ c249f54e
......@@ -19,7 +19,7 @@ This generates a html documentation tree under spex-docs/build
make latexpdf
This generates a html documentation tree under spex-docs/build
This generates a pdf documentation tree under spex-docs/build
You can browse to ``spex-docs/build/html/index.html`` to see the documentation in html format.
......
source/_static/css/custom.css 0 → 100644
View file @ c249f54e
span.eqno {
float: right;
}
source/basis_sets.rst
View file @ c249f54e
......@@ -33,10 +33,10 @@ GCUT (MBASIS)
---------------
If :math:`{N}` is the number of LAPW basis functions, one would naively expect the number of product functions to be roughly :math:`{N^2}`. In the case of the interstitial plane waves, this is not so, since, with a cutoff :math:`{g_\mathrm{max}}`, the maximum momentum of the product would be :math:`{2g_\mathrm{max}}`, leading to :math:`{8N}` as the number of product plane waves. Fortunately, it turns out that the basis size can be much smaller in practice. Therefore, we introduce a reciprocal cutoff radius :math:`{G_\mathrm{max}}` for the interstitial plane waves and find that, instead of :math:`{G_\mathrm{max}=2g_\mathrm{max}}`, good convergence is achieved already with :math:`{G_\mathrm{max}=0.75g_\mathrm{max}}`, the default value. The parameter :math:`{G_\mathrm{max}}` can be set to a different value with the keyword ``GCUT`` in the section ``MBASIS`` of the input file.
+---------+--------------+--+------------------------------------------------+
+---------+--------------+---------------------------------------------------+
| Example | ``GCUT 2.9`` | | Use a reciprocal cutoff radius of 2.9 |
| | | | :math:`Bohr^{-1}` for the product plane waves. |
+---------+--------------+--+------------------------------------------------+
+---------+--------------+---------------------------------------------------+
.. _lcut:
......@@ -54,14 +54,17 @@ In the LAPW basis, the matching conditions at the MT boundaries require large :m
+----------+--------------------------------+------------------------------------------------------------------------------------------------------------------+
| Examples | ``SELECT 2;3`` | | Use products of :math:`{u_{lp} u_{l'p'}}` with :math:`{l\le 2}` and :math:`{l'\le 3}` |
| | | | for :math:`{p=0}` (so-called :math:`{u}`) and no function of :math:`{p=1}` (so-called :math:`{\dot{u}}`). |
| | | | for :math:`{p=0}` (so-called :math:`{u}`) and no function |
| | | | of :math:`{p=1}` (so-called :math:`{\dot{u}}`). |
+----------+--------------------------------+------------------------------------------------------------------------------------------------------------------+
| | ``SELECT 2,1;3,2`` | | Same as before but also include the :math:`{\dot{u}}` functions with :math:`{l\le 2}` and :math:`{l'\le 3}`. |
| | ``SELECT 2,1;3,2`` | | Same as before but also include the :math:`{\dot{u}}` functions |
| | | | with :math:`{l\le 2}` and :math:`{l'\le 3}`. |
+----------+--------------------------------+------------------------------------------------------------------------------------------------------------------+
| | ``SELECT 2,,1100;3,,1111`` | | Same as first line but also include the local orbitals |
| | | | :math:`{p\ge 2}`, which are selected (deselected) by "1" ("0"): |
| | | | here, the first two and all four LOs, respectively. The default behavior is |
| | | | to include semicore LOs but to exclude the ones at higher energies. |
| | | | here, the first two and all four LOs, respectively. |
| | | | The default behavior is to include semicore LOs but to |
| | | | exclude the ones at higher energies. |
+----------+--------------------------------+------------------------------------------------------------------------------------------------------------------+
| | ``SELECT 2,1,1100;3,2,1111`` | | Same as second line with the LOs. |
+----------+--------------------------------+------------------------------------------------------------------------------------------------------------------+
......@@ -73,21 +76,25 @@ TOL (MBASIS)
(*) The set of MT products selected by ``SELECT`` can still be highly linearly dependent. Therefore, in a subsequent optimization step one diagonalizes the MT overlap matrix and retains only those eigenfunctions whose eigenvalues exceed a predefined tolerance value. This tolerance is 0.0001 by default and can be changed with the keyword ``TOL`` in the input file.
+---------+-----------------+-------------------------------------------------------------------------------+
| Example | ``TOL 0.00001`` | Remove linear dependencies that fall below a tolerance of 0.00001 (see text). |
| Example | ``TOL 0.00001`` | | Remove linear dependencies that fall below a |
| | | | tolerance of 0.00001 (see text). |
+---------+-----------------+-------------------------------------------------------------------------------+
OPTIMIZE (MBASIS)
-----------------
The mixed product basis can still be quite large. In the calculation of the screened interaction, each matrix element, when represented in the basis of Coulomb eigenfunctions, is multiplied by :math:`{\sqrt{v_\mu v_\nu}}` with the Coulomb eigenvalues :math:`{\{v_\mu\}}`. This gives an opportunity for reducing the basis-set size further by introducing a Coulomb cutoff :math:`{v_\mathrm{min}}`. The reduced basis set is then used for the polarization function, the dielectric function, and the screened interaction. The parameter :math:`{v_\mathrm{min}}` can be specified after the keyword ``OPTIMIZE MB`` in three ways: first, as a "pseudo" reciprocal cutoff radius :math:`{\sqrt{4\pi/v_\mathrm{min}}}` (which derives from the plane-wave Coulomb eigenvalues :math:`{v_\mathbf{G}=4\pi/G^2}), second, directly as the parameter :math:`{v_\mathrm{min}}` by using a negative real number, and, finally, as the number of basis functions that should be retained when given as an integer. The so-defined basis functions are mathematically close to plane waves. For testing purposes, one can also enforce the usage of plane waves (or rather projections onto plane waves) with the keyword ``OPTIMIZE PW``, in which case the Coulomb matrix is known analytically. No optimization of the basis is applied, if ``OPTIMIZE`` is omitted.
The mixed product basis can still be quite large. In the calculation of the screened interaction, each matrix element, when represented in the basis of Coulomb eigenfunctions, is multiplied by :math:`{\sqrt{v_\mu v_\nu}}` with the Coulomb eigenvalues :math:`{\{v_\mu\}}`. This gives an opportunity for reducing the basis-set size further by introducing a Coulomb cutoff :math:`{v_\mathrm{min}}`. The reduced basis set is then used for the polarization function, the dielectric function, and the screened interaction. The parameter :math:`{v_\mathrm{min}}` can be specified after the keyword ``OPTIMIZE MB`` in three ways: first, as a "pseudo" reciprocal cutoff radius :math:`{\sqrt{4\pi/v_\mathrm{min}}}` (which derives from the plane-wave Coulomb eigenvalues :math:`{v_\mathbf{G}=4\pi/G^2}`), second, directly as the parameter :math:`{v_\mathrm{min}}` by using a negative real number, and, finally, as the number of basis functions that should be retained when given as an integer. The so-defined basis functions are mathematically close to plane waves. For testing purposes, one can also enforce the usage of plane waves (or rather projections onto plane waves) with the keyword ``OPTIMIZE PW``, in which case the Coulomb matrix is known analytically. No optimization of the basis is applied, if ``OPTIMIZE`` is omitted.
+----------+-----------------------+-------------------------------------------------------------------------------------------------------------+
| Examples | ``OPTIMIZE MB 4.0`` | Optimize the mixed product basis by removing eigenfunctions with eigenvalues below ``4\pi/4.5^2``. |
| Examples | ``OPTIMIZE MB 4.0`` | | Optimize the mixed product basis by removing eigenfunctions |
| | | | with eigenvalues below ``4\pi/4.5^2``. |
+----------+-----------------------+-------------------------------------------------------------------------------------------------------------+
| | ``OPTIMIZE MB -0.05`` | Optimize the mixed product basis by removing eigenfunctions with eigenvalues below ``0.05``. |
| | ``OPTIMIZE MB -0.05`` | | Optimize the mixed product basis by removing eigenfunctions |
| | | | with eigenvalues below ``0.05``. |
+----------+-----------------------+-------------------------------------------------------------------------------------------------------------+
| | ``OPTIMIZE MB 80`` | Retain only the eigenfunctions with the 80 largest eigenvalues. |
+----------+-----------------------+-------------------------------------------------------------------------------------------------------------+
| | ``OPTIMIZE PW 4.5`` | Use projected plane waves with the cutoff ``4.5 \mathrm{Bohr}^{-1}`` (for testing only, can be quite slow). |
| | ``OPTIMIZE PW 4.5`` | | Use projected plane waves with the cutoff :math:`{4.5 \mathrm{Bohr}^{-1}}` |
| | | | (for testing only, can be quite slow). |
+----------+-----------------------+-------------------------------------------------------------------------------------------------------------+
In summary, there are a number of parameters that influence the accuracy of the basis set. Whenever a new physical system is investigated, it is recommendable to converge the basis set for that system. The parameters to consider in this respect are ``GCUT``, ``LCUT``, ``SELECT``, and ``OPTIMIZE``.
......@@ -124,7 +131,7 @@ FFT (WFPROD)
--------------
When the interaction potential is represented in the mixed product basis, the coupling to the single-particle states involve projections of the form
:math:`{\langle M_{\mathbf{k}\mu} \phi_{\mathbf{q}n} | \phi_{\mathbf{k+q}n'} \rangle\,.}`
The calculation of these projections can be quite expensive. Therefore, there are a number of keywords that can be used for acceleration. Most of them are, by now, somewhat obsolete. An important keyword, though, is ``FFT`` in the section ``WFPROD`` of the input file. When used, the interstitial terms are evaluated using Fast Fourier Transformations (FFTs), i.e., by transforming into real space (where the convolutions turn into products), instead of by explicit convolutions in reciprocal space. For small systems the latter is faster, but for large systems it is recommendable to use FFTs because of a better scaling with system size. A run with FFTs can be made to yield results identical to the explicit summation. This requires an FFT reciprocal cutoff radius of :math:`{2G_\mathrm{max}+g_\mathrm{max}}`, which can be achieved by setting ``FFT EXACT``, but such a calculation is quite costly. It is, therefore, advisable to use smaller cutoff radii, thereby sacrificing a bit of accuracy but speeding up the computations a lot. If given without an argument, Spex will use 2/3 of the above ''exact'' cutoff. One can also specify a cutoff by a real-valued argument explicitly, good compromises between accuracy and speed are values between 6 and 8 Bohr'^-1^'.
The calculation of these projections can be quite expensive. Therefore, there are a number of keywords that can be used for acceleration. Most of them are, by now, somewhat obsolete. An important keyword, though, is ``FFT`` in the section ``WFPROD`` of the input file. When used, the interstitial terms are evaluated using Fast Fourier Transformations (FFTs), i.e., by transforming into real space (where the convolutions turn into products), instead of by explicit convolutions in reciprocal space. For small systems the latter is faster, but for large systems it is recommendable to use FFTs because of a better scaling with system size. A run with FFTs can be made to yield results identical to the explicit summation. This requires an FFT reciprocal cutoff radius of :math:`{2G_\mathrm{max}+g_\mathrm{max}}`, which can be achieved by setting ``FFT EXACT``, but such a calculation is quite costly. It is, therefore, advisable to use smaller cutoff radii, thereby sacrificing a bit of accuracy but speeding up the computations a lot. If given without an argument, Spex will use 2/3 of the above *exact* cutoff. One can also specify a cutoff by a real-valued argument explicitly, good compromises between accuracy and speed are values between 6 and 8 Bohr'^-1^'.
+----------+---------------+-------------------------------------------------------------------------------+
| Examples | ``FFT 6`` | Use FFTs with the cutoff 6 Bohr'^-1^'. |
......
source/common_keywords.rst
View file @ c249f54e
......@@ -41,13 +41,14 @@ Each Spex run needs a job definition, which defines what Spex should do, e.g., `
Details of these jobs are explained in subsequent sections. The job definition must not be omitted but may be empty: ``JOB``, in which case Spex will just read the wavefunctions and energies, perform some checks and some elemental calculations (e.g., Wannier interpolation), and stop. In principle, Spex supports multiple jobs such as ``JOB GW 1:(1-5) DIELEC 1:{0:1,0.01}``. This feature is, however, seldom used and is not guaranteed to work correctly in all versions.
+----------+------------------------------------------+----------------------------------------------------------------------+
| Examples | ``JOB COSX 1:(1-5)`` | Perform COHSEX calculation. |
+----------+------------------------------------------+----------------------------------------------------------------------+
| | ``JOB COSX 1:(1-5) SCREEN 2:{0:1,0.01}`` | Subsequently, calculate the screened interaction on a frequency mesh |
+----------+------------------------------------------+----------------------------------------------------------------------+
| | ``JOB`` | Just perform some checks and stop |
+----------+------------------------------------------+----------------------------------------------------------------------+
+----------+------------------------------------------+--------------------------------------------+
| Examples | ``JOB COSX 1:(1-5)`` | Perform COHSEX calculation. |
+----------+------------------------------------------+--------------------------------------------+
| | ``JOB COSX 1:(1-5) SCREEN 2:{0:1,0.01}`` | | Subsequently, calculate the screened |
| | | | interaction on a frequency mesh |
+----------+------------------------------------------+--------------------------------------------+
| | ``JOB`` | Just perform some checks and stop |
+----------+------------------------------------------+--------------------------------------------+
BZ
-----
......@@ -68,6 +69,7 @@ This is an important keyword. It enables (a) continuing a calculation that has,
+----------+---------------+----------------------------------------------+
| Examples | ``RESTART`` | Read/write restart file |
+----------+---------------+----------------------------------------------+
| | ``RESTART 2`` | Try to reuse data from standard output files |
+----------+---------------+----------------------------------------------+
......@@ -104,7 +106,7 @@ CHKMISM
MTACCUR
-------
(*) The LAPW method relies on a partitioning of space into MT spheres and the interstitial region. The basis functions are defined differently in the two regions, interstitial plane waves in the latter and numerical functions in the spheres with radial parts :math:`{u(r)}, {\dot{u}(r)=\partial u(r)/\partial\epsilon}`, :math:`{u^\mathrm{LO}(r)}` and spherical harmonics :math:`{Y_{lm}(\hat{\mathbf{r}})}` The plane waves and the angular part of the MT functions can be converged straightforwardly with the reciprocal cutoff radius :math:`{g_\mathrm{max}}` and the maximal l quantum number :math:`{l_\mathrm{max}}`, respectively, whereas the radial part of the MT functions is not converged as easily. The standard LAPW basis is restricted to the functions :math:`{u}` and :math:`{\dot{u}}`. Local orbitals :math:`{u^\mathrm{LO}}` can be used to extend the basis set, to enable the description of semicore and high-lying conduction states. The accuracy of the radial MT basis can be analyzed with the keyword MTACCUR e1 e2 which gives the MT representation error [Phys. Rev. B 83, 081101] in the energy range between e1 and e2. (If unspecified, e1 and e2 are chosen automatically.) The results are written to the output files spex.mt.t where t is the atom type index, or spex.mt.s.t with the spin index s(=1 or 2) for spin-polarized calculations. The files contain sets of data for all l quantum numbers, which can be plotted separately with gnuplot (e.g., plot "spex.mt.1" i 3 for :math:`{l=3}`
(*) The LAPW method relies on a partitioning of space into MT spheres and the interstitial region. The basis functions are defined differently in the two regions, interstitial plane waves in the latter and numerical functions in the spheres with radial parts :math:`{u(r)}, {\dot{u}(r)=\partial u(r)/\partial\epsilon}`, :math:`{u^\mathrm{LO}(r)}` and spherical harmonics :math:`{Y_{lm}(\hat{\mathbf{r}})}` The plane waves and the angular part of the MT functions can be converged straightforwardly with the reciprocal cutoff radius :math:`{g_\mathrm{max}}` and the maximal l quantum number :math:`{l_\mathrm{max}}`, respectively, whereas the radial part of the MT functions is not converged as easily. The standard LAPW basis is restricted to the functions :math:`{u}` and :math:`{\dot{u}}`. Local orbitals :math:`{u^\mathrm{LO}}` can be used to extend the basis set, to enable the description of semicore and high-lying conduction states. The accuracy of the radial MT basis can be analyzed with the keyword MTACCUR e1 e2 which gives the MT representation error [Phys. Rev. B 83, 081101] in the energy range between e1 and e2. (If unspecified, e1 and e2 are chosen automatically.) The results are written to the output files spex.mt.t where t is the atom type index, or spex.mt.s.t with the spin index s(=1 or 2) for spin-polarized calculations. The files contain sets of data for all l quantum numbers, which can be plotted separately with gnuplot (e.g., plot "spex.mt.1" i 3 for :math:`{l=3}`)
+----------+------------------+------------------------------------------------------------+
| Examples | ``MTACCUR -1 2`` | Calculate MT representation error between -1 and 2 Hartree |
......@@ -116,19 +118,19 @@ BANDINFO
--------
(*) In some cases, it may be necessary to replace the energy eigenvalues, provided by the mean-field (DFT) code, by energies (e.g., GW quasiparticle energies) obtained in a previous Spex calculation, for example, to determine the GW Fermi energy or to perform energy-only self-consistent calculations. This can be achieved with the keyword ``ENERGY file``, where ``file`` contains the new energies in eV. The format of ``file`` corresponds to the output of the ``spex.extr`` utility: ``spex.extr g spex.out > file``. It must be made sure that ``file`` contains energy values for the whole irreducible Brillouin zone. Band energies not contained in ``file`` will be adjusted so that the energies are in accending order (provided that there is at least one energy value for the particular k point).
+---------+-----------------------+-----------------------------------------------------------------------------------------------+
| Example | ``ENERGY energy.inp`` | | Replace the mean-field energy eigenvalues by the |
| | | | energies provided in the file ``energy.inp`` |
+---------+-----------------------+-----------------------------------------------------------------------------------------------+
+---------+-----------------------+---------------------------------------------------------+
| Example | ``ENERGY energy.inp`` | | Replace the mean-field energy eigenvalues by the |
| | | | energies provided in the file ``energy.inp`` |
+---------+-----------------------+---------------------------------------------------------+
DELTAEX
-------
(*) This keyword modifies the exchange splitting of a collinear magnetic system, i.e., it shifts spin-up and spin-down energies relative to to each other so as to increase or decrease the exchange splitting. With ``DELTAEX x``, the spin-up (spin-down) energies are lowered (elevated) by x/2. The parameter x can be used to enforce the Goldstone condition in spin-wave calculations [Phys. Rev. B 94, 064433 (2016)]
+---------+-------------------+---------------------------------------------------------------------------------------------------+
| Example | ``DELTAEX 0.2eV`` | | Increase the exchange splitting by 0.2eV |
| | | | (spin-up/down energies are decreased/increased by 0.1eV) |
+---------+-------------------+---------------------------------------------------------------------------------------------------+
+---------+-------------------+---------------------------------------------------------------+
| Example | ``DELTAEX 0.2eV`` | | Increase the exchange splitting by 0.2eV |
| | | | (spin-up/down energies are decreased/increased by 0.1eV) |
+---------+-------------------+---------------------------------------------------------------+
PLUSSOC
-------
......@@ -138,17 +140,18 @@ ITERATE
-------
(*) If specified, Spex only reads the LAPW basis set from the input data, provided by the mean-field (DFT) code, but performs the diagonalization of the Hamiltonian at the k points itself. This calculation effectively replaces the second run of the DFT code. In this sense, the name of the keyword is a bit misleading, as the calculation is non-iterative. The keyword ``ITERATE`` is mostly intended for testing and debugging. It is not available for executables compiled with ``-DLOAD`` (configured with ``--enable-load``).
+----------+---------------------+----------------------------------------------------------------------------------+
| Examples | ``ITERATE NR`` | Diagonalize a non-relativistic Hamiltonian |
+----------+---------------------+----------------------------------------------------------------------------------+
| | ``ITERATE SR`` | Use scalar-relativity |
+----------+---------------------+----------------------------------------------------------------------------------+
| | ``ITERATE FR`` | Also include SOC |
+----------+---------------------+----------------------------------------------------------------------------------+
| | ``ITERATE SR -1`` | Diagonalize scalar-relativistic Hamiltonian and neglect eigenvalues below -1 htr |
+----------+---------------------+----------------------------------------------------------------------------------+
| | ``ITERATE FR STOP`` | Diagonalize relativistic Hamiltonian (including SOC), then stop |
+----------+---------------------+----------------------------------------------------------------------------------+
+----------+---------------------+-------------------------------------------------------------------+
| Examples | ``ITERATE NR`` | Diagonalize a non-relativistic Hamiltonian |
+----------+---------------------+-------------------------------------------------------------------+
| | ``ITERATE SR`` | Use scalar-relativity |
+----------+---------------------+-------------------------------------------------------------------+
| | ``ITERATE FR`` | Also include SOC |
+----------+---------------------+-------------------------------------------------------------------+
| | ``ITERATE SR -1`` | | Diagonalize scalar-relativistic Hamiltonian and |
| | | | neglect eigenvalues below -1 htr |
+----------+---------------------+-------------------------------------------------------------------+
| | ``ITERATE FR STOP`` | Diagonalize relativistic Hamiltonian (including SOC), then stop |
+----------+---------------------+-------------------------------------------------------------------+
Parallelized version
====================
......
source/conf.py
View file @ c249f54e
......@@ -15,6 +15,8 @@
# import os
# import sys
# sys.path.insert(0, os.path.abspath('.'))
def setup(app):
app.add_stylesheet('css/custom.css')
# -- Project information -----------------------------------------------------
......
source/getting_started.rst
View file @ c249f54e
......@@ -28,7 +28,7 @@ For the first and third step consult the manual of your DFT program. (Click `her
KPT X=[0,0,1] L=1/2*[1,1,1]
JOB GW 1:(1,2,5) X:(1,3,5) L:(1-3,5)
.. note:: Refer to the chapter :ref:`keyword_reference` for a full list of available keywords
.. note:: Refer to the tutorials and other chapter for a full list of available keywords
For the second step only the lines beginning with ``BZ`` and ``WRTKPT`` are necessary. The line ``BZ 4 4 4`` defines a 4x4x4 k-point set, and the keyword ``WRTKPT`` tells Spex to write the (irreducible) k-points to a file (``kpts`` for Fleur) and stop.
......
source/index.rst
View file @ c249f54e
......@@ -13,10 +13,7 @@ It needs input from a converged DFT calculation, which can be generated by Fleur
If you use SPEX for your research, please cite the following work:
.. highlights:: Christoph Friedrich, Stefan Blu'gel, Arno Schindlmayr, "Efficient implementation of the GW approximation within the all-electron FLAPW method", Phys. Rev. B 81, 125102 (2010).
User's guide
++++++++++++
.. highlights:: Christoph Friedrich, Stefan Blügel, Arno Schindlmayr, "Efficient implementation of the GW approximation within the all-electron FLAPW method", *Phys. Rev. B 81, 125102 (2010)*.
.. toctree::
:maxdepth: 2
......@@ -27,9 +24,6 @@ User's guide
common_keywords
tutorials
basis_sets
theory
specifics
keyword_reference
spex_faq
source/installation.rst
View file @ c249f54e
......@@ -20,10 +20,9 @@ Configure the spex installation
Once you have obtained the code (``spexVERSION.tgz``) unpack it with your local version of tar and change to the ``spexVERSION`` directory, where ``VERSION`` is the version number, e.g. "05.00". There you should find the source code and a configure shell script that helps to generate a Makefile for your system. Consult the file ``INSTALL`` for a description of the compilation process. In short, if all necessary libraries are in standard directories, ``./configure`` and make should suffice to create a working executable. Special options can be given to the configure script:
* ``--enable-parallel``: Build parallel version (requires an MPI-3 compiler).
* ``--enable-load``: Load wave functions from harddisc when needed (otherwise stored in memory).
* ``--with-wan``: Build with Wannier-function support
* ``--prefix=PREF``: Executables will be installed in directory PREF (`/usr/local` is default).
* ``--enable-load``: Load wave functions from harddisc when needed (otherwise stored in memory).
* ``--with-wan``: Build with Wannier-function support(Wannier-function support requires the Wannier90 library, whose location can be specified with ``–with-wan=DIR``)
* ``--prefix=PREF``: Executables will be installed in directory PREF (`/usr/local` is default).
.. note:: Enter ``./configure -h`` for a full list of configuration options
.. warning:: Wannier-function support requires the Wannier90 library, whose location can be specified with ``–with-wan=DIR``
source/keyword_reference.rst deleted 100644 → 0
View file @ 895e6d5b
.. _keyword_reference:
========================
Keyword Reference
========================
This document gives a reference of available keywords in the input file ``spex.inp``. The syntax of the input file is as follows.
* The file ``spex.inp`` does not use a fixed format, and the keywords may be given in any order.
* Each keyword is given on one line together with its parameters following it and may be given only once.
* All keywords (and section names) are in capital letters.
* Everything after a ``#`` sign is interpreted as a comment. Empty lines are allowed.
* Lines are only interpreted up to the 80th column. Line continuation is possible using a single backslash ``\`` at the end of the previous line.
* Some keywords are only defined inside sections. A section starts with ``SECTION sectionname`` and ends with ``END``.
In the following the keywords are listed and explained alphabetically and for each section separately. If there is no default value, the keyword must be given. **Experimental, badly tested, and obsolete keywords as well as keywords for testing are shown in round brackets.**
.. warning:: The list can be partly out of date or obsolete.
Global Keywords
-----------------
(``ALIGNBD``): Aligns the degenerate states on the unshifted k-point set (see ``KPT +=...``) to the states on the shifted k points. Corresponding transformation matrices are written to the file ``spex.abd`` or read from it if it exists. Normally used to calculate response quantities of metals for small k vectors, e.g., in order to test the expansion around the point '''k=0'''. (Default false)
``BANDINFO``: Prints information about bands: weight of s,p,d,f,g character of each state, (P)DOS plot in separate file (``spex.dos.NNN``), square integral of wave-function products. (Default false)
(``BANDOMIT (bands) ABC``): Omits bands defined in ``bands`` in exchange (``A=1``), susceptibility (``B=1``), and/or correlation self-energy (``C=1``). (Otherwise ``A=0`` etc.) (Default none)
``BZ k l m``: Defines a k-point set ``k``x``l``x``m``.
``CHKMISM``: Checks the mismatch of the DFT wave functions at the MT spheres. (Default false)
``DIPOLE``: Calculates dipole moments for all direct (optical) transitions. (Default false)
``CHKOLAP``: Checks the overlap of the DFT wave functions. (Default false)
(``CORES cores``): Includes core states into the calculation of the susceptibility and self-energy. The core states are defined separately for each atom type as a list in brackets, e.g., ``(4f,5s,5p)``. Empty lists ``()`` are allowed. (Default none)
``CORESOC``: Treats core states as { j,m_j } Dirac spinors. Otherwise, the Dirac states are averaged in each { l,m } channel. (Default false)
(``GAUSS x y``): Use Gauss integration with widths ``x`` and ``y`` instead of tetrahedron integration. Only for debugging. (Default false)
(``IBC n``): Uses the incomplete-basis-set correction (IBC). Experimental! (Default false)
(``ITERATE opt e``): Constructs a (``opt=NR``: non-relativistic, ``opt=SR``: scalar-relativistic, ``opt=FR``: fully relativistic, i.e., including SOC) LAPW(+LO) Hamiltonian from the converged DFT potential and calculates wave functions and energies from it, which are then used in the calculation. This spares you the last DFT run. The parameter ``e`` is the lower energy bound for the electron states. The calculation is fairly slow. (Default none)
``JOB job1 job2 ...``: Defines what Spex should do. Consult the :ref:`tutorials` for details.
``KPT label1 label2 ...``: Defines labels (single characters) for k points. Consult the :ref:`tutorials` for details. (Default none)
``KPTPATH (A,B,C,...)``: Comma-separated list of k points that defines a k-point path. Spex automatically determines all k points (according to the ``BZ`` definition) that lie on the path. The path can be used (e.g., in the ``JOB`` definition) with ``PATH``. If Wannier functions are defined, Spex performs a Wannier interpolation along this path. (default none)
``MEM m``: Restricts the memory usage to ``m`` MB (per node). (Does not work exactly. The code actually needs more memory.) (Default 200)
``MTACCUR emin emax``: Writes plots for the MT representation error in the energy range {``emin``,``emax``} to the files ``spex.mt.NNN``. (Default none)
``NBAND n``: Restricts the number of bands to ``n`` bands or, if ``n`` is a real number, to all bands with energies below that value. (:comment All bands that are not treated explicitly can be taken into account in an approximate way by placing them at a fixed energy above all other energies. For example with ``NBAND 100+5`` this energy would lie 5 ha above the maximum energy (see PRB 78, 085125). :) (Default all bands)
(``PLUSSOC``): Adds spin-orbit coupling to the input data in second variation. (Default false)
``RESTART``: Enables to continue an older calculation (e.g., if the latter has crashed). Intermediate results are written to files (``spex.mb`` - Mixed product basis, ``spex.cou(s)`` - Coulomb matrix, ``spex.cor`` - Dielectric function, ``spex.spc`` - (e.g.) polarization function, ``spex.uwan`` - Wannier U matrices, ``spex.kolap`` - Overlap matrices for Wannier construction) or read from the files if they exist. With ``RESTART SIG``, Spex reads the self-energy from the files ``spex.sigx`` and ``spex.sigc``, which are always written in ``GW/HF FULL`` calculations. (Default false)
``STOREIBZ``: Wave functions are only stored in the IBZ rather than in the full BZ. This decreases the memory demand considerably but slows down the calculation somewhat because wave functions must be regenerated when needed. (Default false)
``WRITE q1 q2 ...``: Tells Spex to write the head element of the specified quantities ``q1/2=`` ``SUSCEP``, ``DIELEC`` or ``SCREEN`` to a file. Optionally a job number can be specified in brackets, as in ``WRITE SUSCEP(2)``. If one of these quantities are explicitly defined in the job definition, they are automatically written to files. With ``q1=INFO``, Spex writes preliminary results to several output files. Consult the :ref:`tutorials` for details. (Default none)
``WRTKPT``: Tells Spex to write out the k-point set and exit. (Default false)
Section ``MBASIS``
-------------------
``ADDBAS``: Augments mixed basis by the radial {u} functions (according to first part of SELECT entry). This improves the basis convergence for COHSEX calculations. (Default false)
``CHKPROD``: Checks the accuracy of the MT product basis. (Default false)
``GCUT G``: G cutoff for the IPWs of the mixed basis.
``LCUT l``: l cutoffs (one for each atom type) for the mixed basis.
``NOAPW``: Switches off construction of "product APWs", which are continuous at the MT sphere boundary. (Default false)
``OPTIMIZE``: Optimize mixed basis for correlation self-energy. Consult the :ref:`tutorials` for details. (Default none)
``SELECT l1,l3,lo1;l2,l4,lo2``: Selection of the MT radial functions from which the mixed basis is constructed. Consult the :ref:`tutorials` for details.
``TOL t``: Tolerance value for the removal of linear dependencies from the MT part of the mixed basis. (Default 0.0001)
(``WFADJUST``): Removes wavefunction coefficients belonging to radial functions that are not used to construct the MT product basis. (Currently the coefficients are actually not removed from the memory.) (Default false)
Section ``COULOMB``
--------------------
``CHKCOUL``: Performs checks on the Coulomb matrix: (1) Project on plane waves and see whether we get :math:`{v_{\mathbf{GG'}}=4\pi \delta_{\mathbf{GG'}}/ |\mathbf{k+G}|^2 }`, (2) compare largest eigenvalue of Coulomb matrix to :math:`{4\pi / k^2}`. (Default false)
(``CUTZERO``): Removes linear dependencies in the overlap matrix of the mixed basis. Otherwise, in the case of a large ``GCUT`` the diagonalization of the Coulomb matrix might fail due to numerical rounding errors in LAPACK. (Default false)
``LEXP``: l cutoff for the expansion of plane waves inside MT spheres. (Default 14)
``NOSTORE``: The default is to precalculate and keep the Coulomb matrices for all k points in memory. With this keyword the matrices are calculated whenever they are needed. This reduces the memory demand but somewhat slows down the calculation. Unless ``APPROXPW`` is chosen, this also applies to the overlap-correction matrix. (Only affects HF and QP calculations.) (Default false)
(``STEPRAD K``): Uses the Fourier transform of the step function as an alternative to the Rayleigh expansion for representing the IPWs and prints the resulting difference. The parameter ``K`` is the corresponding reciprocal cutoff radius. Only for testing. (Default none)
(``TSTCOUL``): Similar to ``CHKCOUL`` but regenerates MT part of the mixed basis from spherical Bessel functions and stops after the test. (Default false)
Section ``WFPROD``
-------------------
(``APPROXPW``): Since version 02.03 the plane-wave part of the wave-function products are calculated exactly leading to much better convergence with respect to ``GCUT``. However, the exact evaluation takes considerably more time. If ``APPROXPW`` is set, the old and approximate calculation of the products is used instead. (Default false)
``LCUT l``:Optional l cutoffs (one for each atom type) for the wave functions in the calculation of the products. (Default none)
``MTTHR d``: Threshold value below which wave-function coefficients are neglected. (1E-10 is a safe choice.) (Default 0)
(``MINCPW n``): Modifies the IPW wave-function coefficients such that their absolute values become as small as possible. This reduces the error in the evaluation of the wave-function products arising from the finite G cutoff and leads to better convergence with respect to ``GCUT`` and smoother band structures, when ``APPROXPW`` is used. The coefficients can be modified, because the set of IPWs is overcomplete. If set, the eigenvectors of the overlap matrix with the ``n`` smallest eigenvalues are used for this modification. Note that it only makes sense to use this together with ``APPROXPW``. (Default 0)
``FFT gcut``: Employs Fast Fourier transformation for the calculation of the plane-wave part of the wave-function products. Scales much better with system size than the direct (default) evaluation. Requires a reciprocal cutoff ``gcut``. The exact limit is :math:`gcut=GCUT{+2k_{\mathrm{max}}}`, where :math:`{k_{\mathrm{max}}}` is the PW cutoff of the DFT calculation, but much lower cutoffs are enough; try with ``gcut=8`` for example. If no ``gcut`` is given, Spex uses the exact limit. (Default none)
Section ``SUSCEP``
------------------
``DISORDER`` :math:`{\tau}`: Replaces the infinitesimal :math:`{i\eta}` by the finite frequency :math:`{i/2\tau}` in the response function. (Default none)
(``FSPEC N x``): Deprecated keyword. Use ``HILBERT`` instead. (Default none)
``HILBERT d x``: Defines the exponential frequency mesh for the Hilbert transformation in one of two ways: (1) ``d`` is the difference between the first (set at the band gap value or zero) mesh point :math:`{\omega_1}` and the second mesh point :math:`{\omega_2}`, and :math:`x` is the factor :math:`{x=(\omega_{i+1}-\omega_i)/(\omega_i-\omega_{i-1})}`; (2) if ``d`` is an integer, it is interpreted as the number of mesh points in the range :math:`{{\omega_1}..5 htr}`, and ``x`` is interpreted as the stretching factor "acquired at 5 htr", i.e., :math:`{x^{1/N}}` is the corresponding factor defined in (1). (Default 0.01 1)
:comment Alternatively, the first argument ``N`` can be a real number in which case it is interpreted as the first nonzero mesh point. Latest version: A negative second argument means the stretching factor that is reached after {N} points, i.e., :math:`{x^N}`. (Default 30 1.05):)
``HUBBARD file``: Calculates Hubbard parameters. If the optional filename ``file`` is given, the Hubbard parameters are read from (written to) ``file`` if it exists (does not exist). (Default false)
``MULTDIFF ON`` or ``OFF``: If set "ON" (and ``MB/PW=`` is used), the BZ integrand in the calculation of the head and wing elements of the polarization function (not for the magnetic susceptibility) is multiplied by KS energy differences. (The integration weights are correspondingly adjusted.) For a small (or zero) '''k''' vector this leads to better numerics (because the integrand is exactly inversely proportional to the KS energy differences in the case '''k=0'''). (Default ``ON `` for '''k=0''', ``OFF`` else)
``PLASMA p``: Sets the plasma frequency at ``p``. ``p=METAL``: use metallic screening. (Default none)
(``TETRAF``): If set, tetrahedron weights are only calculated in the (extended) irreducible part of the BZ. This accelerates the calculation of the weights considerably but introduces slight deviations due to symmetry breaking. (Default false)
``WGHTTHR w``: Sets a threshold value for the (tetrahedron) weights. All transition with weights below ``w`` are neglected. (Default :math:`{10^{-10}}`)
Section ``SENERGY``
----------------------
(``ALIGNVXC``): Aligns chemical potential to quasiparticle state of highest occupied state. (Default false)
``CONTINUE (n)``: If the optional (and now somewhat obsolete) parameter ``n`` is not given, a pade continuation is used. Otherwise, ``n`` specifies the number of poles used in the fit function for the analytic continuation of the self-energy. The fitting procedure can be influenced further by adding single characters to ``n``; character "``c``": employ additional constraints (i.e., integrability of the self-energy and continuity of its derivative at {\omega=0}), "``+``": add a constant to the fit function as a parameter, "``*``": allow poles above the real frequency axis. (Default Pade)
``CONTOUR D d``: Specifies contour integration for the evaluation of the self-energy. The first argument ``D``, if it is a number, defines the interval for the numerical derivative :math:`{d/d\epsilon \Sigma(\epsilon) = [\Sigma(\epsilon+D)-\Sigma(\epsilon-D)]/(2D)}` where :math:`{\epsilon}` is the corresponding KS energy. It can also be defined as a range, e.g. ``{-0.5..0.5,0.01}`` or ``[{-0.5..0.5,0.01}]``, which defines an equidistant mesh (relative to the Kohn-Sham energy or in absolute energies, the latter is the only viable definition for a ``GW FULL`` calculation) on which the self-energy is evaluated and which is used to solve the nonlinear quasiparticle equation (neglecting off-diagonal elements). The second argument ``d`` defines the step size of an equidistant mesh for the screened interaction. If ``d`` is omitted, a Pade continuation is used for the screened interaction (Keywords ``CONTINUE`` and ``CONTOUR`` are mutually exclusive.) (Default none)
``FREQINT SPLINE/PADE``: Algorithm for frequency integration in :math:`{\int G(\omega+\omega')W(\omega')d\omega'}`: the screened interaction is interpolated with a splines or with a Pade approximation. (Default SPLINE)
``LFRAC l``: l cutoff for the treatment of the anisotropy at the point :math:`{k=0}`. For isotropic systems ``l=1`` is enough. (Default 1)
``MESH n x``: Defines the imaginary frequency mesh where ``n`` is the number of points and ``x`` the frequency of the last point. Instead, one can also specify a file that contains the frequency mesh as a list with ``MESH filename``. (Default 10 10.0)
``NOZERO``: Neglect zero order terms in the self-energy coming from combinations of divergent terms math:`{1/k}` and math:`{1/k^2}` in the (bare or screened) interaction with linear and quadratic terms of the other quantities. This is necessary to converge the k-point sampling for materials with small band gaps. (Default false)
``RPAENE``: Calculate RPA correlation energy "on the fly". (Default false)
``VXC READ/CALC``: Specifies whether the vxc matrix elements are calculated or read from the file ``vxcfull``. (Default READ)
.. note:: ``IMAGTIME``: Since version 02.00 the correlation self-energy is evaluated by a direct frequency convolution of {G} and {W} rather than a multiplication in imaginary time. With the keyword ``IMAGTIME`` the latter (older) algorithm can still be used. (In some cases the old algorithm is considerably faster.) (Default false) :)
Section ``WANNIER``
--------------------
``FROZEN e``: Use frozen energy window. Lower bound is defined automatically, upper bound can be defined with the optional parameter ``e``. If ``e`` is not given, Spex guesses a reasonable value. (Default false)
``MAXIMIZE``: Use maximally localized Wannier functions instead of the first-guess ones. (Default false)
``ORBITALS (..) (..) ..``: Defines the orbitals for the first guess. Round brackets ``()`` for atoms, square brackets ``[]`` for atom types. In the brackets, one can use ;-separated lists of s,p,d,f,px,py,pz,dxy,dyz,dxz,dz2,dx2y2,t2g,eg,fz3,fxz2,fyz2,fzxy,fxyz,fxxy,fyxy,sp,sp2,sp3,sp3d,sp3d2. Euler angles can be specified with, e.g., ``sp,120,0,0``. (Default none)
``RSITE latvec``: Calculate off-site Hubbard interaction parameters (in addition to the on-site ones) with ``latvec`` being a lattice vector, e.g., ``(0,0,1)`` or several lattice vectors, e.g., ``(0,0,1) (0,0,3)`` or ``(0,0,1)-(0,0,3)`` or ``(0,1..2,1..3)``. The latter two define a list of lattice vectors: (0,0,1), (0,0,2), (0,0,3) and (0,1,1), (0,2,1), (0,1,2), (0,2,2), (0,1,3), (0,2,3), respectively. (Default none)
(``UREAD``): Wannier U matrix elements are read from the Fleur output file. (Default false)
(``WSCALE s``): Scaling factor ``s`` for the screened Coulomb interaction for spin-wave calculations. ``s`` can be a range ...... to be completed! (Default none)
source/specifics.rst deleted 100644 → 0
View file @ 895e6d5b
.. _specifics:
===================
Specifics
===================
Spex and Fleur
---------------
In the Fleur [[input]] file there is a flag for writing out the necessary data for a Spex calculation. It is called ``gw`` and is appended to line 23 of the Fleur ``inp`` file.
[`23|vchk=F,cdinf=F,pot8=F,gw=n,numbands=N`]
``n`` can take four values:
* ``gw=0``: No output files are generated (default; the same as omitting ``gw`` and ``numbands`` altogether).
* ``gw=1``: Some basic parameters are written to several files. Otherwise Fleur runs as usual.
* ``gw=2``: All output files necessary for Spex are created and Fleur stops after one iteration (without updating the potential). In this case you should also set ``pot8=T`` and the maximal number of bands ``N``. The latter overrides the default ``neigd`` value in [[fl7para]].
* ``gw=3``: Self-consistent cycle for QSGW. Same as ``gw=1`` but adds :math:`{ \Sigma^{\mathrm{QSGW}}_{\mathrm{xc}}(\mathbf{r},\mathbf{r}')-v_{\mathrm{xc}}(\mathbf{r}) }` to the Hamiltonian in each iteration.
The output files are
* ``gwa``: Basic parameters including the atomic numbers and positions in the unit cell, lattice parameters and basis vectors, FLAPW l cutoff, and local-orbital parameters,
* ``LATTC``: FLAPW G cutoff,
* ``radfun``: radial basis functions,
* ``ecore``: core-electron functions,
* ``eig``: k points, wave-function coeffients (interstitial), energies,
* ``abcoeff``: wave-function coefficients (muffin tins),
* ``vxc``: expectation values of the xc potential (diagonal elements),
* ``vxcfull``: matrix of the xc potential,
* ``qsgw``: matrix of the QSGW self-energy (only for QSGW calculations).
Furthermore Spex needs the Fleur files [[fl7para]] and ``sym.out``.
Some comments about the DFT calculation
---------------------------------------
Accurate description of conduction states
"""""""""""""""""""""""""""""""""""""""""
As in a ''GW'' calculation the conduction states enter both the Green function and the screened interaction, they should be accurately described already in the KS system which is our starting point for the perturbation treatment. The LAPW basis, however, only guarantees well described occupied states. In order to obtain well-converged ''GW'' results, one must make the basis set more flexible, especially in the MT regions, by introducing local orbitals either at high energy parameters or as higher-order energy derivatives [see C. Friedrich et al., Phys. Rev. B 74, 045104 (2006)].
Role of semicore states
""""""""""""""""""""""""
High-lying semicore states can appear as badly described "ghost bands" in the valence band region leading to a wrong DFT ground state. A possible solution is to use local orbitals and extend the energy window, such that the semicore states are treated as valence states. On the other hand if the ghost bands are above the Fermi energy, they usually pose no problem in a DFT calculation. In a ''GW'' calculation, however, the conduction states are also relevant, and one must make sure that there are no ghost bands at all in the energy spectrum. Therefore, it might be necessary to treat more (and deeper) semicore states as valence states than are needed in the DFT calculation.
As an indication for such a case the overlap of core states with basis and wave functions calculated in the routine "checkinput" should be checked. As an example, here is the output for Strontium Titanate with a Titanium 3s ghost band::
Overlap <core|basis>
Atom type 1
u(s) udot(s)
1s -0.001431 0.000644
2s -0.000830 0.000414
3s 0.287789 -0.878671
u(p) udot(p) ulo(p) ...
2p -0.000665 0.000112 -0.000494
...
Maximum overlap <core|val> at (band/kpoint)
Atom type 1
1s 0.000611 (031/ 001)
2s 0.000343 (031/ 001)
3s 0.664265 (047/ 001)
2p 0.000340 (003/ 036) 0.000481 (003/ 042) 0.000340 (003/ 036)
...
(:OBSOLETE: !!! Overcompleteness of the interstitial plane waves
The set of interstitial plane waves (IPW) (i.e., plane waves where the MT spheres are cut out) is overcomplete in the sense that a function (defined only in the interstitial region) has a nonunique representation in this set: one can always add the Fourier coefficients of a function, which is restricted to the MT spheres and zero outside. This leads to the fact that the IPW coefficients of the wave functions might not go quickly to zero for large G vectors, especially for a large :math:`G` cutoff in the DFT calculation and large MT radii. In the ``GW`` calculation this gives rise to bad convergence with respect to the parameter ``GCUT`` (:math:`G` cutoff in Spex) as well as jumps in the band structure. In this case Spex can exploit the nonuniqueness of the coefficients to make them approach zero for large :math:`G` vectors as quickly as possible. Use the keyword ``MINCPW`` for this.:)
Setting up ``spex.inp``
-----------------------
Mixed Basis (section ``MBASIS``)
""""""""""""""""""""""""""""""""""""
The bare Coulomb scattering :math:`{ v(\mathbf r,\mathbf r') }` couples two electrons whose incoming and outgoing waves give rise to wave-function products (occupied/unoccupied). The mixed basis is optimized for representing wave-function products and derived from the FLAPW basis set. It is a combined set of interstitial plane waves (IPWs) and MT functions and is defined in section ``MBASIS`` of the input file ``spex.inp`` with the keywords
* ``GCUT``: :math:`G` cutoff for the interstitial plane waves,
* ``LCUT``: L cutoffs (one for every atom type) for the MT functions,
* ``SELECT``: determines the pairs of radial functions from whose products the MT functions are constructed. For every atom type two l cutoffs ``l1`` and ``l2`` must be specified for the functions :math:`{u_l(r)}`. Optionally l cutoffs ``l3`` and ``l4`` can also be defined for :math:`{\dot u_l(r)}`, which are neglected by default. The local orbitals, on the other hand, are always used in the construction of the products by default, but can also be chosen individually by series of zeros (neglect) and ones (select), e.g., ``10100``, ``lo1`` and ``lo2`` for occupied and unoccupied states. (Instead of ``0000111``, one can also use ``4031``.) Examples are --- ``2;3`` --- ``2,2;3,2`` --- ``2,2,10100;3,2,1110`` --- ``2,,10100;3,2,1110``
The so-defined set of product MT functions is usually highly linearly dependent. Therefore, in a subsequent optimization step one diagonalizes the overlap matrix and retains only those eigenfunctions with eigenvalues exceeding a tolerance value which is defined by the keyword ``TOL``.
* ``OPTIMIZE``: Truncation of the polarization and related matrices to ``n``x``n`` by ``MB=n`` where ``n`` is an integer number between 1 and the size of the full mixed basis. Alternatively, one can use ``PW=n`` where plane waves are used instead of the mixed basis (or better: projections of plane waves onto the mixed basis) in which case the Coulomb matrix is analytically known. In both cases (``MB`` and ``PW``), you can also specify the minimum Coulomb eigenvalue instead of ``n`` as a negative real number, e.g. ``MB=-1.0`` . Alternatively, you can specify a "pseudo" reciprocal cutoff radius as a positive real number, e.g. ``MB=4.5``, which is more suitable for convergence tests. This cutoff value :math:`{K}` is related to the minimum Coulomb eigenvalue :math:`{c}` by :math:`{K= \sqrt{4\pi/c}}`. The options ``MB`` and ``PW`` can speed up the calculation considerably.
If any of the keywords (or the whole section) is not defined, Spex guesses reasonable values according to the FLAPW basis parameters.
Coulomb Matrix (section ``COULOMB``)
""""""""""""""""""""""""""""""""""""
In many-body perturbation theory the perturbing force is the Coulomb interaction. Thus its representation in the mixed basis is one of the basic ingredients in the implementation. The IPWs are plane waves :math:`{\exp[i(\mathbf{k+G})\mathbf{r}]}` from which the MT spheres are cut away. In a MT sphere a plane wave is given by the Rayleigh expansion over l quantum numbers. In a practical implementation we must introduce an l cutoff here (keyword ``LEXP``). Multipole interactions between the periodic MT functions and their periodic images are calculated in an Ewald summation involving a real and a Fourier-space sum. The cutoff radii of these are determined during the program run. There is a scaling parameter (``SCALE``) which must be adjusted if one of the sums take much longer to evaluate than the other one. In most calculations, the default values work reliably, though.
Labels for k points (keyword ``KPT``)
"""""""""""""""""""""""""""""""""""""
The keyword ``KPT`` allows you to define labels (single characters) for k points, e.g. ``KPT X=[0,0,1]``. Here, ``X`` is the label and the square brackets denote that cartesian coordinates are used instead of internal coordinates (round brackets). Note: In order for the cartesian coordinates (square brackets) to be interpreted correctly, Spex must know the lattice constant. (In Fleur, this is the global scaling factor for the lattice vectors.) You can also add a prefactor by ``L=0.5*(0,0,1)`` or ``L=1/2*(0,0,1)``. The so-defined k points must be elements of the k mesh defined by ``BZ``. A single k point outside that mesh can be specified by the plus sign ``+`` as a special label. Each time you change this single k point you have to regenerate the k-point set and rerun the DFT code.
Job definition (keyword ``JOB``)
""""""""""""""""""""""""""""""""
The most important entry in ``spex.inp`` is the job definition. It defines what Spex should do. Each job begins with one of the keywords ``HF, QP, SUSCEP, SUSCEPR, DIELEC`` or ``SCREEN`` followed by additional parameters:
* ``HF``: Hartree-Fock correction, e.g., ``HF A:(1-3,5)`` where A is a k-point label or index and ``1-3,5`` are band indices. A spin index (up or down) can be specified by ``A:u(...)`` and ``A:d(...)``. More than one k-point definition is possible in one job, e.g., ``HF A:(1-3,5) 12:(1,2,6)``. Normally, only diagonal elements are calculated, i.e., :math:`{ \langle \phi_{n\mathbf{k}} | \Sigma_{\mathrm{x}} | \phi_{n'\mathbf{k}} \rangle }` with :math:`{ n=n' }`. Full calculations of the self-energy matrix (i.e., :math:`{ n \neq n' }`) are possible by adding ``FULL`` (e.g., ``HF FULL A:(1-10)``). This allows a subsequent self-consistent HF calculation.
* ``GW``: Quasiparticle correction with the ''GW'' approximation. Spin, k points and bands are defined as in ``HF``. A full self-energy calculation is also possible with ``GW FULL``.
* ``SUSCEP``: Calculation of the susceptibility, e.g., ``SUSCEP A:{0..2,0.01}`` where A is a k-point label or index and a frequency mesh from 0 to 2 Ha in 0.02 Ha steps is specified. A more general frequency mesh can also be specified as a list of real or complex frequencies in a file. Then simply write the file name into the brackets, e.g., ``{foo}``. A spin index (``uu, dd, ud, du`` or ``+``) can be specified with ``A:ud{...}``. The spin index ``+`` denotes addition of ``uu`` and ``dd`` and is the default. Furthermore you can add ``MB`` or ``PW`` (see above) and ``OUT=n`` (separated with commas) to the job definition. With ``OUT=n`` an ``n``x``n`` matrix is written instead of only the head element. You can also write the full matrix to a binary file with ``OUT=BIN``. An expression like ``A:u{0..2,0.01},MB=100,OUT=4`` defines one job which can be followed by additional expressions each defining one job.
* ``SUSCEPR``: Calculation of the renormalized susceptibility. Spin, k points and frequencies are defined as in ``SUSCEP``. Additionally you can specify a TDDFT kernel as in ``SUSCEPR A:{0..2,0.01},KERN=ALDA,MB=100``. As spin labels only ``ud``, ``du`` and ``+`` are allowed where the latter is the default. The former spin indices require a TDDFT kernel.
* ``DIELEC``: Calculation of the dielectric function. K points and frequencies are defined as in ``SUSCEP``. A spin index cannot be specified.
* ``SCREEN``: Calculation of the screened interaction. Syntax as in ``DIELEC``.
In the case of an "empty" job definition (``JOB``), Spex will do basic checkings and then stop. (This is useful, e.g., for a simple Wannier interpolation or P/DOS calculation.)
Output files
------------
The main results of the Spex calculation is written to standard output ([[SpexOutputFile|output example]]). You should pipe the output to a file (e.g. ``spex > spex.out``). The spectra are written to separate files:
* ``suscep``: Susceptibility head element.
* ``suscep.XXX.YYY``: Susceptibility ``XXX/YYY`` matrix element (key: ``OUT=NNN`` and ``XXX,YYY`` :math:`{\le}` ``NNN``).
* ``suscep.bin``: Binary output of the susceptibility matrix (key: ``OUT=BIN``).
* ``suscepr``: Renormalized susceptibility head element.
* ``suscepr.XXX.YYY``: Corresponding matrix element.
* ``suscepr.bin``: Binary output.
* ``dielec``: Head element of the dielectric matrix (dielectric function).
* ``dielec.XXX.YYY``: Corresponding matrix element.
* ``dielecLF``: Dielectric function with local-field effects.
* ``screen``: Screened interaction head element.
* ``screen.XXX.YYY``: Corresponding matrix element.
* ``screen.bin``: Binary output.
If more than one job is defined, the job number is appended to the file names (before the dot), e.g. ``suscep001.bin``.
There are a number of additional files which can be written during the program run (``WRITE INFO``) and which tell you more about intermediate results. Some of them are numbered, such that files are never overwritten. From time to time you should remove them from disk, because the highest file count is ``NNN=999``, and they clog up directory listings.
* ``spex.sf.NNN``: If projections ``MB=...`` or ``PW=...`` are used, these files contain the spectral function on the mesh given by ``FSPEC`` for any '''k''' point projected on :math:`{exp(ikr)}`. Column 1: Frequency, column 2: value. The files are useful to check whether the mesh is dense enough and whether the spectral function approaches zero quickly. If it does not, ``GCUT`` might be underconverged or you must use ``MINCPW``.
* ``spex.sew.NNN``: Correlation self-energy on the imaginary frequency axis (only for ``CONTINUE``). Column 1: imaginary frequency, column 2: fitted value (real part), column 3: fitted value (imaginary part), column 4: numerical value (real part), column 5: numerical value (imaginary part).
* ``spex.sec.NNN``: Correlation self-energy on the real frequency axis. Column 1: real frequency, column 2: (fitted) value (real part), column 3: (fitted) value (imaginary part).
* ``spex.head``: Head element of screened interaction on imaginary axis.
Other output files written during the run are
* ``spex.dos.NNN``: (Partial) density of states (keyword ``BANDINFO``).
* ``bands``: Wannier-interpolated band structure (written after the Wannier construction and if ``KPTPATH`` is defined).
* ``hamiltonian_r``: Wannier Hamiltonian at all R points defined by ``BZ`` (if ``bands`` is written).
* ``hamiltonian_k``: Wannier-interpolated Hamiltonian at k points defined in the file ``klist`` (if ``bands`` is written).
For certain keywords in ``spex.inp`` there are special output files that can be used for subsequent calculations.
* ``spex.mb``: Mixed product basis (keyword ``RESTART``).
* ``spex.core``: Core susceptibility (keyword ``CORES``, unmaintained).
* ``spex.cou``: Coulomb matrix (keyword ``RESTART``).
* ``spex.cous``: Special Coulomb matrix for calculation of spectra (keywords ``RESTART`` and ``NOSTORE``).
* ``spex.cor``: Renormalized dielectric matrix for correlation self-energy (keyword ``RESTART``).
* ``spex.spc``: Susceptibility/dielectric/etc. matrix for calculation of spectra (keyword ``RESTART``).
* ``spex.sigx``: Exchange self-energy (HF) matrix elements (keyword ``JOB ... FULL``, can be used with ``RESTART SIG``).
* ``spex.sigc``: Correlation self-energy (GW) matrix elements (keyword ``JOB ... FULL``, can be used with ``RESTART SIG``).
* ``spex.qsgw``: QSGW (or HF) self-energy matrix (keyword ``JOB ... FULL``) for a subsequent self-consistent-field run (``gw=3`` in the FLEUR inp file).
* ``spex.qp``: Quasiparticle energies and amplitudes (keyword ``JOB ... FULL``).
.. note:: ``spex.set.NNN``: Correlation self-energy for any quasiparticle state on the imaginary time axis (only for ``CONTINUE`` and ``IMAGTIME``). Column 1: imaginary time, column 2: interpolated value, column 3: numerical value. :)
source/theory.rst deleted 100644 → 0
View file @ 895e6d5b
.. _theory:
========
Theory
========
.. _gw:
``GW`` calculations
--------------------
The ''GW'' approach has become a routine method to calculate quasiparticle spectra from first principles. It is based on many-body perturbation theory, in which the Dyson equation (here in simplified notation)
:math:`{\displaystyle G(\omega)=G_0(\omega)+G_0(\omega)[\Sigma^{\mathrm{xc}}(\omega)-v^{\mathrm{xc}}]G(\omega)}`
links the interacting Green function :math:`{G}` to the non-interacting one :math:`{G_0}`. (A non-magnetic system is considered in this section for simplicity.) The latter is obtained from a mean-field solution with frequency-independent potential :math:`{v^{\mathrm{xc}}}`, which in the case of a KS system would correspond to the local exchange-correlation potential (the nonlocal Hartree-Fock exchange potential and the ''hermitianized'' self-energy of QSGW are other examples). The self-energy :math:`{\Sigma^{\mathrm{xc}}}` connects the non-interacting mean-field system to the real interacting system and thus accounts for the many-body electronic exchange and correlation effects. It is not known exactly and must be approximated in practice. The most popular approximation to the electronic self-energy is the GW approximation,
: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'\,}`
which has been shown to yield accurate band structures for a wide range of materials. Here, :math:`{G}` is the single-particle Green function (usually :math:`{G_0}` is employed) and :math:`{W}` is the screened Coulomb interaction, which is the effective interaction potential in an interacting system, incorporating the dynamical screening processes. The screened Coulomb interaction is the solution of a Dyson-type equation
:math:`{\displaystyle W(\omega)=v+vP(\omega)W(\omega)\,}`
with the random-phase approximation for the polarization function :math:`{P}`
.. _eqP:
:math:`{\displaystyle P(\omega)=-\frac{i}{\pi}\int_{-\infty}^\infty G(\omega-\omega')G(\omega')d\omega'\,.}`
Usually, the Green function :math:`{G_0}` of a mean-field system is taken for :math:`{G}`, in which case it takes the form
.. _eqG0:
:math:`{\displaystyle G_0(\mathbf{r},\mathbf{r}';\omega)=\sum_\mathbf{k}\sum_n \frac{\phi_{\mathbf{k}n}(\mathbf{r})\phi^*_{\mathbf{k}n}(\mathbf{r}')}{\omega-\epsilon_{\mathbf{k}n}+ i\eta\mathrm{sgn}(-\epsilon_{\mathbf{k}n}\mathrm{F}}\,,}`
where :math:`{\phi_{n\mathbf{k}}(\mathbf{r})}` and :math:`{\epsilon_{n\mathbf{k}}}` are the eigenfunctions and eigenvalues, respectively, of the mean-field system. Here, a natural choice is to employ the solution of the KS equations
:math:`{\displaystyle\left\{-\frac{\nabla}{2}+v^\mathrm{ext}(\mathbf{r})+v^\mathrm{H}(\mathbf{r})+v^\mathrm{xc}(\mathbf{r})\right\}\phi_{\mathbf{k}n}(\mathbf{r})=\epsilon_{\mathbf{k}n}\phi_{\mathbf{k}n}(\mathbf{r})\,,}`
often with the local-density approximation (LDA) for the exchange-correlation potential. In this respect, one says that LDA is the ''starting point'' for the ''GW'' calculation. Other starting points are generalized gradient approximation (GGA), LDA+''U'', hybrid functionals, Hartree-Fock, QSGW, et cetera. The explicit form of :math:`{G_0}` enables us to perform the frequency integration in [[#eq:P|:math:`{P}`]], which yields
.. _eqPexp:
:math:`{\displaystyle P\left(\mathbf{r},\mathbf{r}',\omega\right)=2\sum_{\mathbf{q},\mathbf{k}}^{\mathrm{BZ}}\sum_{n}^{\mathrm{occ}}\sum_{n'}^{\mathrm{unocc}}\phi_{\mathbf{q}n}\left(\mathbf{r}\right)\phi_{\mathbf{q}n}^{*}\left(\mathbf{r}'\right)\phi_{\mathbf{q}+\mathbf{k}n'}\left(\mathbf{r}'\right)\phi_{\mathbf{q}+\mathbf{k}n'}^{*}\left(\mathbf{r}\right)\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(\mathbf{r},\mathbf{r}';\omega')}{\omega-\omega'+i\eta\mathrm{sgn}(\omega')}d\omega'\,,}`
where the last equality implicitly defines the spectral function :math:`{S(\omega)}`.
The Dyson equation can be rewritten in the form of an effective equation of motion of a single particle, the quasiparticle equation
.. _eqPexq:
: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})}`
with the (non-orthonormal) quasiparticle wavefunctions and (complex-valued) quasiparticle energies. It can be shown that the interacting Green function takes the same form as [[#eq:G0|:math:`{G_0}`]] (Lehmann representation) if the eigenfunctions and eigenvalues are replaced by the latter. The fact that this equation of motion is formally similar to the KS equation motivates to use perturbation theory of first order and write the quasiparticle energies as
.. _eqqppert:
:math:`{\displaystyle E_{n\mathbf{k}}=\epsilon_{n\mathbf{k}}+\langle\phi_{n\mathbf{k}}|\Sigma^\mathrm{xc}(E_{n\mathbf{k}})-v^\mathrm{xc}|\phi_{n\mathbf{k}}\rangle\approx\epsilon_{n\mathbf{k}}+Z_{n\mathbf{k}}\langle\phi_{n\mathbf{k}}|\Sigma^\mathrm{xc}(\epsilon_{n\mathbf{k}})-v^\mathrm{xc}|\phi_{n\mathbf{k}}\rangle}`
with the renormalization constant :math:`{Z_{n\mathbf{k}}=[1-\partial\Sigma^{\mathrm{xc}}/\partial\omega(\epsilon_{n\mathbf{k}})]^{-1}}`. Both expressions can be taken to evaluate the quasiparticle energy, the first one is a non-linear equation in :math:`{E_{n\mathbf{k}}}` and requires an iterative solution. We thus have three ways to calculate the quasiparticle energies: (a) by solving the full [[#eq:qpeq|quasiparticle equation]], (b) with the [[#eq:qppert|non-linear equation]], and (c) using the [[#eq:qppert|linearized solution]]. The mathematical complexity, the computational cost, and the accuracy decreases in this order. For example, solution (a) requires the full self-energy matrix (i.e., including the off-diagonal elements) to be evaluated. Once the full matrix :math:`{\Sigma^\mathrm{xc}_{\mathbf{k},nn'}(\omega)}` is known, one can proceed to perform a self-consistent calculation within the QSGW approach. In this approach, the self-energy matrix is ''hermitianized'' and made frequency independent. This self-energy can then be used to replace :math:`{v^\mathrm{xc}}` in the KS equation, defining a new mean-field system. A self-consistent solution of this mean-field system (using a DFT code) is then employed as a new starting point and so on until self-consistency in the quasiparticle energies is achieved.
Interaction parameters (Hubbard ``U``)
--------------------------------------
Wannier functions
--------------------
RPA exchange-correlation energy
-------------------------------
Spectra (EELS, spin excitation spectra etc.)
--------------------------------------------