diff --git a/doc/guide/conv_vasp.rst b/doc/guide/conv_vasp.rst index 513089fb..fb80eac7 100644 --- a/doc/guide/conv_vasp.rst +++ b/doc/guide/conv_vasp.rst @@ -22,7 +22,7 @@ Interface with VASP 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. +in the :ref:`PLOVasp User's Guide `. 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` @@ -55,11 +55,12 @@ harmonics are: * `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 projector type `Pr 2`, one should 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. 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 @@ -88,7 +89,7 @@ Post-processing of `LOCPROJ` data is generally done as follows: #. Prepare an input file `.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 at the end of +#. 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.: @@ -103,7 +104,7 @@ These files are needed for the converter that will be invoked in your DMFT script. The format of input file `.cfg` is described in details in -:ref:`plovasp`. Here we just give a simple example for the case +the :ref:`User's Guide `. Here we just consider a simple example for the case of SrVO3: .. literalinclude:: images_scripts/srvo3.cfg @@ -119,7 +120,7 @@ parameters are required - **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 +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`. diff --git a/doc/guide/plovasp.rst b/doc/guide/plovasp.rst index 8949ba79..99f5e1d9 100644 --- a/doc/guide/plovasp.rst +++ b/doc/guide/plovasp.rst @@ -3,35 +3,33 @@ PLOVasp ======= -The general purpose of the PLOVasp tool is to transform -raw, non-normalized projectors generated by VASP into normalized -projectors corresponding to user-defined projected localized orbitals (PLO). -The PLOs can then be used for DFT+DMFT calculations with or without -charge self-consistency. PLOVasp also provides some utilities -for basic analysis of the generated projectors, such as outputting -density matrices, local Hamiltonians, and projected -density of states. +The general purpose of the PLOVasp tool is to transform raw, non-normalized +projectors generated by VASP into normalized projectors corresponding to +user-defined projected localized orbitals (PLO). The PLOs can then be used for +DFT+DMFT calculations with or without charge self-consistency. PLOVasp also +provides some utilities for basic analysis of the generated projectors, such as +outputting density matrices, local Hamiltonians, and projected density of +states. -PLOs are determined by the energy window in which the raw projectors -are normalized. This allows to define either atomic-like strongly -localized Wannier functions (large energy window) or extended -Wannier functions focusing on selected low-energy states (small -energy window). +PLOs are determined by the energy window in which the raw projectors are +normalized. This allows to define either atomic-like strongly localized Wannier +functions (large energy window) or extended Wannier functions focusing on +selected low-energy states (small energy window). -In PLOVasp all projectors sharing the same energy window are combined -into a `projector group`. Technically, this allows one to define -several groups with different energy windows for the same set of -raw projectors. Note, however, that DFTtools does not support projector -groups at the moment but this feature might appear in future releases. +In PLOVasp, all projectors sharing the same energy window are combined into a +`projector group`. Technically, this allows one to define several groups with +different energy windows for the same set of raw projectors. Note, however, +that DFTtools does not support projector groups at the moment but this feature +might appear in future releases. -A set of projectors defined on sites realted to each other either by symmetry -or by sort along with a set of :math:`l`, :math:`m` quantum numbers forms a -`projector shell`. There could be several projectors shells in a -projector group, implying that they will be normalized within -the same energy window. +A set of projectors defined on sites related to each other either by symmetry +or by an atomic sort, along with a set of :math:`l`, :math:`m` quantum numbers, +forms a `projector shell`. There could be several projectors shells in a +projector group, implying that they will be normalized within the same energy +window. -Projector shells and groups are specified by a user-defined input file -whose format is described below. +Projector shells and groups are specified by a user-defined input file whose +format is described below. Input file format ----------------- @@ -43,7 +41,7 @@ Parameters (or 'options') are grouped into sections specified as A PLOVasp input file can contain three types of sections: #. **[General]**: includes parameters that are independent - of a particular projector set, such as the Fermi level, additional + of a particular projector set, such as the Fermi level, additional output (e.g. the density of states), etc. #. **[Group ]**: describes projector groups, i.e. a set of projectors sharing the same energy window and normalization type. @@ -51,8 +49,8 @@ A PLOVasp input file can contain three types of sections: there should be no more than one projector group. #. **[Shell ]**: contains parameters of a projector shell labelled with ``. If there is only one group section and one shell section, - the group section can be omitted and its required parameters can be - given inside the single shell section. + the group section can be omitted but in this case, the group required + parameters must be provided inside the shell section. Section [General] """"""""""""""""" @@ -61,24 +59,24 @@ The entire section is optional and it contains three parameters: * **BASENAME** (string): provides a base name for output files. Default filenames are :file:`vasp.*`. -* **DOSMESH** ([float float] integer): if this parameter is given - projected density of states for each projected orbital will be +* **DOSMESH** ([float float] integer): if this parameter is given, + the projected density of states for each projected orbital will be evaluated and stored to files :file:`pdos_.dat`, where `n` is the - orbital number. The energy - mesh is defined by three numbers: `EMIN` `EMAX` `NPOINTS`. The first two + orbital index. The energy + mesh is defined by three numbers: `EMIN` `EMAX` `NPOINTS`. The first two can be omitted in which case they are taken to be equal to the projector energy window. **Important note**: at the moment this option works only if the tetrahedron integration method (`ISMEAR = -4` or `-5`) is used in VASP to produce `LOCPROJ`. * **EFERMI** (float): provides the Fermi level. This value overrides the one extracted from VASP output files. - + There are no required parameters in this section. Section [Shell] """"""""""""""" -This section specifies a projector shell. Each shell section must be +This section specifies a projector shell. Each `[Shell]` section must be labeled by an index, e.g. `[Shell 1]`. These indices can then be referenced in a `[Group]` section. @@ -87,17 +85,17 @@ In each `[Shell]` section two parameters are required: * **IONS** (list of integer): indices of sites included in the shell. The sites can be given either by a list of integers `IONS = 5 6 7 8` or by a range `IONS = 5..8`. The site indices must be compatible with - POSCAR file. + the POSCAR file. * **LSHELL** (integer): :math:`l` quantum number of the desired local states. It is important that a given combination of site indices and local states -given by `LSHELL` must be present in LOCPROJ file. +given by `LSHELL` must be present in the LOCPROJ file. There are additional optional parameters that allow one to transform the local states: * **TRANSFORM** (matrix): local transformation matrix applied to all states - in the projector shell. The matrix is defined by (multiline) block + in the projector shell. The matrix is defined by a (multiline) block of floats, with each line corresponding to a row. The number of columns must be equal to :math:`2 l + 1`, with :math:`l` given by `LSHELL`. Only real matrices are allowed. This parameter can be useful to select certain subset of @@ -105,14 +103,14 @@ the local states: * **TRANSFILE** (string): name of the file containing transformation matrices for each site. This option allows for a full-fledged functionality when it comes to local state transformations. The format of this file - is described in :ref:`transformation_file`. + is described :ref:`below `. Section [Group] """"""""""""""" Each defined projector shell must be part of a projector group. In the current -implementation of DFTtools only a single group is supported which can be -labeled by any integer, e.g. `[Group 1]`. This implies that all projector shells +implementation of DFTtools only a single group (labelled by any integer, e.g. `[Group 1]`) +is supported. This implies that all projector shells must be included in this group. Required parameters for any group are the following: @@ -121,18 +119,19 @@ Required parameters for any group are the following: All defined shells must be grouped. * **EWINDOW** (float float): the energy window specified by two floats: bottom and top. All projectors in the current group are going to be normalized within - this window. + this window. *Note*: This option must be specified inside the `[Shell]` section + if only one shell is defined and the `[Group]` section is omitted. Optional group parameters: * **NORMALIZE** (True/False): specifies whether projectors in the group are - to be noramlized. The default value is **True**. + to be normalized. The default value is **True**. * **NORMION** (True/False): specifies whether projectors are normalized on - a per-site (per-ion) basis. That is, if `NORMION = True` the orthogonality + a per-site (per-ion) basis. That is, if `NORMION = True`, the orthogonality condition will be enforced on each site separately but the Wannier functions - on different sites will not be orthogonal. If `NORMION = False` Wannier functions + on different sites will not be orthogonal. If `NORMION = False`, the Wannier functions on different sites included in the group will be orthogonal to each other. - + .. _transformation_file: @@ -140,15 +139,29 @@ File of transformation matrices """"""""""""""""""""""""""""""" .. warning:: - The description below applies only to collinear cases (i.e. without spin-orbit - coupling). In this case the matrices are spin-independent. + The description below applies only to collinear cases (i.e., without spin-orbit + coupling). In this case, the matrices are spin-independent. The file specified by option `TRANSFILE` contains transformation matrices for each ion. Each line must contain a series of floats whose number is either equal to the number of orbitals :math:`N_{orb}` (in this case the transformation matrices are assumed to be real) or to :math:`2 N_{orb}` (for the complex transformation matrices). -The number of lines :math:`N` must be a multiple of the number of ions :math:`N_{ion}` +The total number of lines :math:`N` must be a multiple of the number of ions :math:`N_{ion}` and the ratio :math:`N / N_{ion}`, then, gives the dimension of the transformed orbital space. The lines with floats can be separated by any number of empty or -comment lines which are ignored. +comment lines (starting from `#`), which are ignored. + +A very simple example is a transformation matrix that selects the :math:`t_{2g}` manifold. +For two correlated sites, one can define the file as follows: +:: + + # Site 1 + 1.0 0.0 0.0 0.0 0.0 + 0.0 1.0 0.0 0.0 0.0 + 0.0 0.0 0.0 1.0 0.0 + + # Site 2 + 1.0 0.0 0.0 0.0 0.0 + 0.0 1.0 0.0 0.0 0.0 + 0.0 0.0 0.0 1.0 0.0