.. _spex_and_fleur:
===============
Spex and Fleur
===============
Spex needs input data about a reference mean-field system, for example, the KS system of DFT. A self-consistent mean-field
calculation must thus precede any Spex calculation. The following three steps prepare the input data for Spex.
:Step 1: Self-consistent mean-field calculation.
:Step 2: Generate special k-point set with Spex.
:Step 3: Diagonalize mean-field Hamiltonian with the potential from step 1, which produces the eigensolutions at the new k points.
Fleur
++++++
The Fleur code is an implementation of KS-DFT based on the FLAPW method. Consult the `Fleur manual`_ for details.
.. _Fleur manual: http://www.flapw.de/pm/index.php?n=User-Documentation.FLEUR
We distinguish between an old (v0.26b) and a new generation (MaX releases) of Fleur versions. In the long run, the old versions will become
obsolete. However, as of now, the new Fleur versions have not been completely integrated.
Therefore, both are documented here.
Fleur v0.26b (2019.03)
======================
In the Fleur input file there is a flag for writing out the necessary data for a Spex calculation. It is called ``gw`` and is appended to line 23 of the Fleur "inp" file:
``23|vchk=F,cdinf=F,pot8=F,gw=n,numbands=N``
*n* can take four values:
* ``gw=0``: No output files are generated (default; the same as omitting ``gw`` and ``numbands`` altogether).
* ``gw=1``: Some basic parameters are written to several files. Otherwise Fleur runs as usual.
* ``gw=2``: All output files necessary for Spex are created and Fleur stops after one iteration (without updating the potential). In this case you should also set ``pot8=T`` and the maximal number of bands ``numbands=...``.
* ``gw=3``: Self-consistent cycle for QSGW. Same as ``gw=1`` but adds :math:`\Sigma^{\mathrm{xc,QSGW}}(\mathbf{r},\mathbf{r}')-v^{\mathrm{xc}}(\mathbf{r})` to the Hamiltonian in each iteration.
The output files are
* "gwa": Basic parameters including the atomic numbers and positions in the unit cell, lattice parameters and basis vectors, FLAPW l cutoff, and local-orbital parameters,
* "LATTC": FLAPW G cutoff,
* "radfun": radial basis functions,
* "ecore": core-electron functions,
* "eig": k points, wave-function coeffients (interstitial), energies,
* "abcoeff": wave-function coefficients (muffin tins),
* "KS.hdf": alternative to "eig" and "abcoeff" (now the default),
* "vxc": expectation values of the xc potential (diagonal elements, obsolete),
* "vxcfull": matrix of the xc potential,
* "qsgw": matrix of the QSGW self-energy (only for QSGW calculations).
Furthermore, Spex needs the Fleur file "sym.out".
Fleur MaX Release 3 v0.27
=========================
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 ``-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", "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:
* "basis.hdf": including all information about the basis (atoms, cell, kpts, muffin tin and planewave basis information),
* "ecore": core-electron functions,
* "eig_gw.hdf": energies, wave-function coeffients (interstitial), wave-function coefficients (atomic spheres),
* "pot.hdf": potentials (pottot, potcoul, potx) and relevant information on the stepfunction and structure.
Furthermore, Spex needs the Fleur file "sym.out", which contains the symmetry operations of the system.
.. 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.
A short tutorial can be found at:
https://www.flapw.de/site/CECAM-2019-tut/Day_4_Hands-on_Spex/
Remarks about MT basis
+++++++++++++++++++++++
Conduction states
==================
As in a *GW* calculation the conduction states enter both the Green function and the screened interaction,
they should be accurately described already in the KS system which is our starting point for the perturbation treatment.
The LAPW basis, however, only guarantees well described occupied states. In order to obtain well-converged *GW* results,
one must make the basis set more flexible, especially in the MT regions, by introducing local orbitals either at high energy
parameters or as higher-order energy derivatives [Phys. Rev. B 74, 045104 (2006), Comput. Phys. Commun., 184, 2670 (2013)].
Semicore states
=================
High-lying semicore states can appear as badly described "ghost bands" in the valence band region leading to a wrong DFT ground state.
A possible solution is to use local orbitals and extend the energy window, such that the semicore states are treated as valence states.
On the other hand if the ghost bands are above the Fermi energy, they usually pose no problem in a DFT calculation.
In a *GW* calculation, however, the conduction states are also relevant, and one must make sure that there are no ghost bands at all
in the energy spectrum. Therefore, it might be necessary to treat more (and deeper) semicore states as valence states than are needed
in the DFT calculation.
As an indication for such a case the overlap of core states with basis and wavefunctions calculated in the routine "checkinput"
should be checked. As an example, here is the output for Strontium Titanate with a Titanium 3s ghost band:
.. code-block:: bash
Overlap
Atom type 1
u(s) udot(s)
1s -0.001431 0.000644
2s -0.000830 0.000414
3s 0.287789 -0.878671
u(p) udot(p) ulo(p) ...
2p -0.000665 0.000112 -0.000494
...
Maximum overlap at (band/kpoint)
Atom type 1
1s 0.000611 (031/ 001)
2s 0.000343 (031/ 001)
3s 0.664265 (047/ 001)
2p 0.000340 (003/ 036) 0.000481 (003/ 042) 0.000340 (003/ 036)
...