4. Common Keywords¶
This section discusses several settings that are common for all calculations. Some of them are explained in more detail in later chapters.
4.1. General Settings¶
4.1.1. JOB¶
Most Spex runs need a job definition, which defines what Spex should do, e.g., JOB GW 1:(15)
for a GW calculation of the specified set of bands. The available jobs are
GW
 GW methodHF
 HartreeFock methodPBE0
 PBE0 hybrid functionalSX
 Screened exchangeCOSX
 Coulombhole screenedexchange (COHSEX)GT
 GT methodGWT
 GW and GT combinedHFENE
 Total HartreeFock exchange energyRPAENE
 RPA correlation energySUSCEP
 Susceptibility (Polarization function)SUSCEPR
 Renormalized susceptibility (RPA or BetheSalpeter)DIELEC
 Dielectric functionSCREEN
 Screened interactionSCREENW
 Screened interaction projected onto Wannier basisKS
 Singleparticle energies (e.g., KS energies), included for completeness
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.
The job KS
is included only for convenience. When given, Spex simply writes the singleparticle energies (e.g., KS energies), read from the input data,
to the output in the standard format, similar to the output of GW or HF values.
In principle, Spex supports multiple jobs such as JOB GW 1:(15) DIELEC 1:{0:1,0.01}
.
This feature is, however, seldom used and is not guaranteed to work correctly in all versions.
JOB COSX 1:(15) 
Perform COHSEX calculation for states 1,2,…,5 at the first k point. 
JOB COSX 1:(15) SCREEN 2:{0:1,0.01} 
Subsequently, calculate the screened interaction on a frequency mesh. 
JOB GW 1:(1,2,58) 7:(13,68) 
Perform GW calculation for the specified states at the first and seventh k point. 
JOB 
Just perform some checks and stop. (Same as omitting JOB .) 
4.1.2. BZ¶
There are only two keywords that must not be omitted from the input file. The first is JOB
(Section 4.1.1), the second BZ
,
which defines the kpoint set for the sampling of the Brillouin zone. The keyword requires four integer arguments, e.g., BZ 6 6 4
,
defining, in this case, a \(6\times 6\times 4\) kpoint set. With the commandline option w
(spex w
) (or, alternatively,
if the keyword WRTKPT
is set), Spex uses the BZ
definition to construct the irreducible wedge of the kpoint set and writes the respective list
of k points to a file, which can then be read by the DFT code.
BZ 8 4 2 . 
Define an \(8\times 4\times 2\) kpoint set. 
4.1.3. WRTKPT¶
(*) When set, Spex writes a kpoint file (to be read by the DFT code) and stops (also see Section 4.1.2).
Users are advised to use the equivalent and more convenient commandline option w
, instead (Section 3.1).
4.1.4. MEM¶
Calculations based on manybody 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
followed by the upper limit, either in MB or
in percent of the total memory, as read from the entry “MemTotal” of the system file “/proc/meminfo”.
If MEM
is not specified, Spex sets the limit to 50% of the total memory. If reading from “/proc/meminfo” fails, MEM
defaults to 10 GB.
In parallel Spex, the value would correspond to the upper limit per (physical) node. If possible, Spex will divide the work load into packets in such a way that the memory usage stays below the limit.
(Spex might use a bit more memory than specified. Also keep in mind that the operating system and other tasks running on the computer need memory.)
MEM 2000 
Restrict memory usage to 2 GB. 
MEM 25% 
Restrict memory usage to 25% of the total memory. 
4.1.5. STOREBZ¶
(*) Spex reads (or calculates) wavefunctions and energies as a first step. In general, they are needed at all k vectors in the set
(e.g., for all 64 points of a \(4\times 4\times 4\) set) and would thus occupy a lot of memory.
By default, only the wavefunctions and energies in the irreducible wedge of the Brillouin zone (IBZ)
are stored in memory (e.g., eight instead of the 64 points in the case of a diamond lattice).
Spex generates the wavefunctions on k points outside the IBZ on the fly (by applying symmetry operations).
Of course, this implicates a small computational overhead and might slow down the calculation.
The keyword STOREBZ
switches this feature off and stores the wavefunctions and energies at all k points of the Brillouin zone,
which can also be helpful in code development because all wavefunctions are available in memory at all times and do not have to be generated.
(Until version 05.05, STOREBZ
was the default, and the new default was chosen with STOREIBZ
.)
4.1.6. –enableload¶
(*) Another possibility to reduce the memory consumption is to reconfigure (and recompile) the code with the option enableload
(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.
4.1.7. 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.) It depends on the particular job definition whether RESTART
and/or RESTART 2
are available and how they work. See below for details.
RESTART 
Read/write restart file. 
RESTART 1 
Same as RESTART 
RESTART 2 
Try to reuse data from standard output files. 
(*) 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 Section 3.3 for details): “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 fivedigit integer number, e.g., 22233
,
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). The following table shows to which
file(s) each digit refers to.
“spex.uwan”
“spex.kolap”

“spex.sigc”
“spex.sigt”
“spex.wcou”
spectra files^{1}

“spex.sigx”

“spex.cor”
“spex.cot”
“spex.ccou”
“spex.mb”
“spex.core”^{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 
^{1}The spectra files and “spex.core” are always written.
The arguments 1 and 2 correspond to 22233
and 33333
, respectively. The default (i.e., without RESTART
) is 02202
.
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 tailor calculations, for example, using different kpoint 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.
4.2. Input data¶
Spex needs data from a previous selfconsistent solution of a meanfield system (e.g., KSDFT). Several keywords can be used to analyze, check, and modify the input data.
4.2.1. NBAND¶
The Green function involves a summation over electronic bands, as do the polarization function [Eq. (5)] and the selfenergy. The convergence with respect to the number of bands is a very important aspect in calculations based on manybody 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.
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. 
4.2.2. CORESOC¶
By default, Spex averages over the SOCsplitted states. For example, the two states 2p^{1/2} and the four states 2p^{3/2} are
averaged to give the six quasinonrelativistic states of the 2p shell (or the three spinup 2p states and the three spindown 2p states
in the case of spin polarization). Then, all core states of a given shell have the same energy and the same radial form of the wavefunction. The averaging procedure
can be avoided by specifying CORESOC
. The SOCsplitted states and the different energies and wavefunctions are then retained and taken
into account in the calculations of the selfenergy, polarization function, et cetera. In the case of spin polarization, the Weiss field gives
rise to further lifting of degeneracies. Spex calculates the respective new splittings, energies, and wavefunctions.
For reference, the corestate energies are written to the output file. Usually, the effect of CORESOC
is numerically small, but it
still might play an important role for GW calculations in the case of very small band gaps.
4.2.3. PROJECT (ANALYZE)¶
This keyword lets Spex analyze the orbital character of the wavefunctions. The LAPW basis set (see Section 6.1)
facilitates such an analysis by virtue of the atomic (muffintin) spheres, in which the wavefunctions are expanded in terms
of spherical harmonics: \(\phi_{\mathbf{k}n}(\mathbf{r})=\sum_{lm} \varphi^{\mathbf{k}n}_{lm}(r)Y_{lm}(\hat{\mathbf{r}})\),
where the \(\varphi^{\mathbf{k}n}_{lm}(r)\) are radial functions (defined on a radial grid). For example, the
contribution of the s orbital to \(\phi_{\mathbf{k}n}(\mathbf{r})\) would be given by
\(\langle\varphi^{\mathbf{k}n}_{00}\varphi^{\mathbf{k}n}_{00}\rangle\) (and is between 0 and 1).
By default, the projection is onto s, p, d, f, and g orbitals (summed over the magnetic quantum number m
and over all equivalent atoms). Alternatively, the orbitals can be given as arguments after PROJECT
following the same syntax as the Wannier orbital choice (see Section 6.3.1). With this syntax, the
default would be defined by [s,p,d,f,g]
for each atom type. See below for more examples.
The results are given
in the form of a table in the file “spex.binfo” containing the orbital decomposition for each eigenstate at one or more k points
(at the \(\Gamma\) point, the additional “+” point if defined, see Section 5.1.2, and at all k points that may be
specified in the JOB
definition, which allows giving the k point in a dummy job such as JOB KS X:(1)
).
If DOS
(Section 4.2.4) is given, a corresponding projected densityofstates (DOS) plot is written to the file “spex.dos”.
The orbital analysis is also carried out for quasiparticle wavefunctions if they
are different from the noninteracting reference wavefunctions
(i.e., whenever the FULL
keyword is used, see Section 5.1.19). In addition, it is done for DFT bandstructure calculations
(ITERATE BANDS
, see Section 4.2.9) and Wannier band interpolations (DFT, GW, …) (INTERPOL
, see Section 5.1.17 and Section 6.3.7),
enabling the plot of “fat bands”.
PROJECT 
Calculate orbital decomposition (and DOS plots, see Section 4.2.4) for s, p, d, f, and g orbitals, corresponding to the default
argument [s,p,d,f,g] for each atom type. 
PROJECT [p,eg] 
Do the projection, instead, on p and e_{g} orbitals of the first atom type. Two values are given, the contribution of p states summed over \(p_x\), \(p_y\), and \(p_z\) as well as over all equivalent atoms, and the correspondingly summed contribution of the e_{g} states. 
PROJECT (px,py,pz,dx2y2,dz2) 
The projection is on each orbital separately: \(p_x\), \(p_y\), \(p_z\), \(d_{x^2y^2}\), and \(d_{z^2}\) and only for the first atom. 
PROJECT () (px/90/0/0) 
The first atom is omitted in the analysis (empty parentheses), and the \(p_x\) orbital at the second atom is rotated using Euler angles, see Section 6.3.1. In this particular case, the resulting orbital is identical to \(p_y\). 
4.2.4. DOS (ANALYZE)¶
This lets Spex write a densityofstates (DOS) plot to the file “spex.dos”. See Section 4.2.3 for a definition of the corresponding orbitals for a projected DOS plot.
4.2.5. FIXPHASE¶
The phases of eigenstates are not unique, since multiplying an eigenstate with a complex phase factor (\(c\)
with \(c=1\), e.g., \(c=1\)) gives a valid eigenstate with the same eigenvalue. Likewise, any unitary transformation
of a set of degenerate eigenstates gives an equally valid set of degenerate eigenstates with the same (common) energy eigenvalue.
The wavefunction coefficients are thus not uniquely defined. This can be problematic for quantities that are defined with
respect to the wave functions, e.g., the Wannier U matrix or the GW selfenergy matrix (calculated with GW FULL
)
because a recalculation of the eigenstates is likely to change the phases (and rotations in degenerate eigenspaces).
Spex catches such inconsistencies and will stop with an error message (“inconsistent checksum”). On the other hand,
the keyword FIXPHASE
can be used to make the wavefunction coefficients unique. Obviously, to take effect,
FIXPHASE
has to be set in all calculations that write or read quantities defined with respect to the eigenstates,
e.g., the Wannier U matrix (“spex.uwan”) or the selfenergy matrix (“spex.sigx” or “spex.sigc”).
FIXPHASE
fixes both the phases of the eigenstates and the rotation within degenerate eigenstates. It is not set by default.
4.2.6. ENERGY¶
(*) In some cases, it may be necessary to replace the energy eigenvalues, provided by the meanfield (DFT) calculation,
by energies (e.g., GW quasiparticle energies) obtained in a previous Spex run, for example,
to determine the GW Fermi energy or to perform energyonly selfconsistent 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 ascending order
(provided that there is at least one energy value for the particular k point). The corresponding wave functions will
be ordered accordingly.
This keyword can also be used to define a scissors operator, see examples.
ENERGY "energy.inp" 
Replace the meanfield energy eigenvalues by the energies provided in the file “energy.inp”. 
ENERGY 0.8eV 
Apply a scissors operator with 0.8 eV. 
4.2.7. DELTAEX¶
(*) This keyword modifies the exchange splitting of a collinear magnetic system, i.e., it shifts spinup and spindown energies relative to to each other so as to increase or decrease the exchange splitting. With DELTAEX x
, the spinup (spindown) energies are lowered (elevated) by x/2. The parameter x can be used to enforce the Goldstone condition in spinwave calculations [Phys. Rev. B 94, 064433 (2016)]
DELTAEX 0.2eV 
Increase the exchange splitting by 0.2 eV (spinup/down energies are decreased/increased by 0.1 eV) 
4.2.8. PLUSSOC¶
(*) With this keyword, Spex adds spinorbit coupling (SOC) to the meanfield solution using a oneshot secondvariation approach and stops,
so it is noniterative but updates the wavefunctions and energies.
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 v0.26b (2019.03), the modified files are “gwa”, “KS.hdf”, and “spex.sym”.
The latter is written only if the system is spin polarized (noncollinear 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.)
A possible application of this feature is to add SOC corrections to GW quasiparticle energies already calculated.
To this end, store the GW energies to a file using the “spex.extr” utility (example: spex.extr g spex.out > energy.inp
).
Then, tell Spex to replace the singleparticle energies (that it reads from the input data) by the ones from the file (“energy.inp”) with
the keyword ENERGY
(ENERGY energy.inp
, see Section 4.2.6) and add PLUSSOC
. In a subsequent run, Spex will apply the SOC operator to the GW quasiparticle
energies using a secondvariation technique, write the corrected energies to the output, and write the new input data files.
The latter can be used in a subsequent Spex run, for example, to calculate a Wannierinterpolated band structure,
containing GW quasiparticle and SOC corrections. From a theoretical point of view this approach is a bit inconsistent
[Phys. Rev. B 88, 165136 (2013)], but it is considerably faster than running GW with SOC from the start. Besides, the
latter approach is currently not applicable to systems with noncollinear magnetism. So, using the present procedure with PLUSSOC
is the only viable approach in this case.
4.2.9. ITERATE¶
(*) If ITERATE
is specified, Spex only reads the LAPW basis set from the input data, provided by the meanfield (DFT) code,
but solves the KohnSham (KS) equations (as a generalized eigenvalue problem) at the kpoints 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 noniterative.)
ITERATE
can also run band structure calculations. The kpoint path is taken from KPTPATH
or from a file, see below.
The band structure is written to the file “bands”. Using PROJECT
it is also possible to calculate band structures with
orbital projections (“fat bands”).
Spex offers the possibility of modifying the LAPW basis set (when ITERATE
is used) in the section LAPW
of the input
file (Section 6.1)
The keyword ITERATE
is not available for executables compiled with DLOAD
(configured with enableload
).
ITERATE 
Solve KS equations. (Includes SOC if it is included in the underlying DFT calculation.) 
ITERATE NR 
Solve nonrelativistic KS equations. (Excludes SOC.) 
ITERATE SR 
Solve scalarrelativistic KS equations. (Excludes SOC.) 
ITERATE FR 
Solve relativistic KS equations. (Includes SOC.) 
ITERATE MIN=1 
Solve KS equations and neglect eigenvalues below 1 htr. 
ITERATE SR MIN=5eV 
Solve scalarrelatvisitic KS equations and neglect eigenvalues below 5 eV. 
ITERATE FR STOP 
Solve relativistic KS equations (including SOC), then stop. 
ITERATE BANDS 
Run band structure calculation along the kpoint path defined by KPTPATH , then stop. 
ITERATE FR BANDS "qpts" 
Include SOC in the band structure calculation and take the kpoint path from the file “qpts”. 
Note
ITERATE NR
(or SR
or FR
) overrides the SOC flag from the DFT calculation. For example, ITERATE FR
includes SOC irrespectively
of whether the underlying DFT calculation (which has generated the effective KS potential) has been run with or without SOC.
4.2.10. NOSYM¶
(*) Spex uses spatial (and timereversal) symmetry to speed up calculations.
However, in case of large systems and/or slightly broken symmetry (small
structural distortions), the automatic detection of symmetry and its usage
can be problematic. The keyword NOSYM
allows switching off (riskier
procedures involving) symmetry.
4.2.11. CHKMISM and CHKOLAP¶
(*) The set of wavefunctions read from harddisc can be checked in terms of their orthonormality and continuity (mismatch) at the muffintin (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 readin process or with the data written by the DFT code. The developers should be informed in this case.
4.2.12. 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 \({u(r)}, {\dot{u}(r)=\partial u(r)/\partial\epsilon}\), \({u^\mathrm{LO}(r)}\) and
spherical harmonics \({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 \({g_\mathrm{max}}\)
and the maximal l quantum number \({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 \({u}\) and \({\dot{u}}\). Local orbitals \({u^\mathrm{LO}}\)
can be used to extend the basis set, to enable the description of semicore and highlying 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 spinpolarized 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 \({l=3}\))
MTACCUR 1 2 
Calculate MT representation error between 1 and 2 Hartree. 
MTACCUR 
Automatic energy range. 
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.