5.4. 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.

5.4.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< boost::shared_ptr< SingleDependentVariableSaveSettings > > dependentVariablesList;

where dependentVariableList is populated as follows:

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

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

Once the list of dependent variables to save has been populated, a DependentVariableSaveSettings object needs to be created and passed to PropagatorSettings:

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

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

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.

5.4.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 teh 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.
  • 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_position_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.
  • 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-tah 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.
  • 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. NOTE: THIS COMPUTATON USES THE AVERAGE RADIUS OF THE CENTRAL BODY, NOT THE LOCAL RADIUS. Defined by creating a SingleDependentVariableSaveSettings object with input periapsis_altitude_dependent_variable as variableType.

5.4.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(
          boost::make_shared< SingleDependentVariableSaveSettings >( variableType , associatedBody , secondaryBody ) );

where:

  • variableType

    PropagationDependentVariables variable that can take the following values:

    Variables returning a 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
    • 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
    • single_torque_dependent_variable
    • single_torque_norm_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).
  • 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.

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 saved to the dependentVariablesList using the following code:

dependentVariablesList.push_back(
    boost::make_shared< SingleAccelerationDependentVariableSaveSettings >(
    accelerationModeType, bodyUndergoingAcceleration, bodyExertingAcceleration, useNorm )

where:

  • accelerationModeType

    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.

Warning

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

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(
    boost::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(
    boost::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