`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', 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_body (Spacecraft) – 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_vector (StateArray) – Initial state (position/velocity + parameters) at epoch = state_vector.epoch.
tspan (EpochArray 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_models (ForceModel 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_frame (Frame, optional) – Frame in which dynamics are evaluated. Defaults to J2000 if None.
atol (float, optional) – Absolute/relative tolerances for the numerical integrator.
rtol (float, optional) – Absolute/relative tolerances for the numerical integrator.
integrator (str, optional) – Integration scheme identifier (e.g. "DOP853").
propagate_STM (bool, optional) – If True, propagate the state transition matrix.
STM0 (np.ndarray, optional) – Initial STM. If None, identity is used.
look_event (str, optional) – Placeholder for event handling (WIP).
convert_to_original_frame (bool, optional) – If True, map results back to the original state frame after propagation.
mass_is_variable (bool, optional) – If True, treat mass as a dynamic state (used with thrust models).
display_progress (bool, optional) – If True, displays integration progress bar in the terminal. Defaults to True.
copy_force_models (bool, optional) – If True, creates deep copies of the provided force models to avoid side effects.

Notes

Typical usage sequence:

Construct a StateArray (via StateDefinition).
Construct one or more ForceModel instances (e.g. ForceModelTranslation) configured for the relevant objects.
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.

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.

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.
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_profile: Mass profile of the spacecraft.
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 .
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 instance from a dictionary produced by `to_dict`.
`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.
`to_dict`()	Serialize the Propagator configuration to a dictionary.

classmethod from_dict(data: dict) → Propagator#

Reconstruct a Propagator instance from a dictionary produced by to_dict.

This expects that each serialized force model entry provides enough information (via “class” and “config”) to reconstruct the corresponding ForceModel subclass.

Parameters:: data (dict) – Serialized propagator configuration.
Returns:: A new Propagator instance with reconstructed state, time span, and force models.
Return type:: Propagator

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.

Return type:: None

Reconfigure the propagator with updated inputs and rebuild its internal state.

Any argument left as None is left unchanged.

Parameters:

primary_body (Body, optional) – Updated primary propagated object.
state_vector (StateArray, optional) – Updated initial state. If provided, internal copies and t0 are updated.
tspan (EpochArray, optional) – Updated propagation timespan. Converted to TDB internally if needed.
atol (float, optional) – Updated absolute / relative tolerances.
rtol (float, optional) – Updated absolute / relative tolerances.
integrator (str, optional) – Updated integrator identifier.
propagate_STM (bool, optional) – Whether to propagate the STM.
STM0 (np.ndarray, optional) – Updated initial STM (flattened or matrix); reshaped internally.
look_event (str, optional) – Updated event specification (WIP hook).
base_frame (Frame, optional) – Updated base frame for propagation.
convert_to_original_frame (bool, optional) – Updated flag to map results back to original frame after propagation.
maneuver (Maneuver, optional) – Updated maneuver model; propagated into compatible force models.
force_model (ForceModel 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.

Returns:

The updated propagator instance (for chaining).

Return type:

Propagator

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.

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

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.

Base:: Propagator
Type:: str

property mass_profile: object | None#

Mass profile of the spacecraft.

Base:: Propagator
Type:: SCBPolynomial

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.

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