`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), 331-364.

Functions#

`central`(gravitational_parameter)	Factory function for central gravity field settings object.
`central_spice`()	Factory function to create central gravity field settings from Spice settings.
`spherical_harmonic`(gravitational_parameter, ...)	Factory function for creating a spherical harmonics gravity field settings object.
`spherical_harmonic_triaxial_body`(axis_a, ...)	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 point-mass gravity field model with user-defined 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 point-mass gravity field.
Returns: Instance of the GravityFieldSettings derived CentralGravityFieldSettings class
Return type: CentralGravityFieldSettings

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 point-mass 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 type central_spice”
Return type: GravityFieldSettings

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 body-fixed 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 un-normalized 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 body-fixed reference frame with which the spherical harmonics coefficients are associated.

Returns

Instance of the GravityFieldSettings derived SphericalHarmonicsGravityFieldSettings class

Return type

SphericalHarmonicsGravityFieldSettings

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.484165371736E-03, -0.186987635955E-09, 0.243914352398E-05,  0],
    [0.957254173792E-06,  0.202998882184E-05,  0.904627768605E-06,  0.721072657057E-06]
]
normalized_sine_coefficients = [
    [0,                   0,                   0,                   0],
    [0,                   0,                   0,                   0],
    [0,                   0.119528012031E-08,  -0.140016683654E-05, 0],
    [0,                   0.248513158716E-06,  -0.619025944205E-06, 0.141435626958E-05]
]
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 body-fixed 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 body-fixed reference frame with which the spherical harmonics coefficients are associated.

Returns

Instance of the GravityFieldSettings derived SphericalHarmonicsGravityFieldSettings class

Return type

SphericalHarmonicsGravityFieldSettings

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#

`GravityFieldType`	Enumeration of gravity field types.
`SphericalHarmonicsModel`	Enumeration of spherical harmonics models.

class GravityFieldType#

Enumeration of gravity field types.

Enumeration of gravity field types supported by tudat.

Members:

central_gravity :

central_spice_gravity :

spherical_harmonic_gravity :

property name#

class SphericalHarmonicsModel#

Enumeration of spherical harmonics models.

Enumeration of spherical harmonics models supported by tudat.

Members:

custom_model :

egm96 :

ggm02c :

ggm02s :

glgm3150 :

lpe200 :

jgmro120d :

property name#

Classes#

`GravityFieldSettings`	Base class for providing settings for automatic gravity field model creation.
`CentralGravityFieldSettings`	GravityFieldSettings derived class defining settings of point mass gravity field.
`SphericalHarmonicsGravityFieldSettings`	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#

read-only

Type of gravity field model that is to be created.

Type: GravityFieldType

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.

property gravitational_parameter#

Gravitational parameter of central gravity field.

Type: float

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 body-fixed reference frame with which the coefficients are associated.

Type: str

property create_time_dependent_field#

Boolean that denotes whether the field should be created as time-dependent (even if no variations are imposed initially).

Type: bool

property gravitational_parameter#

Gravitational parameter of gravity field.

Type: float

property normalized_cosine_coefficients#

Cosine spherical harmonic coefficients (geodesy normalized). Entry (i,j) denotes coefficient at degree i and order j.

Type: numpy.ndarray

property normalized_sine_coefficients#

Sine spherical harmonic coefficients (geodesy normalized). Entry (i,j) denotes coefficient at degree i and order j.

Type: numpy.ndarray

property reference_radius#

read-only

Reference radius of spherical harmonic field expansion.

Type: float

gravity_field#

References#

Functions#

Enumerations#

Classes#

`gravity_field`#