Update documentation

ross/bearing_seal_element.py

@@ -233,7 +233,20 @@ def __init__(
         self.dof_global_index = None
 
     def _process_coefficient(self, coefficient):
-        """Helper function used to process the coefficient data."""
+        """Helper function used to process the coefficient data.
+
+        Parameters
+        ----------
+        coefficient : float, array
+            The coefficient data to be processed.
+
+        Returns
+        -------
+        coefficient : float, array
+            The processed coefficient data.
+        interpolated : callable
+            A callable for interpolating the coefficient data.
+        """
         interpolated = None
 
         if isinstance(coefficient, (int, float)):
@@ -276,7 +289,14 @@ def _process_coefficient(self, coefficient):
         return coefficient, interpolated
 
     def _get_coefficient_list(self, ignore_mass=False):
-        """List with all bearing coefficients as strings"""
+        """List with all bearing coefficients as strings
+
+        Parameters
+        ----------
+        ignore_mass : bool, optional
+            If True, mass coefficients are excluded from the list.
+            Default is False.
+        """
         coefficients = [
             attr.replace("_interpolated", "")
             for attr in self.__dict__.keys()
@@ -1172,8 +1192,6 @@ class BearingFluidFlow(BearingElement):
         Number of points along the Z direction (direction of flow).
     ntheta: int
         Number of points along the direction theta. NOTE: ntheta must be odd.
-    nradius: int
-        Number of points along the direction r.
     length: float
         Length in the Z direction (m).
 
@@ -1413,7 +1431,7 @@ class SealElement(BearingElement):
         Default is None.
     scale_factor : float, optional
         The scale factor is used to scale the bearing drawing.
-        Default is 0.5.
+        Defaults to half the parent BearingElement's scale factor if not provided.
     color : str, optional
         A color to be used when the element is represented.
         Default is "#77ACA2".
@@ -1469,6 +1487,7 @@ def __init__(
     ):
         self.seal_leakage = seal_leakage
 
+
         super().__init__(
             n=n,
             frequency=frequency,

ross/coupling_element.py

@@ -77,10 +77,10 @@ class CouplingElement(ShaftElement):
         Default is 0.
     o_d : float, optional
         Outer diameter (m). This parameter is primarily used for visualization
-        purposes and does not affect calculations.
+        purposes and does not affect calculations. Default is 0.2.
     L : float, optional
         Element length (m). This parameter is primarily used for visualization
-        purposes and does not affect calculations.
+        purposes and does not affect calculations. Default is 0.2.
     n : int, optional
         Element number (coincident with it's first node).
         If not given, it will be set when the rotor is assembled
@@ -227,6 +227,17 @@ def save(self, file):
 
     @classmethod
     def read_toml_data(cls, data):
+        """Read and parse data stored in a .toml or .json file.
+
+        Parameters
+        ----------
+        data : dict
+            Dictionary obtained from toml.load() or json.load().
+
+        Returns
+        -------
+        The element object.
+        """
         return cls(**data)
 
     def M(self):
@@ -344,6 +355,15 @@ def K(self):
         return K
 
     def Kst(self):
+        """Stiffness matrix for an instance of a coupling element.
+
+        For a coupling element, the stiffness matrix is a 12x12 numpy array of zeros.
+
+        Returns
+        -------
+        Kst : np.ndarray
+            A 12x12 numpy array of zeros.
+        """
         return np.zeros((12, 12))
 
     def C(self):

ross/disk_element.py

@@ -154,6 +154,13 @@ def __str__(self):
         )
 
     def __hash__(self):
+        """Return the hash value of the disk element.
+
+        Returns
+        -------
+        int
+            Hash value based on the element tag.
+        """
         return hash(self.tag)
 
     def dof_mapping(self):
@@ -438,18 +445,86 @@ def _patch(self, position, fig):
 
     @staticmethod
     def calculate_mass(rho, width, i_d, o_d):
+        """Calculate the mass of a disk from its geometry.
+
+        Parameters
+        ----------
+        rho : float
+            Density of the disk material (kg/m^3).
+        width : float
+            Width of the disk (m).
+        i_d : float
+            Inner diameter of the disk (m).
+        o_d : float
+            Outer diameter of the disk (m).
+
+        Returns
+        -------
+        mass : float
+            Mass of the disk element (kg).
+        """
         return rho * np.pi * width * (o_d**2 - i_d**2) / 4
 
     @staticmethod
     def calculate_Ip(m, i_d, o_d):
+        """Calculate the polar moment of inertia of a disk from its geometry.
+
+        Parameters
+        ----------
+        m : float
+            Mass of the disk element (kg).
+        i_d : float
+            Inner diameter of the disk (m).
+        o_d : float
+            Outer diameter of the disk (m).
+
+        Returns
+        -------
+        Ip : float
+            Polar moment of inertia of the disk element (kg.m^2).
+        """
         return m * (o_d**2 + i_d**2) / 8
 
     @staticmethod
     def calculate_Id(Ip, m, width):
+        """Calculate the diametral moment of inertia of a disk from its geometry.
+
+        Parameters
+        ----------
+        Ip : float
+            Polar moment of inertia of the disk element (kg.m^2).
+        m : float
+            Mass of the disk element (kg).
+        width : float
+            Width of the disk (m).
+
+        Returns
+        -------
+        Id : float
+            Diametral moment of inertia of the disk element (kg.m^2).
+        """
         return 1 / 2 * Ip + 1 / 12 * m * width**2
 
     @staticmethod
     def calculate_width(rho, m, i_d, o_d):
+        """Calculate the width of a disk from its geometry and mass.
+
+        Parameters
+        ----------
+        rho : float
+            Density of the disk material (kg/m^3).
+        m : float
+            Mass of the disk element (kg).
+        i_d : float
+            Inner diameter of the disk (m).
+        o_d : float
+            Outer diameter of the disk (m).
+
+        Returns
+        -------
+        width : float
+            Width of the disk element (m).
+        """
         return 4 * m / (rho * np.pi * (o_d**2 - i_d**2))
 
     @classmethod
@@ -538,16 +613,16 @@ def from_table(cls, file, sheet_name=0, tag=None, scale_factor=None, color=None)
         sheet_name : int or str, optional
             Position of the sheet in the file (starting from 0) or its name.
             If none is passed, it is assumed to be the first sheet in the file.
-        tag_list : list, optional
-            list of tags for the disk elements.
+        tag : list, str, optional
+            Tag or list of tags for the disk elements.
             Default is None
-        scale_factor: list, optional
-            List of scale factors for the disk elements patches.
+        scale_factor: list, float, optional
+            Scale factor or list of scale factors for the disk elements patches.
             The scale factor is used to scale the disk drawing.
-            Default is 1.
-        color : list, optional
-            A color to be used when the element is represented.
-            Default is 'Firebrick'.
+            If None, a default list of 1s is used.
+        color : list, str, optional
+            A color or list of colors to be used when the element is represented.
+            If None, a default list of 'Firebrick' is used.
 
         Returns
         -------

ross/element.py

@@ -92,13 +92,31 @@ def read_toml_data(cls, data):
 
     @classmethod
     def load(cls, file):
+        """Load an element from a .toml or .json file.
+
+        Parameters
+        ----------
+        file : str, pathlib.Path
+            The name of the file the element will be loaded from.
+
+        Returns
+        -------
+        The element object.
+        """
         data = load_data(file)
         # extract single dictionary in the data
         data = list(data.values())[0]
         return cls.read_toml_data(data)
 
     @classmethod
     def get_subclasses(cls):
+        """Get all subclasses of the Element class.
+
+        Returns
+        -------
+        subclasses : list
+            A list containing all subclasses of the Element class.
+        """
         subclasses = []
         for subclass in cls.__subclasses__():
             subclasses.append(subclass)

ross/gear_element.py

@@ -20,6 +20,20 @@
 
 
 def mod(val, max_val):
+    """Calculates the remainder of a division, but replaces 0 with max_val.
+
+    Parameters
+    ----------
+    val : float or array-like
+        The value(s) to be divided.
+    max_val : float
+        The divisor.
+
+    Returns
+    -------
+    mod : float or array-like
+        The remainder of the division, or max_val if the remainder is 0 and val is not 0.
+    """
     mod = np.mod(val, max_val)
     return np.where((np.isclose(mod, 0)) & (val != 0), max_val, mod)
 
@@ -805,6 +819,19 @@ def _inv_ka(self, beta):
         return inv_ka
 
     def _integrate_transiction_term(self, func):
+        """Integrates a function over the transition region of the gear tooth.
+
+        Parameters
+        ----------
+        func : callable
+            The function to be integrated. It should accept the angle, the curve
+            computation method, and the differential method.
+
+        Returns
+        -------
+        inv_k_t : float
+            The integrated inverse stiffness value for the transition region.
+        """
         inv_k_t, _ = sp.integrate.quad(
             lambda gamma: func(gamma, self._compute_transition_curve, self._diff_gamma),
             np.pi / 2,
@@ -813,6 +840,21 @@ def _integrate_transiction_term(self, func):
         return inv_k_t
 
     def _integrate_invol_term(self, func, beta):
+        """Integrates a function over the involute region of the gear tooth.
+
+        Parameters
+        ----------
+        func : callable
+            The function to be integrated. It should accept the angle, the curve
+            computation method, and the differential method.
+        beta : float
+            The upper limit of integration (current contact angle).
+
+        Returns
+        -------
+        inv_k_i : float
+            The integrated inverse stiffness value for the involute region.
+        """
         tau_c = self.tau_c
         inv_k_i, error = sp.integrate.quad(
             lambda tau: func(tau, self._compute_involute_curve, self._diff_tau),
@@ -1093,6 +1135,20 @@ def _square_varying_stiffness(self, theta_range):
         return stiffness
 
     def _calculate_contact_ratio(self, driving_addendum_radius, driven_addendum_radius):
+        """Calculates the contact ratio of the gear pair.
+
+        Parameters
+        ----------
+        driving_addendum_radius : float
+            Addendum radius of the driving gear (m).
+        driven_addendum_radius : float
+            Addendum radius of the driven gear (m).
+
+        Returns
+        -------
+        contact_ratio : float
+            The calculated contact ratio.
+        """
         rb1 = self.driving_gear.base_radius
         rb2 = self.driven_gear.base_radius