gravity_field
#
This module contains a set of factory functions for setting up the gravitational potential models of celestial bodies in an environment.
References#
 1
Balmino, G. (1994). Gravitational potential harmonics from the shape of an homogeneous body. Celestial Mechanics and Dynamical Astronomy, 60(3), 331364.
Functions#

Factory function for central gravity field settings object. 
Factory function to create central gravity field settings from Spice settings. 


Factory function for creating a spherical harmonics gravity field settings object. 

Factory function for spherical harmonics gravity field settings object from triaxial ellipsoid parameters. 
 central(gravitational_parameter: float) tudatpy.kernel.numerical_simulation.environment_setup.gravity_field.GravityFieldSettings #
Factory function for central gravity field settings object.
Factory function for settings object, defining a pointmass gravity field model with userdefined gravitational parameter \(\mu\). The gravitational potential is the defined as:
\[U(\mathbf{r})=\frac{\mu}{\mathbf{r}}\]with \(\mathbf{r}\) the position vector measured from the body’s center of mass.
 Parameters
gravitational_parameter (float) – Gravitational parameter defining the pointmass gravity field.
 Returns
Instance of the
GravityFieldSettings
derivedCentralGravityFieldSettings
class Return type
Examples
In this example, we create
GravityFieldSettings
for Earth using a simple central gravity field model:# define parameters describing central gravity model gravitational_parameter = 3.986e14 # create gravity field settings body_settings.get( "Earth" ).gravity_field_settings = environment_setup.gravity_field.central( gravitational_parameter )
 central_spice() tudatpy.kernel.numerical_simulation.environment_setup.gravity_field.GravityFieldSettings #
Factory function to create central gravity field settings from Spice settings.
Factory function for settings object, defining a pointmass gravity field model. This function provides the same model as
central()
), but with gravitational parameter \(\mu\) from Spice. Returns
Instance of the
GravityFieldSettings
class of gravity field typecentral_spice
” Return type
Examples
In this example, we create
GravityFieldSettings
for Earth using a simple central gravity field model and data from Spice:# create gravity field settings body_settings.get( "Earth" ).gravity_field_settings = environment_setup.gravity_field.central_spice( )
 spherical_harmonic(gravitational_parameter: float, reference_radius: float, normalized_cosine_coefficients: numpy.ndarray[numpy.float64[m, n]], normalized_sine_coefficients: numpy.ndarray[numpy.float64[m, n]], associated_reference_frame: str) tudatpy.kernel.numerical_simulation.environment_setup.gravity_field.GravityFieldSettings #
Factory function for creating a spherical harmonics gravity field settings object.
Factory function for settings object, defining a gravity field model through spherical harmonic expansion. The
associated_reference_frame
must be the same frame ID as the target frame of the body’s rotation model. It represents the frame in which the spherical harmonic field is defined.The gravitational potential is the defined as:
\[U(\mathbf{r})=\sum_{l=0}^{l_{max}}\sum_{m=0}^{l}\mu\left(\frac{{R}^{l}}{r^{l+1}}\right)\bar{P}_{lm}(\sin\phi)\left(\bar{C}_{lm}\cos m\theta+\bar{S}_{lm}\sin m\theta\right)\]with \(\mathbf{r}\) the position vector of the evaluation point, measured from the body’s center of mass. The angles \(\phi\) and \(\theta\) are the bodyfixed latitude and longitude of the evaluation point, and \(\bar{P}_{lm}\) is the associated Legendre polynomial (at degree/order :math`l/m`).
Note: Spherical harmonic coefficients used for this environment model must always be fully normalized. To normalize unnormalized spherical harmonic coefficients, see
normalize_spherical_harmonic_coefficients()
. Parameters
gravitational_parameter (float) – Gravitational parameter \(\mu\) of gravity field.
reference_radius (float) – Reference radius \(R\) of spherical harmonic field expansion.
normalized_cosine_coefficients (numpy.ndarray) – Cosine spherical harmonic coefficients (geodesy normalized). Entry (i,j) denotes coefficient \(\bar{C}_{ij}\) at degree i and order j. As such, note that entry (0,0) of cosine coefficients should be equal to 1.
normalized_sine_coefficients (numpy.ndarray) – Sine spherical harmonic coefficients (geodesy normalized). Entry (i,j) denotes coefficient \(ar{S}_{ij}\) at degree i and order j.
associated_reference_frame (str) – Identifier for bodyfixed reference frame with which the spherical harmonics coefficients are associated.
 Returns
Instance of the
GravityFieldSettings
derivedSphericalHarmonicsGravityFieldSettings
class Return type
Examples
In this example, we create
GravityFieldSettings
for Earth using a spherical harmonics gravity model:# Define the spherical harmonics gravity model gravitational_parameter = 3986004.415E+8 reference_radius = 6378136.3 # Normalized coefficients taken from https://cddis.nasa.gov/archive/egm96/general_info/egm96_to360.ascii # The above file is described in https://cddis.nasa.gov/archive/egm96/general_info/readme.egm96 normalized_cosine_coefficients = [ [1, 0, 0, 0], [0, 0, 0, 0], [0.484165371736E03, 0.186987635955E09, 0.243914352398E05, 0], [0.957254173792E06, 0.202998882184E05, 0.904627768605E06, 0.721072657057E06] ] normalized_sine_coefficients = [ [0, 0, 0, 0], [0, 0, 0, 0], [0, 0.119528012031E08, 0.140016683654E05, 0], [0, 0.248513158716E06, 0.619025944205E06, 0.141435626958E05] ] associated_reference_frame = "IAU_Earth" # Create the gravity field settings and add them to the body "Earth" body_settings.get( "Earth" ).gravity_field_settings = environment_setup.gravity_field.spherical_harmonic( gravitational_parameter, reference_radius, normalized_cosine_coefficients, normalized_sine_coefficients, associated_reference_frame )
 spherical_harmonic_triaxial_body(axis_a: float, axis_b: float, axis_c: float, density: float, maximum_degree: int, maximum_order: int, associated_reference_frame: str) tudatpy.kernel.numerical_simulation.environment_setup.gravity_field.SphericalHarmonicsGravityFieldSettings #
Factory function for spherical harmonics gravity field settings object from triaxial ellipsoid parameters.
Factory function for settings object, defining a gravity field model through spherical harmonic expansion of a homogeneous triaxial ellipsoid, same as
spherical_harmonic
The constant mass distribution in the specified ellipsoid shape is expanded to obtain a spherical harmonic coefficient representation. Gravity fields from this setting object are expressed in normalized spherical harmonic coefficients. The bodyfixed x, y and z axes are assumed to be along the A, B and C axes. This function implements the models of (see Balmino 1). Parameters
axis_a (float) – Dimension of largest axis of triaxial ellipsoid.
axis_b (float) – Dimension of intermediate axis of triaxial ellipsoid.
axis_c (float) – Dimension of smallest axis of triaxial ellipsoid.
density (float) – Density of ellipsoid.
maximum_degree (int) – Maximum degree of spherical harmonics expansion.
maximum_order (int) – Maximum order of spherical harmonics expansion.
associated_reference_frame (str) – Identifier for bodyfixed reference frame with which the spherical harmonics coefficients are associated.
 Returns
Instance of the
GravityFieldSettings
derivedSphericalHarmonicsGravityFieldSettings
class Return type
Examples
In this example, we create
GravityFieldSettings
for Earth using the expansion of a homogeneous triaxial ellipsoid into a spherical harmonics gravity model:# Create the gravity field settings for Earth with Spherical Harmonics from a triaxial ellipsoid body_settings.get( "Earth" ).gravity_field_settings = environment_setup.gravity_field.spherical_harmonic_triaxial_body( axis_a=6378171.88, axis_b=6378102.03, axis_c=6356752.24, density=5520, maximum_degree=50, maximum_order=50, associated_reference_frame="IAU_Earth" )
Enumerations#
Enumeration of gravity field types. 

Enumeration of spherical harmonics models. 
Classes#
Base class for providing settings for automatic gravity field model creation. 

GravityFieldSettings derived class defining settings of point mass gravity field. 

GravityFieldSettings derived class defining settings of spherical harmonic gravity field representation. 
 class GravityFieldSettings#
Base class for providing settings for automatic gravity field model creation.
This class is a functional base class for settings of gravity field models that require no information in addition to their type. Gravity field model classes requiring additional information must be created using an object derived from this class.
 property gravity_field_type#
readonly
Type of gravity field model that is to be created.
 Type
 class CentralGravityFieldSettings#
GravityFieldSettings derived class defining settings of point mass gravity field.
Derived class of GravityFieldSettings for central gravity fields, which are defined by a single gravitational parameter.
 class SphericalHarmonicsGravityFieldSettings#
GravityFieldSettings derived class defining settings of spherical harmonic gravity field representation.
Derived class of GravityFieldSettings for gravity fields, which are defined by a spherical harmonic gravity field representation.
 property associated_reference_frame#
Identifier for bodyfixed reference frame with which the coefficients are associated.
 Type
 property create_time_dependent_field#
Boolean that denotes whether the field should be created as timedependent (even if no variations are imposed initially).
 Type
 property normalized_cosine_coefficients#
Cosine spherical harmonic coefficients (geodesy normalized). Entry (i,j) denotes coefficient at degree i and order j.
 Type
 property normalized_sine_coefficients#
Sine spherical harmonic coefficients (geodesy normalized). Entry (i,j) denotes coefficient at degree i and order j.
 Type