7. PointMassGravity#

class PointMassGravity(state_vector: StateArray, base_frame: Frame)#

Bases: DynamicModel

Models the gravitational acceleration due to a point mass source using Keplerian dynamics.

This model assumes a spherically symmetric gravitational field and computes both acceleration and its partial derivatives with respect to position.

Parameters:

  • state_vector (StateArray) – The state vector representing the spacecraft’s state relative to the point mass gravity source. Contains the reference frame, origin body, and dynamic states such as position and velocity.

  • base_frame (Frame) – The frame of the propagator.

See also

scarabaeus.StateArray

Represents state vectors with origin and reference frames.

Notes

The model assumes a Newtonian point mass gravity field with no perturbations.

Acceleration follows the standard Keplerian formulation:

\[a = \frac{-\mu r}{||r||^3}\]

The partial derivative of acceleration with respect to position is derived from the equation of motion and takes the form of a 3x3 matrix:

\[\begin{split}\frac{\partial\mathbf{a}}{\partial \mathbf{r}} = \begin{bmatrix} \frac{\partial a_x}{\partial x} & \frac{\partial a_x}{\partial y} & \frac{\partial a_x}{\partial z} \\ \frac{\partial a_y}{\partial x} & \frac{\partial a_y}{\partial y} & \frac{\partial a_y}{\partial z} \\ \frac{\partial a_z}{\partial x} & \frac{\partial a_z}{\partial y} & \frac{\partial a_z}{\partial z} \end{bmatrix}\end{split}\]

References

  • Vallado, D. A. (2013). Fundamentals of Astrodynamics and Applications, 4th Ed.

  • Montenbruck, O., & Gill, E. (2000). Satellite Orbits: Models, Methods, and Applications.

Attributes

origin_mu

The gravitational parameter of the origin body.

origin_name

The name of the origin body.

ref_frame

The reference frame associated with the input state vector.

Methods

compute_acceleration(position, ...)

Computes the Keplerian acceleration acting on the spacecraft.

compute_partial_by_position(position, ...)

Computes the Jacobian matrix of the Keplerian acceleration with respect to position.
compute_acceleration(position: ArrayWUnits, current_state: dict, epoch: float, body: CelestialBody) → ArrayWUnits#

Computes the Keplerian acceleration acting on the spacecraft.

The acceleration follows the inverse-square law, where the gravitational force exerted by the central body is proportional to the inverse cube of the position vector magnitude.

Parameters:

  • position (ArrayWUnits) – 3x1 vector describing the spacecraft’s position relative to the central body. Expressed in units of kilometers.

  • current_state (dict) – Dictionary containing the current state parameters.

  • epoch (float) – Current simulation epoch in seconds.

  • body (CelestialBody) – The celestial body exerting the gravitational force.

Returns:

acc_vec – 3x1 vector describing the Keplerian acceleration. Expressed in units of \(\frac{km}{s^2}\).

Return type:

ArrayWUnits

compute_partial_by_position(position: ArrayWUnits, current_state: dict, epoch: float, body: CelestialBody) → ArrayWUnits#

Computes the Jacobian matrix of the Keplerian acceleration with respect to position.

This represents the sensitivity of the acceleration vector to changes in the spacecraft’s position, which is useful for state transition modeling in orbit propagation.

Parameters:

  • position (ArrayWUnits) – 3x1 vector describing the spacecraft’s position relative to the central body. Expressed in units of kilometers.

  • current_state (dict) – Dictionary containing the current state parameters.

  • epoch (float) – Current simulation epoch in seconds.

  • body (CelestialBody) – The celestial body exerting the gravitational force.

Returns:

jacobian – The 3x3 partial derivative (Jacobian) of acceleration with respect to position. Expressed in units of \(\frac{1}{s^2}\).

Return type:

ArrayWUnits

property origin_mu: ArrayWUnits#

The gravitational parameter of the origin body. Expressed in units of of \(\frac{km^3}{s^2}\).

property origin_name: str#

The name of the origin body.

property ref_frame: str#

The reference frame associated with the input state vector.