`MissionSequence`#

class MissionSequence(name: str)#

Bases: object

Ordered container of consecutive trajectory legs joined at shared nodes.

A MissionSequence partitions a trajectory into legs (numerical propagation arcs) separated by nodes (instantaneous boundary points). Legs are continuous propagation intervals; each leg can use an independent Propagator, ForceModel, reference frame, origin, and StateArray definition — enabling changes of dynamical model, reference body, or estimated parameter set between segments.

Each leg may model finite burns (continuous thrust carried by a FiniteBurn force model inside the leg’s propagator). At a node between two legs an impulsive burn can be applied:

\[\begin{split}\mathbf{x}^+_k = \mathbf{x}^-_k + \begin{bmatrix} \mathbf{0} \\ \Delta\mathbf{v}_k \\ \mathbf{0} \end{bmatrix}\end{split}\]

where \(\Delta\mathbf{v}_k\) is the delta-v vector of node \(k\). Nodes with no burn are pure epoch-boundary markers that enforce continuity and allow the propagator or state definition to change.

Parameters:: name (str) – Human-readable identifier for the mission sequence.

Notes

The first leg must define the complete initial state.
Each leg can carry a different Propagator (and thus a different ForceModel, frame, or origin).
Estimated impulsive burns must be followed by a "dv_man" parameter in the next leg’s StateArray.
Epoch continuity across nodes is enforced automatically.

Examples

import scarabaeus as scb

mission = scb.MissionSequence(name="EMA123")

# Minimal — everything derived from the propagator:
mission.addLeg("Outbound Leg", prop=prop1)
mission.addBurn("Midcourse Correction", dV=dV, prop=prop1)
mission.addLeg("Final Approach", prop=prop2)

# Full explicit — backwards-compatible with old call style:
mission.addLeg(
    name="Outbound Leg",
    period=ArrayWUnits(86400, "s"),
    state_vector=state_vec,
    prop=prop1,
    dt=ArrayWUnits(60, "s"),
)

See also

scarabaeus.Propagator: Numerical propagator used by each leg.
scarabaeus.ScenarioSetup: Executes a MissionSequence leg by leg.
scarabaeus.StateArray: State vector definition for each leg.

Attributes:

dts: List of time step lengths used for integration in each segment.
epochs_vec: List of EpochArray objects defining the timestamps associated with each mission phase.
last_idx: Indices marking the last step of each segment within the overall timeline.
models: List of state models, representing either propagation states or impulsive maneuvers.
name: The name of the mission sequence.
names: List of names corresponding to each sequence segment.
num_steps: Number of integration steps per leg, or None for impulsive burns.
origins: List of origins for each leg in the sequence.
periods: List of time durations for each leg in the sequence, or None for impulsive burns.
primary_body: Primary propagated object for the whole sequence (must be consistent).
props: List of propagator models for each leg in the sequence.
states_n: List of the number of states in each leg, or None for impulsive burns.
types: List of segment types, such as "Leg" or "Impulsive Burn".

Methods

`addBurn`(name, dV, prop)	Adds an impulsive burn to the mission sequence.
`addFinalCoast`([name, period, state_vector, ...])	Append a final coasting leg to the mission sequence.
`addFiniteBurn`(name[, period, state_vector, ...])	Add a finite burn maneuver to the mission sequence.
`addInitialCoast`([name, period, ...])	Prepend an initial coasting leg to the mission sequence.
`addLeg`(name[, period, state_vector, prop, ...])	Adds a propagation leg to the mission sequence.
`addNode`(name, prop)	Adds a zero-duration node to the mission sequence.
`propagate`([map_STM_to_t0, verbose])	Propagate the mission sequence and return the resulting scenario.

addBurn(name: str, dV: ImpulsiveBurn, prop: Propagator) → None#

Adds an impulsive burn to the mission sequence.

Inserts an impulsive burn event, modifying the spacecraft’s velocity instantaneously. The burn is added between two propagation legs, and a corresponding velocity update (dv_man) is introduced in the next leg.

Parameters:

name (str) – The name of the impulsive burn.
dV (ImpulsiveBurn) – The impulsive burn model defining the velocity change.
prop (Propagator) – The propagator responsible for simulating the spacecraft dynamics.

Return type:

None

addFinalCoast(name: str = 'Final coast', period: ArrayWUnits = None, state_vector: StateArray = None, prop: Propagator = None, dt: ArrayWUnits = None, epochs: EpochArray = None) → None#

Append a final coasting leg to the mission sequence.

Can be called after all finite burns have been added.

Parameters:

name (str, optional) – Name of the final coast leg. Defaults to "Final coast".
prop (Propagator, optional) – Propagator for this leg.

addFiniteBurn(name, period: ArrayWUnits = None, state_vector: StateArray = None, prop: Propagator = None, dt: ArrayWUnits = None, epochs: EpochArray = None, initial_node_name: str | None = None, add_terminal_node: bool = False, terminal_node_name: str | None = None) → None#

Add a finite burn maneuver to the mission sequence.

All of period, state_vector, prop, dt, and epochs are optional. The minimum required call is just a name — as long as the propagator carries a state_vector and a tspan:

MS.addFiniteBurn("burn 1", prop=prop_fb)

A boundary node is automatically inserted before the burn unless this is the very first segment in the sequence.

Parameters:

name (str) – Name of this finite burn segment.
period (ArrayWUnits, optional) – Duration of the burn arc. Derived automatically when not given.
state_vector (StateArray, optional) – State schema (position/velocity + burn parameters). Derived from prop.state_vector when not provided.
prop (Propagator, optional) – Propagator for this burn arc.
dt (ArrayWUnits, optional) – Output sampling interval (uniform grid only).
epochs (EpochArray, optional) – Explicit epoch grid. Takes priority over everything else.
initial_node_name (str, optional) – Name for the auto-inserted start node. Auto-generated if None.
add_terminal_node (bool, optional) – Insert a node after the burn arc. Default False.
terminal_node_name (str, optional) – Name for the terminal node. Auto-generated if None.

Return type:

None

addInitialCoast(name: str = 'Initial coast', period: ArrayWUnits = None, state_vector: StateArray = None, prop: Propagator = None, dt: ArrayWUnits = None, epochs: EpochArray = None) → None#

Prepend an initial coasting leg to the mission sequence.

Can be called after finite burns have already been added. The leg is inserted at position 0, before all existing segments.

Parameters:

name (str, optional) – Name of the initial coast leg. Defaults to "Initial coast".
prop (Propagator, optional) – Propagator for this leg.

addLeg(name, period: ArrayWUnits = None, state_vector: StateArray = None, prop: Propagator = None, dt: ArrayWUnits = None, epochs: EpochArray = None) → None#

Adds a propagation leg to the mission sequence.

All of period, state_vector, prop, dt, and epochs are optional. The minimum required call is just a name — as long as the propagator carries a state_vector and a tspan:

MS.addLeg("coast", prop=prop_leg)

Resolution order:

state_vector: explicit arg → prop.state_vector
epoch grid: explicit epochs → period``+``dt uniform grid → prop.tspan
period: derived from whichever epoch source is used.

If the immediately preceding segment is a "Finite Burn", a boundary node is inserted automatically before this leg.

Parameters:

name (str) – The name of the leg.
period (ArrayWUnits, optional) – Duration of the leg. Derived from epochs or prop.tspan when not provided.
state_vector (StateArray, optional) – State schema for this leg. Derived from prop.state_vector when not provided.
prop (Propagator, optional) – Propagator for this leg. Its tspan and state_vector are used as fallbacks when the explicit arguments are absent.
dt (ArrayWUnits, optional) – Output sampling interval (used with period for a uniform grid).
epochs (EpochArray, optional) – Explicit epoch grid. Takes priority over all other epoch sources.

Return type:

None

addNode(name: str, prop: Propagator) → None#

Adds a zero-duration node to the mission sequence.

Inserts an event marker at the current sequence boundary without applying any state discontinuity. This is useful for identifying mission events such as the end of a finite-burn arc, the beginning of an observation arc, or any other boundary that later processing should recognize as a node.

Unlike addBurn(), this method does not modify the spacecraft state and does not introduce an impulsive maneuver parameter in the subsequent leg. The node simply records the boundary epoch as an explicit sequence element.

A _NodeSentinel is stored in the slots that have no meaningful value for a node (periods, models, states_n, dts, num_steps). It is falsy like None was, but carries the node name and epoch so downstream code can inspect it instead of getting an opaque None:

isinstance(ms.models[i], _NodeSentinel)  # True  → node
if ms.models[i]:                          # False → node

Parameters:

name (str) – The name of the node.
prop (Propagator) – The propagator associated with this boundary.

Return type:

None

propagate(map_STM_to_t0: bool = False, verbose: bool = True) → ScenarioSetup#

Propagate the mission sequence and return the resulting scenario.

Creates a ScenarioSetup from this sequence, runs propagation through all legs and burns, and returns the populated scenario object. This is the recommended entry point for propagation — it avoids the need to instantiate ScenarioSetup directly.

Parameters:

map_STM_to_t0 (bool, optional) – If True, the State Transition Matrix is mapped continuously from the initial epoch t0 across all legs, so that the STM at any epoch represents sensitivity to the global initial state. If False (default), the STM is reset to identity at each leg boundary, representing only within-leg sensitivity.
verbose (bool, optional) – When True (default), print segment progress and initial-condition summaries during propagation. Set to False to silence all output.

Returns:

scenario – The propagated scenario, with total_position, total_velocity, total_epochsTDB, segment_positions, segment_velocities, and STM populated and ready for use.

Return type:

ScenarioSetup

Examples

scenario = MS.propagate()
traj = scb.Trajectory("traj.bsp", leg_array=scenario)

scenario = MS.propagate(map_STM_to_t0=True)
scenario = MS.propagate(verbose=False)

property dts: list[ArrayWUnits] | None#: List of time step lengths used for integration in each segment.

property epochs_vec: list[EpochArray]#: List of EpochArray objects defining the timestamps associated with each mission phase.

property last_idx: list[int]#: Indices marking the last step of each segment within the overall timeline.

property models: list[StateArray] | list[ImpulsiveBurn]#: List of state models, representing either propagation states or impulsive maneuvers.

property name: str#: The name of the mission sequence.

property names: list[str]#: List of names corresponding to each sequence segment.

property num_steps: list[int] | None#: Number of integration steps per leg, or None for impulsive burns.

property origins: list[int] | None#: List of origins for each leg in the sequence.

property periods: list[ArrayWUnits] | list[None]#: List of time durations for each leg in the sequence, or None for impulsive burns.

property primary_body: Body | None#: Primary propagated object for the whole sequence (must be consistent).

property props: list[Propagator] | None#: List of propagator models for each leg in the sequence.

property states_n: list[int] | None#: List of the number of states in each leg, or None for impulsive burns.

property types: list[str]#: List of segment types, such as "Leg" or "Impulsive Burn".

MissionSequence#

`MissionSequence`#