SphericalHarmonicsGravity#

class SphericalHarmonicsGravity(sph_harm_order: int, sph_harm_cs_file: str, sph_harm_body, origin, sph_harm_norm_flag: bool = True, n_degree_max: int = 100, base_frame: Frame = None, propagated_bodies: list | None = 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. The angles can be estimated as solve-for parameters by including ("pole_ra", spice_id), ("pole_dec", spice_id), ("pole_pm", spice_id) or ("pole_w0", spice_id) entries in the state vector. When estimated, the rotation matrix \(\mathbf{R}\) (body-fixed to 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_orderint

The maximum order of spherical harmonics to use.

sph_harm_cs_filestr

Path to the JSON file containing spherical harmonic coefficients.

sph_harm_bodydict

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.

originBody

Body the propagated position is measured from. Only its identity is needed: it fixes the vector from the propagation origin to the harmonics body, so the model can be built once — in an ops configuration file, for instance — and reused across propagations.

When the field body is not the origin, the acceleration returned is the perturbation felt in the origin-centred frame: the field at the evaluation point less the pull the same body exerts on the origin. That second piece is the indirect term of the classical third-body perturbation, so such a body must not also be listed in third_bodies — ForceModelTranslation drops it from the point-mass list for exactly this reason. When the field body is the origin the expansion is returned as-is.

A StateArray is also accepted, in which case its origin is used. That is the historical form of this argument and is kept so existing call sites keep working.

sph_harm_norm_flagbool, optional

Retained for backward compatibility. Defaults to True. Coefficients are always converted to normalized form on load (required by the rust core), so both normalized and unnormalized coefficient files are supported; the file’s own Normalized field determines whether a conversion is performed.

n_degree_maxint, optional

Maximum degree for harmonics. Defaults to 100.

base_frameFrame, optional

Frame of the propagator. If base_frame = None, defaults to the J2000 frame.

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.

solid_tide

Optional SolidTide perturbing this field.

Methods

compute_acceleration(position, ...)

Computes the acceleration due to spherical harmonics gravity.

See also

scarabaeus.StateArray

Represents state vectors with origins and reference frames.

scarabaeus.ForceModelTranslation

Aggregator that builds this model for a propagation.

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

[1]

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

Examples

Build the model on its own — no state vector needed — so it can live in a configuration file and be reused across propagations.

>>> import scarabaeus as scb
>>> earth = scb.CelestialBody.from_constants("EARTH")
>>> sh = scb.SphericalHarmonicsGravity(
...     8,
...     "data/dynamic_setup/sph_coefficients/earth_ggm03.json",
...     earth,
...     origin = earth,
... )
compute_acceleration(position: ndarray, current_state: dict, epoch, body) → ndarray#

Computes the acceleration due to spherical harmonics gravity.

Parameters:
positionnp.ndarray

3x1 position vector of the spacecraft in the original reference frame, in kilometers.

current_statedict

Dictionary containing the current state information.

epochfloat

Epoch at which the transformation is performed.

bodyNone

Not explicitly used but included for interface consistency.

Returns:
acc_vecnp.ndarray

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

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.

property solid_tide#

Optional SolidTide perturbing this field.

The same tide that displaces a surface station also redistributes mass, which changes the external gravity field. Attaching a tide model here adds its degree-2 coefficient perturbation at every evaluation.

The tide is a known perturbation rather than an estimated one, so it rides on the coefficients passed to the kernel and leaves the Jacobian on the nominal field, exactly as the estimated Cnm/Snm corrections do.

Its central_body must be the body this field belongs to, and the base coefficients’ own tide convention has to be consistent: a zero-tide field already contains the permanent deformation, so adding a tide on top of one counts it twice. That difference is about 1e-8 in normalized C20, comparable to the whole tidal signal, and nothing here can detect it for you.

exception AutogradTracingError#

Bases: Exception

Autograd is tracing the acceleration through the Rust kernels.

The autograd NumPy backend (UseAutoGrad=TRUE) is fine on its own — the model runs on plain arrays under it. Only a traced position cannot pass into Rust. The partials are verified by the Rust dual-number differentiation instead (SphericalHarmonicsCore.compute_jacobian_ad_bf and the GM, C_nm/S_nm and pole counterparts), which is what check_force_model_partials=TRUE runs.

exception InvalidOriginError#

Bases: TypeError

The supplied origin is neither a body nor a state vector holding one.

exception MissingBodyFixedFrameError#

Bases: Exception

The spherical-harmonics body carries no body-fixed (rotating) frame.

exception MissingSpiceNameError#

Bases: Exception

The spherical-harmonics body has no SPICE name to resolve its frame.

exception PropagatedBodyStateMissingError#

Bases: Exception

The harmonics body is integrated in the state vector, but its position is absent from the state handed to this model.

Falling back to the ephemeris here would silently evaluate the field about the a priori position while the filter estimates another, so the absence is reported instead.

exception RustCoreUnavailableError#

Bases: Exception

The rust spherical-harmonics core is unavailable.

Raised by the compute and partial methods when _rust_core could not be built because the extension is not importable. The Rust kernels are the only implementation of the body-fixed acceleration and its analytical partials.