dft_tools/doc/guide/conv_vasp.rst

.. _convVASP:


Interface with VASP
===================

.. warning::
  The VASP interface is in the alpha-version and the VASP part of it is not
  yet publicly released. The documentation may, thus, be subject to changes
  before the final release.

*Limitations of the alpha-version:*

  * The interface works correctly only if the k-point symmetries
    are turned off during the VASP run (ISYM=-1).

  * Generation of projectors for k-point lines (option `Lines` in KPOINTS)
    needed for Bloch spectral function calculations is not possible at the moment.

  * The interface currently supports only collinear-magnetism calculation
    (this implis no spin-orbit coupling) and
    spin-polarized projectors have not been tested.

A detailed description of the VASP converter tool PLOVasp can be found
in the :ref:`PLOVasp User's Guide <plovasp>`. Here, a quick-start guide is presented.

The VASP interface relies on new options introduced since version 5.4.x. In
particular, a new INCAR-option `LOCPROJ
<https://cms.mpi.univie.ac.at/wiki/index.php/LOCPROJ>`_) and new `LORBIT` modes
13 and 14 have been added.

Option `LOCPROJ` selects a set of localized projectors that will
be written to file `LOCPROJ` after a successful VASP run.
A projector set is specified by site indices,
labels of the target local states, and projector type:

  | `LOCPROJ = <sites> : <shells> : <projector type>`

where `<sites>` represents a list of site indices separated by spaces, with the
indices corresponding to the site position in the POSCAR file; `<shells>`
specifies local states (see below); `<projector type>` chooses a particular type
of the local basis function. The recommended projector type is `Pr 2`. This will
perform a projection of the Kohn-Sham states onto the VASP PAW projector
functions. The number specified behind `Pr` is selecting a specific PAW channel, see the
`VASP wiki page
<https://cms.mpi.univie.ac.at/wiki/index.php/LOCPROJ>`_ for more information. The formalism for this
type of projectors is presented in `M. Schüler et al. 2018 J. Phys.: Condens.
Matter 30 475901 <https://doi.org/10.1088/1361-648X/aae80a>`_.

The allowed labels of the local states defined in terms of cubic
harmonics are:

 * Entire shells: `s`, `p`, `d`, `f`

 * `p`-states: `py`, `pz`, `px`

 * `d`-states: `dxy`, `dyz`, `dz2`, `dxz`, `dx2-y2`

 * `f`-states: `fy(3x2-y2)`, `fxyz`, `fyz2`, `fz3`,
   `fxz2`, `fz(x2-y2)`, `fx(x2-3y2)`.

For projector type `Pr`, one should ideally also set `LORBIT = 14` in the INCAR file and
provide parameters `EMIN`, `EMAX`, defining, in this case, an energy range
(energy window) corresponding to the valence states. Note that, as in the case
of a DOS calculation, the position of the valence states depends on the Fermi
level, which can usually be found at the end of the OUTCAR file. Setting `LORBIT=14` will perform an automatic optimization of the PAW projector channel as described in `M. Schüler et al. 2018 J. Phys.: Condens.
Matter 30 475901 <https://doi.org/10.1088/1361-648X/aae80a>`_, by using a linear combination of the PAW channels, to maximize the overlap in the chosen energy window between the projector and the Kohn-Sham state. Therefore, setting `LORBIT=14` will let VASP ignore the channel specified after `Pr`. This optimization is only performed for the projector type `Pr`, not for `Ps` and obviously not for `Hy`. We recommend to specify the PAW channel anyway, in case one forgets to set `LORBIT=14`.

For example, in case of SrVO3 one may first want to perform a self-consistent
calculation, then set `ICHARGE = 1` and add the following additional
lines into INCAR (provided that V is the second ion in POSCAR):

  | `EMIN = 3.0`
  | `EMAX = 8.0`
  | `LORBIT = 14`
  | `LOCPROJ = 2 : d : Pr 2`

The energy range does not have to be precise. Important is that it has a large
overlap with valence bands and no overlap with semi-core or high unoccupied states.

Conversion for the DMFT self-consistency cycle
----------------------------------------------

The projectors generated by VASP require certain post-processing before
they can be used for DMFT calculations. The most important step is to normalize
them within an energy window that selects band states relevant for the impurity
problem. Note that this energy window is different from the one described above
and it must be chosen independently of the energy
range given by `EMIN, EMAX` in INCAR.

Post-processing of `LOCPROJ` data is generally done as follows:

#. Prepare an input file `<name>.cfg` (e.g., `plo.cfg`) that describes the definition
   of your impurity problem (more details below).

#. Extract the value of the Fermi level from OUTCAR and paste it at the end of
   the first line of LOCPROJ.

#. Run :program:`plovasp` with the input file as an argument, e.g.:

     | `plovasp plo.cfg`

   This requires that the TRIQS paths are set correctly (see Installation
   of TRIQS).

If everything goes right one gets files `<name>.ctrl` and `<name>.pg1`.
These files are needed for the converter that will be invoked in your
DMFT script.

The format of input file `<name>.cfg` is described in details in
the :ref:`User's Guide <plovasp>`. Here we just consider a simple example for the case
of SrVO3:

.. literalinclude:: images_scripts/srvo3.cfg

A projector shell is defined by a section `[Shell 1]` where the number
can be arbitrary and used only for user convenience. Several
parameters are required

- **IONS**: list of site indices which must be a subset of indices
  given earlier in `LOCPROJ`.
- **LSHELL**: :math:`l`-quantum number of the projector shell; the corresponding
  orbitals must be present in `LOCPROJ`.
- **EWINDOW**: energy window in which the projectors are normalized;
  note that the energies are defined with respect to the Fermi level.

Option **TRANSFORM** is optional but here, it is specified to extract
only three :math:`t_{2g}` orbitals out of five `d` orbitals given by
:math:`l = 2`.

The conversion to a h5-file is performed in the same way as for Wien2TRIQS::

    from triqs_dft_tools.converters.vasp_converter import *
    Converter = VaspConverter(filename = filename)
    Converter.convert_dft_input()

As usual, the resulting h5-file can then be used with the SumkDFT class.

Note that the automatic detection of the correct block structure might
fail for VASP inputs.
This can be circumvented by setting a bigger value of the threshold in
:class:`SumkDFT <dft.sumk_dft.SumkDFT>`, e.g.::

    SK.analyse_block_structure(threshold = 1e-4)

However, do this only after a careful study of the density matrix and
the projected DOS in the localized basis.