Merge pull request #445 from RocketPy-Team/docs/improve_mass_docs

DOCs: improve mass and inertia docs

Author: Gui-FernandesBR

rocketpy/motors/hybrid_motor.py

@@ -42,15 +42,17 @@ class HybridMotor(Motor):
     HybridMotor.liquid : LiquidMotor
         Liquid motor object that composes the hybrid motor.
     HybridMotor.dry_mass : float
-        The total mass of the motor structure, including chambers
-        and tanks, when it is empty and does not contain any propellant.
+        Same as in Motor class. See the :class:`Motor <rocketpy.Motor>` docs.
     HybridMotor.propellant_initial_mass : float
-        Total propellant initial mass in kg.
+        Total propellant initial mass in kg. This is the sum of the initial
+        mass of fluids in each tank and the initial mass of the solid grains.
     HybridMotor.total_mass : Function
         Total motor mass in kg as a function of time, defined as the sum
-        of propellant and dry mass.
+        of the dry mass (motor's structure mass) and the propellant mass, which
+        varies with time.
     HybridMotor.propellant_mass : Function
-        Total propellant mass in kg as a function of time.
+        Total propellant mass in kg as a function of time, this includes the
+        mass of fluids in each tank and the mass of the solid grains.
     HybridMotor.total_mass_flow_rate : Function
         Time derivative of propellant total mass in kg/s as a function
         of time as obtained by the thrust source.
@@ -199,8 +201,7 @@ def __init__(
 
             .. seealso:: :doc:`Thrust Source Details </user/motors/thrust>`
         dry_mass : int, float
-            The total mass of the motor structure, including chambers
-            and tanks, when it is empty and does not contain any propellant.
+            Same as in Motor class. See the :class:`Motor <rocketpy.Motor>` docs
         dry_inertia : tuple, list
             Tuple or list containing the motor's dry mass inertia tensor
             components, in kg*m^2. This inertia is defined with respect to the
@@ -345,18 +346,19 @@ def exhaust_velocity(self):
     @funcify_method("Time (s)", "Mass (kg)")
     def propellant_mass(self):
         """Evaluates the total propellant mass of the motor as the sum
-        of each tank mass and the grains mass.
+        of fluids mass in each tank and the grains mass.
 
         Returns
         -------
         Function
-            Total propellant mass of the motor, in kg.
+            Total propellant mass of the motor as a function of time, in kg.
         """
         return self.solid.propellant_mass + self.liquid.propellant_mass
 
     @cached_property
     def propellant_initial_mass(self):
-        """Returns the initial propellant mass of the motor.
+        """Returns the initial propellant mass of the motor. See the docs of the
+        HybridMotor.propellant_mass property for more information.
 
         Returns
         -------
@@ -367,8 +369,8 @@ def propellant_initial_mass(self):
 
     @funcify_method("Time (s)", "mass flow rate (kg/s)", extrapolation="zero")
     def mass_flow_rate(self):
-        """Evaluates the mass flow rate of the motor as the sum of each tank
-        mass flow rate and the grains mass flow rate.
+        """Evaluates the mass flow rate of the motor as the sum of mass flow
+        rates from all tanks and the solid grains mass flow rate.
 
         Returns
         -------
@@ -486,14 +488,59 @@ def propellant_I_33(self):
 
     @funcify_method("Time (s)", "Inertia I_12 (kg m²)")
     def propellant_I_12(self):
+        """Inertia tensor 12 component of the propellant, the inertia is
+        relative to the e_1 and e_2 axes, centered at the instantaneous
+        propellant center of mass.
+
+        Returns
+        -------
+        Function
+            Propellant inertia tensor 12 component at time t.
+
+        Notes
+        -----
+            This is assumed to be zero due to axial symmetry of the motor. This
+            could be improved in the future to account for the fact that the
+            motor is not perfectly symmetric.
+        """
         return 0
 
     @funcify_method("Time (s)", "Inertia I_13 (kg m²)")
     def propellant_I_13(self):
+        """Inertia tensor 13 component of the propellant, the inertia is
+        relative to the e_1 and e_3 axes, centered at the instantaneous
+        propellant center of mass.
+
+        Returns
+        -------
+        Function
+            Propellant inertia tensor 13 component at time t.
+
+        Notes
+        -----
+            This is assumed to be zero due to axial symmetry of the motor. This
+            could be improved in the future to account for the fact that the
+            motor is not perfectly symmetric.
+        """
         return 0
 
     @funcify_method("Time (s)", "Inertia I_23 (kg m²)")
     def propellant_I_23(self):
+        """Inertia tensor 23 component of the propellant, the inertia is
+        relative to the e_2 and e_3 axes, centered at the instantaneous
+        propellant center of mass.
+
+        Returns
+        -------
+        Function
+            Propellant inertia tensor 23 component at time t.
+
+        Notes
+        -----
+            This is assumed to be zero due to axial symmetry of the motor. This
+            could be improved in the future to account for the fact that the
+            motor is not perfectly symmetric.
+        """
         return 0
 
     def add_tank(self, tank, position):

rocketpy/motors/liquid_motor.py

@@ -37,14 +37,12 @@ class LiquidMotor(Motor):
         List containing the motor's added tanks and their respective
         positions.
     LiquidMotor.dry_mass : float
-        The total mass of the motor structure, including chambers
-        and tanks, when it is empty and does not contain any propellant.
+        Same as in Motor class. See the :class:`Motor <rocketpy.Motor>` docs.
     LiquidMotor.propellant_initial_mass : float
-        Total propellant initial mass in kg, includes
-        fuel and oxidizer.
+        Total propellant initial mass in kg, includes fuel and oxidizer.
     LiquidMotor.total_mass : Function
         Total motor mass in kg as a function of time, defined as the sum
-        of propellant and dry mass.
+        of propellant mass and the motor's dry mass (i.e. structure mass).
     LiquidMotor.propellant_mass : Function
         Total propellant mass in kg as a function of time, includes fuel
         and oxidizer.
@@ -175,8 +173,7 @@ def __init__(
 
             .. seealso:: :doc:`Thrust Source Details </user/motors/thrust>`
         dry_mass : int, float
-            The total mass of the motor structure, including chambers
-            and tanks, when it is empty and does not contain any propellant.
+            Same as in Motor class. See the :class:`Motor <rocketpy.Motor>` docs.
         dry_inertia : tuple, list
             Tuple or list containing the motor's dry mass inertia tensor
             components, in kg*m^2. This inertia is defined with respect to the
@@ -260,12 +257,20 @@ def exhaust_velocity(self):
         -------
         self.exhaust_velocity : Function
             Gas exhaust velocity of the motor.
+
+        Notes
+        -----
+        The exhaust velocity is computed as the ratio of the thrust and the
+        mass flow rate. Therefore, this will vary with time if the mass flow
+        rate varies with time.
         """
         return self.thrust / (-1 * self.mass_flow_rate)
 
     @funcify_method("Time (s)", "Propellant Mass (kg)")
     def propellant_mass(self):
-        """Evaluates the mass of the motor as the sum of each tank mass.
+        """Evaluates the total propellant mass of the motor as the sum of fluids
+        mass in each tank, which may include fuel and oxidizer and usually vary
+        with time.
 
         Returns
         -------
@@ -281,7 +286,8 @@ def propellant_mass(self):
 
     @cached_property
     def propellant_initial_mass(self):
-        """Property to store the initial mass of the propellant.
+        """Property to store the initial mass of the propellant, this includes
+        fuel and oxidizer.
 
         Returns
         -------
@@ -292,8 +298,9 @@ def propellant_initial_mass(self):
 
     @funcify_method("Time (s)", "Mass flow rate (kg/s)", extrapolation="zero")
     def mass_flow_rate(self):
-        """Evaluates the mass flow rate of the motor as the sum of each tank
-        mass flow rate.
+        """Evaluates the mass flow rate of the motor as the sum of mass flow
+        rate from each tank, which may include fuel and oxidizer and usually
+        vary with time.
 
         Returns
         -------
@@ -317,12 +324,12 @@ def mass_flow_rate(self):
     def center_of_propellant_mass(self):
         """Evaluates the center of mass of the motor from each tank center of
         mass and positioning. The center of mass height is measured relative to
-        the motor nozzle.
+        the origin of the motor's coordinate system.
 
         Returns
         -------
         Function
-            Center of mass of the motor, in meters.
+            Position of the propellant center of mass, in meters.
         """
         total_mass = 0
         mass_balance = 0

rocketpy/motors/motor.py

@@ -36,15 +36,23 @@ class Motor(ABC):
         :doc:`Positions and Coordinate Systems </user/positions>` for more
         information.
     Motor.dry_mass : float
-        The total mass of the motor structure, including chambers
-        and tanks, when it is empty and does not contain any propellant.
+        The mass of the motor when devoid of any propellants, measured in
+        kilograms (kg). It encompasses the structural weight of the motor,
+        including the combustion chamber, nozzles, tanks, and fasteners.
+        Excluded from this measure are the propellants and any other elements
+        that are dynamically accounted for in the `mass` parameter of the rocket
+        class. Ensure that mass contributions from components shared with the
+        rocket structure are not recounted here. This parameter does not vary
+        with time.
     Motor.propellant_initial_mass : float
-        Total propellant initial mass in kg.
+        Total propellant initial mass in kg, including solid, liquid and gas
+        phases.
     Motor.total_mass : Function
         Total motor mass in kg as a function of time, defined as the sum
-        of propellant and dry mass.
+        of propellant mass and the motor's dry mass (i.e. structure mass).
     Motor.propellant_mass : Function
-        Total propellant mass in kg as a function of time.
+        Total propellant mass in kg as a function of time, including solid,
+        liquid and gas phases.
     Motor.total_mass_flow_rate : Function
         Time derivative of propellant total mass in kg/s as a function
         of time as obtained by the thrust source.
@@ -174,8 +182,7 @@ def __init__(
             .. seealso:: :doc:`Thrust Source Details </user/motors/thrust>`
 
         dry_mass : int, float
-            The total mass of the motor structure, including chambers
-            and tanks, when it is empty and does not contain any propellant.
+            Same as in Motor class. See the :class:`Motor <rocketpy.Motor>` docs
         center_of_dry_mass_position : int, float
             The position, in meters, of the motor's center of mass with respect
             to the motor's coordinate system when it is devoid of propellant.
@@ -378,19 +385,19 @@ def exhaust_velocity(self):
         """
         pass
 
-    @funcify_method("Time (s)", "total mass (kg)")
+    @funcify_method("Time (s)", "Total mass (kg)")
     def total_mass(self):
         """Total mass of the motor as a function of time. It is defined as the
         propellant mass plus the dry mass.
 
         Returns
         -------
         Function
-            Total mass as a function of time.
+            Motor total mass as a function of time.
         """
         return self.propellant_mass + self.dry_mass
 
-    @funcify_method("Time (s)", "propellant mass (kg)")
+    @funcify_method("Time (s)", "Propellant mass (kg)")
     def propellant_mass(self):
         """Total propellant mass as a Function of time.
 
@@ -403,11 +410,10 @@ def propellant_mass(self):
             self.total_mass_flow_rate.integral_function() + self.propellant_initial_mass
         )
 
-    @funcify_method("Time (s)", "mass dot (kg/s)", extrapolation="zero")
+    @funcify_method("Time (s)", "Mass flow rate (kg/s)", extrapolation="zero")
     def total_mass_flow_rate(self):
-        """Time derivative of propellant mass. Assumes constant exhaust
-        velocity. The formula used is the opposite of thrust divided by
-        exhaust velocity.
+        """Time derivative of the propellant mass as a function of time. The
+        formula used is the opposite of thrust divided by exhaust velocity.
 
         Returns
         -------
@@ -427,10 +433,8 @@ def total_mass_flow_rate(self):
         Notes
         -----
         This function computes the total mass flow rate of the motor by
-        dividing the thrust data by a constant approximation of the exhaust
-        velocity.
-        This approximation of the total mass flow rate is used in the
-        following manner by the child Motor classes:
+        dividing the thrust data by the exhaust velocity. This is an
+        approximation, and it  is used by the child Motor classes as follows:
 
         - The ``SolidMotor`` class uses this approximation to compute the
           grain's mass flow rate;
@@ -449,7 +453,7 @@ def total_mass_flow_rate(self):
     @property
     @abstractmethod
     def propellant_initial_mass(self):
-        """Propellant initial mass in kg.
+        """Propellant initial mass in kg, including solid, liquid and gas phases
 
         Returns
         -------
@@ -478,8 +482,8 @@ def center_of_mass(self):
     @abstractmethod
     def center_of_propellant_mass(self):
         """Position of the propellant center of mass as a function of time.
-        The position is specified as a scalar, relative to the motor's
-        coordinate system.
+        The position is specified as a scalar, relative to the origin of the
+        motor's coordinate system.
 
         Returns
         -------
@@ -501,7 +505,7 @@ def I_11(self):
         Notes
         -----
         The e_1 direction is assumed to be the direction perpendicular to the
-        motor body axis.
+        motor body axis. Also, due to symmetry, I_11 = I_22.
 
         References
         ----------
@@ -540,7 +544,8 @@ def I_22(self):
         Notes
         -----
         The e_2 direction is assumed to be the direction perpendicular to the
-        motor body axis, and perpendicular to e_1.
+        motor body axis, and perpendicular to e_1. Also, due to symmetry,
+        I_22 = I_11.
 
         References
         ----------
@@ -667,6 +672,7 @@ def I_23(self):
         ----------
         https://en.wikipedia.org/wiki/Moment_of_inertia
         """
+        # wrt = with respect to
         # Propellant inertia tensor 23 component wrt propellant center of mass
         propellant_I_23 = self.propellant_I_23
 
@@ -1103,8 +1109,7 @@ def __init__(
             coordinate system.
             See :doc:`Positions and Coordinate Systems </user/positions>`
         dry_mass : int, float
-            The total mass of the motor structure, including chambers
-            and tanks, when it is empty and does not contain any propellant.
+            Same as in Motor class. See the :class:`Motor <rocketpy.Motor>` docs
         propellant_initial_mass : int, float
             The initial mass of the propellant in the motor.
         center_of_dry_mass_position : int, float, optional