Merge branch 'master' into kpoints-tuple-type

pymatgen/analysis/chempot_diagram.py

@@ -677,7 +677,7 @@ def get_centroid_2d(vertices: np.ndarray) -> np.ndarray:
             circumferentially
 
     Returns:
-        Array giving 2-d centroid coordinates
+        np.array: Giving 2-d centroid coordinates.
     """
     cx = 0
     cy = 0

pymatgen/analysis/diffraction/tem.py

@@ -134,7 +134,8 @@ def get_interplanar_spacings(
             points (tuple): the desired hkl indices.
 
         Returns:
-            Dict of hkl to its interplanar spacing, in angstroms (float).
+            dict[tuple[int, int, int], float]: hkl planes mapped to
+                interplanar spacings, in angstroms (float).
         """
         points_filtered = self.zone_axis_filter(points)
         if (0, 0, 0) in points_filtered:
@@ -152,7 +153,7 @@ def bragg_angles(
             interplanar_spacings (dict): dictionary of hkl to interplanar spacing
 
         Returns:
-            dict of hkl plane (3-tuple) to Bragg angle in radians (float)
+            dict[tuple[int, int, int], float]: hkl planes mapped to Bragg angles [radians]
         """
         plane = list(interplanar_spacings)
         interplanar_spacings_val = np.array(list(interplanar_spacings.values()))

pymatgen/analysis/eos.py

@@ -310,7 +310,7 @@ def _func(self, volume, params):
 
 
 class PourierTarantola(EOSBase):
-    """PourierTarantola EOS."""
+    """Pourier-Tarantola EOS."""
 
     def _func(self, volume, params):
         """Pourier-Tarantola equation from PRB 70, 224107."""

pymatgen/analysis/graphs.py

@@ -1398,7 +1398,7 @@ def __eq__(self, other: object) -> bool:
 
         edges_other = {(u, v, data["to_jimage"]) for u, v, data in other_sorted.graph.edges(keys=False, data=True)}
 
-        return (edges == edges_other) and (self.structure == other_sorted.structure)
+        return edges == edges_other and self.structure == other_sorted.structure
 
     def diff(self, other: StructureGraph, strict: bool = True) -> dict:
         """
@@ -2799,7 +2799,7 @@ def __eq__(self, other: object) -> bool:
 
         edges_other = set(other_sorted.graph.edges(keys=False))
 
-        return (edges == edges_other) and (self.molecule == other_sorted.molecule)
+        return edges == edges_other and self.molecule == other_sorted.molecule
 
     def isomorphic_to(self, other: MoleculeGraph) -> bool:
         """

pymatgen/analysis/hhi.py

@@ -55,10 +55,10 @@ def get_hhi(self, comp_or_form):
         Gets the reserve and production HHI for a compound.
 
         Args:
-            comp_or_form (Composition or String): A Composition or String formula
+            comp_or_form (CompositionLike): A Composition or String formula
 
         Returns:
-            A tuple representing the (HHI_production, HHI_reserve)
+            tuple[float, float]: HHI_production, HHI_reserve
         """
         try:
             if not isinstance(comp_or_form, Composition):

pymatgen/analysis/interface_reactions.py

@@ -589,7 +589,7 @@ def minimum(self):
         mixing ratio x_min.
 
         Returns:
-            Tuple (x_min, E_min).
+            tuple[float, float]: (x_min, E_min).
         """
         return min(((x, energy) for _, x, energy, _, _ in self.get_kinks()), key=lambda tup: tup[1])
 

pymatgen/analysis/local_env.py

@@ -303,7 +303,7 @@ def get_cn(
                 'take_max_species' will use Fe as the site specie.
 
         Returns:
-            cn (float): coordination number.
+            float: coordination number.
         """
         structure = _handle_disorder(structure, on_disorder)
         siw = self.get_nn_info(structure, n)
@@ -322,7 +322,7 @@ def get_cn_dict(self, structure: Structure, n: int, use_weights: bool = False):
                 weight).
 
         Returns:
-            cn (dict): dictionary of CN of each element bonded to site
+            dict[str, float]: coordination number of each element bonded to site with index n in structure.
         """
         siw = self.get_nn_info(structure, n)
 
@@ -409,6 +409,7 @@ def get_all_nn_info(self, structure: Structure):
 
         Args:
             structure (Structure): Input structure
+
         Returns:
             List of NN site information for each site in the structure. Each
                 entry has the same format as `get_nn_info`
@@ -4063,7 +4064,7 @@ def get_cn(self, structure: Structure, n: int, **kwargs) -> float:  # type: igno
                 'take_max_species' will use Fe as the site specie.
 
         Returns:
-            cn (float): coordination number.
+            float: coordination number.
         """
         use_weights = kwargs.get("use_weights", False)
         if self.weighted_cn != use_weights:
@@ -4084,7 +4085,7 @@ def get_cn_dict(self, structure: Structure, n: int, use_weights: bool = False, *
                 weight).
 
         Returns:
-            cn (dict): dictionary of CN of each element bonded to site
+            dict[int, list[dict]]: coordination number and list of coordinated sites
         """
         if self.weighted_cn != use_weights:
             raise ValueError("The weighted_cn parameter and use_weights parameter should match!")

pymatgen/analysis/magnetism/heisenberg.py

@@ -128,10 +128,9 @@ def _get_unique_sites(structure):
             structure (Structure): ground state Structure object.
 
         Returns:
-            unique_site_ids (dict): maps tuples of equivalent site indices to a
-                unique int identifier
-            wyckoff_ids (dict): maps tuples of equivalent site indices to their
-                wyckoff symbols
+            tuple[dict, dict]: unique_site_ids maps tuples of equivalent site indices to a
+                unique int identifier.
+                wyckoff_ids maps tuples of equivalent site indices to their wyckoff symbols
         """
         # Get a nonmagnetic representation of the supercell geometry
         s0 = CollinearMagneticStructureAnalyzer(
@@ -356,7 +355,7 @@ def get_exchange(self):
         solve for the exchange parameters.
 
         Returns:
-            ex_params (dict): Exchange parameter values (meV/atom).
+            dict[str, float]: Exchange parameters (meV/atom).
         """
         ex_mat = self.ex_mat
         # Solve the matrix equation for J_ij values
@@ -466,7 +465,7 @@ def estimate_exchange(self, fm_struct=None, afm_struct=None, fm_e=None, afm_e=No
             afm_e (float): afm energy/atom
 
         Returns:
-            j_avg (float): Average exchange parameter (meV/atom)
+            float: Average J exchange parameter (meV/atom)
         """
         # Get low energy orderings if not supplied
         if any(arg is None for arg in [fm_struct, afm_struct, fm_e, afm_e]):
@@ -503,7 +502,7 @@ def get_mft_temperature(self, j_avg):
             j_avg (float): j_avg (float): Average exchange parameter (meV/atom)
 
         Returns:
-            mft_t (float): Critical temperature (K)
+            float: Critical temperature mft_t (K)
         """
         n_sub_lattices = len(self.unique_site_ids)
         k_boltzmann = 0.0861733  # meV/K
@@ -545,7 +544,7 @@ def get_interaction_graph(self, filename=None):
             filename (str): if not None, save interaction graph to filename.
 
         Returns:
-            igraph (StructureGraph): Exchange interaction graph.
+            StructureGraph: Exchange interaction graph.
         """
         structure = self.ordered_structures[0]
         sgraph = self.sgraphs[0]
@@ -593,7 +592,7 @@ def _get_j_exc(self, i, j, dist):
                 (10E-2 precision)
 
         Returns:
-            j_exc (float): Exchange parameter in meV
+            float: Exchange parameter J_exc in meV
         """
         # Get unique site identifiers
         i_index = 0
@@ -964,7 +963,7 @@ def _get_j_exc(self, i, j, dist):
             dist (float): distance (Angstrom) between sites +- tol
 
         Returns:
-            j_exc (float): Exchange parameter in meV
+            float: Exchange parameter J_exc in meV
         """
         # Get unique site identifiers
         i_index = 0

pymatgen/analysis/piezo_sensitivity.py

@@ -693,6 +693,7 @@ def rand_piezo(struct, pointops, sharedops, BEC, IST, FCM, anumiter=10):
         IST (numpy array): Nx3x3x3 array representing the internal strain tensor
         FCM (numpy array): NxNx3x3 array representing the born effective charge tensor
         anumiter (int): number of iterations for acoustic sum rule convergence
+
     Returns:
         list in the form of [Nx3x3 random born effective charge tenosr,
         Nx3x3x3 random internal strain tensor, NxNx3x3 random force constant matrix, 3x3x3 piezo tensor]

pymatgen/analysis/structure_analyzer.py

@@ -429,9 +429,8 @@ def parse_oxide(self) -> tuple[str, int]:
         Determines if an oxide is a peroxide/superoxide/ozonide/normal oxide.
 
         Returns:
-            oxide_type (str): Type of oxide
-            ozonide/peroxide/superoxide/hydroxide/None.
-            nbonds (int): Number of peroxide/superoxide/hydroxide bonds in structure.
+            tuple[str, int]: Type of oxide (ozonide/peroxide/superoxide/hydroxide/None) and number of
+                peroxide/superoxide/hydroxide bonds in structure.
         """
         structure = self.structure
         relative_cutoff = self.relative_cutoff

pymatgen/analysis/structure_matcher.py

@@ -997,7 +997,7 @@ def get_best_electronegativity_anonymous_mapping(self, struct1: Structure, struc
             struct2 (Structure): 2nd structure
 
         Returns:
-            min_mapping (dict): Mapping of struct1 species to struct2 species
+            dict[Element, Element] | None: Mapping of struct1 species to struct2 species.
         """
         struct1, struct2 = self._process_species([struct1, struct2])
         struct1, struct2, fu, s1_supercell = self._preprocess(struct1, struct2)

pymatgen/analysis/surface_analysis.py

@@ -448,7 +448,7 @@ def get_stable_entry_at_u(
         delu_default=0,
         no_doped=False,
         no_clean=False,
-    ):
+    ) -> tuple[SlabEntry, float]:
         """
         Returns the entry corresponding to the most stable slab for a particular
             facet at a specific chempot. We assume that surface energy is constant
@@ -465,7 +465,7 @@ def get_stable_entry_at_u(
             no_clean (bool): Consider stability of doped slabs only.
 
         Returns:
-            SlabEntry, surface_energy (float)
+            tuple[SlabEntry, float]: The most stable slab entry and its surface energy.
         """
         all_delu_dict = self.set_all_variables(delu_dict, delu_default)
 

pymatgen/core/interface.py

@@ -1373,14 +1373,15 @@ def enum_sigma_hex(cutoff, r_axis, c2_a2_ratio):
                 which is rational number. If irrational, set c2_a2_ratio = None
 
         Returns:
-            sigmas (dict): dictionary with keys as the possible integer sigma values and values as list of the
-                possible rotation angles to the corresponding sigma values. e.g. the format as
-                    {sigma1: [angle11,angle12,...], sigma2: [angle21, angle22,...],...}
-                Note: the angles are the rotation angle of one grain respect to the
-                other grain.
-                When generate the microstructure of the grain boundary using these
-                angles, you need to analyze the symmetry of the structure. Different
-                angles may result in equivalent microstructures.
+            dict: sigmas dictionary with keys as the possible integer sigma values
+                and values as list of the possible rotation angles to the
+                corresponding sigma values. e.g. the format as
+                {sigma1: [angle11,angle12,...], sigma2: [angle21, angle22,...],...}
+                Note: the angles are the rotation angles of one grain respect to
+                the other grain.
+                When generate the microstructures of the grain boundary using these angles,
+                you need to analyze the symmetry of the structure. Different angles may
+                result in equivalent microstructures.
         """
         sigmas = {}
         # make sure gcd(r_axis)==1
@@ -1485,17 +1486,14 @@ def enum_sigma_rho(cutoff, r_axis, ratio_alpha):
                     If irrational, set ratio_alpha = None.
 
         Returns:
-            sigmas (dict):
-                    dictionary with keys as the possible integer sigma values
-                    and values as list of the possible rotation angles to the
-                    corresponding sigma values.
-                    e.g. the format as
-                    {sigma1: [angle11,angle12,...], sigma2: [angle21, angle22,...],...}
-                    Note: the angles are the rotation angle of one grain respect to the
-                    other grain.
-                    When generate the microstructure of the grain boundary using these
-                    angles, you need to analyze the symmetry of the structure. Different
-                    angles may result in equivalent microstructures.
+            dict[int, list[float]]: keys are possible integer sigma values
+                and values are lists of possible rotation angles to the
+                {sigma1: [angle11, angle12,...], sigma2: [angle21, angle22,...],...}
+                Note: the angles are the rotation angle of one grain respect to the
+                other grain.
+                When generating the microstructure of the grain boundary using these
+                angles, you need to analyze the symmetry of the structure. Different
+                angles may result in equivalent microstructures.
         """
         sigmas = {}
         # transform four index notation to three index notation

pymatgen/core/lattice.py

@@ -209,7 +209,7 @@ def d_hkl(self, miller_index: ArrayLike) -> float:
             miller_index ([h,k,l]): Miller index of plane
 
         Returns:
-            d_hkl (float)
+            float: distance between hkl plane and origin
         """
         g_star = self.reciprocal_lattice_crystallographic.metric_tensor
         hkl = np.array(miller_index)

pymatgen/core/sites.py

@@ -544,7 +544,7 @@ def distance(self, other: PeriodicSite, jimage: ArrayLike | None = None):
                 the image that is nearest to the site is found.
 
         Returns:
-            distance (float): Distance between the two sites
+            float: distance between the two sites.
         """
         return self.distance_and_image(other, jimage)[0]
 

pymatgen/electronic_structure/boltztrap.py

@@ -1780,8 +1780,7 @@ def parse_intrans(path_dir):
             path_dir: (str) dir containing the boltztrap.intrans file
 
         Returns:
-            intrans (dict): a dictionary containing various inputs that had
-                been used in the Boltztrap run.
+            dict: various inputs that had been used in the Boltztrap run.
         """
         intrans = {}
         with open(f"{path_dir}/boltztrap.intrans") as file:

pymatgen/electronic_structure/cohp.py

@@ -978,7 +978,7 @@ def icohpvalue(self, spin=Spin.up):
             spin: Spin.up or Spin.down.
 
         Returns:
-            icohpvalue (float) corresponding to chosen spin.
+            float: corresponding to chosen spin.
         """
         if not self.is_spin_polarized and spin == Spin.down:
             raise ValueError("The calculation was not performed with spin polarization")
@@ -992,7 +992,7 @@ def icohpvalue_orbital(self, orbitals, spin=Spin.up):
             spin: Spin.up or Spin.down.
 
         Returns:
-            icohpvalue (float) corresponding to chosen spin.
+            float: corresponding to chosen spin.
         """
         if not self.is_spin_polarized and spin == Spin.down:
             raise ValueError("The calculation was not performed with spin polarization")
@@ -1002,7 +1002,8 @@ def icohpvalue_orbital(self, orbitals, spin=Spin.up):
 
     @property
     def icohp(self):
-        """Dict with icohps for spinup and spindown
+        """Dict with ICOHPs for spin up and spin down.
+
         Returns:
             dict={Spin.up: icohpvalue for spin.up, Spin.down: icohpvalue for spin.down}.
         """

pymatgen/ext/matproj_legacy.py

@@ -297,7 +297,7 @@ def get_materials_id_from_task_id(self, task_id):
             task_id (str): A task id.
 
         Returns:
-            materials_id (str)
+            str: An MP material id.
         """
         return self._make_request(f"/materials/mid_from_tid/{task_id}")
 
@@ -308,7 +308,7 @@ def get_materials_id_references(self, material_id):
             material_id (str): A material id.
 
         Returns:
-            BibTeX (str)
+            str: A BibTeX formatted string.
         """
         return self._make_request(f"/materials/{material_id}/refs")