Updated reference documentation for PLOVASP classes and functions.

doc/guide/conv_vasp.rst

@@ -25,7 +25,6 @@ creates a h5 archive from the :ref:`PLOVASP<refPLOVASP>` output readable by
 
 Here, we will present a guide how the interface `can` be used to create input for a DMFT calculation, using SrVO3 as an example. Full examples can be found in the :ref:`tutorial section of DFTTools<tutorials>`.
 
-|
 Limitations of the interface
 ============================
 
@@ -37,7 +36,6 @@ Limitations of the interface
   (this implies no spin-orbit coupling) and spin-polarized projectors have not
   been tested.
 
-|
 VASP: generating raw projectors
 ===============================
 
@@ -118,7 +116,6 @@ At the same time, **LOCPROJ** contains the total number of projectors (as well
 as the number of `k`-points, bands, and spin channels) in the first line, which
 can be used to allocate the arrays before parsing.
 
-|
 Conversion for the DMFT self-consistency cycle
 ==============================================
 
@@ -165,7 +162,7 @@ for user convenience. Several parameters are required
 The Option **TRANSFORM** is optional here, and it is specified to extract
 only the three :math:`t_{2g}` orbitals out of the five `d` orbitals given by
 :math:`l = 2`. A detailed explanation of all input parameters can be found
-further below `PLOVASP guide`_.
+further below `PLOVASP detailed guide`_.
 
 Next, the converter is executed. This can be done by calling :program:`PLOVASP` directly in the command line with the input file as an argument, e.g.:
      | `plovasp plo.cfg`
@@ -198,7 +195,6 @@ in :class:`SumkDFT <dft.sumk_dft.SumkDFT>`, e.g.::
 
 However, this should only be done after a careful study of the density matrix and the projected DOS in the localized basis. For the complete process for SrVO3 see the tutorial for the VASP interface `here <../tutorials/svo_vasp/svo_notebook.html>`_.
 
-|
 PLOVASP detailed guide
 ======================
 

doc/reference/converters.rst

@@ -22,12 +22,42 @@ Wannier90 Converter
    :members:
    :special-members:
 
+PLOVASP
+----------
+.. _refPLOVASP:
+
+PLOVASP reference, the classes / functions are sorted the way the converter uses them.
+
+.. automodule:: triqs_dft_tools.converters.plovasp.converter
+  :members: generate_and_output_as_text
+
+.. automodule:: triqs_dft_tools.converters.plovasp.inpconf
+  :members: ConfigParameters
+
+.. automodule:: triqs_dft_tools.converters.plovasp.vaspio
+  :members: VaspData, Plocar, Poscar, Kpoints, Eigenval, Doscar, read_symmcar
+
+.. automodule:: triqs_dft_tools.converters.plovasp.elstruct
+  :members: ElectronicStructure
+
+.. automodule:: triqs_dft_tools.converters.plovasp.plotools
+  :members:
+
+.. automodule:: triqs_dft_tools.converters.plovasp.proj_shell
+  :members:
+
+.. automodule:: triqs_dft_tools.converters.plovasp.proj_group
+  :members:
+
+
 VASP Converter
 -------------------
+.. _refVASPconverter:
 .. autoclass:: triqs_dft_tools.converters.vasp_converter.VaspConverter
    :members:
    :special-members:
 
+
 Converter Tools
 ---------------
 .. autoclass:: triqs_dft_tools.converters.converter_tools.ConverterTools

python/converters/plovasp/converter.py

@@ -24,14 +24,16 @@
 #
 ################################################################################
 r"""
-    vasp.main
-    =========
+    plovasp.converter
+    =================
 
-    Main script of PLOVasp.
+    PLOVASP is a tool to transform raw, non-normalized
+    projectors generated by VASP into normalized projectors
+    corresponding to user-defined projected localized orbitals (PLO).
 
     Runs routines in proper order to generate and store PLOs.
 
-    Usage: python main.py <conf-file> [<path-to-vasp-calcultaion>]
+    Usage: python converter.py <conf-file> [<path-to-vasp-calculation>]
 """
 import sys
 import vaspio
@@ -85,4 +87,3 @@ def main():
 
 if __name__ == '__main__':
     main()
-

python/converters/plovasp/elstruct.py

@@ -24,8 +24,8 @@
 #
 ################################################################################
 r"""
-    vasp.elstruct
-    =============
+    plovasp.elstruct
+    ================
 
     Internal representation of VASP electronic structure data.
 """

python/converters/plovasp/inpconf.py

@@ -24,8 +24,8 @@
 #
 ################################################################################
 r"""
-  vasp.inpconfig
-  ==============
+  plovasp.inpconfig
+  =================
 
   Module for parsing and checking an input config-file.
 """
@@ -494,12 +494,11 @@ class ConfigParameters:
 ################################################################################
     def groups_shells_consistency(self):
         """
-        Ensures consistency between groups and shells.
-        In particular:
-        - if no groups are explicitly defined and only shell is defined create
-          a group automatically
-        - check the existance of all shells referenced in the groups
-        - check that all shells are referenced in the groups
+        Ensures consistency between groups and shells. In particular:
+            - if no groups are explicitly defined and only shell is defined create a group automatically
+            - check the existance of all shells referenced in the groups
+            - check that all shells are referenced in the groups
+            
         """
 # Special case: no groups is defined
         if self.ngroups == 0:
@@ -660,4 +659,3 @@ if __name__ == '__main__':
     doscar = vaspio.Doscar()
     doscar.from_file(vasp_dir)
 #    pars = parse_input(filename)
-

python/converters/plovasp/plotools.py

@@ -24,8 +24,8 @@
 #
 ################################################################################
 r"""
-    vasp.plotools
-    =============
+    plovasp.plotools
+    ================
 
     Set of routines for processing and outputting PLOs.
 
@@ -33,6 +33,25 @@ r"""
     the consistency of the input data, generation of projected localized
     orbitals (PLOs) out of raw VASP projectors, and outputting data
     required by DFTTools.
+
+    The first step of PLO processing is to select subsets of projectors
+    corresponding to PLO groups. Each group contains a set of shells. Each
+    projector shell is represented by an object 'ProjectorShell' that contains
+    an array of projectors and information on the shell itself (orbital number,
+    ions, etc.). 'ProjectorShell's are contained in both a list of shells
+    (according to the original list as read from config-file) and in a
+    'ProjectorGroup' object, the latter also providing information about the
+    energy window.
+
+    Order of operations:
+     - transform projectors (all bands) in each shell
+     - select transformed shell projectors for a given group within the window
+     - orthogonalize if necessary projectors within a group by performing
+       the following operations for each k-point:
+       * combine all projector shells into a single array
+       * orthogonalize the array
+       * distribute back the arrays assuming that the order is preserved
+
 """
 import itertools as it
 import numpy as np
@@ -209,6 +228,7 @@ def generate_plo(conf_pars, el_struct):
 def output_as_text(pars, el_struct, pshells, pgroups):
     """
     Output all information necessary for the converter as text files.
+
     """
     ctrl_output(pars, el_struct, len(pgroups))
     plo_output(pars, el_struct, pshells, pgroups)
@@ -260,6 +280,27 @@ def kpoints_output(basename, el_struct):
 def ctrl_output(conf_pars, el_struct, ng):
     """
     Outputs a ctrl-file.
+
+    Control file format
+    """"""""""""""""""""""""""""""
+
+    Filename '<namebase>.ctrl'. Contains the data shared between all shells.
+    The JSON-header consists of the following elements:
+
+     * *nk*: number of `k`-points
+
+     * *ns*: number of spin channels
+
+     * *nc_flag*: collinear/noncollinear case (False/True)
+
+     * *ng*: number of projector groups
+
+     * Symmetry information (list of symmetry operations)
+
+     * *efermi*: Fermi level (optional)
+
+     * Lattice information
+
     """
     ctrl_fname = conf_pars.general['basename'] + '.ctrl'
     head_dict = {}
@@ -311,31 +352,31 @@ def plo_output(conf_pars, el_struct, pshells, pgroups):
     Each group is stored in a '<basename>.plog<Ng>' file. The format is the
     following:
 
-    # Energy window: emin, emax
-    ib_min, ib_max
-    nelect
-    # Eigenvalues
-    isp, ik1, kx, ky, kz, kweight
-    ib1, ib2
-    eig1
-    eig2
-    ...
-    eigN
-    ik2, kx, ky, kz, kweight
-    ...
+    | # Energy window: emin, emax
+    | ib_min, ib_max
+    | nelect
+    | # Eigenvalues
+    | isp, ik1, kx, ky, kz, kweight
+    | ib1, ib2
+    | eig1
+    | eig2
+    | ...
+    | eigN
+    | ik2, kx, ky, kz, kweight
+    | ...
 
-    # Projected shells
-    Nshells
-    # Shells: <shell indices>
-    # Shell <1>
-    Shell 1
-    ndim
-    # complex arrays: plo(ns, nion, ndim, nb)
-    ...
-    # Shells: <shell indices>
-    # Shell <2>
-    Shell 2
-    ...
+    | # Projected shells
+    | Nshells
+    | # Shells: <shell indices>
+    | # Shell <1>
+    | Shell 1
+    | ndim
+    | # complex arrays: plo(ns, nion, ndim, nb)
+    | ...
+    | # Shells: <shell indices>
+    | # Shell <2>
+    | Shell 2
+    | ...
 
     """
     for ig, pgroup in enumerate(pgroups):

python/converters/plovasp/proj_group.py

@@ -24,8 +24,8 @@
 #
 ################################################################################
 r"""
-    vasp.proj_group
-    ===============
+    plovasp.proj_group
+    ==================
 
     Storage and manipulation of projector groups.
 """
@@ -48,10 +48,9 @@ class ProjectorGroup:
     the parameters from the config-file (passed in `pars`).
 
     Parameters:
-
-    - gr_pars (dict) : group parameters from the config-file
-    - shells ([ProjectorShell]) : array of ProjectorShell objects
-    - eigvals (numpy.array) : array of KS eigenvalues
+        - gr_pars (dict) : group parameters from the config-file
+        - shells ([ProjectorShell]) : array of ProjectorShell objects
+        - eigvals (numpy.array) : array of KS eigenvalues
 
     """
     def __init__(self, gr_pars, shells, eigvals):
@@ -238,13 +237,13 @@ class ProjectorGroup:
         This leads to quadtratic projectors P = <l|n> by using a Gram-Schmidt.
 
         The projector on the orthogonal complement of the existing projectors
-        {|l>} is P^u = 1 - sum_l |l><l|
+        |l> is P^u = 1 - sum_l |l><l|
         We get candidates for complement projectors by applying P^u to a Bloch
         state |n>: |l*> = P^u |n>. For numerical stability we select that Bloch
         state which leads to the |l*> with the largest norm (that corresponds to
-        that Bloch state with the smallest overlap with the space spanned by {|l>})
-        We normalize |l*> and add it to {|l>}. We do so untill we have as many
-        |l> states as we have {|n>} states.
+        that Bloch state with the smallest overlap with the space spanned by |l>)
+        We normalize |l*> and add it to |l>. We do so untill we have as many
+        |l> states as we have |n> states.
 
         """
 
@@ -445,7 +444,8 @@ class ProjectorGroup:
         Returns
         -------
 
-        ib_win, nb_min, nb_max : 
+        ib_win, nb_min, nb_max : lowest and highest indices of the selected bands
+
         """
 # Sanity check
         if self.emin > eigvals.max() or self.emax < eigvals.min():
@@ -481,5 +481,3 @@ class ProjectorGroup:
                 ib_max = max(ib_max, ib2)
 
         return ib_win, ib_min, ib_max
-
-

python/converters/plovasp/proj_shell.py

@@ -24,8 +24,8 @@
 #
 ################################################################################
 r"""
-    vasp.proj_shell
-    ===============
+    plovasp.proj_shell
+    ==================
 
     Storage and manipulation on projector shells.
 """
@@ -510,4 +510,3 @@ class ComplementShell(ProjectorShell):
 
     #def density_of_states(self, el_struct, emesh):
     #    raise Exception('not implemented')
-    

python/converters/plovasp/vaspio.py

@@ -24,8 +24,8 @@
 #
 ################################################################################
 r"""
-    vasp.vaspio
-    ===========
+    plovasp.vaspio
+    ==============
 
     Input of required VASP data.
 
@@ -107,16 +107,18 @@ class VaspData:
 ################################################################################
 ################################################################################
 class Plocar:
-    r"""
+    """
     Class containing raw PLO data from VASP.
 
-    Properties
-    ----------
+    Properties:
+        - *plo* (numpy.array((nion, ns, nk, nb, nlmmax))) : raw projectors
+        - *params* (dict) : parameters read from PLOCAR
+        - *ferw* (array(nion, ns, nk, nb)) : Fermi weights from VASP
 
-    - *plo* (numpy.array((nion, ns, nk, nb, nlmmax))) : raw projectors
-    - *params* (dict) : parameters read from PLOCAR
-    - *ferw* (array(nion, ns, nk, nb)) : Fermi weights from VASP
     """
+    def __init__(self):
+        self.plo = None
+        self.proj_params = None
 
     def from_file(self, vasp_dir='./', plocar_filename='PLOCAR'):
         r"""
@@ -330,14 +332,12 @@ class Poscar:
     """
     Class containing POSCAR data from VASP.
 
-    Properties
-    ----------
-
-      nq (int) : total number of ions
-      ntypes ([int]) : number of ion types
-      nions (int) : a list of number of ions of each type
-      a_brav (numpy.array((3, 3), dtype=float)) : lattice vectors
-      q_types ([numpy.array((nions, 3), dtype=float)]) : a list of
+    Properties:
+        - nq (int) : total number of ions
+        - ntypes ([int]) : number of ion types
+        - nions (int) : a list of number of ions of each type
+        - a_brav (numpy.array((3, 3), dtype=float)) : lattice vectors
+        - q_types ([numpy.array((nions, 3), dtype=float)]) : a list of
           arrays each containing fractional coordinates of ions of a given type
     """
     def __init__(self):
@@ -450,16 +450,18 @@ class Kpoints:
     """
     Class describing k-points and optionally tetrahedra.
 
-    Properties
-    ----------
-
-    - nktot (int) : total number of k-points in the IBZ
-    - kpts (numpy.array((nktot, 3), dtype=float)) : k-point vectors (fractional coordinates)
-    - ntet (int) : total number of k-point tetrahedra
-    - itet (numpy.array((ntet, 5), dtype=float) : array of tetrahedra
-    - volt (float) : volume of a tetrahedron (the k-grid is assumed to
-          be uniform)
+    Properties:
+        - nktot (int) : total number of k-points in the IBZ
+        - kpts (numpy.array((nktot, 3), dtype=float)) : k-point vectors (fractional coordinates)
+        - ntet (int) : total number of k-point tetrahedra
+        - itet (numpy.array((ntet, 5), dtype=float) : array of tetrahedra
+        - volt (float) : volume of a tetrahedron (the k-grid is assumed to
+              be uniform)
     """
+    def __init__(self):
+        self.kpts = None
+        self.nktot = None
+        self.kwghts = None
 #
 # Reads IBZKPT file
 #
@@ -617,6 +619,10 @@ class Doscar:
     """
     Class containing some data from DOSCAR
     """
+    def __init__(self):
+        self.ncdij = None
+        self.efermi = None
+
     def from_file(self, vasp_dir='./', dos_filename='DOSCAR'):
         """
         Reads only E_Fermi from DOSCAR.
@@ -712,5 +718,3 @@ def read_symmcar(vasp_dir, symm_filename='SYMMCAR'):
     data.update({ 'nrot': nrot, 'ntrans': ntrans,
                   'lmax': lmax, 'nion': nion,
                   'sym_rots': rot_mats, 'perm_map': rot_map })
-
-