Added docstrings to modules

python/vasp/elstruct.py

@@ -1,4 +1,9 @@
+r"""
+    vasp.elstruct
+    =============
 
+    Internal representation of VASP electronic structure data.
+"""
 import numpy as np
 
 class ElectronicStructure:

python/vasp/inpconf.py

@@ -1,7 +1,9 @@
 r"""
+  vasp.inpconfig
+  ==============
+
   Module for parsing and checking an input config-file.
 """
-
 import ConfigParser
 import numpy as np
 import re

python/vasp/main.py

@@ -1,4 +1,13 @@
+r"""
+    vasp.main
+    =========
 
+    Main script of PLOVasp.
+
+    Runs routines in proper order to generate and store PLOs.
+
+    Usage: python main.py <conf-file> [<path-to-vasp-calcultaion>]
+"""
 import sys
 import vaspio
 from inpconf import ConfigParameters
@@ -18,11 +27,15 @@ if __name__ == '__main__':
         else:
             vasp_dir = './'
 
-
+# Prepare input-file parameters
     pars = ConfigParameters(filename, verbosity=0)
     pars.parse_input()
+
+# Read VASP data
     vasp_data = vaspio.VaspData(vasp_dir)
     el_struct = ElectronicStructure(vasp_data)
     el_struct.debug_density_matrix()
+
+# Generate and store PLOs
     pshells, pgroups = generate_plo(pars, el_struct)
     output_as_text(pars, el_struct, pshells, pgroups)

python/vasp/plotools.py

@@ -1,4 +1,14 @@
+r"""
+    vasp.plotools
+    =============
 
+    Set of routines for processing and outputting PLOs.
+
+    This is the main module containing routines responsible for checking
+    the consistency of the input data, generation of projected localized
+    orbitals (PLOs) out of raw VASP projectors, and outputting data
+    required by DFTTools.
+"""
 import itertools as it
 import numpy as np
 from proj_group import ProjectorGroup
@@ -44,8 +54,6 @@ def check_data_consistency(pars, el_struct):
                 errmsg = "Projector for isite = %s, l = %s does not match PROJCAR"%(ion + 1, lshell)
                 raise Exception(errmsg)
         
-
-
 ################################################################################
 #
 # generate_plo()
@@ -88,6 +96,7 @@ def generate_plo(conf_pars, el_struct):
     for gr_par in conf_pars.groups:
         pgroup = ProjectorGroup(gr_par, pshells, eigvals)
         pgroup.orthogonalize()
+# DEBUG output
         print "Density matrix:"
         dm_all, ov_all = pshells[pgroup.ishells[0]].density_matrix(el_struct)
         nimp = 0.0
@@ -104,6 +113,7 @@ def generate_plo(conf_pars, el_struct):
         for io, ov in enumerate(ov_all[0]):
             print "  Site %i"%(io + 1)
             print ov
+# END DEBUG output
         if 'dosmesh' in conf_pars.general:
             print
             print "Evaluating DOS..."
@@ -128,6 +138,18 @@ def generate_plo(conf_pars, el_struct):
 
     return pshells, pgroups
 
+################################################################################
+#
+# output_as_text
+#
+################################################################################
+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)
+
 
 # TODO: k-points with weights should be stored once and for all
 ################################################################################
@@ -139,7 +161,6 @@ def kpoints_output(basename, el_struct):
     """
     Outputs k-point data into a text file.
     """
-
     kmesh = el_struct.kmesh
     fname = basename + '.kpoints'
     with open(fname, 'wt') as f:
@@ -317,15 +338,3 @@ def plo_output(conf_pars, el_struct, pshells, pgroups):
                                 f.write("\n")
 
 
-################################################################################
-#
-# output_as_text
-#
-################################################################################
-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)
-

python/vasp/proj_group.py

@@ -1,4 +1,9 @@
+r"""
+    vasp.proj_group
+    ===============
 
+    Storage and manipulation of projector groups.
+"""
 import numpy as np
 
 np.set_printoptions(suppress=True)

python/vasp/proj_shell.py

@@ -1,4 +1,9 @@
+r"""
+    vasp.proj_shell
+    ===============
 
+    Storage and manipulation on projector shells.
+"""
 import itertools as it
 import numpy as np
 import vasp.atm.c_atm_dos as c_atm_dos

python/vasp/vaspio.py

@@ -1,4 +1,17 @@
+r"""
+    vasp.vaspio
+    ===========
 
+    Input of required VASP data.
+
+    Six VASP files are required:
+      - PROJCAR
+      - LOCPROJ
+      - POSCAR
+      - IBZKPT
+      - EIGENVAL
+      - DOSCAR
+"""
 import numpy as np
 import re
 #import plocar_io.c_plocar_io as c_plocar_io
@@ -486,7 +499,7 @@ class Doscar:
         sline = f.next().split()
         self.efermi = float(sline[3])
 
-
+# TODO: implement output of SYMMCAR in VASP and read it here
 ################################################################
 #
 # Reads SYMMCAR