ENH: Introduce the StochasticAirBrakes class (#785)

kevin-alcaniz · Gui-FernandesBR · MateusStano · web-flow · commit 4a41f7ac12ee · 2025-03-23T17:52:51.000-03:00
* wind factor bug corrected

the wind factor wasn't applied to the env.wind_velocity properties

* BUG: StochasticModel visualize attributes of a uniform distribution

It showed the nominal and the standard deviation values and it doesn't make sense in a uniform distribution. In a np.random.uniform the 'nominal value' is the lower bound of the distribution, and the 'standard deviation' value is the upper bound. Now, a new condition has been added for the uniform distributions where the mean and semi range are calculated and showed. This way the visualize_attribute function will show the whole range where the random values are uniformly taken in

* variable names corrections

* Corrections requested by the pylint test

* ENH: add multiplication for 2D functions in rocketpy.function

Added the ability to multiply functions with 2D domains in the __mul__ function

* ENH: StochasticAirBrakes class created

The StochasticAirBrakes class has been created. The __init__.py files in the stochastic and rocketpy folders have also been modified accordingly to incorporate this new class

* ENH: set_air_brakes function created

This functions appends an airbrake and controller objects previuosly created to the rocket

* ENH: add StochasticAirBrake to rocketpy.stochastic_rocket

Some functions has been modified and other has been created in order to include the new StochasticAirBrakes feature into the StochasticRocket class. A new function named 'add_air_brakes' has been created to append a StochasticAirBrakes and Controller objects to the StochasticRocket object. A new function '_create_air_brake' has been introduced to create a sample of an AirBrake object through a StochasticAirBrake object. Enventually, the 'create_object' function has been modified to add the sampled AirBrakes to the sampled Rocket

* BUG: StochasticAirBrake object input in _Controller

When defining the _Controller object a StochasticAirBrake was input. This is already corrected and a AirBrake object is now introduced

* ENH: add time_overshoot option to rocketpy.stochastic_flight

Since the new StochasticAirBrake class is defined, we need the 'time_overshoot' option in the Flight class to ensure that the time step defined in the simulation is the controller sampling rate. The MonteCarlo class has had to be modified as well to include this option.

* DOC: StochasticAirBrakes related documentation added

Documentation related to the StochasticAirBrakes implementation has been added in StochasticAirBrakes, StochasticRocket and Rocket classes.

* ENH: pylint recommendations done

* ENH: Reformatted files to pass Ruff linting checks

* ENH: Update rocketpy/stochastic/stochastic_rocket.py

Unnecessary comment

Co-authored-by: Gui-FernandesBR &lt;63590233+Gui-FernandesBR@users.noreply.github.com&gt;

* DOC: improve drag curve factor definition in StochasticAirBrakes

* ENH: Change assert statement to if

Co-authored-by: Gui-FernandesBR &lt;63590233+Gui-FernandesBR@users.noreply.github.com&gt;

* DOC: better explanation of __mul__ function

Co-authored-by: MateusStano &lt;69485049+MateusStano@users.noreply.github.com&gt;

* ENH: delete set_air_brakes function for simplicity

* DOC: CHANGELOG file updated

---------

Co-authored-by: Gui-FernandesBR &lt;63590233+Gui-FernandesBR@users.noreply.github.com&gt;
Co-authored-by: MateusStano &lt;69485049+MateusStano@users.noreply.github.com&gt;
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -34,6 +34,8 @@ Attention: The newest changes should be on top -->
 
 - ENH: Parallel mode for monte-carlo simulations 2 [#768](https://github.com/RocketPy-Team/RocketPy/pull/768)
 - DOC: ASTRA Flight Example [#770](https://github.com/RocketPy-Team/RocketPy/pull/770)
+- ENH: Add Eccentricity to Stochastic Simulations [#792](https://github.com/RocketPy-Team/RocketPy/pull/792)
+- ENH: Introduce the StochasticAirBrakes class [#785](https://github.com/RocketPy-Team/RocketPy/pull/785)
 
 ### Changed
 
@@ -46,6 +48,7 @@ Attention: The newest changes should be on top -->
 - BUG: update flight simulation logic to include burn start time [#778](https://github.com/RocketPy-Team/RocketPy/pull/778)
 - BUG: fixes get_instance_attributes for Flight objects containing a Rocket object without rail buttons [#786](https://github.com/RocketPy-Team/RocketPy/pull/786)
 - BUG: fixed AGL altitude print for parachutes with lag [#788](https://github.com/RocketPy-Team/RocketPy/pull/788)
+- BUG: fix the wind velocity factors usage and better visualization of uniform distributions in Stochastic Classes [#783](https://github.com/RocketPy-Team/RocketPy/pull/783)
 
 
 ## [v1.8.0] - 2025-01-20
diff --git a/rocketpy/__init__.py b/rocketpy/__init__.py
@@ -44,6 +44,7 @@
 from .sensors import Accelerometer, Barometer, GnssReceiver, Gyroscope
 from .simulation import Flight, MonteCarlo
 from .stochastic import (
+    StochasticAirBrakes,
     StochasticEllipticalFins,
     StochasticEnvironment,
     StochasticFlight,
diff --git a/rocketpy/mathutils/function.py b/rocketpy/mathutils/function.py
@@ -2219,10 +2219,10 @@ def __rsub__(self, other):
         """
         return other + (-self)
 
-    def __mul__(self, other):
+    def __mul__(self, other):  # pylint: disable=too-many-statements
         """Multiplies a Function object and returns a new Function object
         which gives the result of the multiplication. Only implemented for 1D
-        domains.
+        and 2D domains.
 
         Parameters
         ----------
@@ -2238,7 +2238,7 @@ def __mul__(self, other):
         Returns
         -------
         result : Function
-            A Function object which gives the result of self(x)*other(x).
+            A Function object which gives the result of self(x)*other(x) or self(x,y)*other(x,y).
         """
         self_source_is_array = isinstance(self.source, np.ndarray)
         other_source_is_array = (
@@ -2250,37 +2250,76 @@ def __mul__(self, other):
         interp = self.__interpolation__
         extrap = self.__extrapolation__
 
-        if (
-            self_source_is_array
-            and other_source_is_array
-            and np.array_equal(self.x_array, other.x_array)
-        ):
-            source = np.column_stack((self.x_array, self.y_array * other.y_array))
-            outputs = f"({self.__outputs__[0]}*{other.__outputs__[0]})"
-            return Function(source, inputs, outputs, interp, extrap)
-        elif isinstance(other, NUMERICAL_TYPES) or self.__is_single_element_array(
-            other
-        ):
-            if not self_source_is_array:
-                return Function(lambda x: (self.get_value_opt(x) * other), inputs)
-            source = np.column_stack((self.x_array, np.multiply(self.y_array, other)))
-            outputs = f"({self.__outputs__[0]}*{other})"
-            return Function(
-                source,
-                inputs,
-                outputs,
-                interp,
-                extrap,
-            )
-        elif callable(other):
-            return Function(lambda x: (self.get_value_opt(x) * other(x)), inputs)
-        else:
-            raise TypeError("Unsupported type for multiplication")
+        if self.__dom_dim__ == 1:
+            if (
+                self_source_is_array
+                and other_source_is_array
+                and np.array_equal(self.x_array, other.x_array)
+            ):
+                source = np.column_stack((self.x_array, self.y_array * other.y_array))
+                outputs = f"({self.__outputs__[0]}*{other.__outputs__[0]})"
+                return Function(source, inputs, outputs, interp, extrap)
+            elif isinstance(other, NUMERICAL_TYPES) or self.__is_single_element_array(
+                other
+            ):
+                if not self_source_is_array:
+                    return Function(lambda x: (self.get_value_opt(x) * other), inputs)
+                source = np.column_stack(
+                    (self.x_array, np.multiply(self.y_array, other))
+                )
+                outputs = f"({self.__outputs__[0]}*{other})"
+                return Function(
+                    source,
+                    inputs,
+                    outputs,
+                    interp,
+                    extrap,
+                )
+            elif callable(other):
+                return Function(lambda x: (self.get_value_opt(x) * other(x)), inputs)
+            else:
+                raise TypeError("Unsupported type for multiplication")
+        elif self.__dom_dim__ == 2:
+            if (
+                self_source_is_array
+                and other_source_is_array
+                and np.array_equal(self.x_array, other.x_array)
+                and np.array_equal(self.y_array, other.y_array)
+            ):
+                source = np.column_stack(
+                    (self.x_array, self.y_array, self.z_array * other.z_array)
+                )
+                outputs = f"({self.__outputs__[0]}*{other.__outputs__[0]})"
+                return Function(source, inputs, outputs, interp, extrap)
+            elif isinstance(other, NUMERICAL_TYPES) or self.__is_single_element_array(
+                other
+            ):
+                if not self_source_is_array:
+                    return Function(
+                        lambda x, y: (self.get_value_opt(x, y) * other), inputs
+                    )
+                source = np.column_stack(
+                    (self.x_array, self.y_array, np.multiply(self.z_array, other))
+                )
+                outputs = f"({self.__outputs__[0]}*{other})"
+                return Function(
+                    source,
+                    inputs,
+                    outputs,
+                    interp,
+                    extrap,
+                )
+            elif callable(other):
+                return Function(
+                    lambda x, y: (self.get_value_opt(x, y) * other(x)), inputs
+                )
+            else:
+                raise TypeError("Unsupported type for multiplication")
 
     def __rmul__(self, other):
         """Multiplies 'other' by a Function object and returns a new Function
         object which gives the result of the multiplication. Only implemented for
-        1D domains.
+        1D and 2D domains.
 
         Parameters
         ----------
@@ -2290,7 +2329,7 @@ def __rmul__(self, other):
         Returns
         -------
         result : Function
-            A Function object which gives the result of other(x)*self(x).
+            A Function object which gives the result of other(x,y)*self(x,y).
         """
         return self * other
 
diff --git a/rocketpy/simulation/monte_carlo.py b/rocketpy/simulation/monte_carlo.py
@@ -458,6 +458,7 @@ def __run_single_simulation(self):
             heading=self.flight._randomize_heading(),
             initial_solution=self.flight.initial_solution,
             terminate_on_apogee=self.flight.terminate_on_apogee,
+            time_overshoot=self.flight.time_overshoot,
         )
 
     def __evaluate_flight_inputs(self, sim_idx):
diff --git a/rocketpy/stochastic/__init__.py b/rocketpy/stochastic/__init__.py
@@ -6,6 +6,7 @@
 """
 
 from .stochastic_aero_surfaces import (
+    StochasticAirBrakes,
     StochasticEllipticalFins,
     StochasticNoseCone,
     StochasticRailButtons,
diff --git a/rocketpy/stochastic/stochastic_aero_surfaces.py b/rocketpy/stochastic/stochastic_aero_surfaces.py
@@ -9,6 +9,7 @@
     RailButtons,
     Tail,
     TrapezoidalFins,
+    AirBrakes,
 )
 
 from .stochastic_model import StochasticModel
@@ -432,3 +433,114 @@ def create_object(self):
         """
         generated_dict = next(self.dict_generator())
         return RailButtons(**generated_dict)
+
+
+class StochasticAirBrakes(StochasticModel):
+    """A Stochastic Air Brakes class that inherits from StochasticModel.
+
+    See Also
+    --------
+    :ref:`stochastic_model` and
+    :class:`AirBrakes <rocketpy.AirBrakes>`
+
+    Attributes
+    ----------
+    object : AirBrakes
+        AirBrakes object to be used for validation.
+    drag_coefficient_curve : list, str
+        The drag coefficient curve of the air brakes can account for
+        either the air brakes' drag alone or the combined drag of both
+        the rocket and the air brakes.
+    drag_coefficient_curve_factor : tuple, list, int, float
+        The drag curve factor of the air brakes. This value scales the
+        drag coefficient curve to introduce stochastic variability.
+    reference_area : tuple, list, int, float
+        Reference area used to non-dimensionalize the drag coefficients.
+    clamp : bool
+        If True, the simulation will clamp the deployment level to 0 or 1 if
+        the deployment level is out of bounds. If False, the simulation will
+        not clamp the deployment level and will instead raise a warning if
+        the deployment level is out of bounds.
+    override_rocket_drag : bool
+        If False, the air brakes drag coefficient will be added to the
+        rocket's power off drag coefficient curve. If True, during the
+        simulation, the rocket's power off drag will be ignored and the air
+        brakes drag coefficient will be used for the entire rocket instead.
+    deployment_level : tuple, list, int, float
+        Initial deployment level, ranging from 0 to 1.
+    name : list[str]
+        List with the air brakes object name. This attribute can't be randomized.
+    """
+
+    def __init__(
+        self,
+        air_brakes,
+        drag_coefficient_curve=None,
+        drag_coefficient_curve_factor=(1, 0),
+        reference_area=None,
+        clamp=None,
+        override_rocket_drag=None,
+        deployment_level=(0, 0),
+    ):
+        """Initializes the Stochastic AirBrakes class.
+
+        See Also
+        --------
+        :ref:`stochastic_model`
+
+        Parameters
+        ----------
+        air_brakes : AirBrakes
+            AirBrakes object to be used for validation.
+        drag_coefficient_curve : list, str, optional
+            The drag coefficient curve of the air brakes can account for
+            either the air brakes' drag alone or the combined drag of both
+            the rocket and the air brakes.
+        drag_coefficient_curve_factor : tuple, list, int, float, optional
+            The drag curve factor of the air brakes. This value scales the
+            drag coefficient curve to introduce stochastic variability.
+        reference_area : tuple, list, int, float, optional
+            Reference area used to non-dimensionalize the drag coefficients.
+        clamp : bool, optional
+            If True, the simulation will clamp the deployment level to 0 or 1 if
+            the deployment level is out of bounds. If False, the simulation will
+            not clamp the deployment level and will instead raise a warning if
+            the deployment level is out of bounds.
+        override_rocket_drag : bool, optional
+            If False, the air brakes drag coefficient will be added to the
+            rocket's power off drag coefficient curve. If True, during the
+            simulation, the rocket's power off drag will be ignored and the air
+            brakes drag coefficient will be used for the entire rocket instead.
+        deployment_level : tuple, list, int, float, optional
+            Initial deployment level, ranging from 0 to 1.
+        """
+        super().__init__(
+            air_brakes,
+            drag_coefficient_curve=drag_coefficient_curve,
+            drag_coefficient_curve_factor=drag_coefficient_curve_factor,
+            reference_area=reference_area,
+            clamp=clamp,
+            override_rocket_drag=override_rocket_drag,
+            deployment_level=deployment_level,
+            name=None,
+        )
+
+    def create_object(self):
+        """Creates and returns an AirBrakes object from the randomly generated
+        input arguments.
+
+        Returns
+        -------
+        air_brake : AirBrakes
+            AirBrakes object with the randomly generated input arguments.
+        """
+        generated_dict = next(self.dict_generator())
+        air_brakes = AirBrakes(
+            drag_coefficient_curve=generated_dict["drag_coefficient_curve"],
+            reference_area=generated_dict["reference_area"],
+            clamp=generated_dict["clamp"],
+            override_rocket_drag=generated_dict["override_rocket_drag"],
+            deployment_level=generated_dict["deployment_level"],
+        )
+        air_brakes.drag_coefficient *= generated_dict["drag_coefficient_curve_factor"]
+        return air_brakes
diff --git a/rocketpy/stochastic/stochastic_flight.py b/rocketpy/stochastic/stochastic_flight.py
@@ -29,6 +29,9 @@ class StochasticFlight(StochasticModel):
     terminate_on_apogee : bool
         Whether or not the flight should terminate on apogee. This attribute
         can not be randomized.
+    time_overshoot : bool
+        If False, the simulation will run at the time step defined by the controller
+        sampling rate. Be aware that this will make the simulation run much slower.
     """
 
     def __init__(
@@ -39,6 +42,7 @@ def __init__(
         heading=None,
         initial_solution=None,
         terminate_on_apogee=None,
+        time_overshoot=None,
     ):
         """Initializes the Stochastic Flight class.
 
@@ -63,11 +67,17 @@ def __init__(
         terminate_on_apogee : bool, optional
             Whether or not the flight should terminate on apogee. This attribute
             can not be randomized.
+        time_overshoot : bool
+            If False, the simulation will run at the time step defined by the controller
+            sampling rate. Be aware that this will make the simulation run much slower.
         """
         if terminate_on_apogee is not None:
             assert isinstance(terminate_on_apogee, bool), (
                 "`terminate_on_apogee` must be a boolean"
             )
+        if time_overshoot is not None:
+            if not isinstance(time_overshoot, bool):
+                raise TypeError("`time_overshoot` must be a boolean")
         super().__init__(
             flight,
             rail_length=rail_length,
@@ -77,6 +87,7 @@ def __init__(
 
         self.initial_solution = initial_solution
         self.terminate_on_apogee = terminate_on_apogee
+        self.time_overshoot = time_overshoot
 
     def _validate_initial_solution(self, initial_solution):
         if initial_solution is not None:
@@ -128,4 +139,5 @@ def create_object(self):
             heading=generated_dict["heading"],
             initial_solution=self.initial_solution,
             terminate_on_apogee=self.terminate_on_apogee,
+            time_overshoot=self.time_overshoot,
         )
diff --git a/rocketpy/stochastic/stochastic_rocket.py b/rocketpy/stochastic/stochastic_rocket.py

Original file line number	Diff line number	Diff line change
`@@ -458,6 +458,7 @@ def __run_single_simulation(self):`
`458`	`458`	`heading=self.flight._randomize_heading(),`
`459`	`459`	`initial_solution=self.flight.initial_solution,`
`460`	`460`	`terminate_on_apogee=self.flight.terminate_on_apogee,`
	`461`	`+ time_overshoot=self.flight.time_overshoot,`
`461`	`462`	`)`
`462`	`463`
`463`	`464`	`def __evaluate_flight_inputs(self, sim_idx):`