Propagator#
- class Propagator(primary_body: Spacecraft, state_vector: StateArray, tspan: EpochArray | Tuple[EpochArray, EpochArray], force_models: ForceModel | Sequence[ForceModel], base_frame: Frame | None = None, atol: float = 2.220446049250313e-14, rtol: float = 2.220446049250313e-14, integrator: Literal['DOP853', 'IAS15'] = 'DOP853', n_densifier: int | None = None, propagate_STM: bool = True, STM0=None, look_event: str | None = None, convert_to_original_frame: bool = False, mass_is_variable: bool = False, display_progress: bool = True, copy_force_models: bool = True, backward: bool = False)#
Bases:
objectScarabaeus interface to numerical propagation.
This class integrates the equations of motion for a given state \(\mathbf{x}\) over a specified timespan:
\[\begin{split}\dot{\mathbf{x}} = \mathbf{f}(\mathbf{x}, t), \qquad \mathbf{x} = \begin{bmatrix} \mathbf{r} \\ \dot{\mathbf{r}} \\ \mathbf{p} \end{bmatrix}\end{split}\]where \(\mathbf{r}\) is position, \(\dot{\mathbf{r}}\) is velocity, and \(\mathbf{p}\) are dynamic/static parameters. When
propagate_STM=Truethe State Transition Matrix \(\boldsymbol{\Phi}\) is propagated alongside the state via the variational equation:\[\dot{\boldsymbol{\Phi}}(t, t_0) = \mathbf{A}(t)\,\boldsymbol{\Phi}(t, t_0), \qquad \boldsymbol{\Phi}(t_0, t_0) = \mathbf{I}\]where \(\mathbf{A}(t) = \partial\mathbf{f}/\partial\mathbf{x}\) is the Jacobian of the dynamics.
- Parameters:
- primary_bodySpacecraft
Nominal “primary” object associated with the propagated state. Used for convenience and compatibility; individual force models may internally act on different objects or subsets of the state.
- state_vectorStateArray
Initial state (position/velocity + parameters) at
epoch = state_vector.epoch.- tspanEpochArray or tuple of two EpochArrays
Times at which the solution is requested. If given an EpochArray, solution will be computed at each time step. If given a tuple of two EpochArrays, solution will computed at time steps determined by the selected integrator.
- force_modelsForceModel or list[ForceModel]
One or more pre-configured force model instances. Each will be initialized with the given
state_vectorandbase_frame. This argument is required in the current interface.- base_frameFrame, optional
Frame in which dynamics are evaluated. Defaults to J2000 if
None.- atol, rtolfloat, optional
Absolute/relative tolerances for the numerical integrator.
- integratorstr, optional
Integration scheme identifier (e.g.
"DOP853").- n_densifierint, optional
Number of sub-intervals each integration step is resampled into, using the integrator’s dense output. Defaults to
10; pass1to get the solver’s own steps unchanged.It applies only when
tspanis a(t0, tf)tuple, because that is the case in which the output sits on the integrator’s adaptive steps. Those steps grow long where the dynamics are quiet, and an SPK written on them leaves SPICE interpolating across wide gaps. The default puts nine extra epochs inside every step, so the output stays fine where the steps are short and coarse where they are long, without imposing one fixed interval over the whole arc. Note that it therefore returns about ten times as many epochs as the bare steps, which costs memory in the propagated states and STMs and size in any SPK written from them.The extra epochs come from the solver’s interpolant, not from fresh integration: DOP853 carries a dedicated 7th-order dense output, so they cost no additional function evaluations beyond the ones
dense_outputalready requires. The solver’s own step endpoints are reproduced exactly, making the densified grid a superset of the undensified one.An
EpochArraytspan already names every output epoch, andintegrator="IAS15"builds no interpolant, so neither can be densified. Leavingn_densifierat its default in those cases simply does nothing; asking for a value explicitly raisesPropagator.DensifierGridErrororPropagator.DensifierIntegratorError, rather than silently ignoring what was asked for.- propagate_STMbool, optional
If True, propagate the state transition matrix. Not yet supported with
integrator="IAS15", which integrates the state alone: that combination makespropagate()raisePropagator.IAS15STMError, so passpropagate_STM=False.- STM0np.ndarray, optional
Initial STM. If None, identity is used.
- look_eventstr, optional
Placeholder for event handling (WIP).
- convert_to_original_framebool, optional
If True, map results back to the original state frame after propagation.
- mass_is_variablebool, optional
If True, treat mass as a dynamic state (used with thrust models).
- display_progressbool, optional
If True, displays integration progress bar in the terminal. Defaults to
True.- copy_force_modelsbool, optional
If True, creates deep copies of the provided force models to avoid side effects.
- Attributes:
AsDynamic Matrices of the propagated state.
STMState Transition Matrix array corresponding to the propagated solution.
STM0The initial State Transition Matrix (STM).
STM_frameThe frame ratios of the State Transition Matrix (STM).
STM_unitsThe units of the State Transition Matrix (STM).
atolAbsolute tolerance for numerical integration.
backwardWhether the propagation runs backward in time.
base_frameThe base reference frame for propagation.
convert_to_original_frameWhether propagate() maps the results back to the original frames.
display_progressWhether propagate() shows a progress bar.
dynamics_mode_listList of active dynamics modes during propagation.
force_modelsForce model used for propagation.
full_state_vectorThe state vector associated with the propagation.
full_state_vector_original_framesThe state vector not associated with the propagation, but with the original frames.
integrationEtsEpoch array (TDB seconds) corresponding to each integrator output step.
integrationYsRaw numerical integration output (states + flattened STM rows).
integratorThe numerical integrator used for propagation.
look_eventThe event type for the propagator.
mass_is_variableWhether the spacecraft mass is modelled as varying.
mass_profileMass profile of the spacecraft.
n_densifierNumber of sub-intervals each integration step is resampled into.
primary_bodyThe primary celestial body for the propagator.
prop_originThe origin body in the reference frame.
propagate_STMIndicates whether the State Transition Matrix (STM) is propagated.
propagated_state_arrayState array corresponding to the propagated solution.
propagated_state_array_original_frameThe state vector not associated propagated, but with the original frames.
rtolRelative tolerance for numerical integration.
stateState array corresponding to the propagated solution.
state_framesThe frames of the State.
state_unitsThe units of the State .
state_vectorThe initial state as it was given, in its original frames.
t0The initial epoch for propagation.
timesTime array corresponding to the propagated solution.
tspanThe time span over which propagation occurs.
tspan_original_frameThe time span over which propagation occurs in the original frame.
ysNumerical solution of the propagated state.
Methods
from_dict(data)Reconstruct a Propagator from a dict produced by
to_dict().The forces acting on each integrated object, as readable labels.
load(filepath[, fmt])Reconstruct a Propagator from a file written by
save().ode(epoch, Y)Compute the time derivative of the state and STM for numerical integration.
propagate([display_progress])Propagates the state of the system using numerical integration.
reinitialize([primary_body, state_vector, ...])Reconfigure the propagator with updated inputs and rebuild its internal state.
save(filepath[, fmt])Save this Propagator's reproducible configuration to a JSON or pickle file.
to_dict()Serialize the Propagator configuration to a dictionary.
See also
scarabaeus.StateArrayState vector consumed and produced by the propagator.
scarabaeus.ForceModelTranslationTranslational force model aggregator.
scarabaeus.ScenarioSetupMulti-leg propagation driver that wraps Propagator.
scarabaeus.MissionSequenceOrdered container of legs passed to ScenarioSetup.
Notes
Typical usage sequence:
Construct a
StateArray(viaStateDefinition).Construct one or more
ForceModelinstances (e.g.ForceModelTranslation) configured for the relevant objects.Pass the model(s) to
Propagator, which will bind them to the provided state and frame viainitialize_force_models.
force_modelsmay be a single instance or a list, enabling multi-object or multi-model configurations.Each provided force model must implement:
initialize_force_models(state_vector, base_frame, t0)dynamics_mode_list(property)the appropriate acceleration/partial APIs used by the propagator.
- classmethod from_dict(data: dict) Propagator#
Reconstruct a Propagator from a dict produced by
to_dict().The reconstructed Propagator reproduces the original setup: rebuilding it and calling
propagate()yields the same propagated states. The singleprimary_bodyinstance is reused as the owner of the matching state components so the spacecraft is not duplicated.- Parameters:
- datadict
Serialized propagator configuration.
- classmethod load(filepath, fmt: str = None) Propagator#
Reconstruct a Propagator from a file written by
save().Reads JSON or pickle; the format follows
fmtor is inferred from the file extension.
- list_forces() dict#
The forces acting on each integrated object, as readable labels.
- Returns:
- dict
Maps the name of every object whose position is integrated — the spacecraft and any celestial body propagated alongside it — to the labels of the forces its force model applies, in that model’s
dynamics_mode_listorder. Entries follow state order.
See also
scarabaeus.ForceModelTranslation.list_forcesThe labels of one force model.
scarabaeus.MissionSequence.list_forcesThe same listing, leg by leg.
Notes
The labels are those of
list_forces()on the bound force models, so they reflect what acts during propagation rather than what was configured: the origin’s point-mass term reinstated next to a non-central harmonics field, the integrated bodies added to the third-body term, a harmonics truncation clamped by its file.Examples
>>> prop.list_forces() {'ORCCA': ['ThreeBodyGravity(SUN, MOON)', 'CannonballSRP', 'PointMassGravity(EARTH)'], 'Moon': ['ThreeBodyGravity(SUN)', 'PointMassGravity(EARTH)']}
- ode(epoch: float, Y: ndarray) ndarray#
Compute the time derivative of the state and STM for numerical integration.
Y layout: [y_reduced, vec(Phi_full)]. All static loop structure is precomputed in _precompute_ode_cache().
- propagate(display_progress: bool | None = None) None#
Propagates the state of the system using numerical integration.
This method integrates the ordinary differential equations (ODEs) that describe the system’s dynamics using the specified integration method. The integration is performed over the time span defined by the initial and final times of the system’s time vector.
- Returns:
- None
- reinitialize(primary_body: Body | None = None, state_vector: StateArray | None = None, tspan: EpochArray | None = None, atol: float | None = None, rtol: float | None = None, integrator: str | None = None, n_densifier: int | None = None, propagate_STM: bool | None = None, STM0: ndarray | None = None, look_event: str | None = None, base_frame: Frame | None = None, convert_to_original_frame: bool | None = None, maneuver: Maneuver = None, force_models: ForceModel | Sequence[ForceModel] | None = None, backward: bool | None = None, dormant_parameters: Iterable[tuple[str, int]] | None = None) Propagator#
Reconfigure the propagator with updated inputs and rebuild its internal state.
Any argument left as
Noneis left unchanged.- Parameters:
- primary_bodyBody, optional
Updated primary propagated object.
- state_vectorStateArray, optional
Updated initial state. If provided, internal copies and t0 are updated.
- tspanEpochArray, optional
Updated propagation timespan. Converted to TDB internally if needed.
- atol, rtolfloat, optional
Updated absolute / relative tolerances.
- integratorstr, optional
Updated integrator identifier.
- n_densifierint, optional
Updated number of sub-intervals per integration step.
- propagate_STMbool, optional
Whether to propagate the STM. Not yet supported with
integrator="IAS15"(seePropagator.IAS15STMError).- STM0np.ndarray, optional
Updated initial STM (flattened or matrix); reshaped internally.
- look_eventstr, optional
Updated event specification (WIP hook).
- base_frameFrame, optional
Updated base frame for propagation.
- convert_to_original_framebool, optional
Updated flag to map results back to original frame after propagation.
- maneuverManeuver, optional
Updated maneuver model; propagated into compatible force models.
- force_modelForceModel or sequence of ForceModel, optional
Replace the current force model set with the provided one(s). Each will be re-initialized against the (possibly updated) state.
- backwardbool, optional
Whether to integrate backward in time.
- dormant_parametersiterable of (str, int), optional
(name, spice_id)of static state components carried through this arc without acting on it. They keep their value and an identity STM block, and the force models never see them. Used byScenarioSetupto keep one parameter across the arcs that do not model it (e.g. a thrust group resumed after a coast). An empty iterable clears the set.
- Returns:
- Propagator
The updated propagator instance (for chaining).
- save(filepath, fmt: str = None) Path#
Save this Propagator’s reproducible configuration to a JSON or pickle file.
The file can be reloaded with
load()to reconstruct an equivalent Propagator. The on-disk format followsfmt("json"or"pickle"); whenfmtisNoneit is inferred from the file extension (.pklor.picklegives pickle, otherwise JSON). Returns the resolved path.
- to_dict() dict#
Serialize the Propagator configuration to a dictionary.
Notes
The state and tspan are stored in their original frames as provided at construction time.
All attached force models are serialized via their own
to_dictmethod if available; otherwise only their class name is stored.
- property STM: ArrayWFrame | None#
State Transition Matrix array corresponding to the propagated solution.
- Base:
Propagator
- Type:
np.ndarray
- property STM0: ndarray#
The initial State Transition Matrix (STM).
- Base:
Propagator
- Type:
np.ndarray
- property STM_frame: ndarray | None#
The frame ratios of the State Transition Matrix (STM).
- Base:
Propagator
- Type:
np.ndarray
- property STM_units: ndarray | None#
The units of the State Transition Matrix (STM).
- Base:
Propagator
- Type:
np.ndarray
- property atol: float#
Absolute tolerance for numerical integration. Settable.
- Base:
Propagator
- Type:
- property convert_to_original_frame: bool#
Whether propagate() maps the results back to the original frames. Settable.
- Base:
Propagator
- Type:
- property display_progress: bool#
Whether propagate() shows a progress bar. Settable.
- Base:
Propagator
- Type:
- property force_models: list[ForceModel]#
Force model used for propagation.
- Base:
Propagator
- Type:
scb.ForceModel
- property full_state_vector: StateArray#
The state vector associated with the propagation.
Setting it is the same as setting
state_vector.- Base:
Propagator
- Type:
scb.StateArray
- property full_state_vector_original_frames: StateArray#
The state vector not associated with the propagation, but with the original frames.
- Base:
Propagator
- Type:
scb.StateArray
- property integrationEts: ndarray | None#
Epoch array (TDB seconds) corresponding to each integrator output step.
- property integrationYs: ndarray | None#
Raw numerical integration output (states + flattened STM rows).
- property look_event: str | None#
The event type for the propagator. Settable;
Noneturns it off.- Base:
Propagator
- Type:
- property mass_is_variable: bool#
Whether the spacecraft mass is modelled as varying. Settable; turning it on requires
primary_bodyto be a Spacecraft.- Base:
Propagator
- Type:
- property n_densifier: int#
Number of sub-intervals each integration step is resampled into.
Defaults to
10;1returns the integrator’s own steps unchanged. Only a(t0, tf)tuple tspan under"DOP853"is densified – anEpochArraytspan and"IAS15"have no solver-chosen grid or no interpolant to refine, and the default is a no-op there.
- property primary_body: Spacecraft#
The primary celestial body for the propagator.
- Base:
Propagator
- Type:
scb.Body
- property propagate_STM: bool#
Indicates whether the State Transition Matrix (STM) is propagated.
- Base:
Propagator
- Type:
- property propagated_state_array: StateArray#
State array corresponding to the propagated solution.
- Base:
Propagator
- Type:
np.ndarray
- property propagated_state_array_original_frame: StateArray | list#
The state vector not associated propagated, but with the original frames.
- Base:
Propagator
- Type:
scb.StateArray
- property rtol: float#
Relative tolerance for numerical integration. Settable.
- Base:
Propagator
- Type:
- property state: ndarray | None#
State array corresponding to the propagated solution.
- Base:
Propagator
- Type:
np.ndarray
- property state_vector: StateArray#
The initial state as it was given, in its original frames.
Setting it is shorthand for
reinitialize(state_vector=value): the force models are re-bound and the nextpropagate()starts from the new state. The tspan is left alone, so a state at another epoch needs a matching tspan as well (reinitialize(state_vector=..., tspan=...)does both in one rebuild).- Base:
Propagator
- Type:
scb.StateArray
- property t0: EpochArray#
The initial epoch for propagation.
- Base:
Propagator
- Type:
scb.EpochArray
- property times: ndarray#
Time array corresponding to the propagated solution.
- Base:
Propagator
- Type:
np.ndarray
- property tspan: EpochArray | tuple#
The time span over which propagation occurs.
- Base:
Propagator
- Type:
EpochArray | Tuple[EpochArray, EpochArray]
- property tspan_original_frame: EpochArray#
The time span over which propagation occurs in the original frame.
- Base:
Propagator
- Type:
scb.EpochArray
- exception DensifierGridError#
Bases:
ValueErrorRaised when
n_densifier> 1 is combined with a tspan that already names every output epoch.
- exception DensifierIntegratorError#
Bases:
ValueErrorRaised when
n_densifier> 1 is asked of an integrator that builds no dense output to resample from.
- exception DensifierValueError#
Bases:
ValueErrorRaised when
n_densifieris not a whole number of at least 1.
- exception IAS15STMError#
Bases:
NotImplementedErrorRaised when
propagate_STM=Trueis combined withintegrator="IAS15", which integrates the state alone.
- exception MissingScaleFactorModelError#
Bases:
ValueErrorRaised when the state holds a force-model scale factor (
eta_srp,eta_thermal,eta_antenna) but no force model applies it, so it would be estimated with a zero partial.