Environment Models

On this page, we provide an overview of the categories of environment models that are available (with links to API documentation), as well as some general notes on their usages, typical pitfalls, hints, etc.

Available Model Types

The complete list of available environment model settings can be found on our API documentation. Below is a list with the different categories of models, and a link to the corresponding Tudatpy module

  • Aerodynamic coefficients, to be assigned to the aerodynamic_coefficient_settings attribute of BodySettings.

    • These models provide various ways in which to define aerodynamics force (and if required, moment) coefficients of a body.

  • Atmosphere models, to be assigned to the atmosphere_settings attribute of BodySettings.

    • These models provide various ways in which to define atmospheric properties of a body. For state propagation, the density will typically be the most important one. However, many of the models here include outputs of temperature, density, etc. as well. Depending on the model, the atmospheric properties may be only altitude-dependent, or fully time- and position-dependent. Note that the atmosphere settings can include wind settings (default: none)

  • Ephemeris models, , to be assigned to the ephemeris_settings attribute of BodySettings.

    • These models provide various ways in which to define predetermined (e.g. not coming from a Tudat propagation) translational states of bodies in the solar system

  • Gravity field models, to be assigned to the gravity_field_settings attribute of BodySettings.

    • These models provide various ways in which to define the gravitational field of solar system bodies. Note: the mass associated with these gravitational field is the gravitational mass, which does not need to be equal to its inertial mass.

  • Gravity field variation models, to be assigned to the gravity_field_variation_settings attribute of BodySettings. Note: this attribute is a list, and any number of variation models may be added.

    • These models provide various ways in which to define the time-variability of a body’s (spherical harmonic) gravitaty field.

  • Rotation models, to be assigned to the rotation_model_settings attribute of BodySettings.

    • These models provide various ways in which to define the orientation of a body w.r.t. inertial space, and produces a quaternion/rotation matrix, and angular velocity vector/rotation matrix derivative. Note that Tudat can also produce such models by numerical propagation of the Euler equations (see Rotational Dynamics).

  • Shape models, to be assigned to the shape_settings attribute of BodySettings.

    • These models provide various ways in which to define the exterior of a natural body and is typically used to calculate (for instance) altitude, ground station position, etc. Note: the exterior shape of an artificial body, from which aerodynamic and radiation pressure properties can be evaluated, uses a different interface, which is currently under development

  • Shape deformation models, to be assigned to the shape_deformation_settings attribute of BodySettings. Note: this attribute is a list, and any number of deformation models may be added.

    • These models provide various ways in which to define time variability of the shape of a body. These are typically relevant for detailed position models of ground stations (note that the models assigned here are global; station-specific models can be assigned to individual stations)

  • Radiation pressure, to be assigned to the rotation_model_settings attribute of BodySettings. Note: this attribute is a dictionary, with one radiation pressure model per source body.

    • These models provide various ways in which to define the response of a body to incident radation pressure.

  • Rigid body properties, to be assigned to the rigid_body_settings attribute of BodySettings.

    • This property defines the mass, center of mass and inertia tensor of a body. If the body has a gravity field, corresponding rigid body properties are automatically created (but, defining rigid body properties does not define a gravity field!) Note: If defined manually, the inertia tensor must be provided in the body-fixed frame (the orientation of which is defined by the body’s rotation model), and must not be normalized.

  • Ground stations, to be assigned to the ground_station_settings attribute of BodySettings. Note: this attribute is a list, and any number of stations may be added.

    • These models define ground stations (which includes planetary landers) on a celestial body. Each ground station may have any number of station motion models assigned to it.

Points of attention

On this page, we give an overview of some specifica aspects of the environment models that may be useful for a user to know, in order to properly select and understand their choice of environment models. This page is meant to supplement the API documentation, and is not a comprehensive overview of all environment models.

Aerodynamic coefficients

See the section on aerodynamic coefficients during the propagation concerning a number of points of attention regarding the aerodynamic coefficients, such as the frame in which they are defined, definition of their independent variables, control surfaces, etc.

Ephemeris models

Spice-based models For many typical applications, natural body ephemerides will be calculated from Spice kernels. In some cases, a user may find that the default Spice kernels are insufficient for their purposes, due to one of two reasons:

  • The body for which the state is required is in the ephemeris Spice kernel, but the time at which the state is needed lies outside of the bounds for which the Spice kernel has data

  • The body for which the state is required is not in the ephemeris Spice kernel

In both cases, a user should load additional Spice kernels. This can be done using the load_kernel(). Spice kernels for many bodies may be found in a number of places. The ‘goto’ place for Spice kernels for ephemerides is the NAIF website (developers of Spice), which you can find here.

Use of scaled models For a sensitivity analysis (among others) it may be useful to modify the ephemeris of a body, for instance to emulate the influence of a 1 km offset in the state provided by the nominal ephemeris. Unlike most other environment models, this cannot be achieved (at least not for most types of ephemerides) by modifying a single defining parameter of the model. Instead, we provide the functions scaled_by_vector() and scaled_by_vector_function(), which take nominal ephemeris settings, and add a user-defined variation (constant or time-varying; absolute or relative) to the inertial Cartesian state elements produced by the ephemeris.

Gravity fields

Unlike most other environment model options in Tudat, there are multiple options for creating either a spherical harmonic gravity field, and a point mass gravity field:

  • Point mass: defining the gravitational parameter manually (central()) or requiring the gravitational parameter to be extracted from Spice (central_spice()).

  • Spherical harmonics: defining all the settings manually (spherical_harmonic()), loading a pre-defined model for a soalr system body (from_file_spherical_harmonic()) or calculating the spherical harmonic coefficients (up to a given degree) based on an ellipsoidal homogeneous mass distribution (spherical_harmonic_triaxial_body())

Rotation models

Tudat has a broad range of rotation models available. In principle, these models can be assigned to both celestial bodies and natural bodies. However, a subset of these models is typically only applied to natural or artificial bodies. Rotation models have a wide range of, sometimes indirect, influences on the dynamics

  • A spherical harmonic acceleration exerted by a central body is first evaluated in a body-fixed frame, and the transformed to an inertial frame. Consequently, the central body’s rotation has a fundamental influence on the exerted spherical harmonic acceleration

  • A thrust acceleration in Tudat is calculated from two models: (1) an engine model, which defined the body-fixed direction of the thrust, and the magnitude of the thrust (2) the orientation of the body in space, defined by its rotation model

  • For a non-spherical central body shape models, the current orientation of this central body has an indirect influence on the altitude at which a vehicle with a given inertial state is located

Rotation and thrust Two rotation models, which are typically used for vehicles under thrust, and/or vehicles undergoing aerodynamic forces, are the following:

  • The rotation model aerodynamic_angle_based(), which calculates the body’s rotation based on the angle of attack, sideslip angle and bank angle. Note that these angles are definend w.r.t. the relative wind. This model is typical when using, for instance, a re-entry simulation. It imposes these three angles, and calculates the body orientation by combination with the latitude, longitude, heading angle, flight path angles. There is a related model, zero_pitch_moment_aerodynamic_angle_based(), that uses the same setup, but does not impose the angle of attack, but caculates by imposing aerodynamic pitch trim (zero pitch moment).

  • The rotation model custom_inertial_direction_based(), which is typical when calculating dynamics of a vehicle under thrust. It is based on linking a body-fixed direction (now limited to the body-fixed x-axis) to an arbitrary inertial direction. This allows the thrust (assuming that this is aligned with this same body-fixed direction) to be guided in an inertial direction determined by a user-defined model.

Relation to gravity field When modifying the rotation model settings, the name of the body-fixed frame may also be changed (as is the case for, for instance, the gcrs_to_itrs(), where the body-fixed frame has the name “ITRS”). One consequence of this is that you may get an error from the spherical harmonic gravity field, which can no longer find the frame to which it is associated. This can be resolved by (for instance) associating the gravity field to the new frame. For the above example, this would be done by the following:

body_settings.get( "Earth" ).gravity_field_settings.associated_reference_frame = "ITRS"

High-accuracy Earth rotation model The gcrs_to_itrs() creates a high accuracy rotation model, following the IERS 2010 Conventions. This includes small variations that are not predicted by models, but are instead measured by geodetic techniques and published as tabulated data by the IERS. If so desired, the exact files used for these corrections may be adapted by the user (see EarthOrientationAnglesCalculator()), which includes specific settings for daily variations in earth rotation angle, which influences the UTC - UT1 time conversion.

Rigid body properties and gravity fields

Rigid body properties will always be created automatically when a body is endowed with a gravity field, as described below:

  • Point-mass gravity field: mass computed from gravitational parameter; zero inertia tensor, and center of mass at origin of body-fixed frame

  • Spherical harmonic gravity field: mass computed from gravitational parameter, center of mass computed from degree 1 gravity field coefficients, inertia tensor as described below

  • Polyhedron gravity field: mass computed from gravitational parameter, center of mass and inertia tensor computed from homogeneous mas distribution inside body

For the spherical harmonic gravity field, the normalized mean moment of inertia must be set by the user, to allow an inertia tensor to be computed. This is done using the scaled_mean_moment_of_inertia attribute of the SphericalHarmonicsGravityFieldSettings class, as in the example below

# Add gravity field model settings to body of spherical harmonic type
body_settings.get( "Mars" ).gravity_field = ...

# Add setting for moment of inertia
body_settings.get( "Mars" ).gravity_field.scaled_mean_moment_of_inertia = 0.365

This code snippet will automatically create a rigid body properties for Mars, with the inertia tensor computed from this value of 0.365 and the degree 2 gravity field coefficients. Note that, if gravity field variations are used for the body, time-variability of the degree 1- and 2- coefficients will be reflected in time-variability of the body’s center of mass and inertia tensor.

Wind models

Wind models may be added to an atmosphere model by using the wind_settings attribute of the atmosphere settings, as in the following example:

# Add atmosphere settings to body (if body does not yet have amosphere settings)
body_settings.get( "Mars" ).atmosphere_settings = ...

# Define settings for wind
wind_frame = environment.vertical_frame
wind_velocity = np.ndarray([0.0, 0.0, 10.0])
body_settings.get( "Mars" ).atmosphere_settings.wind_settings = environment_setup.atmosphere.constant_wind_model( wind_velocity, wind_frame )

Here, a wind vector in the positive z-direction of the vertical frame (downward) of 10 m/s is added, using the constant_wind_model().

By default, an atmosphere has ‘zero wind’, which means that the atmosphere corotates with the body. A user may add a wind model to this atmosphere model, which will modify the freestream velocity that a vehicle in the atmosphere experiences

Ground stations

Although ground stations are considered part of the environment in Tudat (as properties of a Body object), they do not influence the numerical propagation (unless a custom model imposing this is implemented by the user). Ground stations can be defined through the BodySettings as any other model. But, as the rest of the environment does not depend on them, they can safely be added to a body after it is created. The process is similar to the one described for :ref: decorate_empty_body. Specifically, ground station settings are created, and these are then used to create a ground station and add it to the body. The specifics of creating ground station settings is described in the API documentation. An example is given below:

# Create ground station settings
ground_station_settings = environment_setup.ground_station.basic_station(
    "TrackingStation",
    [station_altitude, delft_latitude, delft_longitude],
    element_conversion.geodetic_position_type)

# Add the ground station to the environment
environment_setup.add_ground_station(
    bodies.get_body("Earth"),
    ground_station_settings )s

where a simple ground station is created (with only a name and a position), with its position defined in geodetic elements. The position of a ground station in a body-fixed frame can have two sources of time-variability:

To automatically create a list of settings for all DSN stations (which are then typically assigned to the ground_station_settings of Earth), the dsn_station_settings() can be used.

Polyhedron models

A polyhedron can be used to define both gravity (polyhedron_from_gravitational_parameter()) and shape (polyhedron()) models. Since both models tend to be computationally intensive (the gravity model more so), it is recommended to use polyhedra with the lowest number of facets that allows meeting the desired accuracy. The number of facets of a polyhedron model can be reduced using any mesh processing software, for example PyMeshLab. Additionally, different functions to process a polyhedron are available in Polyhedron utilities.