* Added a test 'parse_groups()'

* Added to docs for config-file a description of all features that
    are implemented or under active development

python/converters/vasp/doc/source/conf.py

@@ -16,7 +16,7 @@ import sys, os
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-sys.path.insert(0, os.path.abspath('../../'))
+sys.path.insert(0, os.path.abspath('../../python'))
 
 # -- General configuration -----------------------------------------------------
 

python/converters/vasp/doc/source/config.rst

@@ -5,8 +5,9 @@ A config-file describes subsets of PLOs that are to be generated.
 The PLOs are defined in terms of `shells` determined uniquely by an orbital
 number `l` and a set of ions (nomrmally, of the same sort).
 The shells are further combined into `groups` such that PLO in each group
-are orthogonalized together. This allows to create several mutually orthogonal
-subsets of PLOs. A group is characterized by a single projection energy window.
+are orthogonalized together. This, for instance, allows to create a group of several
+mutually orthogonal subsets of PLOs.
+A group is characterized by a single projection energy window.
 
 A config-file contains three types of sections:
 
@@ -16,11 +17,6 @@ A config-file contains three types of sections:
    `Ns` used for referencing
  - **[Group <Ng>]** : describes shell groups
 
-..
-  It must contain at least one group defined by a section `[PLO Group 1]`.
-  There is also an optional section `[General]` containing options that concern
-  all PLO groups (e.g. `k`-mesh properties).
-
 The format requirements are relatively flexible. A config-file must contain
 at least one `[Shell]` section. If there is only one shell defined, it is possible
 to specify the energy window by providing parameters `EMIN`, `EMAX` (see below)
@@ -34,28 +30,64 @@ An example of a config-file:
 
 .. literalinclude:: adv_example.cfg
 
-A config file must contain at least on group of PLOs. Each group is described
-by a set of ions to which the projectors are applied, an atomic shell number
-(:math:`l = 0,1,2,3` for `s,p,d,f`, respectively), and an energy window defining
-the subset of bands from which the projectors are constructed.
+Here two shells, one corresponding to `d` states on ions 5-8, another to `p`
+states of ions 9-20, are created. They form a single group that, by default, will be
+orthogonalized within a window `[-7.6, 2.7]` eV. Also Fermi level is explicitly
+specified, which might be necessary sometimes, e.g., for non-self-consistent calcuation
+of the band structure.
 
-In addition, one can define a real or complex transformation, which allows one
-to produce projectors in a basis set different from the original one.
+Below, the sections and their parameters are described.
+All parameter names are case-insensitive.
 
-Below, the format of config-file is described.
-All option names are case-insensitive.
+Section [General]
+-----------------
 
-Required parameters
--------------------
+**Required parameters:**
 
-- **IONS**: ion indices as defined in POSCAR files
-- **LSHELL**: atomic shell (values 0, 1, 2, 3 for `s,p,d,f` orbitals, respectively)
-- **EMIN**, **EMAX**: the bottom and top of the energy window with respect to the Fermi level
+In principle, there are unconditionally required parameters in this section.
+However, if VASP data file do not contain a meaningful value of the Fermi level
+it must be given here using parameter *EFERMI*. Note that if this parameter
+is given it will override a value that might have been read from VASP files.
 
-Optional parameters
--------------------
-
-- **RTRANSFORM**, **CTRANSFORM**: real or complex transformation matrix used to produce projectors
-  in a different basis; the number of columns is determined by the size of the atomic shell
+**Optional parameters:**
+
+
+Section [Shell <Ns>]
+--------------------
+
+Defines a projected shell with an integer index `<Ns>`. Ideally, the indices should
+run uniformly starting from 1. However, since they are used only to reference
+shells in group sections, their values are not important. One should only
+make sure that there are no sections with the same name, in which case one
+of them will be ignored by config parser.
+
+**Required parameters:**
+ - *IONS* ([int]): provides a list of ions. The list can be either given
+   by a explicit enumeration of ion indices or by a range `N1..N2` (ions `N1` and `N2`
+   will be included). 
+ - *LSHELL* (int): orbital number `l` of the shell (`l = 0,1,2,3` for `s,p,d,f`, respectively).
+
+**Optional parameters:**
+ - *RTRANSFORM*, *CTRANSFORM* (matrix of floats): transformation matrices
+   (real or complex) that are applied to projectors before orthogonalization.
+   The number of columns `Nc` must be consistent with the number of orbitals
+   (`Nc = (l+1)**2` for real matrices and `Nc = 2(l+1)**2` for complex ones).
+   The dimension of the resulting orbital space is determined by the number of rows.
+   Note that if the calculation is spin-polarized, both matrix dimensions should be
+   doubled.
+ - *TRANSFILE* (str): file containing transformation matrices for individual ions.
+ - *EMIN*, *EMAX* (float): energy window. Should be given only if no excplicit groups
+   is specified. Otherwise, the values are overriden by group parameters.
+
+
+Section [Group <tag>]
+---------------------
+
+Defines a group of shells. Note that the group tag can be any string without whitespaces.
+It will be used to tag intermediate output files.
+
+**Required parameters:**
+ - *SHELLS* ([int]): indices refering to shells forming the group.
+ - **EMIN**, **EMAX**: the bottom and top of the energy window with respect to the Fermi level.
 
  

python/converters/vasp/python/inpconf.py

@@ -289,7 +289,7 @@ class ConfigParameters:
 # Find group sections
         sections = self.cp.sections()
 
-        gr_patt = re.compile('group *([0-9]*)')
+        gr_patt = re.compile('group +(.*)', re.IGNORECASE)
         sec_groups = filter(gr_patt.match, sections)
 
         self.ngroups = len(sec_groups)

python/converters/vasp/test/inpconf/test6.cfg

@@ -0,0 +1,10 @@
+[General]
+EFERMI = 0.7
+
+[Shell 1]
+LSHELL = 2
+IONS = 5..8
+
+[Shell 2]
+IONS = 9..20
+LSHELL = 1

python/converters/vasp/test/inpconf/test_inpconf.py

@@ -244,6 +244,32 @@ class TestSpecialParsers(unittest.TestCase):
 
         self.assertDictEqual(res, expected)
 
+################################################################################
+#
+# test_parse_groups()
+#
+################################################################################
+    def test_parse_groups(self):
+        """
+        Function:
+
+        def parse_groups(self)
+
+        Scenarios:
+
+        - **if** no [Group] section exists and more than one [Shell] section
+          is given **raise** AssertionError
+        - **if** a [Group] section does not contain all required parameters
+          **raise** Exception
+        - **if** two correct [Shell] sections are defined
+          **return** a dictionary of shell parameters
+        """
+# Scenario 1
+        conf_pars = ConfigParameters('test6.cfg')
+        err_mess = "At least one group"
+        with self.assertRaisesRegexp(AssertionError, err_mess):
+            conf_pars.parse_shells()
+
 
 if __name__ == '__main__':
     suite = unittest.TestLoader().loadTestsFromTestCase(TestSpecialParsers)