ScenarioSetup

class ScenarioSetup(mission_sequence: MissionSequence, map_STM_to_t0: bool = False)

Bases: object

Executes a MissionSequence leg by leg and assembles the full propagated trajectory.

ScenarioSetup drives the numerical propagation of a MissionSequence: it iterates over every leg and node in order, propagates each leg with its own Propagator (which may carry a different force model, reference frame, or origin than adjacent legs), applies any impulsive burn at node boundaries, and concatenates the per-leg outputs into a unified state and STM history.

For a sequence of \(L\) legs each leg \(\ell\) produces a local STM \(\boldsymbol{\Phi}_\ell(t_\ell^f, t_\ell^0)\). When map_STM_to_t0=True the STM is accumulated across nodes:

\[\boldsymbol{\Phi}(t_L, t_0) = \boldsymbol{\Phi}_L \cdots \boldsymbol{\Phi}_2 \boldsymbol{\Phi}_1\]

so that it always represents sensitivity with respect to the global initial state \(\mathbf{x}(t_0)\). When map_STM_to_t0=False (default) the STM is reset to the identity at each node.

Parameters:

• mission_sequence (MissionSequence) – The mission sequence containing legs, burns, and associated state vectors.

• map_STM_to_t0 (bool, optional) – Whether to map the STM (State Transition Matrix) to the initial state. Defaults to False.

See also

scarabaeus.Propagator

the propagator that ScenarioSetup interacts with.

Notes

The ScenarioSetup class is designed to be compatible with the Propagator class. Any updates to propagation functionality should be reflected here.

Enforces mission constraints such as maximum numbers of legs and impulsive burns.

Attributes:

STM

The total concatenated STM history.

atol

The absolute tolerance for numerical integration.

delta_v

The last computed impulsive delta-v, if applicable.

full_state_vector

Full scenario state vector, spanning the union of all legs.

len_sequence

The total number of elements (legs + burns) in the mission sequence.

map_STM_to_t0

Indicates whether the STM should be mapped to the initial time.

mission_sequence

The mission sequence associated with this scenario.

origin

The origin body for the scenario.

primary_body

The primary body for the scenario.

propagated_state_array

State array covering the full propagated mission (all legs combined).

propagator

Internal propagator for the current segment.

rtol

The relative tolerance for numerical integration.

segment_STMs

Maps segment names to STM arrays.

segment_epochsTDB

Maps segment names to epoch arrays.

segment_parameters

Maps segment names to parameter arrays.

segment_positions

Maps segment names to position arrays.

segment_velocities

Maps segment names to velocity arrays.

total_components

Get the total components dictionary.

total_epochsTDB

Epoch array covering the full propagated mission in TDB seconds.

total_parameters

The total set of propagated parameters.

total_position

Position history of the primary body over the full mission (all legs combined).

total_velocity

Velocity history of the primary body over the full mission (all legs combined).

Methods

propagate([verbose])

Executes the propagation of the mission sequence through all defined legs and impulsive burns.

propagate(verbose: bool = True) → None

Executes the propagation of the mission sequence through all defined legs and impulsive burns.

This version uses a SCENARIO-GLOBAL state vector (union of all components across all legs) as the single source of truth for initial conditions and continuity across segments.

Key behaviors: - For each Leg/Finite Burn:

• build leg->global mapping

• extract leg IC from global vector

• apply any pending impulsive burn to BOTH (global and leg IC) consistently

• propagate

• update global vector from terminal propagated state

• For each Impulsive Burn:

  • snapshot segment outputs

  • store pending dv to be applied at next leg

  • (global velocity is updated at the next leg, using that leg’s velocity key)

Parameters:

verbose (bool, optional) – When True (default), print segment progress and initial-condition summaries to stdout during propagation. Set to False to silence all output.

property STM: list[ndarray]

The total concatenated STM history.

property atol: float

The absolute tolerance for numerical integration.

property delta_v: ArrayWUnits | None

The last computed impulsive delta-v, if applicable.

property full_state_vector: StateArray

Full scenario state vector, spanning the union of all legs.

property len_sequence: int

The total number of elements (legs + burns) in the mission sequence.

property map_STM_to_t0: bool

Indicates whether the STM should be mapped to the initial time. True if the STM is mapped to the initial state, otherwise False.

property mission_sequence: MissionSequence

The mission sequence associated with this scenario.

property origin: Body

The origin body for the scenario.

property primary_body: Body

The primary body for the scenario.

property propagated_state_array: StateArray

State array covering the full propagated mission (all legs combined).

After calling propagate(), this returns a StateArray whose epoch spans from the start of the first leg to the end of the last leg, with the full time-history of position, velocity, and any other dynamic state components accumulated across all legs.

If propagate() has not been called yet, falls back to the last-leg only result with a warning.

property propagator: Propagator

Internal propagator for the current segment. Not intended for external use — its value changes at each segment during propagate().

property rtol: float

The relative tolerance for numerical integration.

property segment_STMs: dict

Maps segment names to STM arrays.

property segment_epochsTDB: dict

Maps segment names to epoch arrays.

property segment_parameters: dict

Maps segment names to parameter arrays.

property segment_positions: dict

Maps segment names to position arrays.

property segment_velocities: dict

Maps segment names to velocity arrays.

property total_components: dict

Get the total components dictionary.

property total_epochsTDB: EpochArray | None

Epoch array covering the full propagated mission in TDB seconds.

property total_parameters: list[ArrayWUnits]

The total set of propagated parameters.

property total_position: ArrayWFrame | None

Position history of the primary body over the full mission (all legs combined).

property total_velocity: ArrayWFrame | None

Velocity history of the primary body over the full mission (all legs combined).