MNT: minor improvements to variable names and controller function

docs/user/airbrakes.rst

@@ -174,9 +174,15 @@ Lets define the controller function:
         altitude_ASL = state[2]
         altitude_AGL = altitude_ASL - env.elevation
         vx, vy, vz = state[3], state[4], state[5]
-        mach_number = (vx**2 + vy**2 + vz**2) ** 0.5 / env.speed_of_sound(
-            altitude_AGL - env.elevation
-        )
+
+        # Get winds in x and y directions
+        wind_x, wind_y = env.wind_velocity_x(altitude_ASL), env.wind_velocity_y(altitude_ASL)
+
+        # Calculate Mach number
+        free_stream_speed = (
+            (wind_x - vx) ** 2 + (wind_y - vy) ** 2 + (vz) ** 2
+        ) ** 0.5
+        mach_number = free_stream_speed / env.speed_of_sound(altitude_ASL)
 
         # Get previous state from state_history
         previous_state = state_history[-1]
@@ -186,36 +192,37 @@ Lets define the controller function:
         # returned_time, deployment_level, drag_coefficient = observed_variables[-1]
 
         # Check if the rocket has reached burnout
-        if time > Pro75M1670.burn_out_time:
-            # If below 1500 meters above ground level, air_brakes are not deployment
-            if altitude_AGL < 1500:
-                air_brakes.set_deployment_level(0)
-
-            # Else calculate the deployment level
-            else:
-                # Controller logic
-                new_deployment_level = (
-                    air_brakes.deployment_level + 0.1 * vz + 0.01 * previous_vz**2
-                )
-
-                # Limiting the speed of the air_brakes to 0.2 per second
-                # Since this function is called every 1/sampling_rate seconds
-                # the max change in deployment level per call is 0.2/sampling_rate
-                max_change = 0.2 / sampling_rate
-                if new_deployment_level > air_brakes.deployment_level + max_change:
-                    new_deployment_level = air_brakes.deployment_level + max_change
-                elif new_deployment_level < air_brakes.deployment_level - max_change:
-                    new_deployment_level = air_brakes.deployment_level - max_change
-
-                air_brakes.set_deployment_level(new_deployment_level)
-
-            # Return variables of interest to be saved in the observed_variables list
-            return (
-                time,
-                air_brakes.deployment_level,
-                air_brakes.drag_coefficient(air_brakes.deployment_level, mach_number),
+        if time < Pro75M1670.burn_out_time:
+            return None
+
+        # If below 1500 meters above ground level, air_brakes are not deployed
+        if altitude_AGL < 1500:
+            air_brakes.set_deployment_level(0)
+
+        # Else calculate the deployment level
+        else:
+            # Controller logic
+            new_deployment_level = (
+                air_brakes.deployment_level + 0.1 * vz + 0.01 * previous_vz**2
             )
 
+            # Limiting the speed of the air_brakes to 0.2 per second
+            # Since this function is called every 1/sampling_rate seconds
+            # the max change in deployment level per call is 0.2/sampling_rate
+            max_change = 0.2 / sampling_rate
+            lower_bound = air_brakes.deployment_level - max_change
+            upper_bound = air_brakes.deployment_level + max_change
+            new_deployment_level = min(max(new_deployment_level, lower_bound), upper_bound)
+
+            air_brakes.set_deployment_level(new_deployment_level)
+
+        # Return variables of interest to be saved in the observed_variables list
+        return (
+            time,
+            air_brakes.deployment_level,
+            air_brakes.drag_coefficient(air_brakes.deployment_level, mach_number),
+        )
+
 .. note::
 
     - The code inside the ``controller_function`` can be as complex as needed.
@@ -294,7 +301,7 @@ Part of the data from the CSV can be seen in the code block below.
 .. note:: 
   The air brakes' drag coefficient curve can represent either the air brakes 
   alone or both the air brakes and the rocket. This is determined by the 
-  ``substitute_rocket_drag_coefficient`` argument. If set to True, the drag 
+  ``override_rocket_drag`` argument. If set to True, the drag 
   coefficient curve will include both the air brakes and the rocket. If set to 
   False, the curve will exclusively represent the air brakes.
 
@@ -332,7 +339,7 @@ controller function. If you want to disable this feature, set ``clamp`` to
         reference_area=None,
         clamp=True,
         initial_observed_variables=[0, 0, 0],
-        substitute_rocket_drag_coefficient=False,
+        override_rocket_drag=False,
         name="Air Brakes",
     )
 

rocketpy/rocket/aero_surface.py

@@ -1920,7 +1920,7 @@ def __init__(
         drag_coefficient_curve,
         reference_area,
         clamp=True,
-        substitute_rocket_drag_coefficient=False,
+        override_rocket_drag=False,
         deployment_level=0,
         name="AirBrakes",
     ):
@@ -1931,7 +1931,7 @@ def __init__(
         drag_coefficient_curve : int, float, callable, array, string, Function
             This parameter represents the drag coefficient associated with the
             air brakes and/or the entire rocket, depending on the value of
-            ``substitute_rocket_drag_coefficient``.
+            ``override_rocket_drag``.
 
             - If a constant, it should be an integer or a float representing a
               fixed drag coefficient value.
@@ -1948,7 +1948,7 @@ def __init__(
             - If a Function, it must take two parameters: deployment level and
               Mach number, and return the drag coefficient.
 
-            .. note:: For ``substitute_rocket_drag_coefficient = False``, at
+            .. note:: For ``override_rocket_drag = False``, at
                 deployment level 0, the drag coefficient is assumed to be 0,
                 independent of the input drag coefficient curve. This means that
                 the simulation always considers that at a deployment level of 0,
@@ -1963,7 +1963,7 @@ def __init__(
             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. Default is True.
-        substitute_rocket_drag_coefficient : bool, optional
+        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
@@ -1988,7 +1988,7 @@ def __init__(
         )
         self.reference_area = reference_area
         self.clamp = clamp
-        self.substitute_rocket_drag_coefficient = substitute_rocket_drag_coefficient
+        self.override_rocket_drag = override_rocket_drag
         self._deployment_level = deployment_level
         self.prints = _AirBrakesPrints(self)
         self.plots = _AirBrakesPlots(self)

rocketpy/rocket/rocket.py

@@ -1167,7 +1167,7 @@ def add_air_brakes(
         clamp=True,
         reference_area=None,
         initial_observed_variables=None,
-        substitute_rocket_drag_coefficient=False,
+        override_rocket_drag=False,
         return_controller=False,
         name="AirBrakes",
         controller_name="AirBrakes Controller",
@@ -1180,7 +1180,7 @@ def add_air_brakes(
         drag_coefficient_curve : int, float, callable, array, string, Function
             This parameter represents the drag coefficient associated with the
             air brakes and/or the entire rocket, depending on the value of
-            ``substitute_rocket_drag_coefficient``.
+            ``override_rocket_drag``.
 
             - If a constant, it should be an integer or a float representing a
               fixed drag coefficient value.
@@ -1197,7 +1197,7 @@ def add_air_brakes(
             - If a Function, it must take two parameters: deployment level and
               Mach number, and return the drag coefficient.
 
-            .. note:: For ``substitute_rocket_drag_coefficient = False``, at
+            .. note:: For ``override_rocket_drag = False``, at
                 deployment level 0, the drag coefficient is assumed to be 0,
                 independent of the input drag coefficient curve. This means that
                 the simulation always considers that at a deployment level of 0,
@@ -1251,7 +1251,7 @@ def add_air_brakes(
             function returns. This list is used to initialize the
             `observed_variables` argument of the controller function. The
             default value is None, which initializes the list as an empty list.
-        substitute_rocket_drag_coefficient : bool, optional
+        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
@@ -1280,7 +1280,7 @@ def add_air_brakes(
             drag_coefficient_curve=drag_coefficient_curve,
             reference_area=reference_area,
             clamp=clamp,
-            substitute_rocket_drag_coefficient=substitute_rocket_drag_coefficient,
+            override_rocket_drag=override_rocket_drag,
             deployment_level=0,
             name=name,
         )

rocketpy/simulation/flight.py

@@ -1442,7 +1442,7 @@ def u_dot(self, t, u, post_processing=False):
                     * air_brakes.reference_area
                     * air_brakes_cd
                 )
-                if air_brakes.substitute_rocket_drag_coefficient:
+                if air_brakes.override_rocket_drag:
                     R3 = air_brakes_force  # Substitutes rocket drag coefficient
                 else:
                     R3 += air_brakes_force
@@ -1741,7 +1741,7 @@ def u_dot_generalized(self, t, u, post_processing=False):
                     * air_brakes.reference_area
                     * air_brakes_cd
                 )
-                if air_brakes.substitute_rocket_drag_coefficient:
+                if air_brakes.override_rocket_drag:
                     R3 = air_brakes_force  # Substitutes rocket drag coefficient
                 else:
                     R3 += air_brakes_force