add general information, keywords and templates for tutorials

source/basis_sets.rst

+.. _basis_sets:
+
+===================
+Basis sets
+===================
+
+TODO

source/general_information.rst

+.. _general_information:
+
+===================
+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``.)
+
+.. 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.
+
+Command-line options
++++++++++++++++++++++++++++++
+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"
+* ``-w``: set ``WRTKPT`` automatically
+* ``-o=opt``: use special option ``opt`` (for debugging and testing).
+
+Input file
+++++++++++++
+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.
+* 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.
+* 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.
+* Currently, there are six section keywords: ``MBASIS``, ``WFPROD``, ``COULOMB``, ``SUSCEP``, ``SENERGY``, and ``WANNIER``.
+
+An example for a section in the input file is
+
+.. code-block:: bash
+
+  SECTION SENERGY
+    CONTINUE
+    SPECTRAL {-10eV:1eV,0.01eV}
+  END
+
+(The indentation is not mandatory and only included here for clarity.)
+
+.. note:: The keywords are detailed in the coming chapters. If a keyword belongs to a section, the section's name is specified as well, for example, ``CONTINUE (SENERGY)``.
+
+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::
+
+  routine: Error message.
+  routine: Warning! Warning message.
+  routine: Info! 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).
+
+It is recommendable to pipe the output to a file (in Bash)
+
+Pipes stdout to spex.out and stderr to the screen::
+
+  $ spex > spex.out
+
+Pipes stdout and stderr to spex.out::
+
+  $ spex &> spex.out
+
+Pipes stdout to spex.out and stderr to spex.err::
+
+  $ spex > spex.out 2> spex.err
+
+
+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`.
+
+
+
+

source/keywords.rst

+.. _keywords:
+
+************
+Keywords
+************
+
+
+Common settings
+================
+This section discusses several settings that are common for all calculations. Some of them are explained in more detail in later sections.
+
+MEM
+-----------
+Calculations based on many-body perturbation theory are costly, not only in terms of computation time but also in terms of memory. Since the problem sizes (e.g., number of atoms) are thus effectively restricted by the memory hardware of the computer, the latter constitutes in some ways a more serious limit than the computation time the user can afford to invest. Therefore, an upper limit for the memory that Spex is allowed to use can be defined with the keyword MEM x with x in MB. The default is MEM 1000. In parallel Spex, x is the upper limit per node. If possible, Spex will divide the work load into packets in such a way that the memory usage stays below the limit. (Actually, Spex might use a bit more memory than specified.)
+
++---------------+---------------+----------------------------------------------+
+| Example       |  MEM 2000     |  Restrict memory usage to 2GB (Default: 1GB) |
++---------------+---------------+----------------------------------------------+
+
+JOB
+--------
+Each Spex run needs a job definition, which defines what Spex should do, e.g., ``JOB GW 1:(1-5)`` for a ``GW`` calculation of the specified set of bands. The available jobs are
+
+* ``GW`` - GW method
+* ``HF`` - Hartree-Fock method
+* ``PBE0`` - PBE0 hybrid functional
+* ``SX`` - Screened exchange
+* ``COSX`` - Coulomb-hole screened-exchange (COHSEX)
+* ``GT`` - GT method
+* ``GWT`` - GW and GT combined
+* ``HFENE`` - Total Hartree-Fock exchange energy
+* ``RPAENE`` - RPA correlation energy
+* ``SUSCEP`` - Susceptibility (Polarization function)
+* ``SUSCEPR`` - Renormalized susceptibility (RPA or Bethe-Salpeter)
+* ``DIELEC`` - Dielectric function
+* ``SCREEN`` - Screened interaction
+* ``SCREENW`` - Screened interaction projected onto Wannier basis
+
+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                                    |
++----------+------------------------------------------+----------------------------------------------------------------------+
+
+BZ
+-----
+
+WRTKPT
+-------
+There are only two keywords that may not be omitted from the input file. The first is ``JOB``, the second ``BZ``, which defines the k-point set for the sampling of the Brillouin zone. The keyword requires four integer arguments, BZ l m n, defining an lxmxn k-point set. If the keyword ``WRTKPT`` is set (or, alternatively, with the command line option ``spex -w``), Spex uses the ``BZ`` definition to construct the irreducible wedge of the k-point set and writes the respective list of k points to a file, which is then read by the DFT code.
+
++---------+--------------+---------------------------------+
+| Example | ``BZ 8 4 2`` | Define a 8x4x2 k-point sampling |
++---------+--------------+---------------------------------+
+
+RESTART
+--------
+This is an important keyword. It enables (a) continuing a calculation that has, for some reason, stopped or crashed and (b) reusing data of a previous calculation. If specified, Spex will store intermediate results in a file or read them if the particular data is already present in the file. Even if RESTART was not specified in the first run, Spex might still be able to reuse data from a previous run with ``RESTART 2``. (This option usually gives less freedom for a change of parameters. ``RESTART 1`` and RESTART are equivalent.) It depends on the particular job definition whether ``RESTART`` and/or ``RESTART 2`` are available and how they work. See below for details.
+
++----------+---------------+----------------------------------------------+
+| Examples | ``RESTART``   | Read/write restart file                      |
+|          | ``RESTART 2`` | Try to reuse data from standard output files |
++----------+---------------+----------------------------------------------+
+
+STOREIBZ
+---------
+Spex reads wavefunctions and energies as a first step. In general, these have to be stored for all k vectors in the set (e.g., for all 64 points of a 4x4x4 set), filling up a lot of memory. This can be restricted to the irreducible zone (only eight points in the example) with the keyword ``STOREIBZ``. Spex then regenerates the wavefunctions on equivalent k points on the fly. This might slow down the calculation but is more economical with computer memory.
+
+.. note:: ``--enable-load`` (*) Another possibility to reduce the memory consumption is to reconfigure (and recompile) the code with the option --enable-load (or recompile with the flag -DLOAD in the Makefile). With this option, Spex stores the wavefunctions in memory only temporarily and rereads them from harddisc whenever they are needed. Obviously, this requires a fast harddisc and network connection. The HDF5 library is used for the data transfer. There is no possibility to set the option in the input file because it strongly affects the way the wavefunction data is handled in the code.
+
+Input data
+===========
+Spex needs data from a previous self-consistent solution of a mean-field system (e.g., KS-DFT). Several keywords can be used to analyze, check, and modify the input data.
+
+NBAND
+-----
+The Green function involves a summation over electronic bands, as do the polarization function and the self-energy. The convergence with respect to the number of bands is a very important aspect in calculations based on many-body perturbation theory. The keyword NBAND n sets the number of bands to n. Obviously, n must not be larger than the number of bands provided by the input data. It should be noted that the actual number of bands can differ from n and also from k point to k point because Spex makes sure that degenerate subspaces are not cut in order to avoid symmetry breaking. If n is a real number (i.e., if it contains a decimal point: 3.0), it is interpreted as the maximal band energy. Then, all bands up to this energy are included. This is helpful if one wants to use a single parameter for calculations with differently sized unit cells. For example, when the unit cell doubles, one would have to include twice as many bands to reach the same accuracy, while the maximal band energy practically remains unchanged. If NBAND is unset, all available bands are used.
+
++----------+--------------+-------------------------------+
+| Examples | NBAND 100    | Use 100 bands per k point     |
++----------+--------------+-------------------------------+
+|          | NBAND 3.0    | Use all bands up to 3 Hartree |
++----------+--------------+-------------------------------+
+|          | NBAND 50.0eV | Use all bands up to 50 eV     |
++----------+--------------+-------------------------------+
+
+CHKOLAP
+-------
+
+CHKMISM
+-------
+(*) The set of wavefunctions read from harddisc can be checked in terms of their orthonormality and continuity (mismatch) at the muffin-tin (MT) boundary with the keywords CHKOLAP and CHKMISM, respectively. The former test gives a value for the deviation from exact orthonormality. The smaller the value, the better the condition of orthonormality is fulfilled. If the deviation is too large, the program stops. The second keyword yields for each k point the average and maximal MT mismatch of the wavefunctions. If any of these tests yield too large errors, there could be a problem with the read-in process or with the data written by the DFT code. The developers should be informed in this case.
+
+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}`
+
++----------+------------------+------------------------------------------------------------+
+| Examples | ``MTACCUR -1 2`` | Calculate MT representation error between -1 and 2 Hartree |
++----------+------------------+------------------------------------------------------------+
+|          | ``MTACCUR``      | Automatic energy range                                     |
++----------+------------------+------------------------------------------------------------+
+
+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`` |
++---------+-----------------------+-----------------------------------------------------------------------------------------------+
+
+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) |
++---------+-------------------+---------------------------------------------------------------------------------------------------+
+
+PLUSSOC
+-------
+(*) With this keyword, Spex adds spin-orbit coupling (SOC) to the mean-field solution using a one-shot second-variation approach and stops, so it is non-iterative but updates the wavefunctions and energies. This can be used, for example, to include SOC to a previous ``GW`` calculation that has been carried out without SOC. The new energies are written to standard output and, together with the new wavefunctions, to new input files on the harddisc, thus overwriting the old input data. In the case of Fleur, the modified files are ``gwa``, ``KS.hdf``, and ``spex.sym``. The latter is written only if the system is magnetic (non-collinear magnetism). It has the same form as ``sym.out``. Spex reads the file "spex.sym" if it exists and "sym.out" otherwise. After the ``PLUSSOC`` calculation, a subsequent Spex run will read the new input data, now including SOC. (The keyword PLUSSOC must be removed for this new run, otherwise Spex stops with an error, since it cannot add SOC to a solution that contains it already.)
+
+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                  |
++----------+---------------------+----------------------------------------------------------------------------------+
+
+Parallelized version
+====================
+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.
+
+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.)
+
+

source/tutorials.rst

+.. _tutorials:
+
+===================
+Tutorials
+===================
+
+TODO