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, current_state, epoch, body)	Computes the B_nm coefficients required for spherical harmonics acceleration computation.
compute_partial_by_C(position, ...)	Computes the partial derivatives of the spherical harmonic acceleration with respect to the C coefficients.
compute_partial_by_S(position, ...)	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.
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.
normalize_coeffs()	Normalizes the spherical harmonic coefficients if the loaded coefficients are unnormalized.
rf_transform(position, current_state, epoch)	Transforms a position vector from an arbitrary reference frame to the SPH body-fixed frame.

acceleration_transform_rf(acceleration_bf: ArrayWUnits, epoch: float) → ArrayWUnits

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

Parameters:

• acceleration_bf (ArrayWUnits) – 3x1 acceleration vector in the body-fixed frame. Expressed in units of \(\frac{km}{s^2}\).

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

Returns:

acceleration_rf – 3x1 acceleration vector given in the reference frame. Expressed in units of \(\frac{km}{s^2}\).

Return type:

ArrayWUnits

compute_acceleration(position: ArrayWUnits, current_state: dict, epoch, body) → ArrayWUnits

Computes the acceleration due to spherical harmonics gravity.

Parameters:

• position (ArrayWUnits) – 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 (None) – Not explicitly used but included for interface consistency.

Returns:

acc_vec – The 3x1 acceleration vector due to spherical harmonics in the reference frame. Expressed in units of \(\frac{km}{s^2}\).

Return type:

ArrayWUnits

compute_bnm(position: ArrayWUnits, current_state: dict, epoch, body) → tuple[ArrayWUnits, ArrayWUnits]

Computes the B_nm coefficients required for spherical harmonics acceleration computation.

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 (ArrayWUnits) – 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 (None) – Not explicitly used but included for interface consistency.

Returns:

B_nm coeffs –

A tuple with indices containing the following:

• ArrayWUnits: Real B_nm coefficients (size: (n_degree_max+3)x(n_degree_max+3), unitless).

• ArrayWUnits: Imaginary B_nm coefficients (size: (n_degree_max+3)x(n_degree_max+3), unitless).

Return type:

tuple

compute_partial_by_C(position: ArrayWUnits, current_state: dict, epoch, body) → ArrayWUnits

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

Parameters:

• position (ArrayWUnits) – 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 – 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:

ArrayWUnits

compute_partial_by_S(position: ArrayWUnits, current_state: dict, epoch, body) → ArrayWUnits

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

Parameters:

• position (ArrayWUnits) – 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 – 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:

ArrayWUnits

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

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

Parameters:

• position (ArrayWUnits) – 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 (None) – The celestial body for which spherical harmonics are computed.

Returns:

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

Return type:

ArrayWUnits

jacobian_C_transform_rf(jacobian_C_bf: ArrayWUnits, epoch: float) → ArrayWUnits

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

Parameters:

• jacobian_C_bf (ArrayWUnits) – 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_rfArrayWUnits (The Jacobian matrix in the reference frame)

• (size ((order+1)x(order+1), typical units: km/s^2).)

jacobian_pos_transform_rf(jacobian_bf: ArrayWUnits, epoch: float) → ArrayWUnits

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

Parameters:

• jacobian_bf (ArrayWUnits)) – The 3x3 Jacobian matrix in the body-fixed frame. Expressed in units of \(\frac{1}{s^2}\).

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

Returns:

jacobian_rf – The 3x3 Jacobian matrix given in the reference frame. Expressed in units of \(\frac{1}{s^2}\).

Return type:

ArrayWUnits

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: ArrayWUnits, current_state: dict, epoch: float, body: None = None) → ArrayWUnits

Transforms a position vector from an arbitrary reference frame to the SPH body-fixed frame.

Converts a spacecraft position vector, originally defined in any origin and reference frame, into a position vector centered at the SPH body and expressed in its body-fixed reference frame.

Parameters:

• position (ArrayWUnits) – 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 (None) – Not explicitly used but included for interface consistency.

Returns:

pos_vec_bcbf – 3x1 position vector in the SPH body-centerd, SPH body-fixed frame. Expressed in units of kilometers.

Return type:

ArrayWUnits

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

The imaginary part of the B_nm exterior coefficients. Unitless.

property bnm_ext_real: ArrayWUnits

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

The gravitational parameter of the spherical harmonics body. Expressed 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: ArrayWUnits

The reference radius used in the spherical harmonics model. Expressed in units of kilometers.

property ref_frame: str

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