MNT: refactor parachute implementation (#958)

* mnt: refactor parachute implementation

* ENH: introducing parachute plots in flight class and renaming abstract parachute class to BaseParachute

* mnt: making refactoring backwards compatible

* mnt: applying review suggestions

* mnt: add missing parachute.py file

* mnt: remove unnecessary file and update deprecation message

* MNT: polish parachute refactor docs and deprecation

Add changelog entry for PR #958, align Parachute trigger docstrings with the 4-argument runtime signature, and set a concrete deprecation removal target (1.14.0) for legacy add_parachute usage.

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

* MNT: review fixes for parachute refactor

Address review findings on PR #958 (parachute abstract base + hemispherical
model):

- rocket.py: validate that the new `add_parachute(parachute=...)` object path
  receives a Parachute subclass instance, raising a clear TypeError instead of
  letting a wrong object fail opaquely deep inside the ODE solver.
- parachute.py: fix `__repr__` unit label — `lag` is seconds, was mislabeled
  `m2` (copy-paste from the old `cd_s` repr).
- docs/reference: add a `HemisphericalParachute` autodoc page (the concrete
  class users instantiate; previously only the abstract base was documented).
- docs notebooks/scripts: fix Monte Carlo examples that called
  `Rocket.add_parachute(obj)` positionally — `parachute` is the last kwarg, so
  the object bound to `name` and the example crashed. Use
  `add_parachute(parachute=obj)`. (StochasticRocket.add_parachute(obj) is
  positional and was already correct.)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* BUG: save parachute drag info over accepted solution steps

The refactored parachute implementation saved each parachute's dynamic
information (``parachutes_info``, e.g. drag vs. time) from inside
``u_dot_parachute`` during the raw integration. Because the ODE solver
evaluates the derivative at internal RK stages and rejected steps, the
stored time series was non-monotonic, contained points that did not match
the accepted trajectory and even extended past ``t_final``.

Move the ``add_information_to_flight`` call to the post-processing branch,
which replays the derivatives over the accepted ``solution`` steps only, so
the recorded drag now matches the flight trajectory one-to-one.

Since post-processing is evaluated lazily, ``FlightPlots.parachutes_info``
now forces it before reading the data so the plot still works when called
standalone.

* BUG: fix parachute refactor integration issues found in review

- tests/unit/test_parachute_triggers.py (added on develop) still imported
  the pre-refactor module `rocketpy.rocket.parachute` and instantiated the
  now-abstract `Parachute` directly, which errored at collection time after
  the merge. Point it at `HemisphericalParachute` / the new package path.

- FlightPlots.parachutes_info(name): the single-parachute branch indexed
  `parachutes_info[name]` directly and raised KeyError when the named
  parachute never deployed (or the name was misspelled). Unify the two
  duplicated branches and print a helpful message listing the available
  parachutes instead.

- Flight.to_dict serializes `parachutes_info`, but the decoder's
  set_minimal_flight_attributes never restored it, so parachute drag data
  was silently dropped on every .rpy/JSON round-trip. Add it to the
  restored attribute list (guarded by the existing KeyError handling for
  older files).

* MNT: make Parachute base serialization inheritance-safe

The abstract Parachute.to_dict/from_dict referenced model-specific
attributes (cd_s, radius, drag_coefficient, height, porosity) that the
base no longer owns, and from_dict forwarded a `parachute_type` kwarg that
concrete constructors do not accept. They worked only because
HemisphericalParachute fully overrode them; any future parachute model
inheriting them would hit AttributeError/TypeError.

Reduce the base methods to the fields the base actually owns and expose a
shared `_decode_trigger` helper. HemisphericalParachute now builds on
`super().to_dict()` (matching the repo-wide serialization convention) and
adds only its own fields, removing the verbatim duplication. Serialized
output and round-trip behavior are unchanged. Drop the now-unused imports.

* MNT: satisfy ruff/pylint for parachute changes

- ruff format: collapse the parachutes_info source comprehension to one line.
- pylint (no-value-for-parameter, fail-under=10): the base Parachute could
  not offer a generic from_dict because each concrete model has different
  required constructor arguments. Make from_dict abstract (mirroring u_dot
  and add_information_to_flight); the shared _decode_trigger helper stays on
  the base and HemisphericalParachute keeps its concrete implementation.

---------

Co-authored-by: Gui-FernandesBR <guilherme_fernandes@usp.br>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: 4 people

CHANGELOG.md

@@ -40,6 +40,7 @@ Attention: The newest changes should be on top -->
 - ENH: BUG: fix wind heading and direction wraparound interpolation [#974](https://github.com/RocketPy-Team/RocketPy/pull/974)
 - ENH: MNT: Sync develop's Renovate config with master (#1039) [#1040](https://github.com/RocketPy-Team/RocketPy/pull/1040)
 - ENH: MNT: Configure Renovate Bot targeting develop branch [#972](https://github.com/RocketPy-Team/RocketPy/pull/972)
+- MNT: Refactor parachute implementation with abstract base and hemispherical model split [#958](https://github.com/RocketPy-Team/RocketPy/pull/958)
 - ENH: Monte Carlo Formatting Options [#947](https://github.com/RocketPy-Team/RocketPy/pull/947)
 - ENH: ENH: Auto-Detection of Pressure Conversion Factor [#966](https://github.com/RocketPy-Team/RocketPy/pull/966)
 - ENH: Auto-Detection of Pressure Conversion Factor [#966](https://github.com/RocketPy-Team/RocketPy/pull/966)

README.md

@@ -143,7 +143,7 @@ The following image shows how the four main classes interact with each other:
 A typical workflow starts with importing these classes from RocketPy:
 
 ```python
-from rocketpy import Environment, Rocket, SolidMotor, Flight
+from rocketpy import Environment, Rocket, SolidMotor, Flight, HemisphericalParachute
 ```
 
 An optional step is to import datetime, which is used to define the date of the simulation:
@@ -255,7 +255,7 @@ tail = calisto.add_tail(
 You may want to add parachutes to your rocket as well:
 
 ```python
-main = calisto.add_parachute(
+main = HemisphericalParachute(
     name="main",
     cd_s=10.0,
     trigger=800,  # ejection altitude in meters
@@ -267,7 +267,7 @@ main = calisto.add_parachute(
     porosity=0.0432,
 )
 
-drogue = calisto.add_parachute(
+drogue = HemisphericalParachute(
     name="drogue",
     cd_s=1.0,
     trigger="apogee",  # ejection at apogee
@@ -278,6 +278,9 @@ drogue = calisto.add_parachute(
     height=1.5,
     porosity=0.0432,
 )
+
+calisto.add_parachute(parachute = main)
+calisto.add_parachute(parachute = drogue)
 ```
 
 Finally, you can create a Flight object to simulate your trajectory. To get help on the Flight class, use:

docs/examples/andromeda_flight_sim.ipynb

@@ -37,7 +37,14 @@
    "source": [
     "import matplotlib.pyplot as plt\n",
     "\n",
-    "from rocketpy import Environment, Flight, Function, Rocket, SolidMotor\n",
+    "from rocketpy import (\n",
+    "    Environment,\n",
+    "    Flight,\n",
+    "    Function,\n",
+    "    HemisphericalParachute,\n",
+    "    Rocket,\n",
+    "    SolidMotor,\n",
+    ")\n",
     "\n",
     "plt.style.use(\"seaborn-v0_8-colorblind\")"
    ]
@@ -258,7 +265,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 64,
+   "execution_count": null,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -276,13 +283,15 @@
     "    position=0.3546,\n",
     ")\n",
     "\n",
-    "Drogue = Andromeda.add_parachute(\n",
+    "Drogue = HemisphericalParachute(\n",
     "    \"Drogue\", cd_s=0.84665922014, trigger=\"apogee\", sampling_rate=100, lag=0\n",
     ")\n",
     "\n",
-    "Main = Andromeda.add_parachute(\n",
+    "Main = HemisphericalParachute(\n",
     "    \"Main\", cd_s=8.362919643856031, trigger=500, sampling_rate=100, lag=0\n",
-    ")"
+    ")\n",
+    "Andromeda.add_parachute(parachute=Drogue)\n",
+    "Andromeda.add_parachute(parachute=Main)"
    ]
   },
   {

docs/examples/bella_lui_flight_sim.ipynb

@@ -31,7 +31,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 9,
+   "execution_count": null,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -40,7 +40,14 @@
     "import numpy as np\n",
     "from scipy.signal import savgol_filter\n",
     "\n",
-    "from rocketpy import Environment, Flight, Function, Rocket, SolidMotor"
+    "from rocketpy import (\n",
+    "    Environment,\n",
+    "    Flight,\n",
+    "    Function,\n",
+    "    HemisphericalParachute,\n",
+    "    Rocket,\n",
+    "    SolidMotor,\n",
+    ")"
    ]
   },
   {
@@ -422,18 +429,19 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 44,
+   "execution_count": null,
    "metadata": {},
    "outputs": [],
    "source": [
-    "Drogue = bella_lui.add_parachute(\n",
+    "Drogue = HemisphericalParachute(\n",
     "    \"Drogue\",\n",
     "    cd_s=parameters.get(\"CdS_drogue\")[0],\n",
     "    trigger=\"apogee\",\n",
     "    sampling_rate=105,\n",
     "    lag=parameters.get(\"lag_rec\")[0],\n",
     "    noise=(0, 8.3, 0.5),\n",
-    ")"
+    ")\n",
+    "bella_lui.add_parachute(parachute=Drogue)"
    ]
   },
   {

docs/examples/camoes_flight_sim.ipynb

@@ -52,6 +52,7 @@
     "    Environment,\n",
     "    Flight,\n",
     "    Function,\n",
+    "    HemisphericalParachute,\n",
     "    Rocket,\n",
     "    SolidMotor,\n",
     ")\n",
@@ -299,17 +300,18 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 85,
+   "execution_count": null,
    "metadata": {},
    "outputs": [],
    "source": [
     "def drogue_trigger(p, h, y):\n",
     "    return True if y[5] < 5 and y[2] > 300 else False\n",
     "\n",
     "\n",
-    "Drogue = CAMOES.add_parachute(\n",
+    "Drogue = HemisphericalParachute(\n",
     "    \"Drogue\", cd_s=0.33, sampling_rate=400, lag=1.5, trigger=drogue_trigger\n",
-    ")"
+    ")\n",
+    "CAMOES.add_parachute(parachute=Drogue)"
    ]
   },
   {

docs/examples/defiance_flight_sim.ipynb

@@ -21,13 +21,13 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 1,
+   "execution_count": null,
    "metadata": {},
    "outputs": [],
    "source": [
     "import datetime\n",
     "\n",
-    "from rocketpy import Environment, Flight, Function, Rocket\n",
+    "from rocketpy import Environment, Flight, Function, HemisphericalParachute, Rocket\n",
     "from rocketpy.motors import CylindricalTank, Fluid, HybridMotor\n",
     "from rocketpy.motors.tank import MassFlowRateBasedTank"
    ]
@@ -185,7 +185,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 4,
+   "execution_count": null,
    "metadata": {},
    "outputs": [
     {
@@ -221,11 +221,15 @@
     "\n",
     "defiance.add_tail(top_radius=0.07, bottom_radius=0.064, length=0.0597, position=0.1)\n",
     "\n",
-    "defiance.add_parachute(name=\"main\", cd_s=2.2, trigger=305, sampling_rate=100, lag=0)\n",
+    "Main = HemisphericalParachute(\n",
+    "    name=\"main\", cd_s=2.2, trigger=305, sampling_rate=100, lag=0\n",
+    ")\n",
     "\n",
-    "defiance.add_parachute(\n",
+    "Drogue = HemisphericalParachute(\n",
     "    name=\"drogue\", cd_s=1.55, trigger=\"apogee\", sampling_rate=100, lag=0\n",
-    ")"
+    ")\n",
+    "defiance.add_parachute(parachute=Main)\n",
+    "defiance.add_parachute(parachute=Drogue)"
    ]
   },
   {

docs/examples/genesis_flight_sim.ipynb

@@ -37,7 +37,7 @@
    "source": [
     "import matplotlib.pyplot as plt\n",
     "\n",
-    "from rocketpy import Environment, Flight, Function, Rocket\n",
+    "from rocketpy import Environment, Flight, Function, HemisphericalParachute, Rocket\n",
     "from rocketpy.motors import SolidMotor\n",
     "\n",
     "plt.style.use(\"seaborn-v0_8-colorblind\")"
@@ -267,11 +267,11 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 8,
+   "execution_count": null,
    "metadata": {},
    "outputs": [],
    "source": [
-    "Drogue = GENESIS.add_parachute(\n",
+    "Drogue = HemisphericalParachute(\n",
     "    name=\"Drogue\",\n",
     "    cd_s=0.285005285533666,\n",
     "    trigger=\"apogee\",\n",
@@ -280,14 +280,16 @@
     "    noise=(0, 8.3, 0.5),\n",
     ")\n",
     "\n",
-    "Main = GENESIS.add_parachute(\n",
+    "Main = HemisphericalParachute(\n",
     "    name=\"Main\",\n",
     "    cd_s=1.1,\n",
     "    trigger=870,\n",
     "    sampling_rate=105,\n",
     "    lag=1,\n",
     "    noise=(0, 8.3, 0.5),\n",
-    ")"
+    ")\n",
+    "GENESIS.add_parachute(parachute=Drogue)\n",
+    "GENESIS.add_parachute(parachute=Main)"
    ]
   },
   {

docs/examples/halcyon_flight_sim.ipynb

@@ -31,15 +31,15 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 2,
+   "execution_count": null,
    "metadata": {},
    "outputs": [],
    "source": [
     "import datetime\n",
     "\n",
     "import matplotlib.pyplot as plt\n",
     "\n",
-    "from rocketpy import Environment, Flight, Function, Rocket\n",
+    "from rocketpy import Environment, Flight, Function, HemisphericalParachute, Rocket\n",
     "from rocketpy.motors import CylindricalTank, Fluid, HybridMotor\n",
     "from rocketpy.motors.tank import MassFlowRateBasedTank\n",
     "\n",
@@ -416,17 +416,18 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 11,
+   "execution_count": null,
    "metadata": {},
    "outputs": [],
    "source": [
-    "Main = HALCYON.add_parachute(\n",
+    "Main = HemisphericalParachute(\n",
     "    name=\"Main\",\n",
     "    cd_s=9.621,\n",
     "    trigger=\"apogee\",\n",
     "    sampling_rate=100,\n",
     "    lag=5,\n",
-    ")"
+    ")\n",
+    "HALCYON.add_parachute(parachute=Main)"
    ]
   },
   {

docs/examples/juno3_flight_sim.ipynb

@@ -33,13 +33,20 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 2,
+   "execution_count": null,
    "metadata": {},
    "outputs": [],
    "source": [
     "import matplotlib.pyplot as plt\n",
     "\n",
-    "from rocketpy import Environment, Flight, Function, Rocket, SolidMotor\n",
+    "from rocketpy import (\n",
+    "    Environment,\n",
+    "    Flight,\n",
+    "    Function,\n",
+    "    HemisphericalParachute,\n",
+    "    Rocket,\n",
+    "    SolidMotor,\n",
+    ")\n",
     "from rocketpy.simulation.flight_data_importer import FlightDataImporter\n",
     "\n",
     "plt.style.use(\"seaborn-v0_8-colorblind\")"
@@ -333,18 +340,19 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 15,
+   "execution_count": null,
    "metadata": {},
    "outputs": [],
    "source": [
-    "drogue = juno.add_parachute(\n",
+    "drogue = HemisphericalParachute(\n",
     "    \"Drogue\",\n",
     "    cd_s=0.885,\n",
     "    trigger=\"apogee\",\n",
     "    sampling_rate=105,\n",
     "    noise=(0, 8.3, 0.5),\n",
     "    lag=0.5,\n",
-    ")"
+    ")\n",
+    "juno.add_parachute(parachute=drogue)"
    ]
   },
   {