2. Propagator

class Propagator(main_body: Body, state_vector: StateArray, tspan: EpochArray, third_body: bool = False, cannonball_SRP: bool = False, nPlate_SRP: bool = False, sph_harm: bool = False, sph_harm_info=None, finite_burn: bool = False, impulsive_burn_approx=False, point_masses: list = [], atol: float = 2.220446049250313e-14, rtol: float = 2.220446049250313e-14, integrator: str = 'DOP853', propagate_STM: bool = True, STM0=None, look_event: str = None, base_frame: Frame = None, convert_to_original_frame: bool = False)

Bases: object

Scarabaeus’ interface to propagators.

Supports numerical integration via two different algorithms:

• Scipy’s DOP853 [1]

• PyASA [2]

Using one of these algorithms, integrates the ordinary differential equations (ODEs) that describe the system’s dynamics.

Parameters:

• main_body (Body) – The body to be propagated.

• state_vector (StateArray) – The initial state vector of the body to be propagated.

• tspan (EpochArray) – The timespan over which the propagation should occur.

• third_body (bool, optional) – Indicates whether thirdy body accelerations should be incorporated into the dynamics of the propagation. Defaults to False.

• cannonball_SRP (bool, optional) – Indicates whether SRP accelerations should be incorporated into the dynamics of the propagation via the cannonball model. Defaults to False.

• nPlate_SRP (bool, optional) – Indicates whether SRP accelerations should be incorporated into the dynamics of the propagation via the N-Plate model. Defaults to False.

• sph_harm (bool, optional) – Indicates whether accelerations due to spherical harmonics should be incorporated into the dynamics of the propagation. Defaults to False.

• sph_harm_info (dict optional) – Necessary information to define spherical harmonics. Defaults to None.

• finite_burn (bool, optional) – Indicates whether accelerations due to a finite burn or multiple finite burns should be incorporated into the dynamics of the propagation. Defaults to False.

• impulsive_burn_approx (bool, optional) – Defaults to False.

• point_masses (list[str], optional) – List of all point masses to be included in the dynamics of the propagation. Unused if third_body is set to False. Defaults to [].

• atol (float, optional) – The absolute tolerance of the propagator. Defaults to 2.220446049250313e-14.

• rtol (float, optional) – The relative tolerance of the propagator. Defaults to 2.220446049250313e-14.

• integrator (str, optional) –

  The integrator to be used in the propagation. Can select from:

  • 'PyASA' - WORK IN PROGRESS

  • 'DOP853' - the current supported numerical integrator.

  Defaults to 'DOP853'.

• propagate_STM (bool, optional) – Indicates if the initial STM should be propagated. Defaults to True.

• STM0 (numpy.ndarray, optional) – Initial State Transition Matrix. Defaults to None.

• look_event (str, optional) – WORK IN PROGRESS. Defaults to None.

• base_frame (Frame, optional) – DESC. If base_frame = None, defaults to the J2000 frame.

See also

scarabaeus.ForceModel, scarabaeus.CannonballSRP, scarabaeus.nPlateSRP, scarabaeus.SphericalHarmonicsGravity, sccarabaeus.ThreeBodyGravity

Notes

References

[1]

https://docs.scipy.org/doc/scipy/reference/generated/scipy.integrate.DOP853.html

[2]

https://www.researchgate.net/publication/265787854_IAS15_A_fast_adaptive_high-order_integrator_for_gravitational_dynamics_accurate_to_machine_precision_over_a_billion_orbits

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.
base_frame	The base reference frame for propagation.
dynamics_mode_list	List of active dynamics modes during propagation.
finite_burn	Indicates whether finite burns are considered.
force_model	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.
impulsive_burn	Indicates whether impulsive burns are included.
impulsive_burn_approx	Indicates whether impulsive burns are approximated.
integrator	The numerical integrator used for propagation.
look_event	The event type for the propagator.
main_body	The primary celestial body for the propagator.
origin	The origin body in the reference frame.
point_masses	List of point masses for third-body gravitational effects.
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.
reduced_state_vector	The state vector associated with the propagation.
rtol	Relative tolerance for numerical integration.
sph_harm_info	Spherical harmonics information for gravity modeling.
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

convert_to_original_frames(propagated_state)	Converts the propagated state back to the original frames.
from_dict(data)	Creates a Propagator instance from a dictionary.
ode(epoch, Y, reduced_indices_map, ...)	Compute the time derivative of the state and the Jacobian (STM derivative) for integration by the propagator.
precompute_indices()	Precompute and return indices for position, reduced state, and full state vectors.
propagate()	Propagates the state of the system using numerical integration.
reinitialize([main_body, state_vector, ...])	Reinitializes the Propagator object with new or updated attribute values.
to_dict()	Returns all attributes of the Propagator class as a dictionary.

classmethod from_dict(data: dict) → Propagator

Creates a Propagator instance from a dictionary.

Parameters:

data (dict) – A dictionary representation of a Propagator instance.

Returns:

A new instance of the Propagator class.

Return type:

Propagator

convert_to_original_frames(propagated_state)

Converts the propagated state back to the original frames.

Parameters:

propagated_state (StateArray) – The state array after propagation in the base frame.

Returns:

A new state array with components converted back to their original frames.

Return type:

StateArray

ode(epoch: float, Y: array, reduced_indices_map, reduced_indices_dot_map, indices_map, indices_dot_map)

Compute the time derivative of the state and the Jacobian (STM derivative) for integration by the propagator.

Parameters:

• epoch – Current epoch (float)

• Y – Concatenated state vector and STM (np.array)

Returns:

Time derivative of state and Jacobian to be integrated (np.array)

precompute_indices()

Precompute and return indices for position, reduced state, and full state vectors.

Returns:

A tuple of dictionaries containing precomputed indices.

propagate()

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

Raises:

None –

reinitialize(main_body: Body = None, state_vector: scbt.StateArray = None, tspan: EpochArray = None, third_body: bool = None, cannonball_SRP: bool = None, nPlate_SRP: bool = None, sph_harm: bool = None, sph_harm_info: dict = None, finite_burn: bool = None, impulsive_burn_approx: bool = None, point_masses: list[str] = None, atol: float = None, rtol: float = None, integrator: str = None, propagate_STM: bool = None, STM0: ndarray = None, look_event: str = None, base_frame: Frame = None, convert_to_original_frame: bool = None) → Propagator

Reinitializes the Propagator object with new or updated attribute values.

Parameters:

• main_body (scb.Body, optional) – The primary celestial body for the propagator.

• state_vector (scbt.StateArray, optional) – Updated state vector.

• tspan (scb.EpochArray, optional) – Updated time span for propagation.

• third_body (bool, optional) – Flag for third-body effects.

• cannonball_SRP (bool, optional) – Flag for cannonball SRP model.

• nPlate_SRP (bool, optional) – Flag for n-Plate SRP model.

• sph_harm (bool, optional) – Flag for spherical harmonics gravity model.

• sph_harm_info (dict, optional) – Updated spherical harmonics information.

• finite_burn (bool, optional) – Flag for finite-burn thrust modeling.

• point_masses (list[str], optional) – Updated point masses for third-body effects.

• atol (float, optional) – Absolute tolerance for integration.

• rtol (float, optional) – Relative tolerance for integration.

• integrator (str, optional) – Integrator type (e.g., ‘DOP853’ or ‘PyASA’).

• propagate_STM (bool, optional) – Flag for propagating STM.

• STM0 (np.ndarray, optional) – Updated initial State Transition Matrix.

• look_event (str, optional) – Event type for the propagator.

• base_frame (str, optional) – Base reference frame for propagation.

Returns:

A new instance of the Propagator class with updated attributes.

Return type:

Propagator

to_dict() → dict

Returns all attributes of the Propagator class as a dictionary.

Returns:

A dictionary representation of the Propagator instance.

Return type:

dict

property As

Dynamic Matrices of the propagated state.

Base:

Propagator

Type:

np.ndarray

property STM

State Transition Matrix array corresponding to the propagated solution.

Base:

Propagator

Type:

np.ndarray

property STM0

The initial State Transition Matrix (STM).

Base:

Propagator

Type:

np.ndarray

property STM_frame

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

Base:

Propagator

Type:

np.ndarray

property STM_units

The units of the State Transition Matrix (STM).

Base:

Propagator

Type:

np.ndarray

property atol

Absolute tolerance for numerical integration.

Base:

Propagator

Type:

float

property base_frame

The base reference frame for propagation.

Base:

Propagator

Type:

str

property dynamics_mode_list

List of active dynamics modes during propagation.

Base:

Propagator

Type:

list[str]

property finite_burn

Indicates whether finite burns are considered.

Base:

Propagator

Type:

bool

property force_model

Force model used for propagation.

Base:

Propagator

Type:

scb.ForceModel

property full_state_vector

The state vector associated with the propagation.

Base:

Propagator

Type:

scbt.StateArray

property full_state_vector_original_frames

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

Base:

Propagator

Type:

scbt.StateArray

property impulsive_burn

Indicates whether impulsive burns are included.

Base:

Propagator

Type:

bool

property impulsive_burn_approx

Indicates whether impulsive burns are approximated.

Base:

Propagator

Type:

bool

property integrator

The numerical integrator used for propagation.

Base:

Propagator

Type:

str

property look_event

The event type for the propagator.

Base:

Propagator

Type:

str

property main_body

The primary celestial body for the propagator.

Base:

Propagator

Type:

scb.Body

property origin

The origin body in the reference frame.

Base:

Propagator

Type:

scb.Body

property point_masses

List of point masses for third-body gravitational effects.

Base:

Propagator

Type:

list[str]

property propagate_STM

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

Base:

Propagator

Type:

bool

property propagated_state_array

State array corresponding to the propagated solution.

Base:

Propagator

Type:

np.ndarray

property propagated_state_array_original_frame

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

Base:

Propagator

Type:

scbt.StateArray

property reduced_state_vector

The state vector associated with the propagation.

Base:

Propagator

Type:

scbt.StateArray

property rtol

Relative tolerance for numerical integration.

Base:

Propagator

Type:

float

property sph_harm_info

Spherical harmonics information for gravity modeling.

Base:

Propagator

Type:

dict

property state

State array corresponding to the propagated solution.

Base:

Propagator

Type:

np.ndarray

property state_frames

The frames of the State.

Base:

Propagator

Type:

np.ndarray

property state_units

The units of the State .

Base:

Propagator

Type:

np.ndarray

property t0

The initial epoch for propagation.

Base:

Propagator

Type:

scb.EpochArray

property times

Time array corresponding to the propagated solution.

Base:

Propagator

Type:

np.ndarray

property tspan

The time span over which propagation occurs.

Base:

Propagator

Type:

scb.EpochArray

property tspan_original_frame

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

Base:

Propagator

Type:

scb.EpochArray

property ys

Numerical solution of the propagated state.

Base:

Propagator

Type:

np.ndarray