Environment Models#

On this page, we provide an overview of the categories of environment models that are available, how to create them, how to access them, as well as some general notes on their usages, typical pitfalls, hints, etc. How to define the settings for an environment model is discussed here. Summarizing, settings for an environment model are stored in a BodySettings object, a list of which (one for each body) is stored in a BodyListSettings object. We reiterate that these objects themselves do not have any “functionality”, except providing settings that define how to create the actual (potentially interconnected and interdependent environment models). After creating the environment, you can access any relevant functionality of the environment models (ephemerides, rotation models, etc.) outside the context of a propagation.

Note

For details on how to access the environment during a propagation (for custom models, typically), see this page.

In Tudat, the full environment is stored in a SystemOfBodies object, which in turn stores environment models inside Body objects (one for each natural or artificial body in your model). From each object representing a body, you can extract each separate environment model (see list below). For instance, to retrieve the Ephemeris object from the body named Earth, you can use the following:

bodies = ... # Create system of bodies
earth_ephemeris = bodies.get('Earth').ephemeris

Below, we provide an overview of the different types of environment models for which you can define settings, along with links to submodules of environment_setup in the API documentation, where a comprehensive list of all environment model settings can be found. In addition, we list how to extract the resulting environment model from the Body objects.

Aerodynamic coefficients#

The Aerodynamic coefficients module contains functions to create settings objects of type AerodynamicCoefficientSettings 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. 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.

  • The resulting model can be extracted from the Body object using aerodynamic_coefficient_interface, which provides a AerodynamicCoefficientInterface

  • The following code block gives an overview of the steps to define, create, and extract an aerodynamic coefficient model, for the specific example of constant drag (\(C_{D}=1.5\), \(S_{ref}=2\) m2)

    from tudatpy.numerical_simulation import environment_setup

# Create body settings
body_settings =  environment_setup.get_default_body_settings( ... ) # Typical way to instantiate body settings

# Add empty settings for Vehicle, since no default is defined
body_settings.add_empty_settings( 'Vehicle' )

# Add aerodynamic model settings (base class type AerodynamicCoefficientSettings)
body_settings( 'Vehicle' ).aerodynamic_coefficient_settings = environment_setup.aerodynamic_coefficients.constant(
    reference_area = 2.0,
    constant_force_coefficient = [1.5, 0.0, 0.0])

# Create bodies
bodies = environment_setup.create_system_of_bodies(body_settings)

# Extract aerodynamic coefficient model (base class type AerodynamicCoefficientInterface) from Vehicle
vehicle_aerodynamic_coefficient_model = bodies.get( 'Vehicle' ).aerodynamic_coefficient_interface

Atmosphere models#

The Atmosphere models module contains functions to create settings objects of type AtmosphereSettings 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)

  • The resulting model can be extracted from the Body object using atmosphere_model, which provides a AtmosphereModel

  • The following code block gives an overview of the steps to define, create, and extract an atmosphere model, for the specific example of exponential atmosphere drag (\(\rho_{0}=1.225\) kg/m3, \(H=7200\) m)

    from tudatpy.numerical_simulation import environment_setup

# Create body settings
body_settings =  environment_setup.get_default_body_settings( ... ) # Typical way to instantiate body settings

# Modify atmosphere model settings (base class type AtmosphereSettings)
body_settings( 'Earth' ).atmosphere_settings = environment_setup.atmosphere.exponential(
    scale_height = 7200.0,
    surface_density = 1.225 )

# Create bodies
bodies = environment_setup.create_system_of_bodies(body_settings)

# Extract atmosphere model (base class type AtmosphereModel) from Earth
earth_atmosphere_model = bodies.get( 'Earth' ).atmosphere_model

Ephemeris models#

The Ephemeris models module contains functions to create settings objects of type EphemerisSettings 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

  • The resulting model can be extracted from the Body object using ephemeris, which provides a Ephemeris

  • The following code block gives an overview of the steps to define, create, and extract an ephemeris model, for the specific example of ephemeris of the Earth from Spice, with the Sun as ephemeris origin (and J2000 frame orientation).

    from tudatpy.numerical_simulation import environment_setup

# Create body settings
body_settings =  environment_setup.get_default_body_settings( ... ) # Typical way to instantiate body settings

# Modify ephemeris model settings (base class type EphemerisSettings)
body_settings( 'Earth' ).ephemeris_settings = environment_setup.ephemeris.direct_spice(
    frame_origin = 'Sun',
    frame_orientation = 'J2000' )

# Create bodies
bodies = environment_setup.create_system_of_bodies(body_settings)

# Extract ephemeris model (base class type Ephemeris) from Earth
earth_ephemeris_model = bodies.get( 'Earth' ).ephemeris

Gravity field models#

The Gravity field models module contains functions to create settings objects of type GravityFieldSettings 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.

  • The resulting model can be extracted from the Body object extracted using gravity_field_model, which provides a GravityFieldModel (note that gravity field variations are stored inside this object)

  • The following code block gives an overview of the steps to define, create, and extract a gravity field model, for the specific example of a point-mass model with \(\mu=3.986004418\cdot 10^{14}\) m3/s2.

    from tudatpy.numerical_simulation import environment_setup

# Create body settings
body_settings =  environment_setup.get_default_body_settings( ... ) # Typical way to instantiate body settings

# Modify gravity field model settings (base class type GravityFieldSettings)
body_settings( 'Earth' ).gravity_field_settings = environment_setup.gravity_field.central(
    gravitational_parameter = 3.986004418E14 )

# Create bodies
bodies = environment_setup.create_system_of_bodies(body_settings)

# Extract gravity field model (base class type GravityFieldModel) from Earth
earth_gravity_field_model = bodies.get( 'Earth' ).gravity_field_model

Gravity field variation models#

The Gravity field variation models module contains functions to create settings objects of type GravityFieldVariationSettings 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) gravity field.

  • Unlike most environment models, the gravity field variations are stored inside the gravity field model, rather than directly in the body object The gravity field variations can be extracted from the TimeDependentSphericalHarmonicsGravityField object (a derived class of GravityFieldModel) using gravity_field_variation_models, which provides a list of GravityFieldVariationModel objects

  • The following code block gives an overview of the steps to define, create, and extract a gravity field variation model, for the specific example of a constant \(k_{2}=0.301\) Love number, and both the Sun and Moon as tide-raising bodies.

    from tudatpy.numerical_simulation import environment_setup

# Create body settings
body_settings =  environment_setup.get_default_body_settings( ... ) # Typical way to instantiate body settings

# Modify gravity field variation settings (base class type GravityFieldVariationSettings)
# NOTE, this requires the body_settings( 'Earth' ).gravity_field_settings to define a spherical harmonic gravity field
body_settings( 'Earth' ).gravity_field_variation_settings = [
    environment_setup.gravity_field_variation.solid_body_tide(
       tide_raising_body = 'Sun',
       love_number = 0.301,
       degree = 2 ),
    environment_setup.gravity_field_variation.solid_body_tide(
       tide_raising_body = 'Moon',
       love_number = 0.301,
       degree = 2 ) ]

# Create bodies
bodies = environment_setup.create_system_of_bodies(body_settings)

# Extract list of gravity field variation model (base class type GravityFieldVariationModel) from Vehicle
earth_gravity_field_variation_models = bodies.get( 'Earth' ).gravity_field_model.gravity_field_variation_models

Rotation models#

The Rotation models module contains functions to create settings objects of type RotationModelSettings 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).

  • The resulting model can be extracted from the Body object extracted using rotation_model, which provides a RotationalEphemeris

  • The following code block gives an overview of the steps to define, create, and extract a rotation model, for the specific example of a simple rotation model (constant rotation rate and pole orientation), extracted from the Earth’s pole and rotation rate according to the SPICE IAU_Earth frame at the given reference epoch. The resulting rotation model has J2000 as inertial frame, and the identifier IAU_Earth_simplified as Earth-fixed frame.

    from tudatpy.numerical_simulation import environment_setup
from tudatpy.astro import time_conversion

# Create body settings
body_settings =  environment_setup.get_default_body_settings( ... ) # Typical way to instantiate body settings

# Modify rotation model settings (base class type RotationModelSettings)
body_settings( 'Earth' ).rotation_model_settings = environment_setup.rotation_model.simple_from_spice(
    base_frame = 'J2000',
    target_frame = 'IAU_Earth',
    target_frame_spice = 'IAU_Earth_simplified',
    initial_time = time_conversion.date_time_from_iso_string( '2020-09-08T14:00:00.0' ).epoch( ) )

# Create bodies
bodies = environment_setup.create_system_of_bodies(body_settings)

# Extract rotation model (base class type RotationalEphemeris) from Earth
earth_rotation_model = bodies.get( 'Earth' ).rotation_model

Shape models#

The Shape models module contains functions to create settings objects of type BodyShapeSettings 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

  • The resulting model can be extracted from the Body object using shape_model, which provides a BodyShapeModel

  • The following code block gives an overview of the steps to define, create, and extract a shape model, for the specific example of an oblate spheroid shape model with \(R_{e}=3396.2\) km equatorial radius, and flattening \(f=0.00589\)

    from tudatpy.numerical_simulation import environment_setup
from tudatpy.astro import time_conversion

# Create body settings
body_settings =  environment_setup.get_default_body_settings( ... ) # Typical way to instantiate body settings

# Modify shape model settings (base class type BodyShapeSettings)
body_settings( 'Mars' ).shape_settings = environment_setup.shape.oblate_spherical(
    equatorial_radius = 3396.2E3,
    flattening = 0.00589 )

# Create bodies
bodies = environment_setup.create_system_of_bodies(body_settings)

# Extract shape model (base class type ShapeModel) from Earth
mars_shape_model = bodies.get( 'Mars' ).shape_model

Shape deformation models#

The Shape deformation models are 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 models#

The Radiation pressure source and target models are to be assigned to the radiation_source_settings and radiation_pressure_target_settings attribute of BodySettings.

  • These models provide various ways in which to define the radiation flux emitted by a body, and a response of a body to incident radiation pressure. More details are provided on a dedicated page

  • The resulting model can be extracted from the Body object extracted using radiation_pressure_source and radiation_pressure_target, which provides a RadiationSourceModel and a RadiationPressureTargetModel, respectively.

Rigid body properties#

The Rigid body properties are 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.

  • The resulting model can be extracted from the Body object extracted using rigid_body_properties, which provides a RigidBodyProperties

  • When creating a spherical_harmonic() gravity field, and specifying a scaled_mean_moment_of_inertia in the resulting model, rigid body properties consisent with these are automatically created.

Ground station models#

The Ground stations settings are 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.

  • The dictionary of all ground stations is extracted from a Body object using ground_station_list, which has GroundStation objects as dictionary values

Vehicle systems#

The Vehicle systems are currently limited to the vehicle exterior shape, to be assigned to the vehicle_shape_settings attribute of BodySettings.

  • These models define physical characteristics and hardware systems of the vehicle. This functionality is currently in a preliminary state, and its use in the body settings is limited to the vehicle’s exterior shape.

  • The resulting model can be extracted from the Body object extracted using system_models, which provides a VehicleSystems