Merge branch 'master' of iffgit.fz-juelich.de:spex/spex-docs

.gitignore

 build
 .gitlab-ci.yml
+sec
+*~

source/_static/theme_overrides.css

+/* override table width restrictions */
+@media screen and (min-width: 767px) {
+
+   .wy-table-responsive table td {
+      /* !important prevents the common CSS stylesheets from overriding
+ *          this as on RTD they are loaded after this stylesheet */
+      white-space: normal !important;
+   }
+
+   .wy-table-responsive {
+      overflow: visible !important;
+   }
+}

source/conf.py

@@ -21,15 +21,14 @@ def setup(app):
 
 # -- Project information -----------------------------------------------------
 
-project = 'spex'
-copyright = '2018, PGI, Forschungszentrum Juelich, Germany'
-author = 'spex team'
+project = 'Spex'
+copyright = u'2019, PGI, Forschungszentrum J\u00fclich, Germany'
+author = ''
 
 # The short X.Y version
 version = '0.0.1'
 # The full version, including alpha/beta/rc tags
-release = '0.0.1'
-
+release = open('version').read()
 
 # -- General configuration ---------------------------------------------------
 
@@ -106,6 +105,13 @@ html_theme_options = {
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
 
+html_context = {
+    'css_files': [
+        '_static/theme_overrides.css',  # override wide tables in RTD theme
+        ],
+     }
+
+
 # Custom sidebar templates, must be a dictionary that maps document names
 # to template names.
 #
@@ -147,8 +153,8 @@ latex_elements = {
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    (master_doc, 'spex.tex', 'spex Documentation',
-     'Spex Team', 'manual'),
+    (master_doc, 'spex.tex', 'Spex Manual',
+     '', 'manual'),
 ]
 
 
@@ -157,7 +163,7 @@ latex_documents = [
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    (master_doc, 'spex', 'spex Documentation',
+    (master_doc, 'Spex', 'Spex Manual',
      [author], 1)
 ]
 
@@ -168,8 +174,8 @@ man_pages = [
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-    (master_doc, 'spex', 'spex Documentation',
-     author, 'spex', 'One line description of project.',
+    (master_doc, 'Spex', 'Spex Manual',
+     author, 'Spex', 'One line description of project.',
      'Miscellaneous'),
 ]
 
@@ -195,5 +201,5 @@ epub_copyright = copyright
 epub_exclude_files = ['search.html']
 
 latex_elements = {
-        'releasename' : 'Version'
-        }
+      'releasename' : 'Version'
+      }

source/general_information.rst

@@ -4,9 +4,13 @@
 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``.)
+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".)
 
-.. 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 (*) at first reading.
+.. 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.
+
+.. _cmdlineopt:
 
 Command-line options
 +++++++++++++++++++++++++++++
@@ -14,24 +18,24 @@ The Spex code recognizes several command-line options (``spex [OPTIONS]``):
 
 * ``--version``:  output version information and exit
 * ``--help``:	display help and exit
-* ``--inp=file``: uSie wollen den Besitz und Betrieb von Medienunternehmen doch nicht ernsthaft mit der Entgegennahme von unversteuerten Geschenken von auslndischen Politikern vergleichen.se file as input file instead of the default "spex.inp"
+* ``--inp=file``: use file as input file instead of the default "spex.inp"
 * ``-w``: set ``WRTKPT`` automatically
-* ``-o=opt``: use special option ``opt`` (for debugging and testing).
+* ``-o=opt``: use special integer option parameter ``opt`` (for debugging and testing).
 
 Input file
 ++++++++++++
-By default, Spex reads input parameters from the file ``spex.inp``. The syntax is as follows.
+By default, Spex reads input parameters from the file "spex.inp". The syntax is as follows.
 
-* The file ``spex.inp`` does not use a fixed format, and the keywords may be given in any order.
+* 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.
 * Keywords must not be specified more than once.
-* Some keywords are grouped in sections. A section starts with ``SECTION`` sectionname and ends with END.
+* Some keywords are grouped in sections. A section starts with ``SECTION sectionname`` and ends with ``END``.
 * 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.
 * Most keyword parameters have default values that are used if the keyword is not specified.
-* By default, parameters are given in atomic units. In the case of energies, it is possible to use eV instead, e.g., 1.0eV.
-* The input file can be truncated with the keyword EXIT. Everything after EXIT is ignored.
+* By default, parameters are given in atomic units. In the case of energies, it is possible to use eV instead, e.g., ``1.0eV``.
+* The input file can be truncated with the keyword ``EXIT``. Everything after ``EXIT`` is ignored.
 * Currently, there are six section keywords: ``MBASIS``, ``WFPROD``, ``COULOMB``, ``SUSCEP``, ``SENERGY``, and ``WANNIER``.
 
 An example for a section in the input file is
@@ -51,31 +55,38 @@ An example for a section in the input file is
 
 Output files
 ++++++++++++
-The main output file of a Spex calculation is written directly to standard output (stdout). Errors, warnings, and (additional) info(rmation) are written to standard error (stderr). Errors stop the program run. Errors, warnings, and infos are of the form::
+The main output file of a Spex calculation is written directly to standard output (stdout). 
+Errors, warnings, and (additional) info(rmation) are written to standard error (stderr). 
+Errors stop the program run. Errors, warnings, and infos are of the form::
 
-  routine: Error message.
-  routine: Warning! Warning message.
-  routine: Info! Info message.
+  SPEX-ERROR (source.f:0123) Error message.
+  SPEX-BUG (source.f:0123) Error message.
+  SPEX-WARNING (source.f:0123) Warning message.
+  SPEX-INFO (source.f:0123) Info message.
 
-respectively, where routine is the name of the subroutine where the error (etc.) has occurred. An error message that ends on ... (bug?) indicates a possible bug in the code (please inform the developers).
+respectively, where "source.f" is the name of the source file and 0123 is the respective line where the error (etc.) 
+has occurred. 
+An error message starting with ``SPEX-BUG`` is likely caused by a bug in the code (please inform the developers).
+A warning message indicates a possible problem in the calculation, but the calculation continues anyway.
+An info message informs about a less important issue, for example, about the usage of obsolete syntax in the input file.
 
 It is recommendable to pipe the output to a file (in Bash)
 
-Pipes stdout to spex.out and stderr to the screen::
+Pipes stdout to "spex.out" and stderr to the screen::
 
   $ spex > spex.out
 
-Pipes stdout and stderr to spex.out::
+Pipes stdout and stderr to "spex.out"::
 
   $ spex &> spex.out
 
-Pipes stdout to spex.out and stderr to spex.err::
+Pipes stdout to "spex.out" and stderr to "spex.err"::
 
   $ spex > spex.out 2> spex.err
 
+For the parallelized version, Spex has to be run through an MPI launcher, for example,
+``mpiexec -np 8 spex``. See :numref:`parallel` for details.
 
-Depending on the job type and keywords, there are additional output files containing, for example, the resulting spectra. These output files can be in ASCII and binary format. Further details are given in the :ref:`tutorials`.
-
-
-
+Depending on the job type and keywords, there are additional output files containing, for example, the resulting spectra. 
+These output files can be in ASCII and binary format. Further details are given in :numref:`tutorials`.
 

source/getting_started.rst

@@ -6,21 +6,28 @@ Getting Started
 
 This section is intended to give a first impression on how a typical calculation is carried out. Details are given in later sections.
 
-Many-body perturbation theory is defined with respect to a formally unperturbed system, i.e., a system without electron-electron interaction. Any mean-field theory, e.g., Hartree-Fock or Kohn-Sham (KS) DFT, provides such a system. Thus before running Spex we must find a self-consistent mean-field solution. Normally this first step is fast and we can use a dense k-point set. For the calculation with Spex we have to generate a new (and usually coarser) k-point set and calculate the corresponding wave functions and energies with the mean-field program in a second run. Thus a typical procedure is
+Many-body perturbation theory is defined with respect to a formally unperturbed system, i.e., a system without electron-electron interaction. 
+Any mean-field theory, e.g., Hartree-Fock or Kohn-Sham (KS) DFT, provides such a system. Thus, before running Spex, we must find a self-consistent 
+mean-field solution. Normally this first step is fast and we can use a dense k-point set. For the calculation with Spex, we have to generate a new 
+(and usually coarser) k-point set and calculate the corresponding wavefunctions and energies with the mean-field program in a second run. 
+Thus, a typical procedure is
 
   1. self-consistent DFT calculation (e.g. with Fleur),
   2. generate new k-point set with Spex,
   3. second run of the DFT program to generate the eigenstates at the new k points,
   4. finally run Spex.
 
-For the first and third step consult the manual of your DFT program. (Click `here`_ for the Fleur manual and also read the section `Spex and Fleur`_. You must set ``gw=1`` and ``gw=2`` for the first and third step, respectively.) For the second and fourth step you need to create an input file ``spex.inp`` for Spex. A very simple input file for a GW calculation of Si is this:
+Of course, for subsequent Spex runs, steps 1-3 need not be repeated, unless the reference mean-field system is to be
+recalculated with different parameters (e.g., different k-point set or different crystal structure).
+For the first and third step consult the manual of your DFT program. (Click `here`_ for the Fleur manual and also read 
+:numref:`SpexandFleur`. You must set ``gw=1`` and ``gw=2`` for the first and third step, respectively.) 
+For the second and fourth step you need to create an input file "spex.inp" for Spex. A very simple input file for a *GW* calculation of Si is this:
 
 .. _here: http://www.flapw.de/pm/index.php?n=User-Documentation.FLEUR 
-.. _Spex and Fleur: http://www.flapw.de/pm/index.php?n=User-Documentation.SPEX-FLEUR#Fleur
 
 .. code-block:: bash
 
-  # Quasiparticle energies of bands at the high-symmetry points Gamma, X and L.
+  # Quasiparticle energies of bands at the high-symmetry points Gamma, X, and L.
 
   BZ 4 4 4
   WRTKPT
@@ -28,10 +35,11 @@ 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 tutorials and other chapter for a full list of available keywords
+.. note:: Refer to the tutorials and other chapters 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.
+For the second step, only the lines beginning with ``BZ`` and ``WRTKPT`` are necessary. The line ``BZ 4 4 4`` defines a :math:`4\times 4\times 4` k-point set, and the keyword ``WRTKPT`` tells Spex to write the (irreducible) k-points to a file ("kpts" for Fleur) and stop.
 
-For the fourth step you must remove (or comment out) the keyword ``WRTKPT``. Now all other parameters are needed. The results are written to standard output and should be piped to a :ref:`spex.out` file. As long as you do not change the k-point set, the first three steps need not be repeated for a new run of Spex.
+For the fourth step, you must remove (or comment out) the keyword ``WRTKPT``. Now all other parameters are needed. 
+The results are written to standard output and should be piped to an output file (:numref:`spex.out`). 
 
-.. note:: As an alternative to ``WRTKPT``, the command line option -w can be used (``spex -w``). It sets the keyword ``WRTKPT`` automatically.
+.. note:: As an alternative to ``WRTKPT``, the command line option ``-w`` can be used (``spex -w``). It sets the keyword ``WRTKPT`` automatically (:numref:`cmdlineopt`).

source/index.rst

@@ -3,27 +3,37 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to spex's documentation!
+Spex Manual
 ================================
-Spex is a computer code based on many-body perturbation theory. It uses the all-electron full-potential linearized augmented plane-wave method (FLAPW), which provides an accurate basis set for all kinds of materials including transition metals, oxides and even f-electron systems.
 
-Currently Spex can calculate quasiparticle properties (one-shot and self-consistent) using the GW approximation, EELS and optical spectra as well as total energies in the RPA approximation, and spin-wave spectra from the Bethe-Salpeter equation. (TDDFT is implemented but unmaintained at the moment.)
+Spex is a computer code based on many-body perturbation theory. 
+It uses the all-electron full-potential linearized augmented plane-wave method (FLAPW), 
+which provides an accurate basis set for all kinds of materials including transition metals, 
+oxides, and even f-electron systems.
+
+Currently Spex can calculate quasiparticle properties (one-shot and self-consistent) 
+using the *GW* approximation, EELS and optical spectra as well as total energies 
+in the RPA approximation, and spin-wave spectra from the Bethe-Salpeter equation. 
+(TDDFT is implemented but unmaintained at the moment.)
 
 It needs input from a converged DFT calculation, which can be generated by Fleur but also by any other FLAPW-DFT code.
 
-If you use SPEX for your research, please cite the following work:
+If you use Spex for your research, please cite the following work:
 
-.. 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)*.
+.. 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
-   
+   :numbered:
+
    installation
    getting_started
    general_information
    common_keywords
    tutorials
    basis_sets
+   parallelized_version
+   spex_and_fleur
    spex_faq
 
 

source/installation.rst

@@ -6,23 +6,29 @@ Installation
 
 The Spex source code cannot be downloaded directly. Please contact c.friedrich@fz-juelich.de
 
-Install prerequisite software
-+++++++++++++++++++++++++++++
+Prerequisite software
+++++++++++++++++++++++
 For compiling the source you need:
 
-* a modern FORTRAN compiler (the code uses some FORTRAN 2008 functionality),
+* a modern FORTRAN compiler,
 * the BLAS, LAPACK, FFTW, and HDF5 libraries as well as the Wannier90 library if you need Wannier support,
 * an implementation of the MPI-3 standard if you intend to compile the parallel version.
  
 
-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:
+Compilation
+++++++++++++
+Once you have obtained the code ("spexVERSION.tgz") unpack it and change 
+to the "spexVERSION" directory, where "VERSION" is the version number, e.g. "05.00". There, you find 
+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 working executables. 
+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(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).
+* ``--enable-parallel``: Build parallel version (requires an MPI-3 compiler).
+* ``--enable-load``: Load wavefunctions 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 
+Enter ``./configure -h`` for a full list of configuration options.
 
+.. note:: If the configuration fails, the file "config.log" should be consulted for more details about the failure. In most cases, the compiler does not find a required library or an include file, in which case the corresponding directories must be specified with the environment variables LDFLAGS and FCFLAGS, respectively.

source/parallelized_version.rst

+.. _parallel:
+
+=====================
+Parallelized version
+=====================
+
+General remarks
+++++++++++++++++
+
+The parallelized version of Spex uses the MPI standard 3.1. 
+It can be run on several CPUs on the same node or on several nodes with the command ``mpirun`` or ``mpiexec`` or 
+whatever MPI launcher your computer system uses. In principle, there are no restrictions with respect to 
+the number of processes. A better performance is expected, though, if the number of processes is not a 
+prime number but has a long prime factorization because this gives the code more freedom to distribute 
+the work among the processes.
+
+The default parallelization strategy of Spex is conservative in the sense that memory demand and 
+load imbalances are minimized. Often, the parallelized run can be sped up substantially by using ``MPIKPT``
+or ``MPIBLK``, see below.
+
+Special MPI keywords
++++++++++++++++++++++
+
+MPISPLIT
+---------
+(*) The shared-memory functionality of MPI 3.1 is used for several big arrays, 
+which allows the same memory region to be accessed by several MPI processes. 
+By default, all processes running on one node share the memory. 
+It can be reasonable to change this behavior to, e.g., having processes on the same socket to share memory. 
+This is possible with ``MPISPLIT SHRD=NODE`` (default), ``MPISPLIT SHRD=SOCKET`` (only works with ``OpenMPI``), or ``MPISPLIT SHRD=n``, 
+where n is the number of the shared-memory processes. 
+Using this option increases the memory consumption but might be advantageous 
+in terms of computation time. (There is not much experience yet with this option.)
+
+MPIKPT
+-------
+In many calculation types (*GW*, Hubbard *U* calculations, COHSEX, ...) there is an outer loop over the k-point set. 
+By default, Spex does not parallelize over this loop because different k points need different computation times depending on their symmetry,
+making the work distribution non-trivial. However, if there are many k points, it is recommendable to additionally
+parallelize over this loop. This can be enabled with the keyword ``MPIKPT``. The k-loop parallelization is over nodes, not over processes. 
+The computation for each individual k point runs in parallel over the processes on the respective node, in the same way as all processes would without ``MPIKPT``.
+If you only have a single node (or very few nodes) available, you can still use ``MPIKPT`` in conjunction with ``MPISPLIT``, which
+allows processes to be grouped into virtual nodes.
+
+MPIBLK (SENERGY)
+-----------------
+Another special parallelization layer is the parallelization over blocks of the self-energy matrix (or over the diagonal elements).
+This may speed up the calculation if there are many blocks but may also result in work inbalance. (Different blocks need different
+computation times.) Parallelization over blocks is enabled with the keyword ``MPIBLK``. (An optional argument, e.g., ``MPIBLK 5``, can
+be used to fine-tune the work distribution. It gives the "relative computational overhead" of each block that does not
+scale with the number of bands.
+The default value is 10.) ``MPIBLK`` is enabled automatically for the jobs ``HF``, ``PBE0``, ``SX``, and ``COSX``.
+
+.. list-table:: Examples
+   :widths:  18 100
+ 
+   * - ``MPIBLK``
+     -  Enable parallelization over self-energy blocks (or diagonal elements).
+   * - ``MPIBLK 50``
+     -  Enable parallelization with assumed large "computational overhead".
+   * - ``MPIBLK 0``
+     -  Disable parallellization over blocks.
+
+MPISYM (SENERGY)
+----------------
+(*) Using Padé approximants in the evaluation of the *GW* self-energy (``CONTINUE`` or ``CONTOUR`` with Padé approximant for *W* or
+``FREQINT PADE``)
+might lead to a slight symmetry breaking in the quasiparticle energies, leading to unphysical lifting of degeneracies.
+(This is caused by the fact that Thiele's continued-fraction Padé formula is numerically unstable, especially for a large number
+of imaginary frequencies.)
+Since these errors are usually very small, this is not a big problem. Furthermore, when the full self-energy matrix is calculated
+(e.g., ``GW FULL``), Spex performs a symmetrization of the self-energy matrix, which enforces the correct degeneracies again.
+However, for testing purposes, it is possible to enforce the correct symmetries already in the evaluation of the self-energy by
+using the keyword ``MPISYM``. This requires additional communication among the processes, potentially slowing down
+the calculation due to the necessary blocking synchronization.
+
+RESTART
+--------
+In the parallelized version, the ``RESTART`` option works in exactly the same way as for the serial version
+(see :numref:`RESTART_GW` and :numref:`RESTART_U`). However, the restart 
+data might be written to separate files when ``MPIKPT`` is used. (The underlying reason for this is that binary or HDF5 files can be written
+in parallel, i.e., by all processes at the same time, only if the dataset sizes are known in advance. This is not the case for the restart data.)
+Instead of a single file "spex.cor", Spex writes the files "spex.cor.1", "spex.cor.2",
+et cetera, and a directory "spex.cor.map", which contains, for each k point, *links* to the respective *cor file* that contains the data. 
+Furthermore, in addition to "spex.sigc" ("spex.sigx", "spex.wcou", "spex.ccou", "spex.core"), 
+the files "spex.sigc.2", "spex.sigc.3", et cetera, might be
+written (and analogously for the other file names). These multiple files should be taken into account, when restart files are transferred. 
+Switching between different numbers of processes, different numbers of nodes,
+or between serial and parallel runs should not lead to problems. Spex should be able to always read the correct data.

source/spex_and_fleur.rst

+.. _SpexandFleur:
+
+===============
+Spex and Fleur
+===============
+
+Spex needs input data about a reference mean-field system, for example, the KS system of DFT. A self-consistent mean-field
+calculation must thus precede any Spex calculation. The following three steps prepare the input data for Spex.
+
+:Step 1: Self-consistent mean-field calculation.
+:Step 2: Generate special k-point set with Spex.
+:Step 3: Diagonalize mean-field Hamiltonian with the potential from step 1, which produces the eigensolutions at the new k points.
+
+Fleur
+++++++
+
+The Fleur code is an implementation of KS-DFT based on the FLAPW method. Consult the `Fleur manual`_ for details.
+
+.. _Fleur manual: http://www.flapw.de/pm/index.php?n=User-Documentation.FLEUR 
+
+We distinguish between an old and a new generation of Fleur versions. In the long run, the old versions will become
+obsolete. However, as of now, the new Fleur versions have not been completely integrated.
+Therefore, both are documented here.
+
+Old 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{xc,QSGW}}(\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),
+* "KS.hdf": alternative to "eig" and "abcoeff" (now the default),
+* "vxc": expectation values of the xc potential (diagonal elements, obsolete),
+* "vxcfull": matrix of the xc potential,
+* "qsgw": matrix of the QSGW self-energy (only for QSGW calculations).
+
+Furthermore, Spex needs the Fleur file "sym.out".
+
+New Fleur
+==========
+Spex has to be compiled with ``-DFleurMax`` to make it compatible with the new Fleur "MaX" versions. 
+
+...(undocumented)...
+
+Remarks about MT basis
++++++++++++++++++++++++
+
+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 [Phys. Rev. B 74, 045104 (2006), Comput. Phys. Commun., 184, 2670 (2013)].
+
+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 wavefunctions calculated in the routine "checkinput" 
+should be checked. As an example, here is the output for Strontium Titanate with a Titanium 3s ghost band:
+
+.. code-block:: bash
+
+  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)
+  ...
+

source/spex_faq.rst

@@ -47,7 +47,7 @@ Usage
   * In the calculation of the susceptibility groups of degenerate states are split into different packets. This can only be avoided with a larger ``MEM`` if possible.
   * The tetrahedron method breaks the symmetry. You can use ``GAUSS`` to test this.
 
-**My ``GW`` calculations do not converge wrt the k-point set.**
+**My GW calculations do not converge wrt the k-point set.**
 
 .. highlights:: In systems with small band gaps (e.g. GaAs) the default treatment of the point k=0 might lead to bad k-point convergence. In this case try the option ``NOZERO`` which guarantees a smooth (but slower) convergence. 
 
@@ -65,27 +65,71 @@ Usage
 
 Error Messages
 --------------
-.. highlights:: This is not a complete list of errors. In many error messages a possible solution is already indicated. These are not listed. The program might also stop at places where this is not supposed to happen. Then the message ends with ``...(bug?)``. In this case you should contact the programmers.
+.. highlights:: This is not a complete list of errors. In many error messages a possible solution is already indicated. These are not listed. 
+   The program might also stop at places where this is not supposed to happen. Then, the error message starts with ``SPEX-BUG`` (see :numref:`spex.out`). 
+   In this case you should contact the programmers. Error messages have the form ``SPEX-ERROR (source.f:0123) Error message``, where
+   "source.f" is the name of the source file and 0123 is the respective line where the error occurred. We shorten this to ``(source.f) Error message`` in this list.
  
 **error while loading shared libraries: lib...: cannot open shared object file: No such file or directory**
 
-.. highlights:: The library "lib..." is not found in standard directories. In this case, the location of the library has to be defined in the environment variable ``LD_LIBRARY_PATH``.
+.. highlights:: The library "lib..." is not found in standard directories. In this case, the location of the library has to be defined in the 
+   environment variable ``LD_LIBRARY_PATH`` of the shell. (Consult your Unix or Linux manual.)
 
-**correlation: Solution of quasiparticle equation did not converge after 1000 iterations.**
+**(read_write.f) k-point sets inconsistent (check ...)**
 
-.. highlights:: You probably have poles very close to the real frequency axis (normally with a small weight). Usually a slight change of parameters solves the problem.
+.. highlights:: This error usually occurs if the k-point set defined in "spex.inp" (keyword ``BZ``) conflicts with the one the DFT code has used
+   for writing the input data. Make sure that the k-point sets are identical by generating the k-point set with Spex and running the one-shot
+   DFT calculation in the proper order (steps 2 and 3 in :numref:`getting_started`). (Only for older versions:)
+   The error can also be caused by the internal structure of the direct-access binary file
+   containing the wavefunction data. Make sure that Spex and the DFT code are compiled in such a way that these files are treated identically.
 
-**diagonalize_coulomb: Negative/Residual eigenvalue.**
+**(coulombmatrix.f) Negative eigenvalue.**
 
-.. highlights:: Your Coulomb matrix seems to be underconverged. Try to increase the parameter ``LEXP`` or adjust the scaling with ``SCALE``. If this does not solve the problem, the reason might be that the LAPACK routine fails to solve the general eigenvalue problem because of a nearly singular overlap matrix. Then you might try the option ``CUTZERO`` which removes linear dependencies from the overlap matrix and reattempts the diagonalization.
+.. highlights:: Your Coulomb matrix seems to be underconverged. Try to increase the parameter ``LEXP``. 
+   If this does not solve the problem, the reason might be that the LAPACK routine fails to solve the general eigenvalue problem 
+   because of a nearly singular overlap matrix. Then you might try the option ``CUTZERO`` which removes linear dependencies from 
+   the overlap matrix and reattempts the diagonalization. The accuracy of the Coulomb matrix can be tested with the (undocumented) keywords 
+   ``CHKCOUL``, ``TSTCOUL``, and ``STEPRAD`` (all in section ``COULOMB``).
 
-**intgrf: Negative exponent x in extrapolation a+c*r**x.**
+.. **intgrf: Negative exponent x in extrapolation a+c*r**x.**
+   The first (nonzero) point of your radial MT mesh might be too far away from zero. Modify the mesh accordingly. You can also try to increase ``TOL`` in section ``MBASIS``.
 
-.. highlights:: The first (nonzero) point of your radial MT mesh might be too far away from zero. Modify the mesh accordingly. You can also try to increase ``TOL`` in section ``MBASIS``.
+**(global.f) argument not an element of k-point set.** 
 
-**modulo1: argument not an element of k-point set.** 
+.. highlights:: This message is caused by an inconsistency in the k-point set. Either the k-point set defined by ``BZ``
+   and the one stored in the DFT output file are different or the k points defined by ``KPT`` are not elements of the set. 
+   The latter happens, for example, if you use a definition with square brackets (such as ``KPT A=[1,1,0]``), but 
+   the lattice constant is not properly defined (such definitions are interpreted with respect to the lattice constant).
+   In any case, it is recommended to use internal coordinates (such as ``KPT A=(0,0,1)``). See :numref:`KPT`.
 
-.. highlights:: This message is caused by an error in the k-point set. Either the k-point sets defined by ``BZ`` and in the DFT output file are different or the k points defined by ``KPT`` are not elements of the set. The latter happens, if you use ``KPT ?=[?,?,?]`` and the lattice constant is not properly defined since ``[?,?,?]`` is interpreted with respect to the lattice constant.
+**(getinput.f) Defective symmetry transformation matrix.**
+
+.. highlights:: A calculated symmetry transformation matrix turned out to be non-unitary. This is usually caused by insufficient precision of
+   the lattice basis vectors provided by the DFT code. The obvious solution is to make sure that the lattice basis vectors are defined with
+   sufficient precision in the DFT code. In particular, they have to conform to the crystal symmetries with a precision of at least ten
+   significant digits.
+
+**(getinput.f) Symmetry operation ... rotates spin quantization axis.**
+
+.. highlights:: Similarly to the previous one, this error is caused by insufficient precision: Spex expects the spin-quantization axis to 
+   be invariant with respect to the crystal symmetries in the case of non-collinear magnetism. Obvious solution: Make sure that the spin-quantization axis
+   is defined with sufficient precision in the DFT code.
+
+| **(irreps.f) Broken unitarity ...**
+| **(irreps.f) Deviation in characters; too large irrep threshold increase: ...**
+
+.. highlights:: Both errors are caused by eigenstates (read from the DFT code) that are symmetry broken, i.e., they do not reflect sufficiently
+   the crystal symmetries. This could be a problem of the DFT code. At the moment, there is no general solution to this problem. The second
+   error can be circumvented, though, by setting the parameter ``irrep_threshold`` in "irreps.f" to 0, which might lead to slower calculations.
+   
+.. Found 2 states in subspace of eigenvalue  -2.12487 while expecting 4.
+   Currently no solution to this error.
+   
+**(quasiparticle.f) Solution of quasiparticle equation did not converge after 5000 iterations.**
+
+.. highlights:: If you use analytic continuation (``CONTINUE``), you probably have poles very close to the real frequency axis 
+   (normally with a small weight). Usually a slight change of parameters solves the problem. You can also try to use the keyword ``SMOOTH`` (:numref:`SMOOTH`).
+   In the case of contour integration (``CONTOUR``), strong spectral structure in the self-energy can cause this problem. For example in metallic systems, a small
+   Drude frequency can give rise to a delta-like peak in the self-energy. A possible solution in this case is to use ``PLASMA METAL`` (:numref:`PLASMA`).
 
-To be continued ...
 

source/version

+05.00pre29