ENH: Implementing 3-dof-simulation

[aZira371]

Pull request type

• [x] Code changes (bugfix, features)

Checklist

• [ ] Tests for the changes have been added (if needed)
• [ ] Docs have been reviewed and added / updated
• [ ] Lint (black rocketpy/ tests/) has passed locally
• [ ] All tests (pytest tests -m slow --runslow) have passed locally
• [ ] CHANGELOG.md has been updated (if relevant)

Current behavior

for issue #655

New behavior

(DRAFT) ENH: adds 3 DOF simulation capability to rocketpy.Flight.

*ENH: added "u_dot_3dof" for "solid_propulsion" mode

*ENH: adding "u_dot_generalized_3dof" for "standard" mode (still incomplete)

*ENH: new parameter "simulation_mode" for swtiching between 3 dof and 6 dof

*ENH: updated conditions for "__init_equations_of_motion"

*ENH: 2 new example files have been created to test 3 dof model "test_bella_lui_flight_sim" and "test_camoes_flight_sim"

Breaking change

• [ ] No

Additional information

This is a draft pull request! Equations of motion have been modified in such a way that values related to various rotational dofs is set to zero.

[Lucas-Prates]

Thank you for your interest in implementing 3-DOF in RocketPy, @aZira371 . I will try to take a better look into it, but I notice one thing already: use 6 DOF as the default input for simulation_mode for two reasons:

1. most people will use 6 DOF;
2. changing it to 3 DOF introduces breaking changes, and we really want to avoid that. You can see that a breaking change occurred because the tests failed.

[Gui-FernandesBR]

• [x] Git rebase develop
• [x] Revert changes in the jupyter notebook
• [x] Create PointMassMotor
• [x] Create BaseRocket
• [x] Create PointMassRocket
• [x] Modify Rocket class where it's needed (here other people can help you, including Gui)
• [x] Modify the Flight class again, if needed (delete u_dot_3dof)
• [ ] Include integration tests (here you can ask for help)
• [ ] Format and lint the code (see the Makefile)

[codecov[bot]]

Codecov Report

:x: Patch coverage is 82.23684% with 27 lines in your changes missing coverage. Please review. :white_check_mark: Project coverage is 80.26%. Comparing base (9cf3dd4) to head (567b9e0). :warning: Report is 6 commits behind head on develop.

Files with missing lines	Patch %	Lines
rocketpy/simulation/flight.py	68.11%	22 Missing :warning:
rocketpy/motors/point_mass_motor.py	90.38%	5 Missing :warning:

Additional details and impacted files

@@             Coverage Diff             @@
##           develop     #745      +/-   ##
===========================================
- Coverage    80.27%   80.26%   -0.02%     
===========================================
  Files          104      106       +2     
  Lines        12769    12979     +210     
===========================================
+ Hits         10250    10417     +167     
- Misses        2519     2562      +43     

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.

:rocket: New features to boost your workflow:

• :snowflake: Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Gui-FernandesBR]

@aZira371 great work, code seems cleaner now!!

There's still some work to do, here are suggestions on how to proceed:

1. Rebase this PR onto develop. This will bring the most recent commits to your branch.
2. Remind to run the make format and make lint commands before pushing, this makes review much easier.
3. Resolve each comment in this PR, asking questions if you have any.

Let me know if you need any help on this process.

[aZira371]

@MateusStano Please review this PR. All tests passing except pylint but I think that is not from the 3 dof commits. Tests for 3 dof are not included. Please check and let me know.

[aZira371]

@Gui-FernandesBR I have held discussions about tests with @MateusStano and we think it should be a separate PR along with the documentation. Would be easier to manage otherwise this PR was extending a lot.

[aZira371]

The PR looks good. Main points missing for me that could be easily appended to a following PR:

1. There are still no "sanity-check" tests for the results. We could probably make an "acceptance" test for it, by picking up a known battle-tested Flight and hoping for the landing coordinates being close. The tolerances for it are a point worth discussing. Maybe even comparing to a parabolic trajectory might give some insight (for sanity-checking a ballistic Flight);
2. Still on the validation side: results should be pretty close if one runs a bare-bones Rocket in 6-DOF, right?
3. Some tests lack proper docstrings;
4. Smaller comments I left throughout my review.

I'm fine proceeding with a merge here, but the first point for me is important before releasing the feature.

Agreed on the first and second point. I can run a 3 DOF example of one of the already existing examples and see how it works. From there we will also be able to understand tolerances.

[aZira371]

@Gui-FernandesBR @phmbressan Here is a comparison of results of 3 dof and 6 dof on bella lui rocket example. as expected the impact/landing point is drastically incorrect. This is expected as 3 dof only implements translation motion (meaning the quaternion rates are 0) , to model rotational kinematics I can introduce an evolving unit direction vector for the “effective body/flight‑path axis” with a simple kinematic or quasi‑static weathercocking model. What do you think? This can be an implementation after this PR is merged!

just a small note on how the Weathercocking Model Works:

• Calculate the current body z-axis direction from quaternions (attitude vector)
• Calculate the desired direction as the opposite of the freestream velocity (normalized)
• Compute the rotation axis as the cross product of current and desired directions
• Apply angular velocity proportional to sin(misalignment_angle) (for quasi-static alignment)
• Compute quaternion derivatives from this angular velocity

[aZira371]

Results with preliminary weathercocking implementation and creating quasistatic attitude variation for 3 dof : termination at apogee :- termination at apogee false : -

[Gui-FernandesBR]

@phmbressan thank you for the quick response. I will merge this PR as this is becoming quite dated now. @aZira371 will make smaller, separate PRs to solve your remaining comments.