Commit 25a91c0f authored by Christoph Friedrich's avatar Christoph Friedrich

- RESTART codes included

- KPTPATH clarified
- Spex launcher script documented
parent 2cfad6c4
......@@ -101,18 +101,73 @@ This is an important keyword. It enables (a) continuing a calculation that has,
(*) We will come back to this keyword in the tutorials. Here, we give a more detailed explanation as reference.
Spex writes several files to harddisc during the program run (see :numref:`spex.out` for details):
"spex.cor", "spex.cot", "spex.ccou", "spex.mbas", "spex.core", "spex.sigx", "spex.sigc", "spex.sigt", "spex.wcou", "spex.uwan", "spex.kolap", as well as several files
"spex.cor", "spex.cot", "spex.ccou", "spex.mb", "spex.core", "spex.sigx", "spex.sigc", "spex.sigt", "spex.wcou", "spex.uwan", "spex.kolap", as well as several files
containing spectra ("suscep", "dielec", etc.) and a file "<KS>" containing the KS wavefunctions. (The name of the latter depends on the DFT program used.)
In addition to the arguments 1 and 2, described above, the keyword ``RESTART`` can be given with a general five-digit integer number, e.g., ``32233``,
which explicitly specifies which files should be read and/or written. (The first digit is optional. It is interpreted as 0 if omitted.)
The digits can be 0 (don't read and don't write), 1 (read but don't write), 2 (write but don't read), and 3 (read and write). From right to left, the digits
refer to the files (fifth digit:) "<KS>"; (fourth digit:) "spex.cor", "spex.cot", "spex.ccou", "spex.mbas", "spex.core"; (third digit:) "spex.sigx";
(second digit:) "spex.sigc", "spex.sigt", "spex.wcou", spectra files; (first digit:) "spex.uwan", "spex.kolap". (The spectra files and "spex.core" are always
written.)
The digits can be 0 (don't read and don't write), 1 (read but don't write), 2 (write but don't read), and 3 (read and write). The following table shows to which
file(s) each digit refers to.
.. list-table:: RESTART codes
:widths: 10 5 6 5 6 4
* -
- | "spex.uwan"
| "spex.kolap"
- | "spex.sigc"
| "spex.sigt"
| "spex.wcou"
| spectra files\ :sup:`1`
- | "spex.sigx"
- | "spex.cor"
| "spex.cot"
| "spex.ccou"
| "spex.mb"
| "spex.core"\ :sup:`1`
- | "<KS>"
* - Don't read, don't write
- 0
- 0
- 0
- 0
- 0
* - Read but don't write
- 1
- 1
- 1
- 1
- 1
* - Write but don't read
- 2
- 2
- 2
- 2
- 2
* - Read and write
- 3
- 3
- 3
- 3
- 3
:sup:`1`\ The spectra files and "spex.core" are always written.
The arguments 1 and 2 correspond to ``32233`` and ``33333``, respectively. The default (i.e., without ``RESTART``) is ``02200``.
When using ``MPIKPT`` in a parallel calculation, the restart data is written to multiple
files: "spex.sigx", "spex.sigx.2", "spex.sigx.3", etc. (accordingly for "spex.sigc") as well as "spex.cor.1", "spex.cor.2", etc. In the latter case, there
is also a directory "spex.cor.map" containing, for each k point, links to the respective `cor` file. Whenever restart files need to be copied, make sure that all
files (including the directory) are copied. Apart from that, Spex will always manage to read the correct data, independently of whether the calculation is
in parallel or serial, with or without ``MPIKPT``.
.. warning::
The ``RESTART`` option is a powerful tool. It is not only of practical importance due to the possibility of restarting calculations or reusing data of previous
calculations. It also gives the user a lot of freedom to taylor calculations, for example, using different k-point sets (or different numbers of bands, etc.)
for `G` and `W`. However, this freedom comes with the risk that calculations are performed with inconsistent data. Spex has only limited capabilities to catch
such inconsistencies. The user should be aware of that.
NOSTORE (COULOMB)
------------------
Most job types require the calculation of the Coulomb matrix (with respect to the mixed product basis). The Coulomb matrix is k dependent.
......
......@@ -4,9 +4,8 @@
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 :numref:`installation`.)
Although the Spex executables ("spex.inv", "spex.noinv") can be run directly,
we assume in the following that the Spex launcher script ("spex") is used (see :numref:`installation`).
.. note:: Paragraphs discussing advanced options are preceded with (*), and the ones about obsolete, unmaintained, or experimental options are marked with (**). You can safely skip the paragraphs marked with (*) and (**) at first reading.
......@@ -77,7 +76,7 @@ Errors stop the program run. Errors, warnings, and infos are of the form::
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).
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.
......@@ -107,12 +106,13 @@ These output files can be in ASCII and binary format. Further details are given
For reference, we give a list here:
"spex.cor"
Bare and screened Coulomb matrix
Bare and screened Coulomb matrix. (Depending on the type of calculation,
the susceptibility or dielec matrix might be written to "spex.cor" instead of the screened Coulomb matrix.)
"spex.cot"
`T` matrix
"spex.mbas"
"spex.mb"
MT product basis
"spex.core"
......@@ -137,7 +137,7 @@ For reference, we give a list here:
Wannier-projected Coulomb interaction parameters (Hubbard `U`)
"spex.uwan"
Wannier U transformation matrix
Wannier transformation matrix `U`
"spex.kolap"
Overlap matrix (across k points) for Wannier construction with Wannier90
......
......@@ -25,7 +25,7 @@ For the first and third step consult the manual of your DFT program. (The `Fleur
:numref:`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:
.. _Fleur manual: http://www.flapw.de/pm/index.php?n=User-Documentation.FLEUR
.. _Fleur manual: https://www.flapw.de/site/Docu-Main/
.. code-block:: bash
......@@ -45,3 +45,5 @@ For the fourth step, you must remove (or comment out) the keyword ``WRTKPT``. No
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 (:numref:`cmdlineopt`).
.. note:: Unless you intend to run self-consistent `GW` calculations, the steps 2-4 can be combined into a single Spex run using the keyword ``ITERATE``.
......@@ -27,14 +27,15 @@ Special options can be given to the configure script:
* ``--enable-mpi``: 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``).
* ``--with-dft=PROG``: Build with an interface to the DFT program "PROG" instead of the default, which is fleur.v26 (2019.02); currently, only "fleur" (Fleur MaX version 3.1) is available as an alternative.
* ``--with-dft=PROG``: Build with an interface to the DFT program "PROG" instead of the default, which is fleur.v26 (2019.02); currently, only "fleur" (FLEUR MaX Release 3 v0.27) is available as an alternative.
* ``--prefix=PREF``: Executables will be installed in directory "PREF" (/usr/local is default).
Enter ``./configure -h`` for a full list of configuration options. Also see :numref:`spex_faq_configuration` for common problems in the configuration step.
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. (Consult your Unix or Linux manual.)
Also see :numref:`spex_faq_configuration` for common problems in the configuration step.
The compilation creates the executables
......@@ -44,40 +45,19 @@ The compilation creates the executables
"spex.noinv"
for systems without inversion symmetry or with spin-orbit coupling,
"spex.x"
caller utility,
"spex.extr"
data extraction utility,
which may be installed with ``make install``. Installation is optional. See the file "INSTALL" for details.
The reason for having two executables, one for systems with inversion symmetry and the other for systems without, is that many quantities
(such as the Coulomb matrix, the screened interaction on the imaginary axis, the exchange self-energy, etc.) can be declared in the code
as real-valued instead of complex-valued arrays in the case of inversion symmetry, which speeds up the computation considerably.
(The floating-point multiplication of complex numbers are about eight times slower than the multiplication of real numbers.)
For the sake of code clarity, it is then advantageous to have two executables.
The user can call "spex.inv" or "spex.noinv" directly or use the caller utility "spex.x". The caller utility simply returns the
name of the executable that should be used for the present system ("spex.inv" or "spex.noinv") and prepends the path. (It is assumed that
all executables reside in the same directory.) This allows the proper executable to be called generally by ```spex.x``` (all shells) or
``$(spex.x)`` (BASH). The shell calls "spex.x", which returns the executable's name, and then immediately runs that executable.
For convenience, you can add the line::
alias spex='$(spex.x)'
The user can call "spex.inv" or "spex.noinv" directly or use the Spex launcher script **"spex"**, which executes the proper executable
according to the DFT data in the current directory.
(BASH) or::
alias spex '`spex.x`'
(other shells) to your shell config file (".bashrc" or similar). Spex is then called simply by::
$ spex
and the parallelized version by::
$ mpiexec -np 8 spex
as an example.
The executables and shell scripts may be installed with ``make install``. Installation is optional. See the file "INSTALL" for details.
If the directory "PREF/bin" (see --prefix option) is in the PATH environment variable, Spex can be called from the command line simply by "spex".
......@@ -77,7 +77,7 @@ 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
(see :numref:`RESTART`, :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",
......
......@@ -52,19 +52,19 @@ 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.
Spex has to be configured with ``--with-dft=fleur`` to compile the interface to the new Fleur MaX versions (see :numref:`installation`).
In the Fleur "inp.xml" file, there is a flag for writing out the necessary data for a Spex calculation.
It can be found at the following XML-path ``/calculationSetup/expertModes/@gw``, the ``numbands`` flag can be set at ``/calculationSetup/cutoffs/@numbands``.
When using the input generator for fleur it is adviseable to set the option ``-kpts_gw``.
When using the input generator for fleur it is adviseable to set the option ``-gw``.
This writes out additional options in the "inp.xml", which already include the settings for an alternative kpoint set ("kpts_gw").
The following modes are available:
* ``gw=0``: No output files are generated (default).
* ``gw=1``: The files "basis.hdf" and "ecore" are written. Needed for Spex to construct the "kpts_gw" file. The broyden history is reset. The potential is not updated and Fleur stops after writing out the files.
* ``gw=2``: All output files necessary for Spex are created and Fleur stops after one iteration (without updating the potential).
* ``gw=1``: The files "basis.hdf", "pot.hdf", and "ecore" are written. Needed for Spex to construct the "kpts_gw" file. The broyden history is reset.
* ``gw=2``: All output files necessary for Spex are created and Fleur stops after generating the KS eigensolutions (without updating the potential).
The output files are:
......@@ -78,12 +78,6 @@ Furthermore, Spex needs the Fleur file "sym.out", which contains the symmetry op
.. warning::
Self-consistent *GW* calculations (also HF, PBE0, etc.) are not yet possible with the new Fleur code. Please use the old Fleur code for this feature.
.. When running spex with the new Fleur you have to set the following in the spex.inp file:
.. code-block:: bash
SECTION SENERGY
VXC CALC
END
A short tutorial can be found at:
http://www.flapw.de/pm/index.php?n=User-Documentation.Tutorial-DFT-Lecture-2018-DAY10
......
......@@ -35,19 +35,27 @@ Configuration
You can get further information from the file "config.log".
Installation
Compilation
-------------
**My compiler fails to compile the source.**
.. highlights:: In case of compiler errors, the first thing to try is cleaning up with ``make clean`` before running ``make``.
If this does not solve the problem, please inform us.
We have successfully compiled and run the code with the Intel Fortran compiler (since version 12.1.3), Gfortran (since version 4.9), and NAG Fortran (since version 6.2 6214).
As of May 2018, PGI compilers have a bug (TPR 23745) that prevents compilation of the Spex code. For the parallelized version, we have used Intel MPI, MPICH, and Open MPI.
**My compiler fails to link the object files.**
.. highlights:: If the configuration step has run successfully (with the same system configuration), linking the object files should work. In any case, before
reporting a problem, please try cleaning up before compilation: ``make clean ; make``.
**I want to interface Spex to my own DFT program.**
.. highlights:: The data transfer between the DFT program and Spex is controlled by the routines in "readwrite_PROG.f" (where PROG stands for the name of the
DFT program). You will have to create this file (if it does not exist yet). A template file "readwrite_tmpl.f" with explanations is provided with the source.
The new file "readwrite_PROG.f" is included in the build process by reconfiguring (``./configure``) with the option ``--with-dft=PROG``.
**My compiler fails to compile the source.**
.. highlights:: We have successfully compiled and run the code with the Intel Fortran compiler (since version 12.1.3), Gfortran (since version 4.9), and NAG Fortran (since version 6.2 6214). As of May 2018, PGI compilers have a bug (TPR 23745) that prevents compilation of the Spex code. For the parallelized version, we have used IntelMPI and MPICH. In case of configuration or compilation problems, please inform us.
Usage
-------
......
......@@ -543,12 +543,11 @@ the spex.extr utility has this capability. Finally, one could simply use much de
The keyword ``KPTPATH`` can also be used for the other two methods to calculate a band structure (see :numref:`KPTadd` and :numref:`INTERPOL_GW`).
In these methods, one is not restricted to the k points of the k set and can define k-point paths with arbitrary step sizes. To this end, an integer
argument can be specified at the end of the k-path definition. For example, ``KPTPATH (L,1,X),50`` would give a k path with a step size of (roughly)
:math:`2\pi/(50\sqrt[3]{\Omega})`. The k-points given (L, :math:`\Gamma`, and X in the example) must lie on the path. The actual step size is adjusted
accordingly. Here, :math:`\Omega` is the unit-cell volume, so :math:`8\pi^3/\Omega` is the volume of the Brillouin zone and
:math:`2\pi/\sqrt[3]{\Omega}` the average reciprocal lattice constant.
Larger integer arguments give denser k meshes. The default is 20 for
the method explained in :numref:`KPTadd` and 100 for the one in :numref:`INTERPOL_GW`.
argument can be specified at the end of the k-path definition. For example, ``KPTPATH (L,1,X) 50`` would give a k path with a step size of (roughly)
:math:`K/50`, where :math:`K` is the "average reciprocal lattice constant", defined as :math:`K=2\pi/\sqrt[3]{\Omega}` with :math:`\Omega` the volume
of the unit cell. The actual step size between the defined k points (L, :math:`\Gamma`, and X in the example) is adjusted in such a way that these k points
lie on the path (hence the use of the word "roughly" above).
Larger integer arguments give denser k meshes. The default is 20 for the method explained in :numref:`KPTadd` and 100 for the one in :numref:`INTERPOL_GW`.
.. list-table:: Examples
:widths: 36 100
......@@ -557,7 +556,7 @@ the method explained in :numref:`KPTadd` and 100 for the one in :numref:`INTERPO
- Define k-point path from L over the :math:`\Gamma` point (k index is always 1) to X. The labels L and X must be defined with ``KPT``.
* - ``JOB GW PATH:(1-10)``
- Run *GW* calculation for the first ten bands at all k points defined by ``KPTPATH``.
* - ``KPTPATH (1,N),100``
* - ``KPTPATH (1,N) 100``
- Define k-point path from :math:`\Gamma` to N and use step size of :math:`2\pi/(100\sqrt[3]{\Omega})`.
.. _KPTadd:
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment