ENH: mission architecture implementation on rocketpy

aZira371 · aZira371 · commit 0caf343d1eb5 · 2026-05-28T19:49:27.000+05:30
- ENH: added code architecture a new class called body

- ENH: added code architecture a new class called mission aimed at deployable and stage implementation

- ENH: added code architecture for flight branch class for multistage integration class to simulation
diff --git a/rocketpy/body/__init__.py b/rocketpy/body/__init__.py
@@ -0,0 +1,7 @@
+"""rocketpy.body – body abstraction layer for multistage simulation."""
+
+from rocketpy.body.body_like import BodyLike
+from rocketpy.body.flying_body import FlightBody
+from rocketpy.body.rocket_adapter import RocketAdapter
+
+__all__ = ["BodyLike", "FlyingBody", "RocketAdapter"]
diff --git a/rocketpy/body/body_like.py b/rocketpy/body/body_like.py
@@ -0,0 +1,23 @@
+"""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.
+    """
diff --git a/rocketpy/body/flying_body.py b/rocketpy/body/flying_body.py
@@ -0,0 +1,16 @@
+"""FlyingBody – a first-class, fully configurable flight body."""
+
+from copy import deepcopy
+
+
+class FlyingBody:
+    """A fully configurable flight body composed of interchangeable models.
+
+    Unlike :class:`~rocketpy.rocket.Rocket`, which is a rich user-facing
+    builder object, :class:`FlyingBody` is designed as a clean value object
+    that holds just enough information for the simulation engine to integrate
+    the equations of motion.  Users who need the full Rocket builder
+    experience can convert a :class:`~rocketpy.rocket.Rocket` to a
+    :class:`FlyingBody` via :class:`RocketAdapter`.  It satisfies the
+    :class:`~rocketpy.body.BodyLike` protocol.
+    """
diff --git a/rocketpy/body/rocket_adapter.py b/rocketpy/body/rocket_adapter.py
@@ -0,0 +1,34 @@
+"""RocketAdapter – wraps a legacy :class:`Rocket` as a :class:`BodyLike`.
+
+This module provides a minimal adapter to allow legacy ``Rocket``
+instances to be consumed by code expecting a ``BodyLike`` interface.
+"""
+
+from copy import deepcopy
+
+
+class RocketAdapter:
+    """Adapts a legacy :class:`~rocketpy.rocket.Rocket` to the
+    :class:`BodyLike` interface.
+
+    This allows the existing :class:`~rocketpy.rocket.Rocket` builder to be
+    consumed by the new multistage simulation infrastructure without any
+    changes to the ``Rocket`` class itself.
+
+    Parameters
+    ----------
+    rocket : :class:`~rocketpy.rocket.Rocket`
+        The rocket instance to adapt.
+
+    Attributes
+    ----------
+    rocket : :class:`~rocketpy.rocket.Rocket`
+        The wrapped rocket instance.
+    """
+
+    def __init__(self, rocket):
+        # store a deep copy to avoid accidental mutation of the original
+        self.rocket = deepcopy(rocket)
+
+    def __repr__(self):
+        return f"<RocketAdapter rocket={getattr(self.rocket, 'name', None)!r}>\n"
diff --git a/rocketpy/mission/__initi__.py b/rocketpy/mission/__initi__.py
@@ -0,0 +1,28 @@
+"""rocketpy.mission – mission architecture for multistage rockets."""
+
+from rocketpy.mission.attached_item import AttachedItem
+from rocketpy.mission.attachment import Attachment
+from rocketpy.mission.deployable import Deployable
+from rocketpy.mission.mission import Mission
+from rocketpy.mission.mission_executor import MissionExecutionResult, MissionExecutor
+from rocketpy.mission.parent_update import NoOpParentUpdate, ParentUpdate
+from rocketpy.mission.separation_model import InstantaneousSeparation, SeparationModel
+from rocketpy.mission.stage import Stage
+from rocketpy.mission.stage_state import StageState
+
+__all__ = [
+    "AttachedItem",
+    "Attachment",
+    "Deployable",
+    "InstantaneousSeparation",
+    "Mission",
+    "MissionExecutionResult",
+    "MissionExecutor",
+    "NoOpParentUpdate",
+    "ParentUpdate",
+    "RecoveryEvent",
+    "SeparationModel",
+    "Stage",
+    "StageSeparationEvent",
+    "StageState",
+]
diff --git a/rocketpy/mission/attached_item.py b/rocketpy/mission/attached_item.py
diff --git a/rocketpy/mission/attachment.py b/rocketpy/mission/attachment.py
diff --git a/rocketpy/mission/deployable.py b/rocketpy/mission/deployable.py
@@ -0,0 +1,48 @@
+"""Deployable – a mission item that can be released during flight."""
+
+from rocketpy.mission.attached_item import AttachedItem
+from rocketpy.mission.parent_update import NoOpParentUpdate
+from rocketpy.mission.separation_model import InstantaneousSeparation
+
+
+class Deployable(AttachedItem):
+    """A body that can be deployed (released) from its parent during flight.
+    A :class:`Deployable` is the mission-layer wrapper around a physical
+    body that should be released at some point in flight (e.g. a nose
+    cone, a payload bay, or a secondary vehicle).  It is *not* the physical
+    body itself – that is held in :attr:`body`.
+    Parameters
+    ----------
+    name : str
+        Human-readable identifier (e.g. ``"nose_cone_payload"``).
+    body : :class:`~rocketpy.body.BodyLike`
+        The physical body of the deployable.
+    attachment : :class:`~rocketpy.mission.Attachment`
+        Mechanical link to the parent body.
+    deployment_event : :class:`~rocketpy.mission.DeploymentEvent`
+        The event that triggers this deployable's release.
+    separation : :class:`~rocketpy.mission.SeparationModel`, optional
+        Model for the separation dynamics.  Defaults to
+        :class:`~rocketpy.mission.InstantaneousSeparation`.
+    parent_update : :class:`~rocketpy.mission.ParentUpdate`, optional
+        Callback that modifies the parent body after separation.  Defaults
+        to :class:`~rocketpy.mission.NoOpParentUpdate`.
+    events : list[:class:`~rocketpy.mission.Event`], optional
+        Additional events besides *deployment_event*.
+    Attributes
+    ----------
+    deployment_event : DeploymentEvent
+    separation : SeparationModel
+    parent_update : ParentUpdate
+    """
+
+    def __init__(
+        self,
+        name,
+        body,
+        attachment,
+        deployment_event,
+        separation=None,
+        parent_update=None,
+        events=None,
+    ):
diff --git a/rocketpy/mission/mission.py b/rocketpy/mission/mission.py
diff --git a/rocketpy/mission/mission_executor.py b/rocketpy/mission/mission_executor.py
diff --git a/rocketpy/mission/parent_update.py b/rocketpy/mission/parent_update.py
@@ -0,0 +1,14 @@
+"""ParentUpdate – interface for modifying a parent body after separation."""
+
+from abc import ABC, abstractmethod
+
+
+class ParentUpdate(ABC):
+    """Interface for updating a parent body when a child separates.
+
+    When a :class:`~rocketpy.mission.Deployable` or
+    :class:`~rocketpy.mission.Stage` separates from its parent, the
+    parent body may need to be updated to account for the mass and
+    inertia change caused by the separation.  Concrete implementations
+    of this interface perform that update in place.
+    """
diff --git a/rocketpy/mission/separation_model.py b/rocketpy/mission/separation_model.py
@@ -0,0 +1,18 @@
+"""SeparationModel – interface for child/parent separation dynamics."""
+
+from abc import ABC, abstractmethod
+
+
+class SeparationModel(ABC):
+    """Interface for modelling the separation impulse between two bodies.
+
+    When a :class:`~rocketpy.mission.Deployable` or
+    :class:`~rocketpy.mission.Stage` separates from its parent, a
+    :class:`SeparationModel` is responsible for computing any
+    velocity/orientation perturbations applied to both the parent and
+    child bodies at the instant of separation.
+
+    Implementors should override :meth:`apply` and may store any physical
+    parameters (e.g. spring constant, separation charge energy) as
+    instance attributes.
+    """
diff --git a/rocketpy/mission/stage.py b/rocketpy/mission/stage.py
@@ -0,0 +1,64 @@
+"""Stage – a mission item representing a rocket stage."""
+
+from rocketpy.mission.attached_item import AttachedItem
+from rocketpy.mission.parent_update import NoOpParentUpdate
+from rocketpy.mission.separation_model import InstantaneousSeparation
+from rocketpy.mission.stage_state import StageState
+
+
+class Stage(AttachedItem):
+    """A rocket stage that can ignite and/or separate from its parent.
+
+    A :class:`Stage` is the mission-layer wrapper around the physical
+    body of a rocket stage.  It tracks the stage lifecycle via
+    :class:`~rocketpy.mission.StageState` and holds references to the
+    events that govern separation and ignition.
+
+    Separation and ignition are kept as independent concerns: a stage may
+    separate without igniting (e.g. a fairing) or may ignite before
+    separating (hot staging).
+
+    Parameters
+    ----------
+    name : str
+        Human-readable identifier (e.g. ``"second_stage"``).
+    body : :class:`~rocketpy.body.BodyLike`
+        Physical body of the stage.
+    attachment : :class:`~rocketpy.mission.Attachment`
+        Mechanical link to the parent body.
+    separation_event : :class:`~rocketpy.mission.StageSeparationEvent`, optional
+        Event that triggers mechanical separation.  ``None`` if the stage
+        never separates during the simulated mission.
+    ignition_event : :class:`~rocketpy.mission.IgnitionEvent`, optional
+        Event that triggers motor ignition.  ``None`` if the stage is
+        already burning when the simulation starts (i.e. it is the
+        first stage).
+    separation : :class:`~rocketpy.mission.SeparationModel`, optional
+        Separation dynamics model.  Defaults to
+        :class:`~rocketpy.mission.InstantaneousSeparation`.
+    parent_update : :class:`~rocketpy.mission.ParentUpdate`, optional
+        Updates applied to the parent body after separation.  Defaults
+        to :class:`~rocketpy.mission.NoOpParentUpdate`.
+    events : list[:class:`~rocketpy.mission.Event`], optional
+        Additional events besides *separation_event* and *ignition_event*.
+
+    Attributes
+    ----------
+    separation_event : StageSeparationEvent or None
+    ignition_event : IgnitionEvent or None
+    separation : SeparationModel
+    parent_update : ParentUpdate
+    state : StageState
+    """
+
+    def __init__(
+        self,
+        name,
+        body,
+        attachment,
+        separation_event=None,
+        ignition_event=None,
+        separation=None,
+        parent_update=None,
+        events=None,
+    ):
diff --git a/rocketpy/mission/stage_state.py b/rocketpy/mission/stage_state.py
@@ -0,0 +1,33 @@
+"""StageState – lifecycle states for a Stage."""
+
+from enum import Enum, auto
+
+
+class StageState(Enum):
+    """Enumeration of the lifecycle states a :class:`Stage` can occupy.
+
+    Typical lifecycle progressions are:
+
+    - Powered stage: ``ATTACHED → IGNITED → SEPARATED → SPENT``
+    - Unpowered drop stage (e.g. fairing): ``ATTACHED → SEPARATED``
+    - Sustainer (never physically separated): ``ATTACHED → IGNITED → SPENT``
+
+    Attributes
+    ----------
+    ATTACHED :
+        The stage is attached to the parent body and has not yet ignited.
+    IGNITED :
+        The stage motor has ignited but the stage is still mechanically
+        coupled to the parent.
+    SEPARATED :
+        The stage has mechanically separated from the parent and is flying
+        independently.
+    SPENT :
+        The stage motor has burned out.  The stage may still be attached
+        (e.g. coast phase) or may have separated already.
+    """
+
+    ATTACHED = auto()
+    IGNITED = auto()
+    SEPARATED = auto()
+    SPENT = auto()
diff --git a/rocketpy/simulation/flight_branch.py b/rocketpy/simulation/flight_branch.py
@@ -0,0 +1,45 @@
+"""FlightBranch – a single contiguous integration arc in a multistage flight."""
+
+
+class FlightBranch:
+    """Represents one contiguous integration arc in a branching flight tree.
+    When a :class:`~rocketpy.mission.Stage` separates or a
+    :class:`~rocketpy.mission.Deployable` is released, the simulation engine
+    creates one or more new :class:`FlightBranch` objects.  Each branch tracks
+    its own body, initial state, and list of pending events.
+    The branches together form a directed acyclic graph (DAG) rooted at the
+    first-stage branch.  A :class:`~rocketpy.simulation.Flight` object holds
+    the root branch and drives the full simulation.
+    Parameters
+    ----------
+    body : :class:`~rocketpy.body.BodyLike`
+        The flight-ready body for this branch.  A simulation-safe deep copy
+        should be provided (see
+        :meth:`~rocketpy.body.BodyLike.to_branch_ready_copy`).
+    start_state : object
+        Initial state vector (position, velocity, attitude, …) at the
+        start of this branch.
+    start_time : float
+        Simulation time, in seconds, at which this branch begins.
+    parent : :class:`FlightBranch` or None, optional
+        The branch from which this one was spawned.  ``None`` for the root.
+    events : list[:class:`~rocketpy.mission.Event`], optional
+        Events that are pending on this branch.
+    Attributes
+    ----------
+    body : BodyLike
+    parent : FlightBranch or None
+    children : list[FlightBranch]
+    start_state : object
+    start_time : float
+    events : list[Event]
+    """
+
+    def __init__(
+        self,
+        body,
+        start_state=None,
+        start_time: float = 0.0,
+        parent=None,
+        events=None,
+    ):
