ENH: multistage mission architecture (body, mission, FlightBranch)

rocketpy/__init__.py

@@ -1,4 +1,11 @@
 from ._logging import enable_logging, logger, set_log_level
+from .body import (
+    BodyLike,
+    BodyResolver,
+    FlightBody,
+    FlightCompatibleRocket,
+    RocketAdapter,
+)
 from .control import _Controller
 from .environment import Environment, EnvironmentAnalysis
 from .mathutils import (
@@ -7,6 +14,26 @@
     funcify_method,
     reset_funcified_methods,
 )
+from .mission import (
+    Attachment,
+    BranchResult,
+    Deployable,
+    DeploymentEvent,
+    FlightConfig,
+    IgnitionEvent,
+    InstantaneousSeparation,
+    Mission,
+    MissionExecutionResult,
+    MissionExecutor,
+    MissionResult,
+    NoOpParentUpdate,
+    ParentUpdate,
+    RecoveryEvent,
+    SeparationModel,
+    Stage,
+    StageSeparationEvent,
+    StageState,
+)
 from .motors import (
     CylindricalTank,
     EmptyMotor,
@@ -52,6 +79,7 @@
 from .simulation import (
     Event,
     Flight,
+    FlightBranch,
     MonteCarlo,
     MultivariateRejectionSampler,
 )

rocketpy/body/__init__.py

@@ -0,0 +1,14 @@
+"""rocketpy.body – body abstraction layer for multistage simulation."""
+
+from rocketpy.body.body_like import BodyLike
+from rocketpy.body.body_resolver import BodyResolver, FlightCompatibleRocket
+from rocketpy.body.flight_body import FlightBody
+from rocketpy.body.rocket_adapter import RocketAdapter
+
+__all__ = [
+    "BodyLike",
+    "BodyResolver",
+    "FlightBody",
+    "FlightCompatibleRocket",
+    "RocketAdapter",
+]

rocketpy/body/body_like.py

@@ -0,0 +1,157 @@
+"""BodyLike protocol for the multistage mission architecture.
+
+This module defines a structural typing contract so bodies can satisfy the
+interface without inheriting from a shared base class.
+"""
+
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class BodyLike(Protocol):
+    """Structural interface that every flight-ready body must satisfy.
+
+    Any object that can be integrated by the Flight simulation engine
+    must implement this interface.  Both the native :class:`FlightBody`
+    and the :class:`RocketAdapter` (which wraps a legacy :class:`Rocket`)
+    satisfy it, so that the simulation layer can treat them uniformly.
+    This uses structural typing, so concrete bodies do not need to inherit
+    from :class:`BodyLike` to be accepted by the simulation layer.
+
+    Attributes
+    ----------
+    name : str
+        Human-readable identifier for the body.
+    """
+
+    @property
+    def name(self) -> str:
+        """Human-readable name of the body.
+
+        Returns
+        -------
+        str
+            Body name.
+        """
+        ...
+
+    def mass(self, t: float) -> float:
+        """Total mass of the body at time *t*, in kg.
+
+        Parameters
+        ----------
+        t : float
+            Simulation time in seconds.
+
+        Returns
+        -------
+        float
+            Total mass in kg.
+        """
+        ...
+
+    def inertia_tensor(self, t: float):
+        """Inertia tensor of the body at time *t*, in kg·m².
+
+        Parameters
+        ----------
+        t : float
+            Simulation time in seconds.
+
+        Returns
+        -------
+        array-like
+            3×3 inertia tensor in kg·m².
+        """
+        ...
+
+    def center_of_mass(self, t: float) -> float:
+        """Position of the center of mass along the body axis at time *t*.
+
+        The position is measured in meters relative to the body's own
+        coordinate system origin.
+
+        Parameters
+        ----------
+        t : float
+            Simulation time in seconds.
+
+        Returns
+        -------
+        float
+            Center-of-mass position in meters.
+        """
+        ...
+
+    def aerodynamic_model(self):
+        """Return the aerodynamic model attached to this body.
+
+        Returns
+        -------
+        object
+            Aerodynamic model instance.
+        """
+        ...
+
+    def propulsion_model(self):
+        """Return the propulsion model attached to this body.
+
+        Returns
+        -------
+        object
+            Propulsion model instance.
+        """
+        ...
+
+    def recovery_systems(self):
+        """Return the list of recovery systems attached to this body.
+
+        Returns
+        -------
+        list
+            Recovery systems.
+        """
+        ...
+
+    def sensors(self):
+        """Return the list of sensors attached to this body.
+
+        Returns
+        -------
+        list
+            Sensor instances.
+        """
+        ...
+
+    def controllers(self):
+        """Return the list of active controllers attached to this body.
+
+        Returns
+        -------
+        list
+            Controller instances.
+        """
+        ...
+
+    def coordinate_system_orientation(self) -> str:
+        """Orientation convention for the body's coordinate system.
+
+        Returns
+        -------
+        str
+            One of ``"tail_to_nose"`` or ``"nose_to_tail"``.
+        """
+        ...
+
+    def to_branch_ready_copy(self):
+        """Return a simulation-ready deep copy of this body.
+
+        The copy is detached from user-facing state so that the
+        simulation engine can mutate it freely without side-effects.
+
+        Returns
+        -------
+        BodyLike
+            A deep copy suitable for a :class:`FlightBranch`.
+        """
+        ...

rocketpy/body/body_resolver.py

@@ -0,0 +1,114 @@
+"""BodyResolver – resolves mission bodies to BodyLike / Flight-compatible rockets."""
+
+from typing import Any, Protocol, runtime_checkable
+
+from rocketpy.body.body_like import BodyLike
+from rocketpy.body.flight_body import FlightBody
+from rocketpy.body.rocket_adapter import RocketAdapter
+
+
+@runtime_checkable
+class FlightCompatibleRocket(Protocol):
+    """Structural contract for rocket objects accepted by Flight."""
+
+    def add_motor(self, motor, position):
+        """Add a motor to the rocket body."""
+
+    def total_mass(self, t: float) -> float:
+        """Return total mass at time *t*."""
+
+    def center_of_mass(self, t: float) -> float:
+        """Return center-of-mass position at time *t*."""
+
+
+class BodyResolver:
+    """Resolves mission bodies (``Rocket``, ``RocketAdapter``, ``FlightBody``, ...)
+    into the shapes the simulation engine needs.
+
+    This is a two-step resolver:
+
+    1. :meth:`to_body` resolves any supported source into a :class:`BodyLike`.
+       This step is intentionally permissive – a bare :class:`FlightBody` is a
+       legitimate ``BodyLike`` for mission-level bookkeeping (e.g.
+       :meth:`~rocketpy.mission.Mission.describe`), even though it cannot yet
+       drive a real :class:`~rocketpy.simulation.Flight`.
+    2. :meth:`to_flight_rocket` takes a resolved :class:`BodyLike` and returns
+       an object that can be passed as ``Flight(rocket=...)``. This is where
+       bodies that cannot actually fly (today, a bare :class:`FlightBody`) are
+       rejected with a clear, actionable error instead of failing silently or
+       deep inside ``Flight``'s constructor.
+    """
+
+    @staticmethod
+    def to_body(source: Any) -> BodyLike:
+        """Resolve *source* to a :class:`BodyLike`.
+
+        Parameters
+        ----------
+        source : Rocket, RocketAdapter, FlightBody, or FlightCompatibleRocket
+            The mission body to resolve.
+
+        Returns
+        -------
+        BodyLike
+            A body satisfying the :class:`BodyLike` interface.
+
+        Raises
+        ------
+        TypeError
+            If *source* cannot be resolved to a :class:`BodyLike`.
+        """
+        if isinstance(source, (RocketAdapter, FlightBody)):
+            return source
+        if isinstance(source, BodyLike):
+            return source
+        if hasattr(source, "as_body"):
+            return source.as_body()
+        if isinstance(source, FlightCompatibleRocket):
+            return RocketAdapter(source)
+        raise TypeError(
+            f"BodyResolver cannot resolve {type(source).__name__!r} to a BodyLike. "
+            "Supported sources: Rocket, RocketAdapter, FlightBody, or objects "
+            "satisfying FlightCompatibleRocket."
+        )
+
+    @staticmethod
+    def to_flight_rocket(body: BodyLike):
+        """Return a Flight-compatible rocket object for *body*.
+
+        Parameters
+        ----------
+        body : BodyLike
+            A body previously resolved via :meth:`to_body`.
+
+        Returns
+        -------
+        FlightCompatibleRocket
+            An object that can be passed as ``Flight(rocket=...)``.
+
+        Raises
+        ------
+        TypeError
+            If *body* cannot drive a :class:`~rocketpy.simulation.Flight` yet.
+            This is always the case for a bare :class:`FlightBody`, since it
+            does not implement ``total_mass()``/``add_motor()``.
+        """
+        if isinstance(body, RocketAdapter):
+            return body.rocket
+        if isinstance(body, FlightCompatibleRocket):
+            return body
+        if isinstance(body, FlightBody):
+            raise TypeError(
+                f"Cannot build a Flight from FlightBody {body.name!r}: FlightBody "
+                "does not implement total_mass()/add_motor() and cannot drive "
+                "Flight's physics engine directly yet. Use a Rocket (optionally "
+                "wrapped in RocketAdapter) for real flight execution; "
+                "FlightBody-driven Flight integration is planned future work."
+            )
+        raise TypeError(
+            f"BodyResolver cannot use {type(body).__name__!r} to construct a "
+            "Flight. Supported bodies: a Rocket (optionally wrapped in "
+            "RocketAdapter), or any object satisfying FlightCompatibleRocket "
+            "(add_motor, total_mass, center_of_mass). A bare FlightBody is also "
+            "not yet supported for Flight execution."
+        )