docs (conversion): update VASP-conversion documentation

doc/guide/conversion.rst

@@ -189,54 +189,98 @@ Interface with VASP
   yet publicly released. The documentation may, thus, be subject to changes
   before the final release.
 
-Note that this VASP interface relies on new options introduced since version
+*Limitations of the alpha-version:*
-5.4.x.
 
-Additionally, the interface only works correctly if the k-point symmetries
+  * The interface works correctly only if the k-point symmetries
-are turned off during the VASP run (ISYM=-1).
+    are turned off during the VASP run (ISYM=-1).
 
-The output of raw (non-normalized) projectors is controlled by an INCAR option 
+  * Generation of projectors for k-point lines (option `Lines` in KPOINTS)
-LOCPROJ whose complete syntax is described in the VASP documentaion.
+    needed for Bloch spectral function calculations is not possible at the moment.
 
-The definition of a projector set starts with specifying which sites
+  * The interface currently supports only collinear-magnetism calculation
-and which local states we are going to project onto.
+    (this implis no spin-orbit coupling) and
-This information is provided by option LOCPROJ
+    spin-polarized projectors have not been tested.
+
+A detailed description of the VASP converter tool PLOVasp can be found
+in :ref:`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`
+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 (e.g. :math:`s`, :math:`p`, :math:`d`,
+`<shells>` specifies local states (see below);
-:math:`d_{x^2-y^2}`, etc.);
 `<projector type>` chooses a particular type of the local basis function.
+The recommended projector type is `Pr 2`.
 
-Some projector types also require parameters `EMIN`, `EMAX` in INCAR to
+The allowed labels of the local states defined in terms of cubic
-be set to define an (approximate) energy window corresponding to the 
+harmonics are:
-valence states.
 
-When either a self-consistent (`ICHARG < 10`) or a non-self-consistent
+ * Entire shells: `s`, `p`, `d`, `f`
-(`ICHARG >= 10`) calculation is done VASP produces file `LOCPROJ` which
-will serve as the main input for the conversion routine.
 
+ * `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 2`, one should also set `LORBIT = 14` in INCAR
+and provide parameters `EMIN`, `EMAX` which, in this case, define an
+energy range (window) corresponding to the valence states. Note that as in the case
+of DOS calculation the position of the valence states depends on the
+Fermi level.
+
+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
 """"""""""""""""""""""""""""""""""""""""""""""
 
-In order to use the projectors generated by VASP for defining an
+The projectors generated by VASP require certain post-processing before
-impurity problem they must be processed, i.e. normalized, possibly
+they can be used for DMFT calculations. The most important step is to normalize
-transformed, and then converted to a format suitable for DFT_tools scripts.
+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.
 
-Currently, it is necessary to add the Fermi energy by hand as the fifth value
+Post-processing of `LOCPROJ` data is generally done as follows:
-in the first line of the LOCPROJ file before the next steps can be executed.
 
-The processing of projectors is performed by the program :program:`plovasp`
+#. Prepare an input file `<name>.cfg` (e.g., `plo.cfg`) that describes the definition
-invoked as
+   of your impurity problem (more details below).
 
-  | `plovasp <plo.cfg>`
+#. Extract the value of the Fermi level from OUTCAR and paste at the end of
+   the first line of LOCPROJ.
 
-where `<plo.cfg>` is a input file controlling the conversion of projectors.
+#. Run :program:`plovasp` with the input file as an argument, e.g.:
 
-The format of input file `<plo.cfg>` is described in details in
+     | `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
 :ref:`plovasp`. Here we just give a simple example for the case
 of SrVO3:
 
@@ -257,7 +301,7 @@ 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`.
 
-For the conversion to a h5 file we use on the python level (in analogy to the Wien2kConverter)::
+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)
@@ -265,12 +309,15 @@ For the conversion to a h5 file we use on the python level (in analogy to the Wi
 
 As usual, the resulting h5-file can then be used with the SumkDFT class.
 
-Note that the automatic detection of the correct blockstructure might fail for VASP inputs.
+Note that the automatic detection of the correct block structure might
-This can be circumvented by increase the :class:`SumkDFT <dft.sumk_dft.SumkDFT>` threshold to e.g.::
+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, only do this after a careful study of the density matrix and the dos in the wannier basis.
+However, do this only after a careful study of the density matrix and
+the projected DOS in the localized basis.
 
 A general H(k)
 --------------