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

Scarabaeus 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=True the 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_vector and base_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; pass 1 to get the solver’s own steps unchanged.

It applies only when tspan is 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_output already requires. The solver’s own step endpoints are reproduced exactly, making the densified grid a superset of the undensified one.

An EpochArray tspan already names every output epoch, and integrator="IAS15" builds no interpolant, so neither can be densified. Leaving n_densifier at its default in those cases simply does nothing; asking for a value explicitly raises Propagator.DensifierGridError or Propagator.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 makes propagate() raise Propagator.IAS15STMError, so pass propagate_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:
As

Dynamic Matrices of the propagated state.

STM

State Transition Matrix array corresponding to the propagated solution.

STM0

The initial State Transition Matrix (STM).

STM_frame

The frame ratios of the State Transition Matrix (STM).

STM_units

The units of the State Transition Matrix (STM).

atol

Absolute tolerance for numerical integration.

backward

Whether the propagation runs backward in time.

base_frame

The base reference frame for propagation.

convert_to_original_frame

Whether propagate() maps the results back to the original frames.

display_progress

Whether propagate() shows a progress bar.

dynamics_mode_list

List of active dynamics modes during propagation.

force_models

Force model used for propagation.

full_state_vector

The state vector associated with the propagation.

full_state_vector_original_frames

The state vector not associated with the propagation, but with the original frames.

integrationEts

Epoch array (TDB seconds) corresponding to each integrator output step.

integrationYs

Raw numerical integration output (states + flattened STM rows).

integrator

The numerical integrator used for propagation.

look_event

The event type for the propagator.

mass_is_variable

Whether the spacecraft mass is modelled as varying.

mass_profile

Mass profile of the spacecraft.

n_densifier

Number of sub-intervals each integration step is resampled into.

primary_body

The primary celestial body for the propagator.

prop_origin

The origin body in the reference frame.

propagate_STM

Indicates whether the State Transition Matrix (STM) is propagated.

propagated_state_array

State array corresponding to the propagated solution.

propagated_state_array_original_frame

The state vector not associated propagated, but with the original frames.

rtol

Relative tolerance for numerical integration.

state

State array corresponding to the propagated solution.

state_frames

The frames of the State.

state_units

The units of the State .

state_vector

The initial state as it was given, in its original frames.

t0

The initial epoch for propagation.

times

Time array corresponding to the propagated solution.

tspan

The time span over which propagation occurs.

tspan_original_frame

The time span over which propagation occurs in the original frame.

ys

Numerical solution of the propagated state.

Methods

from_dict(data)

Reconstruct a Propagator from a dict produced by to_dict().

list_forces()

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

State vector consumed and produced by the propagator.

scarabaeus.ForceModelTranslation

Translational force model aggregator.

scarabaeus.ScenarioSetup

Multi-leg propagation driver that wraps Propagator.

scarabaeus.MissionSequence

Ordered container of legs passed to ScenarioSetup.

Notes

Typical usage sequence:

  1. Construct a StateArray (via StateDefinition).

  2. Construct one or more ForceModel instances (e.g. ForceModelTranslation) configured for the relevant objects.

  3. Pass the model(s) to Propagator, which will bind them to the provided state and frame via initialize_force_models.

  • force_models may 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 single primary_body instance 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 fmt or 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_list order. Entries follow state order.

See also

scarabaeus.ForceModelTranslation.list_forces

The labels of one force model.

scarabaeus.MissionSequence.list_forces

The 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 None is 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" (see Propagator.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 by ScenarioSetup to 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 follows fmt ("json" or "pickle"); when fmt is None it is inferred from the file extension (.pkl or .pickle gives 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_dict method if available; otherwise only their class name is stored.

property As: ndarray#

Dynamic Matrices of the propagated state.

Base:

Propagator

Type:

np.ndarray

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:

float

property backward: bool#

Whether the propagation runs backward in time.

Base:

Propagator

Type:

bool

property base_frame: Frame#

The base reference frame for propagation.

Base:

Propagator

Type:

str

property convert_to_original_frame: bool#

Whether propagate() maps the results back to the original frames. Settable.

Base:

Propagator

Type:

bool

property display_progress: bool#

Whether propagate() shows a progress bar. Settable.

Base:

Propagator

Type:

bool

property dynamics_mode_list: list[str]#

List of active dynamics modes during propagation.

Base:

Propagator

Type:

list[str]

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 integrator: str#

The numerical integrator used for propagation.

Base:

Propagator

Type:

str

property look_event: str | None#

The event type for the propagator. Settable; None turns it off.

Base:

Propagator

Type:

str

property mass_is_variable: bool#

Whether the spacecraft mass is modelled as varying. Settable; turning it on requires primary_body to be a Spacecraft.

Base:

Propagator

Type:

bool

property mass_profile: object | None#

Mass profile of the spacecraft.

Base:

Propagator

Type:

SCBPolynomial

property n_densifier: int#

Number of sub-intervals each integration step is resampled into.

Defaults to 10; 1 returns the integrator’s own steps unchanged. Only a (t0, tf) tuple tspan under "DOP853" is densified – an EpochArray tspan 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 prop_origin: Body#

The origin body in the reference frame.

Base:

Propagator

Type:

scb.Body

property propagate_STM: bool#

Indicates whether the State Transition Matrix (STM) is propagated.

Base:

Propagator

Type:

bool

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:

float

property state: ndarray | None#

State array corresponding to the propagated solution.

Base:

Propagator

Type:

np.ndarray

property state_frames: ndarray | None#

The frames of the State.

Base:

Propagator

Type:

np.ndarray

property state_units: ndarray | None#

The units of the State .

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

property ys: ndarray#

Numerical solution of the propagated state.

Base:

Propagator

Type:

np.ndarray

exception DensifierGridError#

Bases: ValueError

Raised when n_densifier > 1 is combined with a tspan that already names every output epoch.

exception DensifierIntegratorError#

Bases: ValueError

Raised when n_densifier > 1 is asked of an integrator that builds no dense output to resample from.

exception DensifierValueError#

Bases: ValueError

Raised when n_densifier is not a whole number of at least 1.

exception IAS15STMError#

Bases: NotImplementedError

Raised when propagate_STM=True is combined with integrator="IAS15", which integrates the state alone.

exception MissingScaleFactorModelError#

Bases: ValueError

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