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:
DynamicModelModels 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—ForceModelTranslationdrops it from the point-mass list for exactly this reason. When the field body is the origin the expansion is returned as-is.A
StateArrayis also accepted, in which case itsoriginis 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 therustcore), so both normalized and unnormalized coefficient files are supported; the file’s ownNormalizedfield 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:
CnmThe matrix of cosine spherical harmonic coefficients.
SPH_bodyThe body object representing the primary body for spherical harmonics calculations.
SnmThe matrix of sine spherical harmonic coefficients.
bnm_ext_imagThe imaginary part of the B_nm exterior coefficients.
bnm_ext_realThe real part of the B_nm exterior coefficients.
cs_fileThe file path of the spherical harmonic coefficient JSON file.
muThe gravitational parameter of the spherical harmonics body.
n_degree_maxThe maximum degree for spherical harmonics calculations.
normalizedIndicates whether the spherical harmonic coefficients are normalized.
orderThe maximum order of the spherical harmonic expansion.
r_refThe reference radius used in the spherical harmonics model.
ref_frameThe reference frame associated with the input state vector, used for acceleration and partial derivative computations.
solid_tideOptional
SolidTideperturbing this field.
Methods
compute_acceleration(position, ...)Computes the acceleration due to spherical harmonics gravity.
See also
scarabaeus.StateArrayRepresents state vectors with origins and reference frames.
scarabaeus.ForceModelTranslationAggregator 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 SPH_body: Body#
The body object representing the primary body for spherical harmonics calculations.
- property mu: float#
The gravitational parameter of the spherical harmonics body. Assumed in units of \(\frac{km^3}{s^2}\).
- 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
SolidTideperturbing 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_bodymust 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:
ExceptionAutograd 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_bfand the GM, C_nm/S_nm and pole counterparts), which is whatcheck_force_model_partials=TRUEruns.
- exception InvalidOriginError#
Bases:
TypeErrorThe supplied origin is neither a body nor a state vector holding one.
- exception MissingBodyFixedFrameError#
Bases:
ExceptionThe spherical-harmonics body carries no body-fixed (rotating) frame.
- exception MissingSpiceNameError#
Bases:
ExceptionThe spherical-harmonics body has no SPICE name to resolve its frame.
- exception PropagatedBodyStateMissingError#
Bases:
ExceptionThe 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.
Bases:
ExceptionThe rust spherical-harmonics core is unavailable.
Raised by the compute and partial methods when
_rust_corecould 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.