`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.

The gravitational potential is expanded as:

\[U = \frac{\mu}{r} \sum_{n=0}^{N} \sum_{m=0}^{n} \left(\frac{R_e}{r}\right)^n \bar{P}_{nm}(\sin\phi) \left[ \bar{C}_{nm} \cos(m\lambda) + \bar{S}_{nm} \sin(m\lambda) \right]\]

where \(\mu\) is the gravitational parameter, \(R_e\) is the reference radius, \(r\), \(\phi\), \(\lambda\) are the spherical coordinates of the spacecraft in the body-fixed frame, \(\bar{P}_{nm}\) are the normalized associated Legendre polynomials, and \(\bar{C}_{nm}\), \(\bar{S}_{nm}\) are the normalized spherical harmonic coefficients. The acceleration is \(\mathbf{a} = \nabla U\), computed in the body-fixed frame via the Pines/Eckman recurrence and rotated to the propagation frame.

The body-fixed frame orientation is defined by the IAU pole model:

\[\alpha_0,\quad \delta_0,\quad W\]

where \(\alpha_0\) (right ascension of the pole), \(\delta_0\) (declination of the pole), and \(W\) (prime meridian angle) are secular polynomials in time whose coefficients come from the PCK kernel. All three angles can be estimated as solve-for parameters by including ("pole_ra", spice_id), ("pole_dec", spice_id), or ("pole_pm", spice_id) entries in the state vector. When estimated, the rotation matrix \(\mathbf{R}\) (body-fixed → inertial) is rebuilt analytically from the estimated angles rather than from SPICE, so partial derivatives with respect to the pole parameters are available.

The coefficients \(\bar{C}_{nm}\) and \(\bar{S}_{nm}\) as well as \(\mu\) itself may also be estimated via ("cnm_n_m", spice_id), ("snm_n_m", spice_id), and ("gm", spice_id) state entries respectively.

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.

SphericalHarmonicsGravity#

`SphericalHarmonicsGravity`#