general_information.rst 4.87 KB
Newer Older
1 2 3 4 5 6
.. _general_information:

===================
General information
===================

7
Although the Spex executable can have different names (e.g., "spex.inv", "spex.noinv"), 
Christoph Friedrich's avatar
Christoph Friedrich committed
8
we assume that "spex" is the name of the executable in the following. 
9
(This can be achieved by using the caller utility, see :numref:`installation`.)
10

11 12 13
.. 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:
14 15 16 17 18 19 20

Command-line options
+++++++++++++++++++++++++++++
The Spex code recognizes several command-line options (``spex [OPTIONS]``):

* ``--version``:  output version information and exit
* ``--help``:	display help and exit
21
* ``--inp=file``: use file as input file instead of the default "spex.inp"
22
* ``-w``: set ``WRTKPT`` automatically
23
* ``-o=opt``: use special integer option parameter ``opt`` (for debugging and testing).
24 25 26

Input file
++++++++++++
27 28
By default, Spex reads input parameters from the file "spex.inp".
The syntax is as follows.
29

30
* The file "spex.inp" does not use a fixed format, and the keywords may be given in any order.
31 32
* Each keyword is given on one line together with its parameters following it.
* Keywords must not be specified more than once.
33
* Some keywords are grouped in sections. A section starts with ``SECTION sectionname`` and ends with ``END``.
34
* All keywords (and section names) are in capital letters.
35 36 37 38
* Everything after a ``#`` sign is interpreted as a comment. 
* Comments starting with ``##`` and ``###`` are written to standard output and standard error, respectively, see below.
* Empty lines are allowed.
* Line continuation is possible using a single backslash ``\`` at the end of the previous line.
39
* Most keyword parameters have default values that are used if the keyword is not specified.
40 41
* 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.
42 43 44 45 46 47 48 49 50 51 52 53 54
* 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.)

55 56 57 58 59
Spex writes the input file in formatted form to standard output without comments except for the special ``##`` and ``###`` comments, which are
written, respectively, to standard output (as a comment) and to standard error (as a warning). The former can be used to give details about the calculation
(example ``## silicon bulk (QSGW)``) and the latter to give a special warning (example ``### test run with extreme parameters``)
that, for greater visibility, should appear in the standard error stream.

60 61
.. 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)``.

62 63 64
The shell script "spex.setkey" allows the Spex input file to be modified from the command line. This is useful, in particular, for multiple calculations run from a batch script.
Type "spex.setkey --help" for a description.

anoop chandran's avatar
anoop chandran committed
65 66
.. _spex.out:

67 68
Output files
++++++++++++
69 70 71
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::
72

73 74 75 76
  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.
77

78 79 80 81 82
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.
83 84 85

It is recommendable to pipe the output to a file (in Bash)

86
Pipes stdout to "spex.out" and stderr to the screen::
87 88 89

  $ spex > spex.out

90
Pipes stdout and stderr to "spex.out"::
91 92 93

  $ spex &> spex.out

94
Pipes stdout to "spex.out" and stderr to "spex.err"::
95 96 97

  $ spex > spex.out 2> spex.err

98 99
For the parallelized version, Spex has to be run through an MPI launcher, for example,
``mpiexec -np 8 spex``. See :numref:`parallel` for details.
100

101 102
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`.
103