MissionSequence#
- class MissionSequence(name: str, grid_bound_tol: float = 1e-06)#
Bases:
objectOrdered container of consecutive trajectory legs joined at shared nodes.
A
MissionSequencepartitions a trajectory into legs (numerical propagation arcs) separated by nodes (instantaneous boundary points). Legs are continuous propagation intervals; each leg can use an independentPropagator,ForceModel, reference frame, origin, andStateArraydefinition — enabling changes of dynamical model, reference body, or estimated parameter set between segments.Each leg may model finite burns (continuous thrust carried by a
FiniteBurnforce 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 to1e-6.
- Attributes:
grid_bound_tolfloatTolerance, in TDB seconds, on the bounds of an integrator-chosen grid.
deferred_gridslist of boolPer-segment flag marking the legs whose output grid is chosen by the integrator rather than declared up front (a
(t0, tf)tupletspan).
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 through the segments that do not declare them.
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.PropagatorNumerical propagator used by each leg.
scarabaeus.ScenarioSetupExecutes a MissionSequence leg by leg.
scarabaeus.StateArrayState 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 differentForceModel, frame, or origin).Estimated impulsive burns must be followed by a
"dv_man"parameter in the next leg’sStateArray.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, andepochsare optional. The minimum required call is just aname— as long as the propagator carries astate_vectorand atspan:MS.addFiniteBurn("burn 1", prop=prop_fb)
A
(t0, tf)tupletspandefers the grid to the integrator, as inaddLeg().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_vectorwhen 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, andepochsare optional. The minimum required call is just aname— as long as the propagator carries astate_vectorand atspan:MS.addLeg("coast", prop=prop_leg)
Resolution order:
state_vector: explicit arg, thenprop.state_vectorepoch grid: explicit
epochs, then a uniformperiod+dtgrid, thenprop.tspanperiod: derived from whichever epoch source is used.
When
prop.tspanis a(t0, tf)tuple the leg declares no grid of its own: it holds the two bounds, andpropagate()adopts the epochs the integrator’s own steps landed on (seeadopt_propagated_grid()). Both integrators do this — DOP853 throught_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 legepochsorperiod+dtwhen 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
epochsorprop.tspanwhen not provided.- state_vectorStateArray, optional
State schema for this leg. Derived from
prop.state_vectorwhen not provided.- propPropagator, optional
Propagator for this leg. Its
tspanandstate_vectorare used as fallbacks when the explicit arguments are absent.- dtArrayWUnits, optional
Output sampling interval, in any time unit (used with
periodfor 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
_NodeSentinelis stored in the slots that have no meaningful value for a node (periods,models,states_n,dts,num_steps). It is falsy likeNonewas, but carries the nodenameandepochso downstream code can inspect it instead of getting an opaqueNone: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
ScenarioSetupright after a segment whosetspanwas 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_stepsandlast_idxare 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
StateDefinitionrequires; carried considered components go last.dv_manblocks 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_forcesThe listing of one segment.
scarabaeus.ForceModelTranslation.list_forcesThe 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
ScenarioSetupfrom 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 instantiateScenarioSetupdirectly.- Parameters:
- map_STM_to_t0bool, optional
If
True, the State Transition Matrix is mapped continuously from the initial epocht0across all legs, so that the STM at any epoch represents sensitivity to the global initial state. IfFalse(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 toFalseto silence all output.
- Returns:
- scenarioScenarioSetup
The propagated scenario, with
total_position,total_velocity,total_epochsTDB,segment_positions,segment_velocities, andSTMpopulated 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)tupletspan). Untilpropagate()runs, those segments hold only their two bounds inepochs_vec; the propagated grid replaces them throughadopt_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 of1e-6is 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 num_steps: list[int] | None#
Number of integration steps per leg, or None for impulsive burns.
- property periods: list[ArrayWUnits] | list[None]#
Duration of each segment, in seconds, for legs and finite burns;
Nonefor impulsive burns and a_NodeSentinelfor 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.
- exception GridToleranceError#
Bases:
ValueErrorRaised when the tolerance on an integrator-chosen grid is not a non-negative number of seconds.
- exception TimeSpanError#
Bases:
ValueErrorRaised when a segment’s time span does not define an output grid.