ThreeBodyGravity#

class ThreeBodyGravity(origin: CelestialBody, point_masses: List[CelestialBody], base_frame: Frame, t0: float, tf: float, propagated_bodies: List[CelestialBody] | None = None, epoch_buffer: float = 86400.0)#

Bases: DynamicModel

Models third-body gravitational perturbations from one or more point masses.

For each listed point mass, the acceleration follows the standard three-body formulation:

\[\mathbf{a}_{3b} = \mu_i \left( \frac{\mathbf{r}_{\mathrm{body} \to i}}{\|\mathbf{r}_{\mathrm{body} \to i}\|^3} - \frac{\mathbf{r}_{\mathrm{origin} \to i}}{\|\mathbf{r}_{\mathrm{origin} \to i}\|^3} \right)\]

If a third body is propagated in the StateArray (i.e., its position is a dynamic state), its position is taken from current_state rather than from SPICE, enabling full coupled propagation. Each \(\mu_i\) can also be estimated as a solve-for parameter; when the state vector contains a ("gm", spice_id) entry for body \(i\), its value overrides the body default at each function evaluation, for propagated and SPICE bodies alike.

Parameters:
originCelestialBody

Propagation origin: supplies the name and gravitational parameter, and anchors the ephemeris cache.

pnt_masseslist

List of point mass bodies to be used in computing third body accelerations.

propagated_bodieslist of CelestialBody, optional

Third bodies that are integrated in the state vector rather than read from the ephemeris. Their positions are taken from the propagated state, so they are excluded from the SPICE ephemeris cache. The other bodies’ positions are read from the ephemeris cache using their SPICE ID, which can be defined directly by providing direct int entries, or implied by CelestialBody entries. Direct and implied definitions can be mixed within the list.

base_frameFrame

Reference frame in which accelerations are returned.

t0float

Starting epoch of the force model. Assumed in seconds TDB.

tffloat

Final epoch of the force model. Assumed in seconds TDB.

epoch_bufferfloat, optional

Margin added to the start and end epochs to allow an integrator space to step before and after the defined time interval. Defaults to 86400.0, equivalent to one day.

Attributes:
origin_mu

Gravitational parameter of the origin body, in km^3/s^2.

origin_name

Name of the propagation-origin celestial body.

pnt_masses

Ordered list of point-mass body name strings (Constants keys).

ref_frame

Reference frame in which third-body accelerations are returned.

Methods

compute_acceleration(position, ...)

Compute third-body gravitational acceleration.

See also

scarabaeus.PointMassGravity

Single-body Newtonian gravity.

scarabaeus.ForceModelTranslation

Aggregator that instantiates this model.

References

[1]

Vallado, D. A. Fundamentals of Astrodynamics and Applications, 4th Ed., Microcosm Press, 2013.

compute_acceleration(position: ndarray, current_state: dict, epoch: float, body: CelestialBody) → ndarray#

Compute third-body gravitational acceleration.

If a third body is propagated in the state vector, its position is taken from current_state; otherwise from the ephemeris cache.

Autograd can differentiate it with respect to position and the ("gm", spice_id) state entries.

property origin_mu: float#

Gravitational parameter of the origin body, in km^3/s^2.

property origin_name: str#

Name of the propagation-origin celestial body.

property pnt_masses: list[str]#

Ordered list of point-mass body name strings (Constants keys).

property ref_frame: Frame#

Reference frame in which third-body accelerations are returned.

exception NoChebyCoeffsWarning#

Bases: RuntimeWarning

exception NoLoadedSPKError#

Bases: Exception