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
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
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
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
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
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
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
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
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
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.
Ground stations, to be assigned to the
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.
See the section on aerodynamic coefficients during the propagation concerning a number of points of attention regarding the aerodynamic coefficients, concerning the frame in which they are defined.
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
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
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.
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 (
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 (
A polyhedron can be used to define both gravity (
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.
TODO: write documentation
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
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.
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
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
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
GroundStationMotionSettingsobjects, 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.