Imperative doc strings (#3792)

* standardize first line class doc strings to imperative style

np.average->np.mean

* imperative doc strings

* imperative doc strings

* revert np.mean to np.average where passing weight kwarg

* imperative doc strings

* """Returns -> """Get

* remove "Returns:" from property doc strings

* bug fix: as_dict should not have been property on SeparationPlane and ExplicitPermutationsAlgorithm

* format property doc strings with leading line break

* ", e.g.," -> ", e.g."

* remove leading "Get" from property doc strings

* Fix TestCoordinationGeometries using as_dict as property which should have been normal method all along

Author: janosh

dev_scripts/chemenv/strategies/multi_weights_strategy_parameters.py

@@ -73,12 +73,12 @@ def simple_expansion(cls, initial_environment_symbol, expected_final_environment
         )
 
     def figure_fractions(self, weights_options: dict, morphing_factors: Sequence[float] | None = None) -> None:
-        """
-        Plot the fractions of the initial and final coordination environments as a function of the morphing factor.
+        """Plot the fractions of the initial and final coordination environments as a
+        function of the morphing factor.
 
         Args:
-            weights_options (dict): The weights options.
-            morphing_factors (list): The morphing factors.
+            weights_options (dict): The weights options. morphing_factors (list): The
+            morphing factors.
         """
         if morphing_factors is None:
             morphing_factors = np.linspace(1.0, 2.0, 21)

pymatgen/alchemy/materials.py

@@ -281,7 +281,7 @@ def from_cif_str(
             primitive (bool): Option to set if the primitive cell should be
                 extracted. Defaults to True. However, there are certain
                 instances where you might want to use a non-primitive cell,
-                e.g., if you are trying to generate all possible orderings of
+                e.g. if you are trying to generate all possible orderings of
                 partial removals or order a disordered structure. Defaults to True.
             occupancy_tolerance (float): If total occupancy of a site is
                 between 1 and occupancy_tolerance, the occupancies will be
@@ -352,8 +352,7 @@ def from_dict(cls, dct: dict) -> Self:
         return cls(struct, history=dct["history"], other_parameters=dct.get("other_parameters"))
 
     def to_snl(self, authors: list[str], **kwargs) -> StructureNL:
-        """
-        Generate a StructureNL from TransformedStructure.
+        """Generate a StructureNL from TransformedStructure.
 
         Args:
             authors (List[str]): List of authors contributing to the generated StructureNL.

pymatgen/alchemy/transmuters.py

@@ -182,7 +182,7 @@ def add_tags(self, tags):
 
         Args:
             tags: A sequence of tags. Note that this should be a sequence of
-                strings, e.g., ["My awesome structures", "Project X"].
+                strings, e.g. ["My awesome structures", "Project X"].
         """
         self.set_parameter("tags", tags)
 
@@ -336,7 +336,7 @@ def batch_write_vasp_input(
             Defaults to True.
         subfolder: Function to create subdirectory name from
             transformed_structure.
-            e.g., lambda x: x.other_parameters["tags"][0] to use the first
+            e.g. lambda x: x.other_parameters["tags"][0] to use the first
             tag.
         include_cif (bool): Boolean indication whether to output a CIF as
             well. CIF files are generally better supported in visualization

pymatgen/analysis/adsorption.py

@@ -139,7 +139,7 @@ def from_bulk_and_miller(
         surf_props, under_coords = [], []
         this_mi_vec = get_mi_vec(this_slab)
         mi_mags = [np.dot(this_mi_vec, site.coords) for site in this_slab]
-        average_mi_mag = np.average(mi_mags)
+        average_mi_mag = np.mean(mi_mags)
         for n, site in enumerate(this_slab):
             bulk_coord = this_slab.site_properties["bulk_coordinations"][n]
             slab_coord = len(vnn_surface.get_nn(this_slab, n))
@@ -355,9 +355,9 @@ def ensemble_center(cls, site_list, indices, cartesian=True):
                 Cartesian coordinate
         """
         if cartesian:
-            return np.average([site_list[idx].coords for idx in indices], axis=0)
+            return np.mean([site_list[idx].coords for idx in indices], axis=0)
 
-        return np.average([site_list[idx].frac_coords for idx in indices], axis=0)
+        return np.mean([site_list[idx].frac_coords for idx in indices], axis=0)
 
     def add_adsorbate(self, molecule: Molecule, ads_coord, repeat=None, translate=True, reorient=True):
         """Add an adsorbate at a particular coordinate. Adsorbate represented

pymatgen/analysis/bond_dissociation.py

@@ -44,8 +44,7 @@ def __init__(
         allow_additional_charge_separation: bool = False,
         multibreak: bool = False,
     ) -> None:
-        """
-        Note that the entries passed by the user must have the following keys: formula_pretty, initial_molecule,
+        """The provided entries must have the following keys: formula_pretty, initial_molecule,
         final_molecule. If a PCM is present, all entries should also have a pcm_dielectric key.
 
         Args:
@@ -327,8 +326,7 @@ def filter_fragment_entries(self, fragment_entries: list) -> None:
                 self.filtered_entries += [entry]
 
     def build_new_entry(self, frags: list, bonds: list) -> list:
-        """
-        Build a new entry for bond dissociation that will be returned to the user.
+        """Build a new entry for bond dissociation that will be returned to the user.
 
         Args:
             frags (list): Fragments involved in the bond dissociation.

pymatgen/analysis/bond_valence.py

@@ -126,8 +126,7 @@ def __init__(
         charge_neutrality_tolerance=CHARGE_NEUTRALITY_TOLERANCE,
         forbidden_species=None,
     ):
-        """
-        Initializes the BV analyzer, with useful defaults.
+        """Initialize the BV analyzer, with useful defaults.
 
         Args:
             symm_tol:
@@ -204,16 +203,15 @@ def _calc_site_probabilities_unordered(self, site, nn):
         return prob
 
     def get_valences(self, structure: Structure):
-        """
-        Returns a list of valences for each site in the structure.
+        """Get a list of valences for each site in the structure.
 
         Args:
             structure: Structure to analyze
 
         Returns:
             A list of valences for each site in the structure (for an ordered structure),
-            e.g., [1, 1, -2] or a list of lists with the valences for each fractional
-            element of each site in the structure (for an unordered structure), e.g., [[2,
+            e.g. [1, 1, -2] or a list of lists with the valences for each fractional
+            element of each site in the structure (for an unordered structure), e.g. [[2,
             4], [3], [-2], [-2], [-2]]
 
         Raises:
@@ -469,7 +467,7 @@ def add_oxidation_state_by_site_fraction(structure, oxidation_states):
     Args:
         oxidation_states (list): List of list of oxidation states for each
             site fraction for each site.
-            E.g., [[2, 4], [3], [-2], [-2], [-2]]
+            e.g. [[2, 4], [3], [-2], [-2], [-2]]
     """
     try:
         for idx, site in enumerate(structure):

pymatgen/analysis/chemenv/connectivity/connected_components.py

@@ -625,14 +625,14 @@ def _order_periodicity_vectors(self):
 
     @property
     def periodicity_vectors(self):
-        """Get periodicity vectors of this connected component."""
+        """Periodicity vectors of this connected component."""
         if self._periodicity_vectors is None:
             self.compute_periodicity()
         return [np.array(pp) for pp in self._periodicity_vectors]
 
     @property
     def periodicity(self):
-        """Get periodicity of this connected component."""
+        """Periodicity of this connected component."""
         if self._periodicity_vectors is None:
             self.compute_periodicity()
         return f"{len(self._periodicity_vectors)}D"

pymatgen/analysis/chemenv/coordination_environments/chemenv_strategies.py

@@ -196,9 +196,8 @@ def from_dict(cls, dct: dict) -> Self:
 
 
 class AbstractChemenvStrategy(MSONable, abc.ABC):
-    """
-    Class used to define a Chemenv strategy for the neighbors and coordination environment to be applied to a
-    StructureEnvironments object.
+    """Base class to define a Chemenv strategy for the neighbors and coordination environment
+    to be applied to a StructureEnvironments object.
     """
 
     AC = AdditionalConditions()