3. ScenarioSetup

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

Bases: object

Manages the setup and propagation of a mission scenario.

This class is responsible for orchestrating the execution of a mission sequence, ensuring consistency in propagated states, epochs, and dynamical models. It interacts with the propagator to execute trajectory propagation while handling State Transition Matrices (STMs) and maneuver modeling.

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.
STM_old	The last computed State Transition Matrix (STM).
atol	The absolute tolerance for numerical integration.
delta_v	The last computed impulsive delta-v, if applicable.
et_old	The last computed epoch in the mission sequence.
full_state_vector	Retrieve the full state vector array for the scenario.
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 corresponding to the propagated solution.
propagator	The propagator responsible for trajectory calculations.
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.
state_size_old	The size of the last computed state vector.
state_vector_old	The last computed state vector.
total_components	Get the total components dictionary.
total_epochsTDB	Returns the total number of epochs for the TDB (presumably "Trajectory Data Base" or similar) by retrieving the epoch value from the primary "position" data source.
total_parameters	The total set of propagated parameters.
total_position	Returns the primary position value by invoking the _pick_primary method with "position" as the argument.
total_velocity	Calculate and return the total velocity from the primary velocity attribute.

Methods

deviation_history_to_global_dx(...[, ...])	Convert a deviation history list to a global state deviation vector.
merge_state_list_with_old(new_list)	Merge a new state list with the previous state vector, inheriting values from old parameters. This method matches parameters in the new list with those from the previous state vector using a composite key of (parameter name, spice_id, size). For matched parameters, the previous quantity values are inherited; for new parameters, their initial condition values are used. All parameters are wrapped in new ArrayWFrame objects. :param new_list: A list of tuples, each containing: - cname (str): Parameter name - csize: Parameter size - cest: Parameter estimate - cdyn: Parameter dynamics - cbody: Body object (may have spice_id attribute) - cawf (ArrayWFrame): Parameter with quantity and frame information :type new_list: list.
propagate()	Executes the propagation of the mission sequence through all defined legs and impulsive burns.
reinitialize_scenario_state_def(new_state_def, *)	Reinitialize the scenario state definition and propagate changes throughout the mission sequence. This method performs a comprehensive state schema migration that: 1. Snapshots the current global state vector 2. Installs the new state definition and associated index mapping 3. Projects values from the old global state to the new one, preserving overlapping keys 4. Optionally refills new state variables from the first model that provides them 5. Updates all StateArray models with new values from the global state vector 6. Reinitializes ImpulsiveBurn models from their corresponding DV parameter blocks 7. Resets cached state tracking variables (STM, state vector, state size) :param new_state_def: The new state definition schema to install. Contains all state variable specifications. :type new_state_def: StateDefinition :param refill_from_models: If True, fill new state variables (not present in the old state) from initial model state values. The first model in the mission sequence that contains a matching state variable will seed the value. Default is True. :type refill_from_models: bool, optional :param update_models: If True, propagate the updated global state values back into all StateArray model instances in the mission sequence. Default is True. :type update_models: bool, optional :param update_states_n: If True, update the states_n tracking array with the new state dimensions for each rebuilt model. Default is False. :type update_states_n: bool, optional.
update_stm(new_list)	Updates the State Transition Matrix (STM) to match a new state vector layout.

reinitialize_from_deviation_global

deviation_history_to_global_dx(deviation_history: list, *, as_column: bool = True, strict: bool = True) → ndarray

Convert a deviation history list to a global state deviation vector.

This method maps per-segment (Leg/Finite Burn) deviation vectors from a deviation_history list to their corresponding positions in the global scenario state vector.

Parameters:

• deviation_history (list) – A list of deviation vectors, one per active segment (Leg or Finite Burn). Each entry should be array-like and will be converted to a 1D numpy array. Length must equal the number of active segments in the mission sequence.

• as_column (bool, optional) – If True (default), return the global deviation vector as a column vector with shape (N_global, 1). If False, return as a 1D array with shape (N_global,).

• strict (bool, optional) – If True (default), enforce strict size matching. Raises ValueError if any deviation entry does not match its expected local dimension or is too short. If False, truncates or pads vectors as needed without raising errors.

Returns:

Global state deviation vector of shape (N_global, 1) if as_column=True, or (N_global,) if as_column=False, where N_global is the total dimension of the global scenario state.

Return type:

np.ndarray

Raises:

• ValueError – If length of deviation_history does not match the number of active segments. If strict=True and any deviation entry has mismatched dimensions.

• KeyError – If a leg component key is not found in the scenario-global index map, indicating the scenario union state_def is incomplete.

Notes

• Only “Leg” and “Finite Burn” segments are considered active.

• The scenario index map is built on-demand if not already present.

• Leg-to-global mappings are cached in _leg_to_global_maps for reuse.

merge_state_list_with_old(new_list: list) → list

Merge a new state list with the previous state vector, inheriting values from old parameters. This method matches parameters in the new list with those from the previous state vector using a composite key of (parameter name, spice_id, size). For matched parameters, the previous quantity values are inherited; for new parameters, their initial condition values are used. All parameters are wrapped in new ArrayWFrame objects. :param new_list: A list of tuples, each containing:

• cname (str): Parameter name

• csize: Parameter size

• cest: Parameter estimate

• cdyn: Parameter dynamics

• cbody: Body object (may have spice_id attribute)

• cawf (ArrayWFrame): Parameter with quantity and frame information

Returns:

A list of updated tuples with the same structure as new_list, where each

tuple contains (cname, csize, cest, cdyn, cbody, new_awf) with new_awf containing inherited or initial quantity values.

Return type:

list

propagate() → 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)

reinitialize_from_deviation_global(deviation_global: list, *, commit: bool = True, relative_to_ref: bool = True) → None

reinitialize_scenario_state_def(new_state_def: StateDefinition, *, refill_from_models: bool = True, update_models: bool = True, update_states_n: bool = False) → None

Reinitialize the scenario state definition and propagate changes throughout the mission sequence. This method performs a comprehensive state schema migration that: 1. Snapshots the current global state vector 2. Installs the new state definition and associated index mapping 3. Projects values from the old global state to the new one, preserving overlapping keys 4. Optionally refills new state variables from the first model that provides them 5. Updates all StateArray models with new values from the global state vector 6. Reinitializes ImpulsiveBurn models from their corresponding DV parameter blocks 7. Resets cached state tracking variables (STM, state vector, state size) :param new_state_def: The new state definition schema to install. Contains all state variable specifications. :type new_state_def: StateDefinition :param refill_from_models: If True, fill new state variables (not present in the old state) from initial model

state values. The first model in the mission sequence that contains a matching state variable will seed the value. Default is True.

Parameters:

• update_models (bool, optional) – If True, propagate the updated global state values back into all StateArray model instances in the mission sequence. Default is True.

• update_states_n (bool, optional) – If True, update the states_n tracking array with the new state dimensions for each rebuilt model. Default is False.

Return type:

None

Notes

• State key matching is based on (name, size, spice_id, frame_name, occurrence_index)

• Only overlapping state variables are copied from old to new; missing variables either remain zero-initialized or are filled from models if refill_from_models is True.

• ImpulsiveBurn models are matched to DV parameters by their burn occurrence order.

• The method assumes DV parameters follow the naming convention “dv_man”, “dv_man1”, etc.

• Cached fields (_state_vector_old, _state_size_old, _STM_old, _delta_v) are reset.

update_stm(new_list: list)

Updates the State Transition Matrix (STM) to match a new state vector layout.

This method constructs a new STM matrix based on the provided new_list layout, copying matching blocks and cross-partials from the previous STM if available. It also handles injection of maneuver delta-v blocks if specified.

Parameters:

• new_list (list) – The new state vector layout, where each element is a tuple containing (name, size, …, body, …). The layout determines the block structure of the STM.

• np.ndarray – The updated STM matrix, sized according to the new state vector layout.

Raises:

ValueError – If the previous STM matrix (STM_old) is not square.

Notes

• If no previous STM exists or mapping is disabled, returns an identity matrix, with optional delta-v maneuver injection.

• Matching blocks are copied by (name, spice_id) and occurrence index.

• Cross-partials between matching blocks are also copied.

• Delta-v maneuver blocks (“dv_man”, “dv_man1”, “dv_man2”) are injected into corresponding velocity blocks if self.delta_v is set.

property STM: list[ndarray]

The total concatenated STM history.

property STM_old: ndarray

The last computed State Transition Matrix (STM).

property atol: float

The absolute tolerance for numerical integration.

property delta_v: ArrayWUnits | None

The last computed impulsive delta-v, if applicable.

property et_old: EpochArray

The last computed epoch in the mission sequence.

property full_state_vector

Retrieve the full state vector array for the scenario.

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

State array corresponding to the propagated solution.

Base:

Propagator

Type:

np.ndarray

property propagator: Propagator

The propagator responsible for trajectory calculations.

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 state_size_old: int

The size of the last computed state vector.

property state_vector_old: StateArray

The last computed state vector.

property total_components: dict

Get the total components dictionary.

property total_epochsTDB

Returns the total number of epochs for the TDB (presumably “Trajectory Data Base” or similar) by retrieving the epoch value from the primary “position” data source.

property total_parameters: list[ArrayWUnits]

The total set of propagated parameters.

property total_position

Returns the primary position value by invoking the _pick_primary method with “position” as the argument.

property total_velocity

Calculate and return the total velocity from the primary velocity attribute.