ENH: 3-dof lateral motion improvement #883

aZira371 · 2025-11-27T13:07:11Z

Pull request type

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

The 3-DOF flight simulation keeps a fixed attitude throughout the flight. The quaternion derivatives are always zero, meaning the body axis direction never evolves despite changes in the relative wind direction.
#882

New behavior

Introduces an evolving unit direction vector for the body axis using a quasi-static weathercocking model. The rocket's attitude gradually aligns toward the relative wind direction.

Changes:

New weathercock_coeff parameter in Flight.init (default: 1.0)
Updated u_dot_generalized_3dof to compute quaternion derivatives proportional to misalignment with relative wind
Angular velocity = weathercock_coeff * sin(misalignment_angle)
Added example notebook docs/examples/bella_lui_3dof_vs_6dof_comparison.ipynb comparing 6-DOF and 3-DOF simulations

Breaking change

No

Additional information

A new jupyter notebook to be added, depicting comparison of 3 dof and 6 dof. It also highlights use of weathercocking coefficient.

codecov · 2025-11-27T13:16:04Z

Codecov Report

❌ Patch coverage is 97.14286% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 80.99%. Comparing base (9cf3dd4) to head (3693e5e).
⚠️ Report is 20 commits behind head on develop.

Files with missing lines	Patch %	Lines
rocketpy/simulation/flight.py	97.14%	1 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##           develop     #883      +/-   ##
===========================================
+ Coverage    80.27%   80.99%   +0.72%     
===========================================
  Files          104      107       +3     
  Lines        12769    13642     +873     
===========================================
+ Hits         10250    11050     +800     
- Misses        2519     2592      +73

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

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

aZira371 · 2025-11-27T14:42:15Z

This is a new implementation within 3 dof. Please critique it and suggest improvements!

docs/examples/bella_lui_3dof_vs_6dof_comparison.ipynb

Copilot

Pull request overview

This PR introduces a quasi-static weathercocking model for 3-DOF flight simulations to improve lateral motion realism. Previously, the 3-DOF simulation maintained a fixed attitude throughout flight, which was unrealistic. The new implementation allows the rocket's body axis to gradually align with the relative wind direction based on a configurable coefficient.

Key changes:

Added weathercock_coeff parameter to control the rate of attitude alignment in 3-DOF simulations
Implemented quaternion evolution in u_dot_generalized_3dof using cross-product-based rotation toward relative wind
Added comprehensive unit tests validating the weathercocking behavior across different scenarios

Reviewed changes

Copilot reviewed 3 out of 4 changed files in this pull request and generated 13 comments.

File	Description
rocketpy/simulation/flight.py	Added `weathercock_coeff` parameter (default 1.0) and implemented weathercocking model that computes quaternion derivatives to align body axis with relative wind direction in 3-DOF mode
tests/unit/simulation/test_flight_3dof.py	Added 5 new tests covering parameter storage, default values, fixed attitude with zero coefficient, attitude evolution with misalignment, and alignment verification
tests/conftest.py	Fixed import ordering to follow alphabetical convention (matplotlib before netCDF4)

tests/unit/simulation/test_flight_3dof.py

rocketpy/simulation/flight.py

tests/integration/simulation/test_flight_3dof.py

tests/unit/simulation/test_flight_3dof.py

rocketpy/simulation/flight.py

tests/integration/simulation/test_flight_3dof.py

rocketpy/simulation/flight.py

Copilot

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 6 comments.

docs/user/index.rst

tests/unit/simulation/test_flight_3dof.py

rocketpy/simulation/flight.py

docs/user/index.rst

- ENH: a new notebook bella_lui_3dof_vs_6dof.ipynb which uses new implementations of weathercocking model on 3dof

- ENH: introduced new weathercock_coeff parameter in Flight.init (default: 1.0) - ENH: updated u_dot_generalized_3dof to compute quaternion derivatives proportional to misalignment with relative wind - ENH: angular velocity = weathercock_coeff * sin(misalignment_angle)

- ENH: unit tests added for weathercocking to check whether weathercock_coeff=0 results in fixed attitude (no quaternion change). - MNT: format and lint updates for new additions

- DOC: added 3 dof and 6 dof comparison analysis to three_dof_simulation.rst - DOC: updated iusers/index.rst to build three_dof_simulation.rst - MNT: deleted the bella_lui_3dof_vs_6dof_comparison.ipynb as the doc now covers this section

- MNT: corrected doc string to represent correct orientation - MNT: improved tolerance of check on quaternion derivative which should be ideally very small when axes are aligned

…lementation

…cocking - BUG: implemented a dot product check to ensure that singularity bug is avoided when rocket body and wind velocity are anti aligned to make rocket statically stable (in u_dot_generalized_3dof) - MNT: removed redundant double assignment of e0 and w0 vectors within u_dot_generalized_3dof - MNT: format correction to test_flight_3dof.py

- 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

Gui-FernandesBR

overall the code looks clean. I see a few things that concerns me, so I listed below.

tests/unit/simulation/test_flight_3dof.py

tests/integration/simulation/test_flight_3dof.py

docs/user/three_dof_simulation.rst

rocketpy/simulation/flight.py

…cking coeff usage and value.

…xtures to test_flight_3dof.py

- MNT: fixed default weathercock_coeff value in flight.py to match 3 dof behaviour by default - MNT: corrected fixtures and docstrings in test_flight_3dof.py

tests/integration/simulation/test_flight_3dof.py

Gui-FernandesBR

@aZira371 overall I'm pretty confident with this PR.

You can already update the CHANGELOG to include this PR.

Let's wait a few more days to see if there's any other comment from copilot, Stano ou Bressan. If not, I will proceed with merging this one already.

Great job!!

Copilot

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 17 comments.

rocketpy/simulation/flight.py

docs/user/three_dof_simulation.rst

tests/integration/simulation/test_flight_3dof.py

rocketpy/simulation/flight.py

docs/user/three_dof_simulation.rst

tests/integration/simulation/test_flight_3dof.py

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

- MNT: correction of docstring now that fixtures are used. Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

- MNT: perp_axis singularity value error implemented to handle edge case for perp_axis being parallel to body axis in weathercocking model of 3 dof.

Copilot · 2025-12-03T20:51:46Z

@aZira371 I've opened a new pull request, #902, to work on those changes. Once the pull request is ready, I'll request review from you.

* Initial plan * DOC: Add note about motor file paths in 3-DOF comparison section Co-authored-by: aZira371 <99824864+aZira371@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: aZira371 <99824864+aZira371@users.noreply.github.com>

Copilot · 2025-12-03T21:35:19Z

@aZira371 I've opened a new pull request, #903, to work on those changes. Once the pull request is ready, I'll request review from you.

…lized_3dof (#903) * Initial plan * Refactor: eliminate quaternion derivative code duplication in u_dot_generalized_3dof Co-authored-by: aZira371 <99824864+aZira371@users.noreply.github.com> * Improve comment clarity in weathercocking aligned case Co-authored-by: aZira371 <99824864+aZira371@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: aZira371 <99824864+aZira371@users.noreply.github.com>

…otion improvement

Gui-FernandesBR

LGTM

github-project-automation bot added this to LibDev Roadmap Nov 27, 2025

github-project-automation bot moved this to Backlog in LibDev Roadmap Nov 27, 2025

aZira371 changed the title ~~Enh/3 dof lateral motion improvement~~ ENH/3-dof lateral motion improvement Nov 27, 2025

aZira371 changed the title ~~ENH/3-dof lateral motion improvement~~ ENH: 3-dof lateral motion improvement Nov 27, 2025

aZira371 self-assigned this Nov 27, 2025

aZira371 marked this pull request as ready for review November 27, 2025 14:42

aZira371 requested a review from a team as a code owner November 27, 2025 14:42

Gui-FernandesBR requested a review from Copilot November 27, 2025 14:50

Copilot started reviewing on behalf of Gui-FernandesBR November 27, 2025 14:51 View session

Gui-FernandesBR reviewed Nov 27, 2025

View reviewed changes

docs/examples/bella_lui_3dof_vs_6dof_comparison.ipynb Outdated Show resolved Hide resolved

Copilot finished reviewing on behalf of Gui-FernandesBR November 27, 2025 14:55

Copilot AI reviewed Nov 27, 2025

View reviewed changes

aZira371 requested a review from Copilot November 27, 2025 19:27

Copilot started reviewing on behalf of aZira371 November 27, 2025 19:28 View session

Copilot finished reviewing on behalf of aZira371 November 27, 2025 19:32

Copilot AI reviewed Nov 27, 2025

View reviewed changes

aZira371 requested a review from Gui-FernandesBR November 27, 2025 20:09

aZira371 and others added 8 commits November 27, 2025 21:17

ENH: addition of bella lui based 3 dof and 6 dof comparison notebook

7b34022

- ENH: a new notebook bella_lui_3dof_vs_6dof.ipynb which uses new implementations of weathercocking model on 3dof

ENH: added tests for weathercocking to test_flight_3dof.py

ef1d003

- ENH: unit tests added for weathercocking to check whether weathercock_coeff=0 results in fixed attitude (no quaternion change). - MNT: format and lint updates for new additions

MNT: corrections to test_flight_3dof.py

7cd0050

- MNT: corrected doc string to represent correct orientation - MNT: improved tolerance of check on quaternion derivative which should be ideally very small when axes are aligned

MNT: docstring corrections to flight.py around new weathercocking imp…

5ff03cd

…lementation

Gui-FernandesBR force-pushed the enh/3-dof-lateral-motion-improvement branch from 5f33d7f to fc4228c Compare November 28, 2025 00:17

Gui-FernandesBR reviewed Nov 28, 2025

View reviewed changes

tests/unit/simulation/test_flight_3dof.py Outdated Show resolved Hide resolved

tests/unit/simulation/test_flight_3dof.py Outdated Show resolved Hide resolved

tests/integration/simulation/test_flight_3dof.py Show resolved Hide resolved

docs/user/three_dof_simulation.rst Show resolved Hide resolved

Gui-FernandesBR reviewed Nov 28, 2025

View reviewed changes

rocketpy/simulation/flight.py Outdated Show resolved Hide resolved

aZira371 added 3 commits December 1, 2025 00:21

DOC: three_dof_simulation.rst update to add explanation of weather co…

a564397

…cking coeff usage and value.

MNT: changed default value of weather_coeff in flight.py and added fi…

174efa9

…xtures to test_flight_3dof.py

MNT: shifting test_flight_dof.py to integration tests.

c6b8efe

- MNT: fixed default weathercock_coeff value in flight.py to match 3 dof behaviour by default - MNT: corrected fixtures and docstrings in test_flight_3dof.py

Gui-FernandesBR reviewed Dec 1, 2025

View reviewed changes

tests/integration/simulation/test_flight_3dof.py Show resolved Hide resolved

Gui-FernandesBR requested a review from Copilot December 1, 2025 00:40

Copilot started reviewing on behalf of Gui-FernandesBR December 1, 2025 00:41 View session

Gui-FernandesBR reviewed Dec 1, 2025

View reviewed changes

Copilot finished reviewing on behalf of Gui-FernandesBR December 1, 2025 00:45

Copilot AI reviewed Dec 1, 2025

View reviewed changes

aZira371 and others added 10 commits December 1, 2025 14:52

MNT: docsrting update in test_flight_3dof.py

9afa353

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

MNT: Update of docstring in test_flight_3dof.py

a179962

- MNT: correction of docstring now that fixtures are used. Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

DOC: Update of three_dof_simulation.rst

dc18ed8

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update tests/integration/simulation/test_flight_3dof.py

d5b9f37

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Docstring Update tests/integration/simulation/test_flight_3dof.py

3d1a6ed

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

docstring Update tests/integration/simulation/test_flight_3dof.py

b1e6212

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

docstring Update docs/user/three_dof_simulation.rst

8b35366

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Docstring Update rocketpy/simulation/flight.py

f3f3b0a

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

MNT: Docstring updates to various files related to 3 dof

90acba7

MNT: unit vector edge case check in flight.py

b309d5e

- MNT: perp_axis singularity value error implemented to handle edge case for perp_axis being parallel to body axis in weathercocking model of 3 dof.

Copilot AI mentioned this pull request Dec 3, 2025

DOC: Add note about motor file paths in 3-DOF comparison section #902

Merged

3 tasks

Copilot AI mentioned this pull request Dec 3, 2025

Refactor: eliminate quaternion derivative code duplication in u_dot_generalized_3dof #903

Merged

3 tasks

Copilot AI and others added 3 commits December 4, 2025 03:34

Merge branch 'develop' into enh/3-dof-lateral-motion-improvement

0e104ff

DOC: CHANGELOG.md update to reflect implementation of 3 dof lateral m…

3693e5e

…otion improvement

Gui-FernandesBR approved these changes Dec 3, 2025

View reviewed changes

Gui-FernandesBR merged commit 14b9984 into develop Dec 3, 2025
10 checks passed

Gui-FernandesBR deleted the enh/3-dof-lateral-motion-improvement branch December 3, 2025 22:36

Uh oh!

ENH: 3-dof lateral motion improvement #883

ENH: 3-dof lateral motion improvement #883

Conversation

aZira371 commented Nov 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pull request type

Checklist

Current behavior

New behavior

Breaking change

Additional information

Uh oh!

codecov bot commented Nov 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

aZira371 commented Nov 27, 2025

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Gui-FernandesBR left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Gui-FernandesBR left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI commented Dec 3, 2025

Uh oh!

Copilot AI commented Dec 3, 2025

Uh oh!

Gui-FernandesBR left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

aZira371 commented Nov 27, 2025 •

edited

Loading

codecov bot commented Nov 27, 2025 •

edited

Loading