Added descriptions to model_method.py classes

simulationdataschema/model_method.py

@@ -44,7 +44,10 @@
 
 
 class Mesh(ArchiveSection):
-    """ """
+    """
+    A base section used to specify the settings of a sampling mesh. It supports uniformly-spaced
+    meshes and symmetry-reduced representations.
+    """
 
     dimensionality = Quantity(
         type=np.int32,
@@ -141,14 +144,18 @@ class Mesh(ArchiveSection):
 
     def normalize(self, archive, logger):
         super().normalize(archive, logger)
+
         self.dimensionality = 3 if not self.dimensionality else self.dimensionality
         if self.grid is None:
             return
         self.n_points = np.prod(self.grid) if not self.n_points else self.n_points
 
 
 class LinePathSegment(ArchiveSection):
-    """ """
+    """
+    A base section used to define the settings of a single line path segment within a
+    multidimensional mesh.
+    """
 
     start_point = Quantity(
         type=str,
@@ -181,7 +188,9 @@ class LinePathSegment(ArchiveSection):
 
 
 class KMesh(Mesh):
-    """ """
+    """
+    A base section used to specify the settings of a sampling mesh in reciprocal space.
+    """
 
     offset = Quantity(
         type=np.float64,
@@ -220,6 +229,17 @@ class KMesh(Mesh):
     line_path_segments = SubSection(sub_section=LinePathSegment.m_def, repeats=True)
 
     def get_k_line_density(self, lattice_vectors_reciprocal):
+        """
+        Calculates the k-line density of the KMesh. This quantity is used to have an idea
+        of the precision of the KMesh sampling.
+
+        Args:
+            lattice_vectors_reciprocal (np.array): Reciprocal lattice vectors of the
+            atomic cell.
+
+        Returns:
+            (np.float64): The k-line density of the KMesh.
+        """
         if lattice_vectors_reciprocal is None:
             return
         if len(lattice_vectors_reciprocal) != 3 or len(self.grid) != 3:
@@ -266,11 +286,15 @@ def normalize(self, archive, logger):
                 )
                 return
             reciprocal_vectors = model_system.atomic_cell[0].lattice_vectors_reciprocal
-            self.k_line_density = self.get_k_line_density(reciprocal_vectors)
+            if k_line_density := self.get_k_line_density(reciprocal_vectors):
+                self.k_line_density = k_line_density * ureg("m")
 
 
 class FrequencyMesh(Mesh):
-    """ """
+    """
+    A base section used to specify the settings of a sampling mesh in the 1D frequency
+    real or imaginary space.
+    """
 
     points = Quantity(
         type=np.complex128,
@@ -293,7 +317,10 @@ def normalize(self, archive, logger):
 
 
 class TimeMesh(Mesh):
-    """ """
+    """
+    A base section used to specify the settings of a sampling mesh in the 1D time real or
+    imaginary space.
+    """
 
     smearing = Quantity(
         type=np.float64,
@@ -348,21 +375,70 @@ class ModelMethod(ArchiveSection):
         a_eln=ELNAnnotation(component="URLEditQuantity"),
     )
 
+    starting_method_ref = Quantity(
+        type=Reference(SectionProxy("ModelMethod")),
+        description="""
+        Links the current section method to a section method containing the starting
+        parameters.
+        """,
+    )
+
     k_mesh = SubSection(sub_section=KMesh.m_def)
 
     frequency_mesh = SubSection(sub_section=FrequencyMesh.m_def, repeats=True)
 
     time_mesh = SubSection(sub_section=TimeMesh.m_def, repeats=True)
 
-    starting_method_ref = Quantity(
-        type=Reference(SectionProxy("ModelMethod")),
+    relativity_method = Quantity(
+        type=MEnum(
+            "scalar_relativistic",
+            "pseudo_scalar_relativistic",
+            "scalar_relativistic_atomic_ZORA",
+        ),
         description="""
-        Links the current section method to a section method containing the starting
-        parameters.
+        Describes the relativistic treatment used for the calculation of the final energy
+        and related quantities. If empty, no relativistic treatment is applied.
+        """,
+    )
+
+    van_der_waals_method = Quantity(
+        type=MEnum("TS", "OBS", "G06", "JCHS", "MDB", "XC"),
+        description="""
+        Describes the Van der Waals method. If empty, no Van der Waals correction is applied.
+
+        | Van der Waals method  | Description                               |
+
+        | --------------------- | ----------------------------------------- |
+
+        | `"TS"`                | A. Tkatchenko and M. Scheffler, [Phys. Rev. Lett.
+        **102**, 073005 (2009)](http://dx.doi.org/10.1103/PhysRevLett.102.073005) |
+
+        | `"OBS"`               | F. Ortmann, F. Bechstedt, and W. G. Schmidt, [Phys. Rev.
+        B **73**, 205101 (2006)](http://dx.doi.org/10.1103/PhysRevB.73.205101) |
+
+        | `"G06"`               | S. Grimme, [J. Comput. Chem. **27**, 1787
+        (2006)](http://dx.doi.org/10.1002/jcc.20495) |
+
+        | `"JCHS"`              | P. Jurečka, J. Černý, P. Hobza, and D. R. Salahub,
+        [Journal of Computational Chemistry **28**, 555
+        (2007)](http://dx.doi.org/10.1002/jcc.20570) |
+
+        | `"MDB"`               | Many-body dispersion. A. Tkatchenko, R. A. Di Stasio Jr,
+        R. Car, and M. Scheffler, [Physical Review Letters **108**, 236402
+        (2012)](http://dx.doi.org/10.1103/PhysRevLett.108.236402) and A. Ambrosetti, A. M.
+        Reilly, R. A. Di Stasio Jr, and A. Tkatchenko, [The Journal of Chemical Physics
+        **140**, 18A508 (2014)](http://dx.doi.org/10.1063/1.4865104) |
+
+        | `"XC"`                | The method to calculate the Van der Waals energy uses a
+        non-local functional which is described in section_XC_functionals. |
         """,
     )
 
     def resolve_model_method_name(self, logger):
+        """
+        Resolves the name of the ModelMethod section if it is not already defined from the
+        section inheriting from this one.
+        """
         if self.m_def.inherited_sections is None:
             logger.warning(
                 "Could not find if the ModelMethod section used is inheriting from another section."
@@ -386,7 +462,10 @@ def normalize(self, archive, logger):
 
 
 class TB(ModelMethod):
-    """ """
+    """
+    A base section containing the parameters pertaining to a tight-binding model calculation.
+    The type of tight-binding model is specified in the `type` quantity.
+    """
 
     type = Quantity(
         type=MEnum("DFTB", "xTB", "Wannier", "SlaterKoster", "unavailable"),
@@ -421,7 +500,10 @@ def normalize(self, archive, logger):
 
 
 class Wannier(TB):
-    """ """
+    """
+    A base section containing the parameters pertaining to a Wannier tight-binding model
+    calculation.
+    """
 
     is_maximally_localized = Quantity(
         type=bool,