doc string return type fixes

.pre-commit-config.yaml

@@ -8,14 +8,14 @@ ci:
 
 repos:
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.3.4
+    rev: v0.3.5
     hooks:
       - id: ruff
         args: [--fix, --unsafe-fixes]
       - id: ruff-format
 
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.5.0
+    rev: v4.6.0
     hooks:
       - id: check-yaml
       - id: end-of-file-fixer

pymatgen/analysis/dimensionality.py

@@ -67,7 +67,7 @@ def get_dimensionality_larsen(bonded_structure):
             CrystalNN.get_bonded_structure() method.
 
     Returns:
-        (int): The dimensionality of the structure.
+        int: The dimensionality of the structure.
     """
     return max(c["dimensionality"] for c in get_structure_components(bonded_structure))
 
@@ -108,19 +108,19 @@ def get_structure_components(
             objects for zero-dimensional components.
 
     Returns:
-        (list of dict): Information on the components in a structure as a list
-        of dictionaries with the keys:
-
-        - "structure_graph": A pymatgen StructureGraph object for the
-            component.
-        - "dimensionality": The dimensionality of the structure component as an
-            int.
-        - "orientation": If inc_orientation is `True`, the orientation of the
-            component as a tuple. E.g. (1, 1, 1)
-        - "site_ids": If inc_site_ids is `True`, the site indices of the
-            sites in the component as a tuple.
-        - "molecule_graph": If inc_molecule_graph is `True`, the site a
-            MoleculeGraph object for zero-dimensional components.
+        list[dict]: Information on the components in a structure as a list
+            of dictionaries with the keys:
+
+            - "structure_graph": A pymatgen StructureGraph object for the
+                component.
+            - "dimensionality": The dimensionality of the structure component as an
+                int.
+            - "orientation": If inc_orientation is `True`, the orientation of the
+                component as a tuple. E.g. (1, 1, 1)
+            - "site_ids": If inc_site_ids is `True`, the site indices of the
+                sites in the component as a tuple.
+            - "molecule_graph": If inc_molecule_graph is `True`, the site a
+                MoleculeGraph object for zero-dimensional components.
     """
     comp_graphs = (bonded_structure.graph.subgraph(c) for c in nx.weakly_connected_components(bonded_structure.graph))
 
@@ -167,8 +167,7 @@ def get_structure_components(
 
 
 def calculate_dimensionality_of_site(bonded_structure, site_index, inc_vertices=False):
-    """
-    Calculates the dimensionality of the component containing the given site.
+    """Calculates the dimensionality of the component containing the given site.
 
     Implements directly the modified breadth-first-search algorithm described in
     Algorithm 1 of:
@@ -186,10 +185,10 @@ def calculate_dimensionality_of_site(bonded_structure, site_index, inc_vertices=
             images) of the component.
 
     Returns:
-        (int or tuple): If inc_vertices is False, the dimensionality of the
-        component will be returned as an int. If inc_vertices is true, the
-        function will return a tuple of (dimensionality, vertices), where
-        vertices is a list of tuples. E.g. [(0, 0, 0), (1, 1, 1)].
+        int | tuple: If inc_vertices is False, the dimensionality of the
+            component will be returned as an int. If inc_vertices is true, the
+            function will return a tuple of (dimensionality, vertices), where
+            vertices is a list of tuples. E.g. [(0, 0, 0), (1, 1, 1)].
     """
 
     def neighbors(comp_index):
@@ -258,7 +257,7 @@ def zero_d_graph_to_molecule_graph(bonded_structure, graph):
             interest.
 
     Returns:
-        (MoleculeGraph): A MoleculeGraph object of the component.
+        MoleculeGraph: A MoleculeGraph object of the component.
     """
     seen_indices = []
     sites = []
@@ -327,8 +326,8 @@ def get_dimensionality_cheon(
              structures. Testing with a larger cell circumvents this problem
 
     Returns:
-        (str): dimension of the largest cluster as a string. If there are ions
-        or molecules it returns 'intercalated ion/molecule'
+        str: dimension of the largest cluster as a string. If there are ions
+            or molecules it returns 'intercalated ion/molecule'
     """
     if ldict is None:
         ldict = JmolNN().el_radius
@@ -396,9 +395,9 @@ def find_connected_atoms(struct, tolerance=0.45, ldict=None):
             from JMol are used as default
 
     Returns:
-        (np.ndarray): A numpy array of shape (number of atoms, number of atoms);
-        If any image of atom j is bonded to atom i with periodic boundary
-        conditions, the matrix element [atom i, atom j] is 1.
+        np.ndarray: A numpy array of shape (number of atoms, number of atoms);
+            If any image of atom j is bonded to atom i with periodic boundary
+            conditions, the matrix element [atom i, atom j] is 1.
     """
     if ldict is None:
         ldict = JmolNN().el_radius

pymatgen/analysis/graphs.py

@@ -812,7 +812,7 @@ def get_coordination_of_site(self, n: int) -> int:
             n: index of site
 
         Returns:
-            (int): number of neighbors of site n.
+            int: number of neighbors of site n.
         """
         n_self_loops = sum(1 for n, v in self.graph.edges(n) if n == v)
         return self.graph.degree(n) - n_self_loops
@@ -2496,7 +2496,7 @@ def get_coordination_of_site(self, n) -> int:
             n: index of site
 
         Returns:
-            (int): the number of neighbors of site n.
+            int: the number of neighbors of site n.
         """
         n_self_loops = sum(1 for n, v in self.graph.edges(n) if n == v)
         return self.graph.degree(n) - n_self_loops

pymatgen/analysis/local_env.py

@@ -1965,7 +1965,7 @@ def vol_tetra(vt1, vt2, vt3, vt4):
         vt4 (array-like): coordinates of vertex 4.
 
     Returns:
-        (float): volume of the tetrahedron.
+        float: volume of the tetrahedron.
     """
     return np.abs(np.dot((vt1 - vt4), np.cross((vt2 - vt4), (vt3 - vt4)))) / 6
 
@@ -1982,7 +1982,7 @@ def get_okeeffe_params(el_symbol):
         el_symbol (str): element symbol.
 
     Returns:
-        (dict): atom-size ('r') and electronegativity-related ('c') parameter.
+        dict: atom-size ('r') and electronegativity-related ('c') parameter.
     """
     el = Element(el_symbol)
     if el not in list(BV_PARAMS):

pymatgen/analysis/phase_diagram.py

@@ -3823,13 +3823,13 @@ def order_phase_diagram(lines, stable_entries, unstable_entries, ordering):
             'Left','Right']
 
     Returns:
-        (newlines, newstable_entries, newunstable_entries):
-        - newlines is a list of list of coordinates for lines in the PD.
-        - newstable_entries is a {coordinate : entry} for each stable node
-        in the phase diagram. (Each coordinate can only have one
-        stable phase)
-        - newunstable_entries is a {entry: coordinates} for all unstable
-        nodes in the phase diagram.
+        tuple[list, dict, dict]:
+            - new_lines is a list of list of coordinates for lines in the PD.
+            - new_stable_entries is a {coordinate: entry} for each stable node
+            in the phase diagram. (Each coordinate can only have one
+            stable phase)
+            - new_unstable_entries is a {entry: coordinates} for all unstable
+            nodes in the phase diagram.
     """
     yup = -1000.0
     xleft = 1000.0
@@ -3859,104 +3859,104 @@ def order_phase_diagram(lines, stable_entries, unstable_entries, ordering):
             # The coordinates were already in the user ordering
             return lines, stable_entries, unstable_entries
 
-        newlines = [[np.array(1 - x), y] for x, y in lines]
-        newstable_entries = {(1 - c[0], c[1]): entry for c, entry in stable_entries.items()}
-        newunstable_entries = {entry: (1 - c[0], c[1]) for entry, c in unstable_entries.items()}
-        return newlines, newstable_entries, newunstable_entries
+        new_lines = [[np.array(1 - x), y] for x, y in lines]
+        new_stable_entries = {(1 - c[0], c[1]): entry for c, entry in stable_entries.items()}
+        new_unstable_entries = {entry: (1 - c[0], c[1]) for entry, c in unstable_entries.items()}
+        return new_lines, new_stable_entries, new_unstable_entries
     if nameup == ordering[1]:
         if nameleft == ordering[2]:
             c120 = np.cos(2 * np.pi / 3.0)
             s120 = np.sin(2 * np.pi / 3.0)
-            newlines = []
+            new_lines = []
             for x, y in lines:
                 newx = np.zeros_like(x)
                 newy = np.zeros_like(y)
                 for ii, xx in enumerate(x):
                     newx[ii] = c120 * (xx - cc[0]) - s120 * (y[ii] - cc[1]) + cc[0]
                     newy[ii] = s120 * (xx - cc[0]) + c120 * (y[ii] - cc[1]) + cc[1]
-                newlines.append([newx, newy])
-            newstable_entries = {
+                new_lines.append([newx, newy])
+            new_stable_entries = {
                 (
                     c120 * (c[0] - cc[0]) - s120 * (c[1] - cc[1]) + cc[0],
                     s120 * (c[0] - cc[0]) + c120 * (c[1] - cc[1]) + cc[1],
                 ): entry
                 for c, entry in stable_entries.items()
             }
-            newunstable_entries = {
+            new_unstable_entries = {
                 entry: (
                     c120 * (c[0] - cc[0]) - s120 * (c[1] - cc[1]) + cc[0],
                     s120 * (c[0] - cc[0]) + c120 * (c[1] - cc[1]) + cc[1],
                 )
                 for entry, c in unstable_entries.items()
             }
-            return newlines, newstable_entries, newunstable_entries
+            return new_lines, new_stable_entries, new_unstable_entries
         c120 = np.cos(2 * np.pi / 3.0)
         s120 = np.sin(2 * np.pi / 3.0)
-        newlines = []
+        new_lines = []
         for x, y in lines:
             newx = np.zeros_like(x)
             newy = np.zeros_like(y)
             for ii, xx in enumerate(x):
                 newx[ii] = -c120 * (xx - 1.0) - s120 * y[ii] + 1.0
                 newy[ii] = -s120 * (xx - 1.0) + c120 * y[ii]
-            newlines.append([newx, newy])
-        newstable_entries = {
+            new_lines.append([newx, newy])
+        new_stable_entries = {
             (
                 -c120 * (c[0] - 1.0) - s120 * c[1] + 1.0,
                 -s120 * (c[0] - 1.0) + c120 * c[1],
             ): entry
             for c, entry in stable_entries.items()
         }
-        newunstable_entries = {
+        new_unstable_entries = {
             entry: (
                 -c120 * (c[0] - 1.0) - s120 * c[1] + 1.0,
                 -s120 * (c[0] - 1.0) + c120 * c[1],
             )
             for entry, c in unstable_entries.items()
         }
-        return newlines, newstable_entries, newunstable_entries
+        return new_lines, new_stable_entries, new_unstable_entries
     if nameup == ordering[2]:
         if nameleft == ordering[0]:
             c240 = np.cos(4 * np.pi / 3.0)
             s240 = np.sin(4 * np.pi / 3.0)
-            newlines = []
+            new_lines = []
             for x, y in lines:
                 newx = np.zeros_like(x)
                 newy = np.zeros_like(y)
                 for ii, xx in enumerate(x):
                     newx[ii] = c240 * (xx - cc[0]) - s240 * (y[ii] - cc[1]) + cc[0]
                     newy[ii] = s240 * (xx - cc[0]) + c240 * (y[ii] - cc[1]) + cc[1]
-                newlines.append([newx, newy])
-            newstable_entries = {
+                new_lines.append([newx, newy])
+            new_stable_entries = {
                 (
                     c240 * (c[0] - cc[0]) - s240 * (c[1] - cc[1]) + cc[0],
                     s240 * (c[0] - cc[0]) + c240 * (c[1] - cc[1]) + cc[1],
                 ): entry
                 for c, entry in stable_entries.items()
             }
-            newunstable_entries = {
+            new_unstable_entries = {
                 entry: (
                     c240 * (c[0] - cc[0]) - s240 * (c[1] - cc[1]) + cc[0],
                     s240 * (c[0] - cc[0]) + c240 * (c[1] - cc[1]) + cc[1],
                 )
                 for entry, c in unstable_entries.items()
             }
-            return newlines, newstable_entries, newunstable_entries
+            return new_lines, new_stable_entries, new_unstable_entries
         c240 = np.cos(4 * np.pi / 3.0)
         s240 = np.sin(4 * np.pi / 3.0)
-        newlines = []
+        new_lines = []
         for x, y in lines:
             newx = np.zeros_like(x)
             newy = np.zeros_like(y)
             for ii, xx in enumerate(x):
                 newx[ii] = -c240 * xx - s240 * y[ii]
                 newy[ii] = -s240 * xx + c240 * y[ii]
-            newlines.append([newx, newy])
-        newstable_entries = {
+            new_lines.append([newx, newy])
+        new_stable_entries = {
             (-c240 * c[0] - s240 * c[1], -s240 * c[0] + c240 * c[1]): entry for c, entry in stable_entries.items()
         }
-        newunstable_entries = {
+        new_unstable_entries = {
             entry: (-c240 * c[0] - s240 * c[1], -s240 * c[0] + c240 * c[1]) for entry, c in unstable_entries.items()
         }
-        return newlines, newstable_entries, newunstable_entries
+        return new_lines, new_stable_entries, new_unstable_entries
     raise ValueError("Invalid ordering.")

pymatgen/analysis/solar/slme.py

@@ -60,7 +60,7 @@ def to_matrix(xx, yy, zz, xy, yz, xz):
         xz (float): xz component of the matrix.
 
     Returns:
-        (np.array): The matrix, as a 3x3 numpy array.
+        np.array: The matrix, as a 3x3 numpy array.
     """
     return np.array([[xx, xy, xz], [xy, yy, yz], [xz, yz, zz]])
 
@@ -94,7 +94,7 @@ def absorption_coefficient(dielectric):
             - element 2: imaginary dielectric tensors, in ``[xx, yy, zz, xy, xz, yz]`` format.
 
     Returns:
-        (np.array): absorption coefficient using eV as frequency units (cm^-1).
+        np.array: absorption coefficient using eV as frequency units (cm^-1).
     """
     energies_in_eV = np.array(dielectric[0])
     real_dielectric = parse_dielectric_data(dielectric[1])

pymatgen/analysis/structure_prediction/dopant_predictor.py

@@ -26,13 +26,13 @@ def get_dopants_from_substitution_probabilities(structure, num_dopants=5, thresh
             returned.
 
     Returns:
-        (dict): Dopant suggestions, given as a dictionary with keys "n_type" and
-        "p_type". The suggestions for each doping type are given as a list of
-        dictionaries, each with they keys:
+        dict: Dopant suggestions, given as a dictionary with keys "n_type" and
+            "p_type". The suggestions for each doping type are given as a list of
+            dictionaries, each with they keys:
 
-        - "probability": The probability of substitution.
-        - "dopant_species": The dopant species.
-        - "original_species": The substituted species.
+            - "probability": The probability of substitution.
+            - "dopant_species": The dopant species.
+            - "original_species": The substituted species.
     """
     els_have_oxi_states = [hasattr(s, "oxi_state") for s in structure.species]
 
@@ -72,15 +72,15 @@ def get_dopants_from_shannon_radii(bonded_structure, num_dopants=5, match_oxi_si
             returned.
 
     Returns:
-        (dict): Dopant suggestions, given as a dictionary with keys "n_type" and
-        "p_type". The suggestions for each doping type are given as a list of
-        dictionaries, each with they keys:
+        dict: Dopant suggestions, given as a dictionary with keys "n_type" and
+            "p_type". The suggestions for each doping type are given as a list of
+            dictionaries, each with they keys:
 
-        - "radii_diff": The difference between the Shannon radii of the species.
-        - "dopant_spcies": The dopant species.
-        - "original_species": The substituted species.
+            - "radii_diff": The difference between the Shannon radii of the species.
+            - "dopant_species": The dopant species.
+            - "original_species": The substituted species.
     """
-    # get a list of all Species for all elements in all their common oxid states
+    # get a list of all Species for all elements in all their common oxidation states
     all_species = [Species(el, oxi) for el in Element for oxi in el.common_oxidation_states]
 
     # get a series of tuples with (coordination number, specie)
@@ -164,13 +164,13 @@ def _shannon_radii_from_cn(species_list, cn_roman, radius_to_compare=0):
             shannon radii and this radius.
 
     Returns:
-        (list of dict): The Shannon radii for all Species in species. Formatted
-        as a list of dictionaries, with the keys:
+        list[dict]: The Shannon radii for all Species in species. Formatted
+            as a list of dictionaries, with the keys:
 
-        - "species": The species with charge state.
-        - "radius": The Shannon radius for the species.
-        - "radius_diff": The difference between the Shannon radius and the
-            radius_to_compare optional argument.
+            - "species": The species with charge state.
+            - "radius": The Shannon radius for the species.
+            - "radius_diff": The difference between the Shannon radius and the
+                radius_to_compare optional argument.
     """
     shannon_radii = []
 

pymatgen/analysis/surface_analysis.py

@@ -1304,7 +1304,7 @@ def entry_dict_from_list(all_slab_entries):
         all_slab_entries (list): List of SlabEntry objects
 
     Returns:
-        (dict): Dictionary of SlabEntry with the Miller index as the main
+        dict: Dictionary of SlabEntry with the Miller index as the main
             key to a dictionary with a clean SlabEntry as the key to a
             list of adsorbed SlabEntry.
     """