Improve type annotations and comments for io.cif (#3820)

* remove duplicate warning * type and docstring tweaks * add some types for io.cif * add comments and types * temp save of some formatting * revert functional change * revert unrelated changes * fix unit test * remove update that does nothing * relocate `sub_space_group` and `space_groups` to their usage * add more types * pre-commit auto-fixes * breaking: make parse_magmom/oxi_stats private * remove merge header * fix unit test * add more types * fix mypy errors * add a few spaces * remove if name ==main * simplify "check to see if" in comments * final tweaks * revise docstring * replace deprecated abc.abstractproperty * add missing doc strings and standardize existing * breaking: fix typo in method name orthongonalize_structure * revert accidental change in test_composition.py --------- Co-authored-by: Janosh Riebesell <janosh.riebesell@gmail.com>
materialsproject · May 15, 2024 · bb68c78 · bb68c78
1 parent 50043c9
commit bb68c78
Show file tree

Hide file tree

Showing 33 changed files with 606 additions and 507 deletions.
diff --git a/docs/pymatgen.md b/docs/pymatgen.md
diff --git a/pymatgen/alchemy/materials.py b/pymatgen/alchemy/materials.py
@@ -30,8 +30,7 @@
 
 
 class TransformedStructure(MSONable):
-    """Container object for new structures that include history of
-    transformations.
+    """Container for new structures that include history of transformations.
 
     Each transformed structure is made up of a sequence of structures with
     associated transformation history.

diff --git a/pymatgen/analysis/chemenv/coordination_environments/chemenv_strategies.py b/pymatgen/analysis/chemenv/coordination_environments/chemenv_strategies.py
@@ -1265,7 +1265,7 @@ def from_dict(cls, dct: dict) -> Self:
 
 
 class NbSetWeight(MSONable, abc.ABC):
-    """Abstract object for neighbors sets weights estimations."""
+    """Abstract base class for neighbor set weight estimations."""
 
     @abc.abstractmethod
     def as_dict(self):
@@ -1282,7 +1282,7 @@ def weight(self, nb_set, structure_environments, cn_map=None, additional_info=No
             additional_info: Additional information.
 
         Returns:
-            Weight of the neighbors set.
+            float: Weight of the neighbors set.
         """
 
 
@@ -1313,7 +1313,7 @@ def weight(self, nb_set, structure_environments, cn_map=None, additional_info=No
             additional_info: Additional information.
 
         Returns:
-            Weight of the neighbors set.
+            float: Weight of the neighbors set.
         """
         return self.aw(nb_set=nb_set)
 
@@ -1534,7 +1534,7 @@ def weight(self, nb_set, structure_environments, cn_map=None, additional_info=No
             additional_info: Additional information.
 
         Returns:
-            Weight of the neighbors set.
+            float: Weight of the neighbors set.
         """
         fda_list = self.fda(nb_set=nb_set)
         return self.eval(fda_list=fda_list)
@@ -1680,7 +1680,7 @@ def weight(self, nb_set, structure_environments, cn_map=None, additional_info=No
             additional_info: Additional information.
 
         Returns:
-            Weight of the neighbors set.
+            float: Weight of the neighbors set.
         """
         effective_csm = get_effective_csm(
             nb_set=nb_set,
@@ -1791,7 +1791,7 @@ def weight(self, nb_set, structure_environments, cn_map=None, additional_info=No
             additional_info: Additional information.
 
         Returns:
-            Weight of the neighbors set.
+            float: Weight of the neighbors set.
         """
         effcsm = get_effective_csm(
             nb_set=nb_set,
@@ -2006,7 +2006,7 @@ def weight(self, nb_set, structure_environments, cn_map=None, additional_info=No
             additional_info: Additional information.
 
         Returns:
-            Weight of the neighbors set.
+            float: Weight of the neighbors set.
         """
         return self.cn_weights[len(nb_set)]
 
@@ -2186,7 +2186,7 @@ def weight(self, nb_set, structure_environments, cn_map=None, additional_info=No
             additional_info: Additional information.
 
         Returns:
-            Weight of the neighbors set.
+            float: Weight of the neighbors set.
         """
         return self.area_weight(
             nb_set=nb_set,
@@ -2379,7 +2379,7 @@ def weight(self, nb_set, structure_environments, cn_map=None, additional_info=No
             additional_info: Additional information.
 
         Returns:
-            Weight of the neighbors set.
+            float: Weight of the neighbors set.
         """
         return self.weight_rf.eval(nb_set.distance_plateau())
 
@@ -2446,7 +2446,7 @@ def weight(self, nb_set, structure_environments, cn_map=None, additional_info=No
             additional_info: Additional information.
 
         Returns:
-            Weight of the neighbors set.
+            float: Weight of the neighbors set.
         """
         return self.weight_rf.eval(nb_set.angle_plateau())
 
@@ -2509,7 +2509,7 @@ def weight(self, nb_set, structure_environments, cn_map=None, additional_info=No
             additional_info: Additional information.
 
         Returns:
-            Weight of the neighbors set.
+            float: Weight of the neighbors set.
         """
         cn = cn_map[0]
         isite = nb_set.isite
@@ -2590,7 +2590,7 @@ def weight(self, nb_set, structure_environments, cn_map=None, additional_info=No
             additional_info: Additional information.
 
         Returns:
-            Weight of the neighbors set.
+            float: Weight of the neighbors set.
         """
         cn = cn_map[0]
         isite = nb_set.isite

diff --git a/pymatgen/analysis/cost.py b/pymatgen/analysis/cost.py
@@ -112,7 +112,7 @@ def get_entries(self, chemsys):
 
 @singleton
 class CostDBElements(CostDBCSV):
-    """Singleton object that provides the cost data for elements."""
+    """Singleton that provides the cost data for elements."""
 
     def __init__(self):
         CostDBCSV.__init__(self, f"{module_dir}/costdb_elements.csv")

diff --git a/pymatgen/analysis/ewald.py b/pymatgen/analysis/ewald.py
@@ -638,7 +638,7 @@ def _recurse(self, matrix, m_list, indices, output_m_list=None):
             indices: Set of indices which haven't had a permutation
                 performed on them.
         """
-        # check to see if we've found all the solutions that we need
+        # Check if we've found all the solutions that we need
         if self._finished:
             return
 

diff --git a/pymatgen/analysis/fragmenter.py b/pymatgen/analysis/fragmenter.py
@@ -166,7 +166,7 @@ def _fragment_one_level(self, old_frag_dict: dict) -> dict:
         """
         Perform one step of iterative fragmentation on a list of molecule graphs. Loop through the graphs,
         then loop through each graph's edges and attempt to remove that edge in order to obtain two
-        disconnected subgraphs, aka two new fragments. If successful, check to see if the new fragments
+        disconnected subgraphs, aka two new fragments. If successful, check if the new fragments
         are already present in self.unique_fragments, and append them if not. If unsuccessful, we know
         that edge belongs to a ring. If we are opening rings, do so with that bond, and then again
         check if the resulting fragment is present in self.unique_fragments and add it if it is not.

diff --git a/pymatgen/analysis/magnetism/analyzer.py b/pymatgen/analysis/magnetism/analyzer.py
@@ -161,7 +161,7 @@ def __init__(
             except ValueError:
                 warnings.warn(f"Could not assign valences for {structure.reduced_formula}")
 
-        # check to see if structure has magnetic moments
+        # Check if structure has magnetic moments
         # on site properties or species spin properties,
         # prioritize site properties
 

diff --git a/pymatgen/analysis/reaction_calculator.py b/pymatgen/analysis/reaction_calculator.py
@@ -36,7 +36,7 @@
 
 
 class BalancedReaction(MSONable):
-    """An object representing a complete chemical reaction."""
+    """Represent a complete chemical reaction."""
 
     # Tolerance for determining if a particular component fraction is > 0.
     TOLERANCE = 1e-6

diff --git a/pymatgen/analysis/thermochemistry.py b/pymatgen/analysis/thermochemistry.py
@@ -20,7 +20,7 @@
 
 
 class ThermoData:
-    """A object container for an experimental Thermochemical Data."""
+    """Container for experimental thermo-chemical data."""
 
     def __init__(
         self,

diff --git a/pymatgen/core/libxcfunc.py b/pymatgen/core/libxcfunc.py
@@ -499,8 +499,3 @@ def from_dict(cls, dct: dict) -> Self:
     def to_json(self) -> str:
         """Get a json string representation of the LibxcFunc."""
         return json.dumps(self.as_dict(), cls=MontyEncoder)
-
-
-if __name__ == "__main__":
-    for xc in LibxcFunc:
-        print(xc)
diff --git a/pymatgen/core/structure.py b/pymatgen/core/structure.py
@@ -4056,7 +4056,7 @@ def substitute(self, index: int, func_group: IMolecule | Molecule | str, bond_or
             fgroup = func_group
 
         else:
-            # Check to see whether the functional group is in database.
+            # Check whether the functional group is in database.
             if func_group not in FunctionalGroups:
                 raise ValueError(
                     f"Can't find functional group {func_group!r} in list. Provide explicit coordinates instead"
@@ -4949,7 +4949,7 @@ def substitute(self, index: int, func_group: IMolecule | Molecule | str, bond_or
         if isinstance(func_group, Molecule):
             functional_group = func_group
         else:
-            # Check to see whether the functional group is in database.
+            # Check whether the functional group is in database.
             if func_group not in FunctionalGroups:
                 raise RuntimeError("Can't find functional group in list. Provide explicit coordinate instead")
             functional_group = FunctionalGroups[func_group]

diff --git a/pymatgen/core/xcfunc.py b/pymatgen/core/xcfunc.py
@@ -24,7 +24,7 @@
 
 
 class XcFunc(MSONable):
-    """This object stores information about the XC correlation functional.
+    """Store information about the XC correlation functional.
 
     Client code usually creates the object by calling the class methods:
 
@@ -162,7 +162,7 @@ def aliases(cls) -> list[str]:
 
     @classmethod
     def asxc(cls, obj) -> Self:
-        """Convert object into XcFunc."""
+        """Convert to XcFunc."""
         if isinstance(obj, cls):
             return obj
         if isinstance(obj, str):

diff --git a/pymatgen/electronic_structure/bandstructure.py b/pymatgen/electronic_structure/bandstructure.py
@@ -681,9 +681,8 @@ def from_old_dict(cls, dct) -> Self:
 
 
 class BandStructureSymmLine(BandStructure, MSONable):
-    r"""This object stores band structures along selected (symmetry) lines in the
-    Brillouin zone. We call the different symmetry lines (ex: \\Gamma to Z)
-    "branches".
+    r"""Store band structures along selected (symmetry) lines in the Brillouin zone.
+    We call the different symmetry lines (ex: \\Gamma to Z) "branches".
     """
 
     def __init__(

diff --git a/pymatgen/electronic_structure/core.py b/pymatgen/electronic_structure/core.py
@@ -355,7 +355,7 @@ def get_suggested_saxis(magmoms):
 
     @staticmethod
     def are_collinear(magmoms) -> bool:
-        """Check to see if a set of magnetic moments are collinear with each other.
+        """Check if a set of magnetic moments are collinear with each other.
 
         Args:
             magmoms: list of magmoms (Magmoms, scalars or vectors).

diff --git a/pymatgen/entries/compatibility.py b/pymatgen/entries/compatibility.py
@@ -1354,7 +1354,7 @@ def get_adjustments(self, entry: ComputedEntry) -> list[EnergyAdjustment]:
         # TODO - detection of embedded water molecules is not very sophisticated
         # Should be replaced with some kind of actual structure detection
 
-        # For any compound except water, check to see if it is a hydrate (contains
+        # For any compound except water, check if it is a hydrate (contains
         # H2O in its structure). If so, adjust the energy to remove MU_H2O eV per
         # embedded water molecule.
         # in other words, we assume that the DFT energy of such a compound is really