heyoka.model.sh_gravity_pot

Contents

heyoka.model.sh_gravity_pot#

heyoka.model.sh_gravity_pot(xyz: Iterable[expression], sh_coefficients: Iterable[Iterable[expression]], mu: expression, a: expression, max_degree: int | None = None, max_order: int | None = None) → expression#

Custom spherical harmonics gravitational potential.

Added in version 7.12.0.

This function will return the value of a custom spherical harmonics gravitational potential at the input Cartesian position xyz. The potential is fully determined by the user-supplied normalised harmonic coefficients sh_coefficients, the gravitational parameter mu and the reference radius a. The definitions and conventions adopted for the spherical harmonics expansion - in particular, the normalisation of the harmonic coefficients - follow §3.2 of [MG00].

xyz is expected to represent the position vector with respect to the body-fixed frame in which the harmonic coefficients are defined.

sh_coefficients is the list of normalised \(\bar{C}_{nm}\) and \(\bar{S}_{nm}\) harmonic coefficients, provided as an iterable of [C, S] pairs. The coefficients are read in degree-then-order order, that is:

\[\left[\left(\bar{C}_{0,0}, \bar{S}_{0,0}\right),\ \left(\bar{C}_{1,0}, \bar{S}_{1,0}\right),\ \left(\bar{C}_{1,1}, \bar{S}_{1,1}\right),\ \left(\bar{C}_{2,0}, \bar{S}_{2,0}\right),\ \ldots\ \left(\bar{C}_{n,n}, \bar{S}_{n,n}\right)\right].\]

The maximum harmonic degree of the model is inferred from the number of coefficients provided. Each coefficient can be any object convertible to a heyoka expression, including numerical constants, runtime parameters or arbitrary expressions.

mu and a are, respectively, the gravitational parameter and the reference radius to be used in the computation. Both are expected to be provided in units consistent with each other and with xyz.

max_degree and max_order can be used to optionally restrict the computation to a subset of the full model inferred from sh_coefficients. If left to None, the full model is used.

Parameters:

  • xyz – the position at which the potential will be evaluated.

  • sh_coefficients – the list of [C, S] normalised harmonic coefficient pairs.

  • mu – the gravitational parameter.

  • a – the reference radius.

  • max_degree – the maximum harmonic degree to be used in the computation.

  • max_order – the maximum harmonic order to be used in the computation.

Returns:

an expression for the gravitational potential at the position xyz.

Raises:

ValueError – if max_order > max_degree or if the requested degree exceeds the model inferred from sh_coefficients.

Contents