MissionSequence#

class MissionSequence(name: str, grid_bound_tol: float = 1e-06)#

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:
namestr

Human-readable identifier for the mission sequence.

grid_bound_tolfloat, optional

Tolerance, in TDB seconds, on the bounds of a grid chosen by the integrator (see grid_bound_tol). Defaults to 1e-6.

Attributes:
grid_bound_tolfloat

Tolerance, in TDB seconds, on the bounds of an integrator-chosen grid.

deferred_gridslist of bool

Per-segment flag marking the legs whose output grid is chosen by the integrator rather than declared up front (a (t0, tf) tuple tspan).

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.

adopt_propagated_grid(index, epochs)

Replace a deferred segment's bounds with the grid the integrator used.

carry_static_parameters()

Carry static parameters through the segments that do not declare them.

list_forces()

The forces acting on each integrated object, segment by segment.

propagate([map_STM_to_t0, verbose])

Propagate the mission sequence and return the resulting scenario.

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.

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"),
)
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:
namestr

The name of the impulsive burn.

dVImpulsiveBurn

The impulsive burn model defining the velocity change.

propPropagator

The propagator responsible for simulating the spacecraft dynamics.

Returns:
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:
namestr, optional

Name of the final coast leg. Defaults to "Final coast".

propPropagator, 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 (t0, tf) tuple tspan defers the grid to the integrator, as in addLeg().

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

Parameters:
namestr

Name of this finite burn segment.

periodArrayWUnits, optional

Duration of the burn arc, in any time unit (stored in seconds). Derived automatically when not given.

state_vectorStateArray, optional

State schema (position/velocity + burn parameters). Derived from prop.state_vector when not provided.

propPropagator, optional

Propagator for this burn arc.

dtArrayWUnits, optional

Output sampling interval, in any time unit (uniform grid only).

epochsEpochArray, optional

Explicit epoch grid. Takes priority over everything else.

initial_node_namestr, optional

Name for the auto-inserted start node. Auto-generated if None.

add_terminal_nodebool, optional

Insert a node after the burn arc. Default False.

terminal_node_namestr, optional

Name for the terminal node. Auto-generated if None.

Returns:
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:
namestr, optional

Name of the initial coast leg. Defaults to "Initial coast".

propPropagator, 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, then prop.state_vector

  • epoch grid: explicit epochs, then a uniform period + dt grid, then prop.tspan

  • period: derived from whichever epoch source is used.

When prop.tspan is a (t0, tf) tuple the leg declares no grid of its own: it holds the two bounds, and propagate() adopts the epochs the integrator’s own steps landed on (see adopt_propagated_grid()). Both integrators do this — DOP853 through t_eval=None, IAS15 through its adaptive steps. How fine the resulting grid is, is the error control’s call — on slow dynamics it can be the two bounds alone. A default degree-3 type-13 SPK segment still writes from two nodes, but one cubic then spans the whole leg; give the leg epochs or period + dt when the output density matters.

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

Parameters:
namestr

The name of the leg.

periodArrayWUnits, optional

Duration of the leg, in any time unit (stored in seconds). Derived from epochs or prop.tspan when not provided.

state_vectorStateArray, optional

State schema for this leg. Derived from prop.state_vector when not provided.

propPropagator, optional

Propagator for this leg. Its tspan and state_vector are used as fallbacks when the explicit arguments are absent.

dtArrayWUnits, optional

Output sampling interval, in any time unit (used with period for a uniform grid).

epochsEpochArray, optional

Explicit epoch grid. Takes priority over all other epoch sources.

Returns:
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:
namestr

The name of the node.

propPropagator

The propagator associated with this boundary.

Returns:
None
adopt_propagated_grid(index: int, epochs: EpochArray) → None#

Replace a deferred segment’s bounds with the grid the integrator used.

Called by ScenarioSetup right after a segment whose tspan was a (t0, tf) tuple has been propagated, so that the rest of the framework — SPK writing, measurement mapping, process noise, filter leg boundaries — sees the epochs the states actually sit on. num_steps and last_idx are refreshed to match.

Parameters:
indexint

Index of the segment in the sequence.

epochsEpochArray

Epochs of the propagated states, in ascending order.

Raises:
TimeSpanError

If the propagated grid does not start and end at the segment’s declared bounds, to within grid_bound_tol, which would break epoch continuity with the neighbouring segments.

carry_static_parameters() → list[frozenset]#

Carry static parameters through the segments that do not declare them.

A static parameter declared on two segments with others in between (a thrust group resumed after a coast, a bias observed on alternate arcs) is one parameter of the scenario. Each segment in between gets the parameter added to its state, so its value and covariance flow through that segment instead of being dropped at the first boundary and re-introduced with a fresh a priori at the next one. A carried component is dormant there: the propagator holds it constant and hides it from the force models (Propagator.reinitialize).

Carried estimated components go before the segment’s first considered one, as StateDefinition requires; carried considered components go last. dv_man blocks are never carried: they belong to the impulsive burn in front of the segment declaring them.

The carry is recomputed from the states the segments were declared with, so calling this again is harmless and accounts for segments added in the meantime.

Returns:
list of frozenset

One entry per segment: the (name, spice_id) of its dormant components; empty for segments carrying nothing, nodes, and impulsive burns.

list_forces() → dict#

The forces acting on each integrated object, segment by segment.

Returns:
dict

Maps the name of every propagated segment — legs and finite burns, in sequence order — to that segment’s list_forces(): a dict from the name of each integrated object to the labels of the forces it feels there. Impulsive burns and nodes are instantaneous, so they have no entry.

See also

scarabaeus.Propagator.list_forces

The listing of one segment.

scarabaeus.ForceModelTranslation.list_forces

The labels of one force model.

Examples

>>> seq.list_forces()
{'Cruise': {'Orbiter': ['ThreeBodyGravity(EARTH, JUPITER)', 'PointMassGravity(SUN)']},
 'Approach': {'Orbiter': ['ThreeBodyGravity(EARTH, JUPITER)', 'CannonballSRP', 'PointMassGravity(SUN)']}}
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_t0bool, 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.

verbosebool, optional

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

Returns:
scenarioScenarioSetup

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

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 deferred_grids: list[bool]#

Per-segment flag marking the legs whose output grid is chosen by the integrator rather than declared up front (a (t0, tf) tuple tspan). Until propagate() runs, those segments hold only their two bounds in epochs_vec; the propagated grid replaces them through adopt_propagated_grid().

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 grid_bound_tol: float#

Tolerance, in TDB seconds, on the bounds of an integrator-chosen grid.

adopt_propagated_grid() rejects a propagated grid whose first or last epoch sits further than this from the bounds the segment declared, because that gap or overlap would break epoch continuity with the neighbouring segments. The default of 1e-6 is about a decimal digit above the float64 resolution of an ephemeris epoch, so it absorbs rounding without hiding a grid that genuinely stops short.

Raises:
GridToleranceError

If set to something other than a non-negative real number.

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]#

Duration of each segment, in seconds, for legs and finite burns; None for impulsive burns and a _NodeSentinel for the boundary nodes inserted between consecutive propagated segments.

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".

exception GridToleranceError#

Bases: ValueError

Raised when the tolerance on an integrator-chosen grid is not a non-negative number of seconds.

exception TimeSpanError#

Bases: ValueError

Raised when a segment’s time span does not define an output grid.