MNT: updating location of 3 dof doc in users index.rst

- MNT: 3 dof documentation only referred in users section/getting started - MNT: correction of docstring in flight.py - MNT: corrected unit_vector call when defining rotation axis in u_dot_generalized_3dof - MNT: docstring correction in test_flight_3dof.py - ENH: test coverage added for anti alignment case in weathercock model to test_flight_3dof.py
RocketPy-Team · Gui-FernandesBR · Dec 3, 2025 · Nov 27, 2025 · Nov 27, 2025 · Nov 27, 2025
commit fc4228c57de17995c08b0ea15e579635091436da
@@ -7,7 +7,7 @@ RocketPy's User Guide
 
    Installation and Requirements <installation.rst>
    First Simulation <first_simulation.rst>
-   3-DOF Simulations <three_dof_simulation.rst>
+   3 DOF Simulations and comparison <three_dof_simulation.rst>
 
 .. toctree::
    :maxdepth: 1
@@ -28,7 +28,7 @@ RocketPy's User Guide
    Air Brakes Example <airbrakes.rst>
    ../notebooks/sensors.ipynb
    ../matlab/matlab.rst
-   3 DOF Simulations and comparison<three_dof_simulation.rst>
+
 .. toctree::
    :maxdepth: 2
    :caption: Monte Carlo Simulations

@@ -1810,7 +1810,7 @@ def u_dot_generalized_3dof(self, t, u, post_processing=False):
         t : float
             Time in seconds.
         u : list
-            State vector: [x, y, z, vx, vy, vz, q0, q1, q2, q3, omega1, omega2, omega3].
+            State vector: [x, y, z, vx, vy, vz, e0, e1, e2, e3, omega1, omega2, omega3].
         post_processing : bool, optional
             If True, adds flight data to self variables like self.angle_of_attack.
 
@@ -1940,7 +1940,6 @@ def u_dot_generalized_3dof(self, t, u, post_processing=False):
                 sin_angle = min(1.0, max(-1.0, sin_angle))
 
                 # Angular velocity magnitude proportional to misalignment angle
-                # Angular velocity magnitude proportional to sin(angle)
                 omega_mag = self.weathercock_coeff * sin_angle
 
                 # Angular velocity in inertial frame
@@ -1976,7 +1975,7 @@ def u_dot_generalized_3dof(self, t, u, post_processing=False):
                         # If parallel, use y axis
                         y_axis = Vector([0.0, 1.0, 0.0])
                         perp_axis = body_z_inertial ^ y_axis
-                    rotation_axis = perp_axis.normalized()
+                    rotation_axis = perp_axis.unit_vector
                     # 180 degree rotation: sin(angle) = 1
                     omega_mag = self.weathercock_coeff * 1.0
                     omega_inertial = rotation_axis * omega_mag

@@ -141,6 +141,7 @@ def test_invalid_simulation_mode(example_plain_env, calisto):
 
 def test_weathercock_coeff_stored(example_plain_env, point_mass_rocket):
     """Tests that the weathercock_coeff parameter is correctly stored.
+
     Parameters
     ----------
     example_plain_env : rocketpy.Environment
@@ -160,6 +161,7 @@ def test_weathercock_coeff_stored(example_plain_env, point_mass_rocket):
 
 def test_weathercock_coeff_default(example_plain_env, point_mass_rocket):
     """Tests that the default weathercock_coeff is 1.0.
+
     Parameters
     ----------
     example_plain_env : rocketpy.Environment
@@ -180,6 +182,7 @@ def test_weathercock_zero_gives_fixed_attitude(example_plain_env, point_mass_roc
     """Tests that weathercock_coeff=0 results in fixed attitude (no quaternion change).
     When weathercock_coeff is 0, the quaternion derivatives should be zero,
     meaning the attitude does not evolve.
+
     Parameters
     ----------
     example_plain_env : rocketpy.Environment
@@ -208,6 +211,7 @@ def test_weathercock_nonzero_evolves_attitude(example_plain_env, point_mass_rock
     """Tests that non-zero weathercock_coeff causes attitude evolution.
     When the body axis is misaligned with the relative wind and weathercock_coeff
     is positive, the quaternion derivatives should be non-zero.
+
     Parameters
     ----------
     example_plain_env : rocketpy.Environment
@@ -238,6 +242,7 @@ def test_weathercock_aligned_no_evolution(example_plain_env, point_mass_rocket):
     """Tests that when body axis is aligned with relative wind, no rotation occurs.
     When the rocket's body z-axis is already aligned with the negative of the
     freestream velocity, the quaternion derivatives should be approximately zero.
+
     Parameters
     ----------
     example_plain_env : rocketpy.Environment
@@ -266,3 +271,42 @@ def test_weathercock_aligned_no_evolution(example_plain_env, point_mass_rocket):
     assert e_dot_magnitude < 1e-8, (
         "Quaternion derivatives should be very small when aligned"
     )
+
+
+def test_weathercock_anti_aligned_uses_perp_axis_and_evolves(
+    example_plain_env, point_mass_rocket
+):
+    """Tests the anti-aligned case where body z-axis is opposite freestream.
+
+    This should exercise the branch that selects a perpendicular axis (y-axis)
+    when the cross with x-axis is nearly zero, producing a non-zero quaternion
+    derivative.
+    """
+    flight = Flight(
+        rocket=point_mass_rocket,
+        environment=example_plain_env,
+        rail_length=1,
+        simulation_mode="3 DOF",
+        weathercock_coeff=1.0,
+    )
+
+    sqrt2_2 = np.sqrt(2) / 2
+    # Build quaternion that makes body z-axis = [-1, 0, 0]
+    # This corresponds to a -90 deg rotation about the y-axis: e0=cos(45°), e2=-sin(45°)
+    e0 = sqrt2_2
+    e1 = 0
+    e2 = -sqrt2_2
+    e3 = 0
+
+    # State: [x, y, z, vx, vy, vz, e0, e1, e2, e3, w1, w2, w3]
+    # Set velocity so desired_direction becomes [1,0,0]
+    u = [0, 0, 100, 50, 0, 0, e0, e1, e2, e3, 0, 0, 0]
+
+    result = flight.u_dot_generalized_3dof(0, u)
+
+    # Quaternion derivatives (indices 6-9) should be non-zero in anti-aligned case
+    e_dot = result[6:10]
+    e_dot_magnitude = sum(ed**2 for ed in e_dot) ** 0.5
+    assert e_dot_magnitude > 1e-6, (
+        "Quaternion derivatives should be non-zero for anti-aligned"
+    )