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 ofBodySettings
.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 ofBodySettings
.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 ofBodySettings
.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 ofBodySettings
.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 ofBodySettings
. 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 ofBodySettings
.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 ofBodySettings
.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 ofBodySettings
. 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 ofBodySettings
. 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 ofBodySettings
.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 ofBodySettings
. 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:
From shape deformation models of the body on which it is located
From a list of
GroundStationMotionSettings
objects, which can be assigned to the ground station settings (see e.g.basic_station()
). These models define time-variability of individual ground stations, in addition to the global shape deformation.
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.