Use of thrust models - Legacy

Warning

This page is only for the old versions of Tudatpy (< 0.6.x). It is included purely to temporarily support people using such legacy versions of Tudatpy. See thrust and rotation refactor for more information on the changes between 0.6.x and 0.7.

This page deals with the inclusion of a thrust force into the dynamical model. Note that, when using thrust models, it may often be desirable to propagate the mass of the vehicle at the same time (removing mass of the burnt propellant, for instance). Details on how to propagate the mass of a body are given in Mass Dynamics. Details on combining translation and mass propagators is given in Multi-type dynamics.

Thrust acceleration methods - Legacy

In Tudat, the acceleration that a body undergoes due to the addition of thrust can be setup in three different ways:

thrust_from_custom_function(): this method lets you specify a custom variable thrust vector as a function, a constant specific impulse, and the frame in which the thrust is defined (default: inertial orientation).

thrust_and_isp_from_custom_function(): this method adds the capability of specifying a custom variable specific impulse as a function.

thrust_from_direction_and_magnitude(): this method takes ThrustDirectionSettings and ThrustMagnitudeSettings as inputs. These thrust objects are presented below separately for thrust direction and magnitude. The settings are created using factory functions, in the same was as acceleration settings, environment settings, etc.

A typical representative example on how the thrust acceleration can be set up, using the available thrust_from_direction_and_magnitude() function, is provided below:

The Tudat(Py) API docs give more details on the ThrustDirectionSettings and ThrustMagnitudeSettings classes.

# Create the dictionary containing the thrust acceleration
accelerations_on_vehicle_dict = {
    "Vehicle": [
        propagation_setup.acceleration.thrust_from_direction_and_magnitude(
            thrust_direction_settings,
            thrust_magnitude_settings
        )
    ]
}
# Setup the accelerations as acting on the Vehicle
acceleration_dict = {"Vehicle": accelerations_on_vehicle_dict}
# Create the acceleration model in the system of bodies
acceleration_model = propagation_setup.create_acceleration_models(
    system_of_bodies, accelerations_on_vehicle_dict, bodies_to_propagate, central_bodies
)

std::shared_ptr< ThrustDirectionGuidanceSettings > thrustDirectionSettings;
std::shared_ptr< ThrustMagnitudeSettings > thrustMagnitudeSettings;

SelectedAccelerationMap accelerationSettingsMap;
accelerationSettingsMap[ "Vehicle" ][ "Vehicle" ].push_back( std::make_shared< ThrustAccelerationSettings >( thrustDirectionSettings, thrustMagnitudeSettings ) );

In the above code snippet, note that we define the thrust acceleration as one that the vehicle exerts on itself.

Thrust direction - Legacy

Below, the different methods that have been implemented to define the direction of the thrust are outlined. All of these methods return a ThrustDirectionSettings object.

Note that these settings are only relevant if you use the thrust_from_direction_and_magnitude() function.

Note

In all of these methods, the thrust direction that is defined is always in the inertial frame, either directly or indirectly. It is important to realize that, when specifying a thrust direction, the vehicle orientation itself is automatically defined. The direction of the thrust in the body-fixed frame can be additionally defined when specifying the thrust magnitude (note that this design is currently under review, and may well be refactored in the near future).

Note

In Tudat(Py), a distinction is made between the thrust orientation and the thrust direction. The thrust direction refers to a unit vector that defines along which direction the thrust acceleration acts, defined in the inertial frame. The thrust orientation refers to a rotation matrix between the body-fixed frame to the inertial frame.

Thrust direction from state guidance settings

In various simplified cases, the thrust direction can be assumed to be in line with either the position or velocity vector of the body undergoing thrust w.r.t. some (central) body.

This thrust direction setting is shown on the Tudat(Py) API docs page of the thrust_direction_from_state_guidance() function.

Custom thrust direction settings

For a generalized thrust direction guidance, the thrust direction can be defined as an arbitrary function of time. This allows a broad range of options to be defined, at the expense of increased complexity — somehow this thrust direction needs to be manually defined.

A custom thrust direction can be defined in the inertial frame as on the Tudat(Py) API docs page of the custom_thrust_direction() function.

Warning

When using this option, the inertial to body-fixed rotation cannot be unambiguously defined. If you require this rotation (for instance when you also incorporate aerodynamic forces), the custom_thrust_orientation() option should be used instead.

Warning

The direction vector that is being returned by the custom function should be a unit vector.

Custom thrust orientation settings

Thrust orientation settings can also be created trough a custom function that returns this time not the direction but the orientation of the thrust.

This thrust orientation needs to be provided through a rotation matrix representing the rotation from body-fixed thrust direction to the inertial thrust direction.

The use of this orientation setting is shown on the Tudat(Py) API docs page of the custom_thrust_orientation() function.

Thrust direction from existing orientation

The orientation of the vehicle is in some cases already defined. This could be because of the aerodynamic guidance or the propagation of rotational dynamics. In this context, the thrust direction can be computed from the body-fixed orientation.

In such a case, the thrust direction is computed from the existing vehicle orientation. Do note that an additional angle from the vehicle can be defined, for instance in case Thrust Vectoring Control is used. This angle, the body fixed thrust direction, can be defined in the ThrustMagnitudeSettings class.

How to use this thrust orientation setting is shown on the Tudat(Py) API docs page of the thrust_from_existing_body_orientation() function.

Thrust magnitude - Legacy

Below, the different methods that have been implemented to define the magnitude of the thrust are outlined. All of these methods return a ThrustMagnitudeSettings object.

Note that these settings are only relevant if you use the thrust_from_direction_and_magnitude() function.

Constant thrust magnitude

Thrust magnitude settings may be used to specified a constant thrust (in Newtons) and a constant specific impulse (in seconds). Optionally, a constant direction of the thrust with respect to the body can also be specified. When a time-varying body-fixed thrust is required, for instance to define Thrust Vectoring Control, the custom_thrust_magnitude() option should be used.

An example of how to use this constant thrust magnitude setting is shown on the Tudat(Py) API docs page of the constant_thrust_magnitude() function.

Custom thrust magnitude

Thrust magnitude settings can also be created trough a custom function that returns the magnitude in Newton as a function of time.

These settings can additionally be used to first specify whether the engine is on or off. This can save precious CPU time by avoiding to waste CPU time computing the thrust magnitude, by first checking whether the engine is indeed turned on. A so-called thrust reset function can also be specified, so that Tudat(Py) calls it first, before calling any of the other thrust magnitude-related functions. This thrust reset function can for instance be used to update all relevant aspects of the environment.

How to use this custom thrust magnitude setting is shown on the Tudat(Py) API docs page of the custom_thrust_magnitude() function.

Note

When FromFunctionThrustMagnitudeSettings are used, it is recommended to setup a custom thrust class, encompassing all of the following functions: thrust_magnitude_function(), specific_impulse_function(), and is_engine_on_function(). Potentially, one may also wish to include the following functions in this class: body_fixed_thrust_direction(), custom_thrust_reset_function(), and/or thrust_direction_function(). The idea being that using one global user-defined thrust class gives more control on all of the aspects that have to be updated to define whether thrust is turned on, what is its magnitude, and orientation.

Thrust with the environment - Legacy

This section deals with selected cases in which the thrust model is integrated with the simulated environment.

Mass rate settings - Legacy

If thrust is added to the model, the vehicle is most likely going to loose mass (its propellant) over time.

A mass rate setting is available in Tudat(Py) to make the loss of mass of the vehicle consistent with the magnitude of the thrust and its specific impulse over time. This is available trough the from_thrust() function, which has to be setup after the acceleration models are defined, as follows:

# Create the acceleration model, which contains the thrust of the vehicle on itself
acceleration_model = propagation_setup.create_acceleration_models(
    system_of_bodies, accelerations_on_vehicle_dict, bodies_to_propagate, central_bodies
)

# Define the mass rate settings of the Vehicle from its thrust
mass_rate_settings = {
    "Vehicle": [propagation_setup.mass_rate.from_thrust()]
}

# Create the mass rate model
mass_rate_models = propagation_setup.create_mass_rate_models(
    system_of_bodies,
    mass_rate_settings,
    acceleration_model
)

// Oops, this snippet still has to be implemented... %!

More details and options on mass propagation are provided on the Mass Dynamics page.

Note

The specific impulse is in principle only used for mass rate settings. If the mass is not to be propagated, or if custom mass rate settings are used, the specific impulse input of the thrust magnitude settings can in most cases be set to any value without impacting the results.

Thrust and rotational dynamics - Legacy

For support in this functionality using the Tudatpy legacy versions, please contact the Tudat development team.

Thrust Vectoring Control - Legacy

In some cases, the thrust may not be aligned with the orientation of the vehicle that has been defined.

For instance, if Thrust Vectoring Control (TVC) is to be used, with a nozzle deflection that varies over time, the true thrust direction will vary from the x-axis of the vehicle.

In Tudat(Py), this deviation in thrust direction from the vehicle can be defined in the body-fixed frame through the thrust magnitude definition. When using the constant_thrust_magnitude(), a constant body-fixed thrust direction can be defined where, when using the custom_thrust_magnitude(), this body-fixed thrust direction can be defined as a function of time, allowing TVC to be incorporated.

This can be done as follows:

# Define constant thrust magnitude settings with a deviation from the body-fixed x-axis of 0.5 rad
thrust.constant_thrust_magnitude(
    thrust_magnitude=1.5e3,
    specific_impulse=315,
    body_fixed_thrust_direction=[np.cos(0.5), np.sin(0.5), 0]
)

# Define a variable deflection of TVC from the centreline that varies with time from -0.5rad to +0.5rad
def body_fixed_thrust_direction_function(time):
    TVC_deflection_angle = 0.5*np.sin(time*np.pi/1000)
    return [np.cos(TVC_deflection_angle), np.sin(TVC_deflection_angle), 0]

# Define custom thrust magnitude settings with the variable TVC deflection
thrust.custom_thrust_magnitude( 
	thrust_magnitude_function = lambda t: 1.5e3, 
	specific_impulse_function = lambda t: 315, 
	body_fixed_thrust_direction = body_fixed_thrust_direction_function)

// Oops, this snippet still has to be implemented... %!

Thrust and aerodynamic guidance - Legacy

This section elaborates on the definition of the thrust orientation in case aerodynamics are also taken into account in the simulation model.

For instance, let’s assume that an aerodynamic coefficient interface is set up, in which the aerodynamic coefficients depend on the vehicle’s orientation (angle of attack/sideslip), and that an aerodynamic acceleration is used in the propagation. The orientation of the vehicle must then somehow be specified. In this section, we will discuss the option of defining the orientation of the vehicle for thrust and aerodynamic either separately, or linked to one another.

Separate orientations - Legacy

For support in this functionality using the Tudatpy legacy versions, please contact the Tudat development team.

Thrust direction from aerodynamics - Legacy

For support in this functionality using the Tudatpy legacy versions, please contact the Tudat development team.