8. SphericalHarmonicsGravity#

class SphericalHarmonicsGravity(sph_harm_order: int, sph_harm_cs_file: str, sph_harm_body, state_vector: StateArray, sph_harm_norm_flag: bool = True, n_degree_max: int = 100, base_frame: Frame = None)#

Bases: DynamicModel

Models the gravitational acceleration due to a body’s non-spherical mass distribution using spherical harmonics.

Computes accelerations and their partial derivatives based on preloaded spherical harmonic coefficients.

Parameters:

  • sph_harm_order (int) – The maximum order of spherical harmonics to use.

  • sph_harm_cs_file (str) – Path to the JSON file containing spherical harmonic coefficients.

  • sph_harm_body (dict) – Dictionary containing body-specific parameters, including: * 'spice_name' (str): The SPICE name of the body. * 'ref_name' (str): The reference frame in which harmonics are computed.

  • state_vector (StateArray) – The state vector of the main spacecraft, containing: * All dynamic and static parameters considered in the simulation (e.g., position, velocity, estimated parameters). * The reference frame in which the state is defined. * The origin body relative to which the state is expressed. * The epoch corresponding to the state.

  • sph_harm_norm_flag (bool, optional) – Flag indicating whether to normalize coefficients. Defaults to True.

  • n_degree_max (int, optional) – Maximum degree for harmonics. Defaults to 100.

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

See also

scarabaeus.StateArray

Represents state vectors with origins and reference frames.

Notes

The spherical harmonic model accounts for deviations from a perfect sphere, ypically used for planetary bodies.

Coefficients can be loaded in normalized or unnormalized form.

Uses the gravitational parameter and reference radius for calculations.

References

Kaula, W. M. (1966). Theory of Satellite Geodesy.

Attributes

Cnm

The matrix of cosine spherical harmonic coefficients.

SPH_body

The body object representing the primary body for spherical harmonics calculations.

Snm

The matrix of sine spherical harmonic coefficients.

bnm_ext_imag

The imaginary part of the B_nm exterior coefficients.

bnm_ext_real

The real part of the B_nm exterior coefficients.

cs_file

The file path of the spherical harmonic coefficient JSON file.

mu

The gravitational parameter of the spherical harmonics body.

n_degree_max

The maximum degree for spherical harmonics calculations.

normalized

Indicates whether the spherical harmonic coefficients are normalized.

order

The maximum order of the spherical harmonic expansion.

r_ref

The reference radius used in the spherical harmonics model.

ref_frame

The reference frame associated with the input state vector, used for acceleration and partial derivative computations.

Methods

acceleration_transform_rf(acceleration_bf, epoch)

Transforms an acceleration vector from the body-fixed frame to the reference frame.

compute_acceleration(position, ...)

Computes the acceleration due to spherical harmonics gravity.

compute_bnm(position, epoch)

Computes the B_nm coefficients required for spherical harmonics acceleration computation - using raw ndarray

compute_partial_by_C(position, epoch)

Computes the partial derivatives of the spherical harmonic acceleration with respect to the C coefficients.

compute_partial_by_S(position, epoch)

Computes the partial derivatives of the spherical harmonic acceleration with respect to the S coefficients.

compute_partial_by_position(position, ...)

Computes the partial derivatives of the spherical harmonic acceleration with respect to position as ndarray.

jacobian_C_transform_rf(jacobian_C_bf, epoch)

Transforms the Jacobian matrix from the body-fixed frame to the reference frame.

jacobian_pos_transform_rf(jacobian_bf, epoch)

Transforms the Jacobian matrix from the body-fixed frame to the reference frame (unit-free).

kronecker_delta(j)

Kronecker delta function.

normalize_coeffs()

Normalizes the spherical harmonic coefficients if the loaded coefficients are unnormalized.

rf_transform(position, epoch)

position: 3x1 vector of the evaluation body (self._eval_body)
acceleration_transform_rf(acceleration_bf: ndarray, epoch: float) → ndarray#

Transforms an acceleration vector from the body-fixed frame to the reference frame.

Parameters:

  • acceleration_bf (np.ndarray) – 3x1 acceleration vector in the body-fixed frame (in km/s^2).

  • epoch (float) – Epoch at which the transformation is computed.

Returns:

acceleration_rf – 3x1 acceleration vector in the reference frame (in km/s^2).

Return type:

np.ndarray

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

Computes the acceleration due to spherical harmonics gravity.

Parameters:

  • position (np.ndarray) – 3x1 position vector of the spacecraft in the original reference frame, in kilometers.

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

  • epoch (float) – Epoch at which the transformation is performed.

  • body (None) – Not explicitly used but included for interface consistency.

Returns:

acc_vec – The 3x1 acceleration vector due to spherical harmonics in the reference frame, in km/s^2. Expressed in the input reference frame

Return type:

np.ndarray

compute_bnm(position: ndarray, epoch: float) → tuple[ndarray, ndarray]#

Computes the B_nm coefficients required for spherical harmonics acceleration computation - using raw ndarray

Evaluates the real and imaginary components of the B_nm terms based on the spacecraft’s position relative to the SPH body, considering whether the coefficients are normalized or not.

Parameters:

  • position (np.ndarray) – 3x1 position vector in the original reference frame (in km).

  • epoch (float) – Epoch at which the transformation is performed.

Returns:

B_nm coeffs – A tuple with indices containing the following: tuple[np.ndarray, np.ndarray] Real and imaginary B_nm coefficient matrices, shape (n_degree_max+3, n_degree_max+3).

Return type:

tuple

compute_partial_by_C(position: ndarray, epoch) → ndarray#

Computes the partial derivatives of the spherical harmonic acceleration with respect to the C coefficients.

Parameters:

  • position (np.ndarray) – 3x1 position vector of the spacecraft in the original reference frame. Expressed in units of kilometers.

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

  • epoch (float) – Epoch at which the transformation is performed.

  • body (CelestialBody) – The celestial body for which spherical harmonics are computed.

Returns:

partials_a_by_C – Partial derivatives of acceleration with respect to the C coefficients. Size of (order+1)x(order+1). Expressed in units of \(\frac{km}{s^2}\).

Return type:

np.ndarray

compute_partial_by_S(position: ndarray, epoch) → ndarray#

Computes the partial derivatives of the spherical harmonic acceleration with respect to the S coefficients.

Parameters:

  • position (np.ndarray) – 3x1 position vector of the spacecraft in the original reference frame. Expressed in units of kilometers.

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

  • epoch (float) – Epoch at which the transformation is performed.

  • body (CelestialBody) – The celestial body for which spherical harmonics are computed.

Returns:

partials_a_by_S – Partial derivatives of acceleration with respect to the S coefficients. Size of (order+1)x(order+1). Expressed in units \(\frac{km}{s^2}\).

Return type:

np.ndarray

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

Computes the partial derivatives of the spherical harmonic acceleration with respect to position as ndarray.

Parameters:

  • position (np.ndarray) – 3x1 position vector.

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

  • epoch (float) – Epoch at which the transformation is performed.

  • body (None) – Not explicitly used but included for interface consistency.

Returns:

partial_a_by_pos – The 3x3 partial derivative (Jacobian) of acceleration with respect to position. Assumed in units of \(\frac{1}{s^2}\). Expressed in the input reference frame

Return type:

np.ndarray

jacobian_C_transform_rf(jacobian_C_bf: ndarray, epoch: float) → ndarray#

Transforms the Jacobian matrix from the body-fixed frame to the reference frame.

Parameters:

  • jacobian_C_bf (np.ndarray) – The Jacobian matrix in the body-fixed frame with size (order+1)x(order+1). Expressed in units of \(\frac{km}{s^2}\).

  • epoch (float) – The epoch time at which the transformation is computed.

Returns:

jacobian_C_rf – The Jacobian matrix in the reference frame (size: (order+1)x(order+1), typical units: km/s^2).

Return type:

np.ndarray

jacobian_pos_transform_rf(jacobian_bf: ndarray, epoch: float) → ndarray#

Transforms the Jacobian matrix from the body-fixed frame to the reference frame (unit-free).

Parameters:

  • jacobian_bf (np.ndarray) – The 3x3 Jacobian matrix in the body-fixed frame (float only, no units).

  • epoch (float) – The epoch at which the transformation is computed.

Returns:

The 3x3 Jacobian matrix in the reference frame (unit-free).

Return type:

np.ndarray

kronecker_delta(j: int)#

Kronecker delta function. See https://en.wikipedia.org/wiki/Kronecker_delta

Parameters:

  • i (int) – First value

  • j (int) – Second value

Returns:

1 if i == j, or 0 if i ~= j

Return type:

int

normalize_coeffs() → None#

Normalizes the spherical harmonic coefficients if the loaded coefficients are unnormalized.

Normalization is performed using the formula:

\[N = \sqrt{\frac{(2 - \delta_{0_m}) * (2(n + 1)) * (n - m)!}{(n + m)!}}\]

where \(\delta_{0_m}\) is 1 if m = 0, otherwise 0.

This ensures the coefficients comply with the normalization convention.

Return type:

None

rf_transform(position: ndarray, epoch: float) → ndarray#
position: 3x1 vector of the evaluation body (self._eval_body)

w.r.t. the propagation origin (self._origin), expressed in self._ref_frame, in km.

property Cnm: ndarray#

The matrix of cosine spherical harmonic coefficients.

property SPH_body: Body#

The body object representing the primary body for spherical harmonics calculations.

property Snm: ndarray#

The matrix of sine spherical harmonic coefficients.

property bnm_ext_imag: ndarray#

The imaginary part of the B_nm exterior coefficients. Unitless.

property bnm_ext_real: ndarray#

The real part of the B_nm exterior coefficients. Unitless.

property cs_file: str#

The file path of the spherical harmonic coefficient JSON file.

property mu: float#

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

property n_degree_max: int#

The maximum degree for spherical harmonics calculations.

property normalized: bool#

Indicates whether the spherical harmonic coefficients are normalized.

property order: int#

The maximum order of the spherical harmonic expansion.

property r_ref: float#

The reference radius used in the spherical harmonics model. Assumed in units of \(km\).

property ref_frame: str#

The reference frame associated with the input state vector, used for acceleration and partial derivative computations.