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)
• 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.21622% with 13 lines in your changes missing coverage. Please review.
✅ Project coverage is 81.42%. Comparing base (9cf3dd4) to head (b51eb90).
⚠️ Report is 98 commits behind head on develop.

Files with missing lines	Patch %	Lines
rocketpy/plots/flight_plots.py	80.00%	4 Missing ⚠️
rocketpy/rocket/rocket.py	77.77%	4 Missing ⚠️
rocketpy/simulation/flight.py	81.25%	3 Missing ⚠️
...ketpy/rocket/parachutes/hemispherical_parachute.py	97.14%	2 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##           develop     #958      +/-   ##
===========================================
+ Coverage    80.27%   81.42%   +1.15%     
===========================================
  Files          104      118      +14     
  Lines        12769    15160    +2391     
===========================================
+ Hits         10250    12344    +2094     
- Misses        2519     2816     +297     

☔ View full report in Codecov by Harness.
📢 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]

Quick update on #958 (latest head: ad0777bc):

• rebased branch on current develop and resolved conflicts
• added missing CHANGELOG.md Unreleased entry for the parachute refactor
• aligned Parachute trigger docstrings with runtime behavior (callable may receive sensors as 4th argument)
• set concrete deprecation removal target for legacy Rocket.add_parachute(...) usage to 1.14.0

Local checks run for this update:

• ruff check on touched files
• pytest tests/unit/rocket/test_parachute.py -q
• pytest tests/integration/simulation/test_flight.py -q