3. General information

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 Section 1).

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.

3.1. 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: use file as input file instead of the default “spex.inp”
  • -w: set WRTKPT automatically
  • -o=opt: use special integer option parameter opt (for debugging and testing).

3.2. 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.
  • 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.
  • 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

SECTION SENERGY
  CONTINUE
  SPECTRAL {-10eV:1eV,0.01eV}
END

(The indentation is not mandatory and only included here for clarity.)

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.

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).

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.

3.3. 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:

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 “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.

Often, when an MPI run stops with an error, the output gets cluttered with many error messages from the MPI library and the operating system. In this case, you should find the relevant Spex error message before these lines.

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

For the parallelized version, Spex has to be run through an MPI launcher, for example, mpiexec -np 8 spex. See Section 7 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 Section 5.

For reference, we give a list here:

“spex.cor”
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.mb”
MT product basis
“spex.core”
Core contribution to susceptibility (it is k-independent, therefore precalculated)
“spex.dos”
Density of states
“spex.sigx”
Exchange (HF or COHSEX) self-energy
“spex.sigc”
Correlation (GW) self-energy
“spex.sigt”
Correlation (GT) self-energy
“spex.ccou”
Contracted screened Coulomb interaction (e.g., for COHSEX)
“spex.wcou”
Wannier-projected Coulomb interaction parameters (Hubbard U)
“spex.uwan”
Wannier transformation matrix U
“spex.kolap”
Overlap matrix (across k points) for Wannier construction with Wannier90
“suscep”, “dielec”, etc.
Files containing spectra
“<KS>”
KS eigensolutions (the name depends on the DFT program used, e.g., “KS.hdf”.)