ENH: add Deployable to rocketpy.rocket.multistage

Second slice of the multistage/mission architecture. Deployable is
the mission-layer wrapper for an inert carried body (payload, nose
cone, etc.) that gets ejected during flight: mass/inertia/position
while attached, plus either a fully built free_rocket or surfaces
added via add_surface() for its free-flight aerodynamics -
mutually exclusive, matching mission_multistage_design.md.

Also revises SeparableBody from the previous commit: it no longer
holds a shared "separation" attribute. Stage's release event is
named separation, Deployable's is named ejection - forcing both
through one base attribute name was misleading, so each subclass
now owns its own.

Author: aZira371

rocketpy/rocket/multistage.py

@@ -10,16 +10,20 @@ class SeparableBody:
     name : str
         Unique body name within the vehicle; used to group Mission
         results (e.g. ``mission.flights["booster"]``).
-    separation : Event, optional
-        Event that releases this body. If None, never separates.
     separation_delta_v : float, optional
         Relative separation speed along the stack's longitudinal axis,
         in m/s, split by momentum conservation. Default 0.
+
+    Notes
+    -----
+    Subclasses each hold their own release-event attribute under its own
+    name (``Stage.separation``, ``Deployable.ejection``) rather than a
+    shared base attribute, since the two events are conceptually similar
+    but not interchangeable.
     """
 
-    def __init__(self, name, separation=None, separation_delta_v=0.0):
+    def __init__(self, name, separation_delta_v=0.0):
         self.name = name
-        self.separation = separation
         self.separation_delta_v = separation_delta_v
 
 
@@ -56,10 +60,9 @@ def __init__(
         ignition=None,
         ignition_delay=0.0,
     ):
-        super().__init__(
-            name=name, separation=separation, separation_delta_v=separation_delta_v
-        )
+        super().__init__(name=name, separation_delta_v=separation_delta_v)
         self.rocket = rocket
+        self.separation = separation
         self.ignition = ignition
         self.ignition_delay = ignition_delay
 
@@ -72,3 +75,82 @@ def burn_out_time(self):
     def dry_mass(self):
         """Stage dry mass (structure + motor dry mass), in kg."""
         return self.rocket.dry_mass
+
+
+class Deployable(SeparableBody):
+    """An inert body carried by the vehicle and ejected in flight.
+
+    No aerodynamic identity while attached: contributes only mass and
+    inertia at a position inside the carrying stage.
+
+    Free-flight aerodynamics come from one of two sources, mutually
+    exclusive:
+    - ``free_rocket``: a fully built Rocket or PointMassRocket (full
+      control);
+    - surfaces added with ``add_surface()``: Mission assembles the
+      free-flight Rocket from the deployable's mass, inertia, radius and
+      the added surfaces.
+
+    Parameters
+    ----------
+    name : str
+        Unique body name; used to group Mission results.
+    mass : float
+        Carried mass in kg.
+    inertia : tuple of float
+        Inertia (I11, I22, I33) about the deployable's own center of
+        mass, in kg*m^2.
+    position : float
+        Position of the deployable's center of mass in the carrying
+        stage's rocket coordinate system, in meters.
+    radius : float, optional
+        The deployable's largest radius in meters. Required only when
+        defining its free-flight aerodynamics via add_surface().
+    free_rocket : Rocket, PointMassRocket, optional
+        Free-flight configuration after ejection. Mutually exclusive
+        with add_surface().
+    ejection : Event, optional
+        When the deployable is released, e.g. Event(trigger="apogee").
+    separation_delta_v : float, optional
+        See SeparableBody.
+    """
+
+    def __init__(
+        self,
+        name,
+        mass,
+        inertia,
+        position,
+        radius=None,
+        free_rocket=None,
+        ejection=None,
+        separation_delta_v=0.0,
+    ):
+        super().__init__(name=name, separation_delta_v=separation_delta_v)
+        self.mass = mass
+        self.inertia = inertia
+        self.position = position
+        self.radius = radius
+        self.free_rocket = free_rocket
+        self.ejection = ejection
+        self.surfaces = []
+
+    def add_surface(self, surface, position):
+        """Add an aerodynamic surface to the deployable's free flight.
+
+        Takes effect only after ejection; while attached the deployable
+        still contributes only mass and inertia. ``position`` is in the
+        deployable's own coordinate system, in meters. Requires
+        ``radius`` to be set and is mutually exclusive with
+        ``free_rocket``.
+        """
+        if self.free_rocket is not None:
+            raise ValueError(
+                "add_surface is mutually exclusive with free_rocket; "
+                "a free_rocket was already provided for this deployable."
+            )
+        if self.radius is None:
+            raise ValueError(
+                "add_surface requires radius to be set on the deployable."
+            )
+        self.surfaces.append((surface, position))

tests/unit/rocket/test_multistage.py

@@ -1,4 +1,6 @@
-from rocketpy.rocket.multistage import Stage
+import pytest
+
+from rocketpy.rocket.multistage import Deployable, Stage
 
 
 def test_stage_dry_mass_matches_wrapped_rocket(calisto):
@@ -11,3 +13,62 @@ def test_stage_burn_out_time_matches_wrapped_rocket_motor(calisto):
     stage = Stage(name="stage_1", rocket=calisto)
 
     assert stage.burn_out_time == calisto.motor.burn_out_time
+
+
+def test_deployable_stores_constructor_arguments():
+    deployable = Deployable(
+        name="payload",
+        mass=4.5,
+        inertia=(0.1, 0.1, 0.001),
+        position=1.10,
+        radius=0.05,
+    )
+
+    assert deployable.name == "payload"
+    assert deployable.mass == 4.5
+    assert deployable.inertia == (0.1, 0.1, 0.001)
+    assert deployable.position == 1.10
+    assert deployable.radius == 0.05
+    assert deployable.free_rocket is None
+    assert deployable.ejection is None
+    assert not deployable.surfaces
+
+
+def test_add_surface_raises_when_free_rocket_already_set(calisto_nose_cone):
+    deployable = Deployable(
+        name="payload",
+        mass=4.5,
+        inertia=(0.1, 0.1, 0.001),
+        position=1.10,
+        radius=0.05,
+        free_rocket=object(),
+    )
+
+    with pytest.raises(ValueError):
+        deployable.add_surface(calisto_nose_cone, position=0.5)
+
+
+def test_add_surface_raises_when_radius_not_set(calisto_nose_cone):
+    deployable = Deployable(
+        name="payload",
+        mass=4.5,
+        inertia=(0.1, 0.1, 0.001),
+        position=1.10,
+    )
+
+    with pytest.raises(ValueError):
+        deployable.add_surface(calisto_nose_cone, position=0.5)
+
+
+def test_add_surface_appends_surface_and_position(calisto_nose_cone):
+    deployable = Deployable(
+        name="payload",
+        mass=4.5,
+        inertia=(0.1, 0.1, 0.001),
+        position=1.10,
+        radius=0.05,
+    )
+
+    deployable.add_surface(calisto_nose_cone, position=0.5)
+
+    assert deployable.surfaces == [(calisto_nose_cone, 0.5)]