MNT: refactor parachute implementation

[Lucas-Prates]

Pull request type

• Code changes (bugfix, features)
• Code maintenance (refactoring, formatting, tests)
• ReadMe, Docs and GitHub updates

Checklist

• Tests for the changes have been added (MODIFIED EXISTING TESTS)
• Docs have been reviewed and added / updated (PARTIALLY)
• 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 current implementation of parachutes in RocketPy considers a simplified drag based round parachute, henceforth called Hemispherical Parachute. The Parachute class stores basic parachute information (drag, triggers, etc...) and all the physics (equations of motion) is handled by the Flight class inside the u_dot_parachute function. The problem is: different parachute types and models require different physics, which would create several "u_dot_parachute"s functions (or a really big messy one). Moreover, different parachutes require different information (some have lift coefficient, others have yaw coefficient, others have bank angle, angle of attack, and so on), so perhaps we should have different parachute classes, not just a big one.

New behavior

The Parachute class is now an abstract class which cannot be instantiated. All parachute models which will be created from now on should have it as a parent class. Our current implementation of the parachute is in the HemisphericalParachute class.

Each parachute class will have only the attributes it uses for its modelling and it contains the u_dot function! The idea is that the Parachute class has an abstract method called u_dot_parachute which each child must implement! Hence, the design proposal is to allow each parachute model to handle the physics! The SciPy solver is still called in the Flight class: an u_dot_parachute_wrapper is constructed in the Flight class to allow the parachute to use flight information and still maintain its arguments conforming to the SciPy solver requirement.

The Rocket method add_parachute was also changed. Since the idea is to have several parachute models, we now construct the parachute and then pass it as and object to that method. Hence, we now have a syntax such as

Main = HemisphericalParachute(
    "Main",
    cd_s=10.0,
    trigger=800,
    sampling_rate=105,
    lag=1.5,
    noise=(0, 8.3, 0.5),
)

Drogue = HemisphericalParachute(
    "Drogue",
    cd_s=1.0,
    trigger="apogee",
    sampling_rate=105,
    lag=1.5,
    noise=(0, 8.3, 0.5),
)

calisto.add_parachute(Main)
calisto.add_parachute(Drogue)

Hence, add_parachute also changed (compare to how it was done before).

Breaking change

• Will be (currently still support legacy parachute use)

Additional information

I look forward for your opinions on design choice and modifications/improvements!

I modified the tests and notebooks to work properly. However, I did not change much of the documentation, so it probably teaches how to add a Parachute incorrectly. Moreover, I did a quick dirty job on the Monte Carlo modification, it needs to be rewritten.

TODO LIST:

[ ] Verify and modify the documentation
[ ] Modify the Stochastic version of parachute

🪂 I'm baking up a low-fidelity 3DoF Parafoil model which motivated this hard refactor :) 🪂

[codecov]

Codecov Report

❌ Patch coverage is 91.46341% with 14 lines in your changes missing coverage. Please review.
✅ Project coverage is 80.98%. Comparing base (9cf3dd4) to head (bc64b7a).
⚠️ Report is 72 commits behind head on develop.

Files with missing lines	Patch %	Lines
rocketpy/plots/flight_plots.py	65.21%	8 Missing ⚠️
rocketpy/rocket/rocket.py	80.00%	3 Missing ⚠️
rocketpy/simulation/flight.py	85.00%	3 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##           develop     #958      +/-   ##
===========================================
+ Coverage    80.27%   80.98%   +0.71%     
===========================================
  Files          104      115      +11     
  Lines        12769    14650    +1881     
===========================================
+ Hits         10250    11865    +1615     
- Misses        2519     2785     +266     

☔ 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.

[Copilot]

Pull request overview

Refactors RocketPy’s parachute architecture to support multiple parachute models by introducing an abstract Parachute base class, moving parachute EoM (u_dot) into parachute implementations, and updating the Rocket API + project examples/tests/docs to the new creation/attachment flow.

Changes:

• Introduces rocketpy.rocket.parachutes.Parachute (abstract) and migrates the existing model to HemisphericalParachute.
• Updates Flight to call a per-parachute u_dot via a wrapper instead of hardcoding parachute dynamics in Flight.
• Changes Rocket.add_parachute to accept a parachute object, and updates tests/docs/notebooks accordingly.

Reviewed changes

Copilot reviewed 38 out of 39 changed files in this pull request and generated 13 comments.

Show a summary per file

File	Description
tests/unit/stochastic/test_stochastic_parachute.py	Updates stochastic parachute unit test to expect HemisphericalParachute.
tests/unit/rocket/test_parachute.py	Migrates parachute unit tests from Parachute to HemisphericalParachute (incl. serialization tests).
tests/integration/simulation/test_flight.py	Updates integration flight test to construct parachutes explicitly and then add them to the rocket.
tests/fixtures/rockets/rocket_fixtures.py	Updates rocket fixtures to use HemisphericalParachute objects before add_parachute.
tests/fixtures/parachutes/parachute_fixtures.py	Updates parachute fixtures to instantiate HemisphericalParachute.
tests/acceptance/test_ndrt_2020_rocket.py	Updates acceptance test parachute creation + attachment to new API.
tests/acceptance/test_bella_lui_rocket.py	Updates acceptance test parachute creation + attachment to new API.
rocketpy/stochastic/stochastic_rocket.py	Adapts stochastic rocket parachute handling to the new parachute class/module.
rocketpy/stochastic/stochastic_parachute.py	Updates stochastic parachute object creation to instantiate HemisphericalParachute.
rocketpy/simulation/flight.py	Replaces Flight.u_dot_parachute with a per-parachute wrapper calling parachute.u_dot.
rocketpy/rocket/rocket.py	Changes Rocket.add_parachute API to accept a parachute instance and append it.
rocketpy/rocket/parachutes/parachute.py	Adds new abstract base Parachute with trigger/noise utilities + (current) base serialization helpers.
rocketpy/rocket/parachutes/hemispherical_parachute.py	Turns old parachute implementation into HemisphericalParachute(Parachute) and implements u_dot + serialization.
rocketpy/rocket/parachutes/init.py	Adds parachutes package export(s).
rocketpy/rocket/init.py	Updates rocket package exports to include HemisphericalParachute.
rocketpy/init.py	Updates top-level exports to include HemisphericalParachute (and remove old Parachute).
docs/user/rocket/rocket_usage.rst	Updates user docs to the new parachute construction + add_parachute flow.
docs/user/first_simulation.rst	Updates “first simulation” docs to import/use HemisphericalParachute and then add to rocket.
docs/user/deployable.rst	Updates deployable example to use HemisphericalParachute and then add to rocket.
docs/user/compare_flights.rst	Updates compare-flights docs to the new parachute API.
docs/notebooks/trajectory.kml	Adds a KML output artifact used by notebook workflows/examples.
docs/notebooks/monte_carlo_analysis/monte_carlo_sensitivity_simulation.py	Updates Monte Carlo sensitivity notebook script to the new parachute API.
docs/notebooks/monte_carlo_analysis/monte_carlo_class_usage.ipynb	Updates Monte Carlo usage notebook imports + parachute creation/attachment.
docs/notebooks/monte_carlo_analysis/monte_carlo_analysis.ipynb	Updates Monte Carlo analysis notebook imports + parachute creation/attachment.
docs/notebooks/getting_started_colab.ipynb	Updates getting started (Colab) notebook imports + parachute creation/attachment.
docs/notebooks/getting_started.ipynb	Updates getting started notebook imports + parachute creation/attachment.
docs/examples/valetudo_flight_sim.ipynb	Updates example notebook to new parachute creation/attachment.
docs/examples/prometheus_2022_flight_sim.ipynb	Updates example notebook to new parachute creation/attachment.
docs/examples/ndrt_2020_flight_sim.ipynb	Updates example notebook to new parachute creation/attachment.
docs/examples/lince_flight_sim.ipynb	Updates example notebook to new parachute creation/attachment.
docs/examples/juno3_flight_sim.ipynb	Updates example notebook to new parachute creation/attachment.
docs/examples/halcyon_flight_sim.ipynb	Updates example notebook to new parachute creation/attachment.
docs/examples/genesis_flight_sim.ipynb	Updates example notebook to new parachute creation/attachment.
docs/examples/defiance_flight_sim.ipynb	Updates example notebook to new parachute creation/attachment.
docs/examples/camoes_flight_sim.ipynb	Updates example notebook to new parachute creation/attachment.
docs/examples/bella_lui_flight_sim.ipynb	Updates example notebook to new parachute creation/attachment.
docs/examples/andromeda_flight_sim.ipynb	Updates example notebook to new parachute creation/attachment.
README.md	Updates README snippets to the new parachute creation + add_parachute flow.

[Gui-FernandesBR]

"will be removed in a future release" is usually not a good idea

Can you already set a version for this feature to be removed? If we are 1.x.y, try 1.(x+2).0, for example

2 versiosn is tipically acceptable

[Gui-FernandesBR]

do you really need to add this file? docs/notebooks/trajectory.kml