ENH: Implement 3-DOF Single Rail Button Flight Phase (Tip-off Analysis)

[giovaniceotto]

Is your feature request related to a problem? Please describe. Currently, the Flight simulation transitions instantly from Phase 1 (Two buttons on rail, 1-DOF linear motion) to Phase 3 (Free flight, 6-DOF).

It skips an intermediate Phase 2: The "Single Rail Button" phase. This occurs when the upper rail button has left the rail guide, but the lower rail button is still attached. During this split-second interval, the rocket is free to rotate (pitch/yaw) around the lower button due to wind or thrust misalignment, while still being constrained translationally along the rail axis.

Ignoring this phase ignores "Rod Whip" or "Tip-off" effects, which can significantly alter the initial conditions ($w_0$, $\theta_0$) of the free flight, affecting dispersion accuracy.

Describe the solution you'd like I would like to implement the equations of motion for this specific phase in the Flight class. The structure is already prepared in the code as udot_rail2, but the method is currently empty/unimplemented.

Implementation Details

• Target Method: Flight.udot_rail2(t, u) in rocketpy/flight/flight.py.
• Physics Model:
  • Constraints: The rocket is pinned at the lower rail button location (sliding along the rail vector).
  • Degrees of Freedom (3-DOF):
    1. Translation along the rail ($v_{rail}$).
    2. Rotation around the local Y-axis (Pitch).
    3. Rotation around the local Z-axis (Yaw).
  • Forces: Thrust, Gravity, Aerodynamics (Lift/Drag), and the Reaction Force at the lower button (which acts as a pivot).
• Transition Logic (in Flight main loop):
  • Start of Phase 2: When distance traveled > Flight.effective_1rl.
  • End of Phase 2: When distance traveled > Flight.effective_2rl.

Helpful Properties The Flight class already has the necessary geometric properties to determine the start and end of this phase:

• Flight.effective_1rl: Distance to clear the first button.
• Flight.effective_2rl: Distance to clear the second button.

Acceptance Criteria

• [ ] Implement the dynamics in udot_rail2 to return the derivative of the state vector $[v, \omega, ...]$.
• [ ] Update the integration loop in Flight to detect when z > effective_1rl and switch the integration method from udot_rail1 to udot_rail2.
• [ ] Ensure udot_rail2 transitions smoothly to u_dot (free flight) once z > effective_2rl.
• [ ] Verify that wind acting during this phase causes the rocket to "whip" or turn into the wind before fully leaving the rail.

Additional Context

• This is often referred to as "Tip-off" analysis.
• Warning: The equations of motion for a body constrained to a line at a specific offset point (lower button) involving rotation are more complex than standard free-body dynamics. Lagragian mechanics might be the easiest way to derive these equations.

[giovaniceotto]

Working on it in the rail_buttons branch.