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>

Author: DanielYang59

docs/pymatgen.md

@@ -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.

pymatgen/alchemy/materials.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

pymatgen/analysis/chemenv/coordination_environments/chemenv_strategies.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")

pymatgen/analysis/cost.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
 

pymatgen/analysis/ewald.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.

pymatgen/analysis/fragmenter.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
 

pymatgen/analysis/magnetism/analyzer.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

pymatgen/analysis/reaction_calculator.py

@@ -20,7 +20,7 @@
 
 
 class ThermoData:
-    """A object container for an experimental Thermochemical Data."""
+    """Container for experimental thermo-chemical data."""
 
     def __init__(
         self,

pymatgen/analysis/thermochemistry.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)

pymatgen/core/libxcfunc.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]

pymatgen/core/structure.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):

pymatgen/core/xcfunc.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__(

pymatgen/electronic_structure/bandstructure.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).

pymatgen/electronic_structure/core.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