3.3. Propagator Settings: Dependent Variables¶

By default, the DynamicsSimulator propagates the state of a body which uniquely defines its position and velocity. However, it is possible to define a number of dependent variables that are derived from such state. These dependent variables can be used as termination conditions as discussed in Propagator Settings: Termination Settings or saved for further post-processing. This page describes the dependent variables currently available and how these are retrieved from Tudat.

The general procedure consists of defining an object of class DependentVariableSaveSettings, and then feeding it to a derived class of PropagatorSettings.

class DependentVariableSaveSettings¶

// Create object with list of dependent variables
std::shared_ptr< DependentVariableSaveSettings > dependentVariablesToSave =
std::make_shared< DependentVariableSaveSettings >( dependentVariablesList );

// Create propagation settings.
std::shared_ptr< TranslationalStatePropagatorSettings< double > > propagatorSettings =
std::make_shared< TranslationalStatePropagatorSettings< double > >
( centralBodies, accelerationModelMap, bodiesToPropagate, systemInitialState,
  terminationSettings, propagator, dependentVariablesToSave );

This is the general class describing the dependent variables to be saved during propagation. Its only input is a list of dependent variables, which can be of many different types. In the sections below, you will find a thorough description of what can be added to said list.

Note

In the example above, the TranslationalStatePropagatorSettings derived class is used. Please note that any of the derived classes described in Propagator Settings: Basics can be used, as long as these support dependent variable saving.

3.3.1. Saving Dependent Variables¶

The dependent variables are computed during the body propagation, thus the user must provide a list of dependent variables to save prior creating the DynamicsSimulator:

// Define list of dependent variables to save.
std::vector< std::shared_ptr< SingleDependentVariableSaveSettings > > dependentVariablesList;

where dependentVariableList is populated as follows:

dependentVariablesList.push_back(
          std::make_shared< SingleDependentVariableSaveSettings >( variableType , associatedBody , secondaryBody ) );

The details of the creation of the settings SingleDependentVariableSaveSettings object are discussed below.

3.3.2. Available Dependent Variables¶

Below, we provide a list of all dependent variables that can be saved using Tudat, with a link to the corresponding (derived class) of SingleDependentVariableSaveSettings, and associated input. In some cases, the requirements on the environment for a variable to be saved are not necesarilly intuitive. In those cases, we mention the requirements explicitly.

Mach number in atmosphere. Requires an aerodynamic acceleration to be acting on the vehicle. Defined by creating a SingleDependentVariableSaveSettings object with input mach_number_dependent_variable as variableType.

Altitude above body exerting aerodynamic acceleration. Requires an aerodynamic acceleration to be acting on the vehicle. Defined by creating a SingleDependentVariableSaveSettings object with input altitude_dependent_variable as variableType.

Airspeed in atmosphere of body exerting aerodynamic acceleration. Requires an aerodynamic acceleration to be acting on the vehicle. Defined by creating a SingleDependentVariableSaveSettings object with input airspeed_dependent_variable as variableType.

Local density in atmosphere of body exerting aerodynamic acceleration (at position of body undergoing acceleration). Requires an aerodynamic acceleration to be acting on the vehicle. Defined by creating a SingleDependentVariableSaveSettings object with input local_density_dependent_variable as variableType.

Local temperature in atmosphere of body exerting aerodynamic acceleration (at position of body undergoing acceleration). Requires an aerodynamic acceleration to be acting on the vehicle. Defined by creating a SingleDependentVariableSaveSettings object with input local_temperature_dependent_variable as variableType.

Local dynamic pressure felt by the vehicle based on the current velocity and atmospheric conditions, i.e., computed with \(\frac{1}{2} \rho V^2\). Requires an aerodynamic acceleration to be acting on the vehicle. Defined by creating a SingleDependentVariableSaveSettings object with input local_dynamic_pressure_dependent_variable as variableType.

Local aerodynamic heat rate felt by the vehicle based on the current velocity and atmospheric conditions, i.e., computed with \(\frac{1}{2} \rho V^3\). Requires an aerodynamic acceleration to be acting on the vehicle. Defined by creating a SingleDependentVariableSaveSettings object with input local_aerodynamic_heat_rate_dependent_variable as variableType.

Relative speed (scalar velocity) of body w.r.t. a second body (between centers of mass). Defined by creating a SingleDependentVariableSaveSettings object with input relative_speed_dependent_variable as variableType.

Relative velocity of body w.r.t. a second body (between centers of mass). Defined by creating a SingleDependentVariableSaveSettings object with input relative_velocity_dependent_variable as variableType.

Relative distance of body from a second body (between centers of mass). Defined by creating a SingleDependentVariableSaveSettings object with input relative_distance_dependent_variable as variableType.

Relative position of body w.r.t. a second body (between centers of mass). Defined by creating a SingleDependentVariableSaveSettings object with input relative_position_dependent_variable as variableType.

Radiation pressure coefficient of body, due to radiation exerted by another body. Defined by creating a SingleDependentVariableSaveSettings object with input radiation_pressure_dependent_variable as variableType.

Total acceleration acting on a body. Defined by creating a SingleDependentVariableSaveSettings object with input total_acceleration_dependent_variable as variableType.

Total torque acting on a body. Defined by creating a SingleDependentVariableSaveSettings object with input total_torque_dependent_variable as variableType.

Total mass rate of body. Requires mass to be one of the numerically propagated variables. Defined by creating a SingleDependentVariableSaveSettings object with input total_mass_rate_dependent_variables as variableType.

Norm of total acceleration acting on a body. Defined by creating a SingleDependentVariableSaveSettings object with input total_acceleration_norm_dependent_variable as variableType.

Norm of total torque acting on a body. Defined by creating a SingleDependentVariableSaveSettings object with input total_torque_norm_dependent_variable as variableType.

Norm of single acceleration acting on a body. Defined by creating a SingleAccelerationDependentVariableSaveSettings, with useNorm set to true.

Single acceleration acting on a body. Defined by creating a SingleAccelerationDependentVariableSaveSettings, with useNorm set to false.

Spherical harmonic acceleration terms acting on a body, thus the full list of accelerations for each spherical harmonics term. Defined by creating a SphericalHarmonicAccelerationTermsDependentVariableSaveSettings object.

Variation in spherical harmomic acceleration acting on a body. Defined by creating a SingleVariationSphericalHarmonicAccelerationSaveSettings object.

Variation in spherical harmomic acceleration terms acting on a body, thus the full list of accelerations for each spherical harmonics term.. Defined by creating a SingleVariationSingleTermSphericalHarmonicAccelerationSaveSettings object.

Norm of single torque acting on a body. Defined by creating a SingleTorqueDependentVariableSaveSettings, with useNorm set to true.

Single torque acting on a body. Defined by creating a SingleTorqueDependentVariableSaveSettings, with useNorm set to false.

Aerodynamic force coefficients of a body. Defined by creating a SingleDependentVariableSaveSettings object with input aerodynamic_force_coefficients_dependent_variable as variableType.

Aerodynamic moment coefficients of a body. Defined by creating a SingleDependentVariableSaveSettings object with input aerodynamic_moment_coefficients_dependent_variable as variableType.

Rotation matrix to body-fixed frame of a body. Defined by creating a SingleDependentVariableSaveSettings object with input rotation_matrix_to_body_fixed_frame_variable as variableType.

Rotation matrix between frames used for aerodynamics. Defined by creating a IntermediateAerodynamicRotationVariableSaveSettings class, with the two frames (start and end frames) provided as input. The following frames can be used (see Mooij, 1994 for details):

Inertial frame

Body-fixed (corotating) frame of central body.

Vehicle-centered vertical frame

Vehicle-centered trajectory frame

Vehicle-centered aerodynamic frame

Vehicle-fixed body frame

Rotation angle used for aerodynamics. Defined by creating a BodyAerodynamicAngleVariableSaveSettings class, with the desired angle provided as input. The following angles can be used (see Mooij, 1994 for details):

Latitude angle

Longitude angle

Heading angle

Flight-path angle

Angle of attack

Sideslip angle

Bank angle

Airspeed-based velocity vector (body velocity w.r.t. wind vector, assumes corotating atmosphere if no wind model is defined). Requires an aerodynamic acceleration to be acting on the vehicle. Defined by creating a SingleDependentVariableSaveSettings object with input body_fixed_airspeed_based_velocity_variable as variableType.

Groundspeed-based velocity vector (equal to airspeed-based velocity in absence of wind). Requires an aerodynamic acceleration to be acting on the vehicle. Defined by creating a SingleDependentVariableSaveSettings object with input body_fixed_groundspeed_based_velocity_variable as variableType.

G-load induced by aerodynamic acceleration. Requires an aerodynamic acceleration to be acting on the vehicle. Defined by creating a SingleDependentVariableSaveSettings object with input total_aerodynamic_g_load_variable as variableType.

Stagnation point-heat flux induced by atmospheric friction. Requires an aerodynamic acceleration to be acting on the vehicle, and a nose radius to be defined on the vehicle. Defined by creating a SingleDependentVariableSaveSettings object with input stagnation_point_heat_flux_dependent_variable as variableType.

Geodetic latitude (w.r.t. central body). Requires an aerodynamic acceleration to be acting on the vehicle. Defined by creating a SingleDependentVariableSaveSettings object with input geodetic_latitude_dependent_variable as variableType.

Control surface deflection of a given aerodynamic control surface of body. Defined by creating a SingleDependentVariableSaveSettings object with input control_surface_deflection_dependent_variable as variableType.

Keplerian state of body. Defined by creating a SingleDependentVariableSaveSettings object with input keplerian_state_dependent_variable as variableType.

Modified equinoctial state of body. Defined by creating a SingleDependentVariableSaveSettings object with input modified_equinocial_state_dependent_variable as variableType. The value of the parameter I is automatically chosen as +1 or -1, depending on whether the inclination is smaller or larger than 90 degrees.

Relative Cartesian position, based on position of vehicle and orbited body, expressed in the body fixed frame. Defined by creating a SingleDependentVariableSaveSettings object with input body_fixed_relative_cartesian_position as variableType.

Relative spherical position, based on position of vehicle and orbited body, expressed in the body fixed frame. Defined by creating a SingleDependentVariableSaveSettings object with input body_fixed_relative_spherical_position as variableType.

Rotation of LVLH to inertial frame, Rotation matrix from Local Vertical, Local Horizontal (LVLH) frame of body to inertial frame. Defined by creating a SingleDependentVariableSaveSettings object with input lvlh_to_inertial_frame_rotation_dependent_variable as variableType.

Periapsis altitude, based on current osculating elements. Defined by creating a SingleDependentVariableSaveSettings object with input periapsis_altitude_dependent_variable as variableType.

Warning

The computaton of the periapsis altitude uses the average radius of the central body, not the local radius.

3.3.3. Setting Up Dependent Variables¶

The framework discussed in the previous section explains how the dependentVariablesList is populated and passed to the PropagatorSettings. The goal of this section is to list the available dependent variables and to explain how these are pushed to the dependentVariablesList.

class SingleDependentVariableSaveSettings¶

This base-class is a generic method to retrieve a large number of dependent variables that are not classified under a particular group. Variables are saved to the dependentVariablesList using the following code:

dependentVariablesList.push_back(
          std::make_shared< SingleDependentVariableSaveSettings >( variableType , associatedBody , secondaryBody, componentIndex ) );

where:

variableType
PropagationDependentVariables variable that can take the following values:
Variables returning dependent variable of size 1:

mach_number_dependent_variable

altitude_dependent_variable

airspeed_dependent_variable

local_density_dependent_variable

relative_speed_dependent_variable (secondary body defines body w.r.t. which the relative speed is computed)

relative_distance_dependent_variable (secondary body defines body w.r.t. which the relative distance is computed)

radiation_pressure_dependent_variable (secondary body defines the source of radiation for which the readiation pressure coefficient is to be provided)

total_aerodynamic_g_load_variable (secondary body defines body with atmosphere that exerts the aerodynamic acceleration that induces the g-load)

stagnation_point_heat_flux_dependent_variable

local_temperature_dependent_variable

local_dynamic_pressure_dependent_variable

local_aerodynamic_heat_rate_dependent_variable

geodetic_latitude_dependent_variable

control_surface_deflection_dependent_variable (secondary body defines name of control surface for which deflection is to be provided)

total_mass_rate_dependent_variables

periapsis_altitude_dependent_variable (secondary body defines body w.r.t. which the periapsis altitude is computed)

total_torque_norm_dependent_variable

Variables returning a multi-valued dependent variable:

relative_position_dependent_variable (secondary body defines body w.r.t. which the relative position is computed)

relative_velocity_dependent_variable (secondary body defines body w.r.t. which the relative velocity is computed)

body_fixed_airspeed_based_velocity_variable

total_acceleration_norm_dependent_variable

total_acceleration_dependent_variable

aerodynamic_force_coefficients_dependent_variable

aerodynamic_moment_coefficients_dependent_variable

lvlh_to_inertial_frame_rotation_dependent_variable (secondary body defines body w.r.t. which the state is computed when determining the matrix, taken as SSB if left empty)

rotation_matrix_to_body_fixed_frame_variable

total_torque_dependent_variable

body_fixed_groundspeed_based_velocity_variable

keplerian_state_dependent_variable (secondary body defines body w.r.t. which the Keplerian state is computed)

modified_equinocial_state_dependent_variable (secondary body defines body w.r.t. which the modified equinoctial state is computed)

body_fixed_relative_cartesian_position (secondary body defines body w.r.t. which the Cartesian state is computed)

body_fixed_relative_spherical_position (secondary body defines body w.r.t. which the spherical state is computed)
associatedBody

Indicates to which body the saved dependent variables are associated.
secondaryBody

Optional argument that provides a secondary body that may be necessary to save the dependent variable. By default, this argument is empty. In the list above, it is indicated which parameters require a secondaryBody to be defined, and what this parameter represents.
componentIndex

int denoting which element of the acceleration vector is to be saved. Default value is -1, which means all elements are saved. Make sure that this value is compatible with the size of variableType.

class SingleAccelerationDependentVariableSaveSettings¶

This derived class is used to retrieve acceleration-related dependent variables. A large number of acceleration models are supported and both the acceleration-norm and the acceleration-vector can be saved. Variables are added to the dependentVariablesList using the following code:

dependentVariablesList.push_back(
    std::make_shared< SingleAccelerationDependentVariableSaveSettings >(
    accelerationModelType, bodyUndergoingAcceleration, bodyExertingAcceleration, useNorm, componentIndex );

where:

accelerationModelType
AvailableAcceleration variable that defines the type of acceleration that must be retrieved. It can take the following values:
undefined_acceleration

central_gravity

aerodynamic

cannon_ball_radiation_pressure

spherical_harmonic_gravity

mutual_spherical_harmonic_gravity

third_body_central_gravity

third_body_spherical_harmonic_gravity

third_body_mutual_spherical_harmonic_gravity

thrust_acceleration
bodyUndergoingAcceleration

std::string variable that indicates the body that experiences the acceleration that needs to be retrieved. Make sure that the body’s name is listed in NamedBodyMap.
bodyExertingAcceleration

std::string variable that indicates the body that exerts the acceleration that needs to be retrieved on bodyUndergoingAcceleration. Make sure that the body’s name is listed in NamedBodyMap.
useNorm

bool variable that indicates if the norm of the acceleration (true) or the acceleration vector (false) must be retrieved.
componentIndex

int denoting which element of the acceleration vector is to be saved. Default value is -1, which means all elements are saved.

Warning

Make sure that the selected bodyExertingAcceleration is compatible with the accelerationModelType.

class SphericalHarmonicAccelerationTermsDependentVariableSaveSettings¶

This derived class is used to save contributions to spherical harmonic acceleration at separate degree/order. This type of variable is added to the dependentVariablesList using the following code:

dependentVariablesList.push_back(
    std::make_shared< SphericalHarmonicAccelerationTermsDependentVariableSaveSettings >(
    bodyUndergoingAcceleration, bodyExertingAcceleration, maximumDegree, maximumOrder, componentIndex );

bodyUndergoingAcceleration

std::string variable that indicates the body that experiences the gravitational acceleration. Make sure that the body’s name is listed in NamedBodyMap.
bodyExertingAcceleration

std::string variable that indicates the body that exerts the gravitational acceleration that needs to be retrieved on bodyUndergoingAcceleration. Make sure that the body’s name is listed in NamedBodyMap.
maximumDegree

int denoting the maximum degree of the spherical harmonics model, for which an acceleration has to be saved.
maximumOrder

int denoting the maximum order of the spherical harmonics model, for which an acceleration has to be saved. Make sure that this value is smaller or equal to maximumDegree.
componentIndex

int denoting which element of the acceleration vector is to be saved. Default value is -1, which means all elements are saved.

class SingleVariationSphericalHarmonicAccelerationSaveSettings¶

This derived class is used to save contributions to the variation of the spherical harmonic acceleration. This type of variable is added to the dependentVariablesList using the following code:

dependentVariablesList.push_back(
    std::make_shared< SingleVariationSphericalHarmonicAccelerationSaveSettings >(
    bodyUndergoingAcceleration, bodyExertingAcceleration, deformationType, identifier );

bodyUndergoingAcceleration

std::string variable that indicates the body that experiences the gravitational acceleration. Make sure that the body’s name is listed in NamedBodyMap.
bodyExertingAcceleration

std::string variable that indicates the body that exerts the gravitational acceleration that needs to be retrieved on bodyUndergoingAcceleration. Make sure that the body’s name is listed in NamedBodyMap.
deformationType
BodyDeformationTypes variable defining the type of gravity field variation. The supported values are:
basic_solid_body

tabulated_variation
identifier

std::string variable denoting the identifier for gravity field variation.

class SingleVariationSingleTermSphericalHarmonicAccelerationSaveSettings¶

This derived class is used to save contributions to the variation of the spherical harmonic acceleration at separate degree/order. This type of variable is added to the dependentVariablesList using the following code:

dependentVariablesList.push_back(
    std::make_shared< SingleVariationSingleTermSphericalHarmonicAccelerationSaveSettings >(
    bodyUndergoingAcceleration, bodyExertingAcceleration, maximumDegree, maximumOrder, deformationType, identifier );

bodyUndergoingAcceleration

std::string variable that indicates the body that experiences the gravitational acceleration. Make sure that the body’s name is listed in NamedBodyMap.
bodyExertingAcceleration

std::string variable that indicates the body that exerts the gravitational acceleration that needs to be retrieved on bodyUndergoingAcceleration. Make sure that the body’s name is listed in NamedBodyMap.
maximumDegree

int denoting the maximum degree of the spherical harmonics model, for which an acceleration has to be saved.
maximumOrder

int denoting the maximum order of the spherical harmonics model, for which an acceleration has to be saved. Make sure that this value is smaller or equal to maximumDegree.
deformationType
BodyDeformationTypes variable defining the type of gravity field variation. The supported values are:
basic_solid_body

tabulated_variation
identifier

std::string variable denoting the identifier for gravity field variation.

class SingleTorqueDependentVariableSaveSettings¶

This derived class is used to retrieve torque-related dependent variables. A number of torque models are supported and both the norm and the vector form of the torque can be saved. Variables are added to the dependentVariablesList using the following code:

dependentVariablesList.push_back(
    std::make_shared< SingleTorqueDependentVariableSaveSettings >(
    torqueModelType, bodyUndergoingTorque, bodyExertingTorque, useNorm, componentIndex );

where:

torqueModelType
AvailableTorque variable that defines the type of torque that must be retrieved. It can take the following values:
underfined_torque

second_order_gravitational_torque

aerodynamic_torque
bodyUndergoingAcceleration

std::string variable that indicates the body that experiences the torque that needs to be retrieved. Make sure that the body’s name is listed in NamedBodyMap.
bodyExertingAcceleration

std::string variable that indicates the body that exerts the torque that needs to be retrieved on bodyUndergoingAcceleration. Make sure that the body’s name is listed in NamedBodyMap.
useNorm

bool variable that indicates if the norm of the torque (true) or the torque vector (false) must be retrieved.
componentIndex

int denoting which element of the torque vector is to be saved. Default value is -1, which means all elements are saved.

Warning

Make sure that the selected bodyExertingAcceleration is compatible with the accelerationModelType.

class IntermediateAerodynamicRotationVariableSaveSettings¶

This derived class is used to retrieve the rotation matrix between two desired frames. Variables are saved to the dependentVariablesList using the following code:

dependentVariablesList.push_back(
    std::make_shared< IntermediateAerodynamicRotationVariableSaveSettings >(
        associatedBody, baseFrame, targetFrame )

where:

associatedBody

std::string variable that indicates the body for which a rotation matrix is to be saved. Make sure that the body’s name is listed in NamedBodyMap.
baseFrame
AerodynamicsReferenceFrames variable indicates the frame from which the rotation is to be saved. The following frames are available:
- inertial_frame
- corotating_frame
- vertical_frame
- trajectory_frame
- aerodynamic_frame
- body_frame
targetFrame

AerodynamicsReferenceFrames variable indicates the frame to which the rotation is to be saved. The available frames are listed above.

class BodyAerodynamicAngleVariableSaveSettings¶

This derived class is used to retrieve a number of rotation angles. Variables are saved to the dependentVariablesList using the following code:

dependentVariablesList.push_back(
    std::make_shared< BodyAerodynamicAngleVariableSaveSettings >(
        associatedBody, angle )

where:

associatedBody

std::string variable that indicates the body for which the angle is to be saved. Make sure that the body’s name is listed in NamedBodyMap.
angle
AerodynamicsReferenceFrameAngles variable that provides the angle to be saved. The following angles can be saved using this method:
- latitude_angle
- longitude_angle
- heading_angle
- flight_path_angle
- angle_of_attack
- angle_of_sideslip
- bank_angle