MNT: address PR #911 review comments

Core changes:
- Remove unused altitude_trigger_factory
- Restore trigger docstring format with 3/4/5 arg support
- Remove backend note about u_dot computation
- Remove weathercock_coeff docstring (merge error)
- Remove 'legacy support' wording from apogee trigger
- Rename 'legacy' test to 'basic'

Documentation:
- Convert Sensor Noise to note with sensors link
- Add numeric altitude trigger example
- Remove Performance Considerations and Best Practices
- Add logic explanations to all custom trigger examples
- Remove duplicate liftoff example
- Standardize section naming and format with 'Logic:' and 'Usage:' blocks
- Update sensor example for Accelerometer with vector measurements
- Reframe example as 'Simulating Drogue Deployment'

Author: ViniciusCMB

docs/user/parachute_triggers.rst

@@ -42,17 +42,40 @@ Detects apogee when the rocket starts descending.
 **Detection criteria:**
 - Vertical velocity becomes negative (descent starts)
 
+Numeric Altitude Trigger
+------------------------
+
+You can also pass a numeric altitude (int or float) to deploy at a fixed height
+while descending.
+
+.. code-block:: python
+
+    main = Parachute(
+        name="Main",
+        cd_s=10.0,
+        trigger=400,  # meters above ground level
+        sampling_rate=100,
+        lag=0.5
+    )
+
 Custom Triggers
 ---------------
 
 You can create custom triggers that use acceleration data:
 
-Motor Burnout Trigger (Custom Example)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. code-block:: python
+
+    from rocketpy import Parachute
+
+Custom Trigger: Motor Burnout
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Motor burnout is highly mission-dependent, so it is recommended as a custom
 trigger with user-defined thresholds:
 
+Logic: check for a drop in vertical or total acceleration once the rocket is
+above a minimum height and still ascending.
+
 .. code-block:: python
 
     def burnout_trigger_factory(
@@ -76,6 +99,10 @@ trigger with user-defined thresholds:
 
         return burnout_trigger
 
+Usage:
+
+.. code-block:: python
+
     drogue = Parachute(
         name="Drogue",
         cd_s=1.0,
@@ -89,36 +116,65 @@ trigger with user-defined thresholds:
         lag=1.5,
     )
 
-Apogee by Acceleration (Custom Example)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Custom Trigger: Apogee by Acceleration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Logic: near-zero vertical velocity with downward acceleration.
 
 .. code-block:: python
 
     def apogee_acc_trigger(_pressure, _height, state_vector, u_dot):
+        if u_dot is None or len(u_dot) < 6:
+            return False
         vz = state_vector[5]
         az = u_dot[5]
+        # Apogee is indicated by near-zero vertical velocity and downward acceleration.
         return abs(vz) < 1.0 and az < -0.1
 
-Free-fall (Custom Example)
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+Usage:
+
+.. code-block:: python
+
+    main = Parachute(
+        name="Main",
+        cd_s=10.0,
+        trigger=apogee_acc_trigger,
+        sampling_rate=100,
+        lag=0.5
+    )
+
+Custom Trigger: Free-fall
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Logic: low total acceleration while descending above a small height.
 
 .. code-block:: python
 
     def freefall_trigger(_pressure, height, state_vector, u_dot):
+        if u_dot is None or len(u_dot) < 6:
+            return False
         ax, ay, az = u_dot[3], u_dot[4], u_dot[5]
         total_acc = (ax**2 + ay**2 + az**2) ** 0.5
         vz = state_vector[5]
+        # Free-fall is a low-acceleration phase while descending.
         return height > 5.0 and vz < -0.2 and total_acc < 11.5
 
-Liftoff by Acceleration (Custom Example)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Usage:
 
 .. code-block:: python
 
-    def liftoff_trigger(_pressure, _height, _state_vector, u_dot):
-        ax, ay, az = u_dot[3], u_dot[4], u_dot[5]
-        total_acc = (ax**2 + ay**2 + az**2) ** 0.5
-        return total_acc > 15.0
+    drogue = Parachute(
+        name="Drogue",
+        cd_s=1.0,
+        trigger=freefall_trigger,
+        sampling_rate=100,
+        lag=1.5
+    )
+
+Custom Trigger: Threshold-based
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Logic: deploy when total acceleration drops below a threshold while descending.
 
 .. code-block:: python
 
@@ -144,6 +200,9 @@ Liftoff by Acceleration (Custom Example)
             True to trigger parachute deployment
         """
         # Extract acceleration components (m/s²)
+        if u_dot is None or len(u_dot) < 6:
+            return False
+
         ax = u_dot[3]
         ay = u_dot[4]
         az = u_dot[5]
@@ -155,7 +214,10 @@ Liftoff by Acceleration (Custom Example)
         vz = state_vector[5]
         return total_acc < 5.0 and vz < -10.0
 
-    # Use custom trigger
+Usage:
+
+.. code-block:: python
+
     parachute = Parachute(
         name="Custom",
         cd_s=2.0,
@@ -164,10 +226,13 @@ Liftoff by Acceleration (Custom Example)
         lag=1.0
     )
 
-Sensor and Acceleration Triggers
----------------------------------
+Custom Trigger: Sensors and Acceleration
+----------------------------------------
+
+Triggers can also accept sensor data alongside acceleration.
 
-Triggers can also accept sensor data alongside acceleration:
+Logic: compare measured vertical acceleration from an Accelerometer with the
+computed ``u_dot`` value.
 
 .. code-block:: python
 
@@ -186,18 +251,29 @@ Triggers can also accept sensor data alongside acceleration:
         -------
         bool
         """
-        # Access sensor measurements
-        if len(sensors) > 0:
-            imu_reading = sensors[0].measurement
+        # Access accelerometer measurements (vector)
+        if len(sensors) == 0:
+            return False
+
+        acc_reading = sensors[0].measurement
+        if acc_reading is None or len(acc_reading) < 3:
+            return False
 
-        # Define threshold for IMU reading (example value)
-        threshold = 100.0  # Adjust based on sensor units and trigger criteria
+        if u_dot is None or len(u_dot) < 6:
+            return False
 
-        # Use acceleration data
+        # Example threshold for measured vertical acceleration (m/s^2)
+        meas_az = acc_reading[2]
+        threshold = -5.0
+
+        # Use acceleration data from both sensor and dynamics
         az = u_dot[5]
 
-        # Combine sensor and acceleration logic
-        return az < -5.0 and imu_reading > threshold
+        return (az < -5.0) and (meas_az < threshold)
+
+Usage:
+
+.. code-block:: python
 
     parachute = Parachute(
         name="Advanced",
@@ -206,46 +282,23 @@ Triggers can also accept sensor data alongside acceleration:
         sampling_rate=100
     )
 
-Sensor Noise
-------------
-
-For realistic IMU behavior, use RocketPy sensors with their own noise models.
-Parachute trigger functions can receive ``sensors`` and use those measurements
-directly instead of injecting noise in the flight solver.
-
-Performance Considerations
---------------------------
+.. note::
 
-Computing acceleration (``u_dot``) requires evaluating the equations of motion,
-which adds computational cost. RocketPy optimizes this by:
+    For realistic IMU behavior, use RocketPy sensors with their own noise models.
+    Parachute trigger functions can receive ``sensors`` and use those measurements
+    directly instead of injecting noise in the flight solver. See the
+    :doc:`Sensor Classes </reference/classes/sensors/index>` for available sensors.
 
-1. **Lazy evaluation**: ``u_dot`` is only computed if the trigger actually needs it
-2. **Metadata detection**: The wrapper inspects trigger signatures to determine requirements
-3. **Caching**: Derivative evaluations are reused when possible
-
-**Trigger signature detection:**
-
-- 3 parameters ``(p, h, y)``: Legacy trigger, no ``u_dot`` computed
-- 4 parameters with ``u_dot``: Only acceleration computed
-- 4 parameters with ``sensors``: Only sensors passed
-- 5 parameters: Both sensors and acceleration provided
-
-Best Practices
---------------
-
-1. **Choose appropriate sampling rates**: 50-200 Hz is typical for flight computers
-2. **Add realistic noise**: Real IMUs have noise; simulate it for validation
-3. **Test edge cases**: Verify triggers work at low altitudes, high speeds, etc.
-4. **Use robust custom logic**: Add mission-specific guards and thresholds
-5. **Document custom triggers**: Include detection criteria in docstrings
-
-Example: Complete Dual-Deploy System
+Example: Simulating Drogue Deployment
 -------------------------------------
 
+Logic: in RocketPy, only one parachute is active at a time, so you can simulate
+dual-deploy by treating the first trigger as a drogue event and the second as the
+main deployment.
+
 .. code-block:: python
 
     from rocketpy import Rocket, Parachute, Flight, Environment
-    import numpy as np
 
     # Environment and rocket setup
     env = Environment(latitude=32.99, longitude=-106.97, elevation=1400)
@@ -258,7 +311,7 @@ Example: Complete Dual-Deploy System
         if u_dot is None or len(u_dot) < 6:
             return False
         az = u_dot[5]
-        vz = state_vector[5] if len(state_vector) > 5 else 0
+        vz = state_vector[5]
         return height > 10 and vz > 1 and az < -8.0
 
     drogue = Parachute(
@@ -271,9 +324,11 @@ Example: Complete Dual-Deploy System
     )
     my_rocket.add_parachute(drogue)
 
-    # Main parachute: Deploy at 800m using custom trigger
-    def main_deploy_trigger(pressure, height, state_vector, u_dot):
-        """Deploy main at 800m while descending with positive vertical acceleration."""
+    # Main parachute: Deploy at 800m using a custom trigger
+    def main_deploy_trigger(_pressure, height, state_vector, u_dot):
+        """Deploy main at 800m while descending with modest acceleration."""
+        if u_dot is None or len(u_dot) < 6:
+            return False
         vz = state_vector[5]
         az = u_dot[5]
         return height < 800 and vz < -5 and az > -15

rocketpy/rocket/parachute.py

@@ -8,22 +8,6 @@
 from ..prints.parachute_prints import _ParachutePrints
 
 
-def altitude_trigger_factory(target_altitude, require_descent=True):
-    """Return a trigger that deploys when altitude <= target_altitude.
-
-    If require_descent is True, also require vertical velocity negative
-    (descending) to avoid firing during ascent.
-    """
-
-    def trigger(_pressure, height, state_vector, _u_dot=None):
-        vz = float(state_vector[5])
-        if require_descent:
-            return (height <= target_altitude) and (vz < 0)
-        return height <= target_altitude
-
-    return trigger
-
-
 class Parachute:
     """Keeps information of the parachute, which is modeled as a hemispheroid.
 
@@ -69,8 +53,8 @@ class Parachute:
           case, the parachute will be ejected when the rocket reaches this height
           above ground level while descending.
 
-        - A string for built-in triggers:
-          - ``"apogee"``: Apogee detection (velocity-based)
+        - The string "apogee" which triggers the parachute at apogee, i.e.,
+          when the rocket reaches its highest point and starts descending.
 
 
     Parachute.triggerfunc : function
@@ -84,8 +68,6 @@ class Parachute:
         .. note::
 
             The function will be called according to the sampling rate specified.
-            For performance, ``u_dot`` is only computed if the trigger signature
-            indicates it is needed.
 
     Parachute.sampling_rate : float
         Sampling rate, in Hz, for the trigger function.
@@ -371,7 +353,7 @@ def triggerfunc(p, h, y, sensors, u_dot):  # pylint: disable=unused-argument
             self.triggerfunc = triggerfunc
             return
 
-        # Special case: "apogee" (legacy support)
+        # Special case: "apogee"
         if isinstance(trigger, str) and trigger.lower() == "apogee":
 
             def triggerfunc(p, h, y, sensors, u_dot):  # pylint: disable=unused-argument

rocketpy/simulation/flight.py

@@ -590,16 +590,6 @@ def __init__(  # pylint: disable=too-many-arguments,too-many-statements
         simulation_mode : str, optional
             Simulation mode to use. Can be "6 DOF" for 6 degrees of freedom or
             "3 DOF" for 3 degrees of freedom. Default is "6 DOF".
-        weathercock_coeff : float, optional
-            Proportionality coefficient (rate coefficient) for the alignment rate of the rocket's body axis
-            with the relative wind direction in 3-DOF simulations, in rad/s. The actual angular velocity
-            applied to align the rocket is calculated as ``weathercock_coeff * sin(angle)``, where ``angle``
-            is the angle between the rocket's axis and the wind direction. A higher value means faster alignment
-            (quasi-static weathercocking). This parameter is only used when simulation_mode is '3 DOF'.
-            Default is 0.0 to mimic a pure 3-DOF simulation without any weathercocking (fixed attitude).
-            Set to a positive value to enable quasi-static weathercocking behaviour.
-
-
         Returns
         -------
         None

tests/unit/test_parachute_triggers.py

@@ -76,20 +76,20 @@ def user_trigger(_p, _h, _y, u_dot):
     assert np.allclose(recorded["u_dot"][3:6], np.array([-1.0, -2.0, -3.0]))
 
 
-def test_legacy_trigger_does_not_compute_u_dot():
+def test_basic_trigger_does_not_compute_u_dot():
     def derivative_func(_t, _y):
         raise RuntimeError("derivative should not be called for legacy triggers")
 
     called = {}
 
-    def legacy_trigger(_p, _h, _y):
+    def basic_trigger(_p, _h, _y):
         called["ok"] = True
         return True
 
     parachute = Parachute(
-        name="legacy",
+        name="basic",
         cd_s=1.0,
-        trigger=legacy_trigger,
+        trigger=basic_trigger,
         sampling_rate=100,
     )