propagation
¶
Functionalities and utilities of propagation objects.
This module provides functionalities for propagation settings objects. It also contains some utility functions that extract specific quantities from propagation settings and body objects. Note that the classes in this module are rarely created manually, but are instead created by the functionality in the propagation_setup module.
Functions¶

Function to get the translational states of a set of bodies, with respect to some set of central bodies, at the requested time. 
Function to compute an initial rotational state for which the proper mode of rotation is damped. 

Function to retrieve the initial state for a list of propagator settings. 


Construct a dictionarylike object (DependentVariableDictionary) which maps which maps dependent variables to their time histories. 
 get_state_of_bodies(bodies_to_propagate: list[str], central_bodies: list[str], body_system: tudatpy.kernel.numerical_simulation.environment.SystemOfBodies, initial_time: float) numpy.ndarray[numpy.float64[m, 1]] ¶
Function to get the translational states of a set of bodies, with respect to some set of central bodies, at the requested time.
Function to get the translational states of a set of bodies, with respect to some set of central bodies, at the requested time. This function is typically used to extract an initial state for a propagation of a set of bodies, for which the initial state is extracted from the existing ephemerides of the bodies.
 Parameters:
bodies_to_propagate (SystemOfBodies) – List of names of bodies for which the state is to be extracted
central_bodies (list[str]) – List of central bodies, w.r.t. which the states are to be computed (in the same order as
bodies_to_propagate
)bodies_to_propagate – System of bodies that define the environment
initial_time (float) – Time at which the states are to be extracted from the environment
 Returns:
Vector of size \(6\times N\), with the translational states of each entry of body from
bodies_to_propagate
w.r.t. the corresponding central body incentral_bodies
. Return type:
 get_damped_proper_mode_initial_rotational_state(bodies: tudatpy.kernel.numerical_simulation.environment.SystemOfBodies, propagator_settings: tudat::propagators::SingleArcPropagatorSettings<double, double>, body_mean_rotational_rate: float, dissipation_times: list[float], propagate_undamped: bool = True) tudatpy.kernel.numerical_simulation.propagation.RotationalProperModeDampingResults ¶
Function to compute an initial rotational state for which the proper mode of rotation is damped.
Function to compute an initial rotational state for which the proper mode of rotation is damped, using the algorithm used by Rambaux et al. (2010) to compute an initial rotational state for Phobos. This algorithm propagates the dynamics of the system a number of times, with the settings specified by the user and a specific modification to damp the proper mode. Since a number of propagations are performed by this function, it may take some time to run. Specifically, the algorithm works as follows:
Introduce a damping torque (see below) to damp the proper mode, with damping time \(\tau_{d}\)
Propagate the dynamics forward in time for a period of \(10\tau_{d}\)
Remove the virtual torque, and propagate the dynamics back to the initial time \(t_{0}\)
Repeat the above for the list of damping times provided by the user
The state after the final backwards propagation to \(t_{0}\) is provided as output by this function, to be used as damped initial state. The output from this function also provides the user access to the full state history and dependent variable history of the forward and backward propagations, to allow a user to track and validate the pgress of the algorithm.
The damping torque \(\Gamma\) is defined as follows:
\[\begin{split}\boldsymbol{\Gamma}= \frac{1}{\tau_{d}}\mathbf{I}\begin{pmatrix}\omega_{x}\\ \omega_{y}\\ \omega_{x}\omega_{p} \end{pmatrix}\end{split}\]where :math:mathbf{I}` is the body’s inertia tensor (in its bodyfixed frame), \(\tau_{d}\) the damping time of the current propagation, and \(\omega_{x}, \omega_{y}, \omega_{z}\) the body’s current rotation about its bodyfixed, x, y and zaxes, respectively. The damping torque is implemented to damp out all rotations along the bodyfixed x and yaxes, and any deviations from constant rotation with frequency :omega_{p}: about the bodyfixed zaxis.
Note
The mean rotation rate of the body \(\omega_{p}\) is a userdefined input, and must be tuned to the dynamics of the system.
 Parameters:
bodies (SystemOfBodies) – Set of body objects that defines the environment
propagator_settings (SingleArcPropagatorSettings) – Propagator settings for the dynamics of which the initial rotational state is to be damped. These propagator settings must be for rotational dynamics only, or for multitype rotational dynamics that contains rotational dynamics for a single body (e.g. translationalrotational dynamics for a single body)
body_mean_rotational_rate (float) – Mean rotational rate \(\omega_{p}\) to which the damping algorithm will force the bodyfixed rotation about its zaxis.
dissipation_times (list[ float ]) – List of damping times \(\tau_{d}\) for which the algorithm is to be run. Note that this list should be organized in ascending order for the algorithm to perform properly
propagate_undamped (bool, default = True) – Boolean defining whether the first forward/backward propagation performed by the damping algorithm has damping turned off (damping turned off if True, damping turned on if False). Propagating without any damping before starting the damping algorithm is useful for verification purposes, but not required for the algorithm itself.
 Returns:
Object that contains the results of the damping algorithm (final damped rotational state, and forward/backward propagation results).
 Return type:
DampedInitialRotationalStateResults
 combine_initial_states(propagator_settings_per_type: dict[tudat::propagators::IntegratedStateType, list[tudat::propagators::SingleArcPropagatorSettings<double, double>]]) numpy.ndarray[numpy.float64[m, 1]] ¶
Function to retrieve the initial state for a list of propagator settings.
Function to retrieve the initial state for a list of propagator settings. This way, the initial state for different quantities to be propagated (e.g., translational state, rotational state, mass) are retrieved and organized in a single container.
 Parameters:
propagator_settings_per_type (dict) – Propagator settings where the type of propagation is reported as key and the respective list of propagator settings as value.
 Returns:
Vector of initial states, sorted in order of IntegratedStateType, and then in the order of the vector of SingleArcPropagatorSettings of given type.
 Return type:
 create_dependent_variable_dictionary(dynamics_simulator: SingleArcSimulator) DependentVariableDictionary [source]¶
Construct a dictionarylike object (DependentVariableDictionary) which maps which maps dependent variables to their time histories. See the documentation of DependentVariableDictionary to learn more about how time histories are saved, and how the time history of a given dependent variable can be retrieved.
 Parameters:
dynamics_simulator (SingleArcSimulator) – SingleArcSimulator object containing the results of the numerical propagation
Returns –
dependent_variable_dictionary (DependentVariableDictionary) – DependentVariableDictionary of propagation
Enumerations¶
Enumeration of types of termination of propagation. 
Classes¶
Base class for objects that store all results of a numerical propagation. 

Class that stores all the results (including logging data) of a singlearc propagation 

Class that provides information on the reason for the termination of the propagation. 

Class that provides information on the reason for the termination of the propagation, for hybrid termination conditions 

Object that stores the results of the algorithm to damp the proper mode of rotational dynamics for an initial state, as computed by the 


Dictionarylike class designed to store and retrieve dependent variable time histories using dependent variable settings objects (instances of VariableSettingsderived classes, check the Tudat API docs for more information about this class). 
 class SimulationResults¶
Base class for objects that store all results of a numerical propagation.
Base class for objects that store all results of a numerical propagation. Derived class are implemented for single, multi and hybridarc propagation of botj dynamics and variational equations
 property dependent_variable_interface¶
No documentation found.
 class SingleArcSimulationResults¶
Class that stores all the results (including logging data) of a singlearc propagation
 property cumulative_computation_time_history¶
readonly
History of cumulative computation time in seconds needed during the propagation as keyvalue pairs. At each epoch (key) the computation time (value) in seconds is the total computation time used up to and including that time step. This includes the total time up to and including the current time step, since the beginning of the (singlearc) propagation.
 property cumulative_number_of_function_evaluations_history¶
No documentation found.
 property dependent_variable_history¶
readonly
Dependent variables computed during the propagation as keyvalue pairs. The vector of all dependent variables concatenated into a single vector as value, with the epoch as key. They order of the concatenated dependent variables in a single value is provided by the
dependent_variable_ids
attribute of this object. Type:
 property dependent_variable_ids¶
readonly
Keyvalue container with the starting entry of the dependent variables saved (key), along with associated ID (value).
 property initial_and_final_times¶
No documentation found.
 property integration_completed_successfully¶
readonly
Boolean defining whether the last propagation was finished successfully, as defined by the termination conditions, or if it was terminated prematurely (for instance due to an exception, or an Inf/NaN state entry being detected).
 Type:
 property ordered_dependent_variable_settings¶
No documentation found.
 property processed_state_ids¶
readonly
Keyvalue container with the starting entry of the states (key), along with associated ID (value).
 property propagated_state_ids¶
readonly
Keyvalue container with the starting entry of the states (key), along with associated ID (value).
 property propagated_state_vector_length¶
No documentation found.
 property propagation_is_performed¶
No documentation found.
 property solution_is_cleared¶
No documentation found.
 property state_history¶
readonly
Numerical solution of the equations of motion as keyvalue pairs. The key denotes the epoch. The value contains the numerically calculated state at this epoch. For this function, the states are always converted to socalled ‘processed’ formulations (e.g. Cartesian states for translational dynamics), see here for details. For the history of the states that were actually propagated, use the
unprocessed_state_history
.Note
The propagated state at each epoch contains the state types in the following order: Translational ( T ), Rotational ( R ), Mass ( M ), and Custom ( C ). When propagating two bodies, an example of what the output state would look like is for instance: [ T Body 1, T Body 2, R Body 1, R Body 2, M Body 1, M Body 2 ] The specifics can be retrieved using the
state_ids
attribute of this classNote
For propagation of translational dynamics using cowell propagator, the conventional and propagated coordinates are identical.
 Type:
 property termination_details¶
readonly
Object describing the details of the event that triggered the termination of the last propagation.
 property total_computation_time¶
No documentation found.
 property total_number_of_function_evaluations¶
No documentation found.
 property unordered_dependent_variable_settings¶
No documentation found.
 property unprocessed_state_history¶
readonly
Numerical solution of the equations of motion as keyvalue pairs, without any processing applied. The key denotes the epoch. The value contains the numerically calculated state at this epoch. This attribute contains the states of the propagated bodies expressed in the “raw” form in which the propagation took place. For instance, when using a GaussKepler propagation scheme, this attribute will contain the numerically propagated Keplerian elements at each time epoch
 Type:
 class PropagationTerminationDetails¶
Class that provides information on the reason for the termination of the propagation.
 property terminated_on_exact_condition¶
Boolean defining whether the propagation was terminated on an exact final condition, or once the propagation went past the determined final condition. The choice of behaviour is defined by the termination settings provided as input to the Simulator object. This variable only has a meaningful definition if the
termination_reason
has valuetermination_condition_reached
 Type:
 property termination_reason¶
Enum defining the reason the propagation was terminated
 class PropagationTerminationDetailsFromHybridCondition¶
Class that provides information on the reason for the termination of the propagation, for hybrid termination conditions
Derived class from
PropagationTerminationDetails
that provides information on the reason for the termination of the propagation, for the case of hybrid termination conditions (defined using thehybrid_termination()
) function property was_condition_met_when_stopping¶
List of booleans defining, per entry in
termination_settings
when callinghybrid_termination()
, whether the corresponding entry of the hybrid termination settings was met or not
 class RotationalProperModeDampingResults¶
Object that stores the results of the algorithm to damp the proper mode of rotational dynamics for an initial state, as computed by the
get_damped_proper_mode_initial_rotational_state()
function property damped_initial_state¶
Initital state produced by the damping algorithm, for which the signature of the proper mode should be removed (or at least, substantially reduced). Note that this initial state corresponds to the full state vector that is provided to the
get_damped_proper_mode_initial_rotational_state
function (e.g. is size 7 for rotational dynamics of a single body, size 13 for coupled orbitalrotational dynamics of a single body, etc.) Type:
np.ndarray
 property forward_backward_dependent_variables¶
As
forward_backward_states
, but for the dependent variables.
 property forward_backward_states¶
Data structure that contains the full state histories used by the damping algorithm. The contents are are as follows:
The \(i^{th}\) entry of the list corresponds to the \(i^{th}\) iteration of the forwardbackward propagation
Each tuple in the list contains two dictionaries, the first one corresponding to the forward propagation results, the seconds one to the backward propagation results
 class DependentVariableDictionary(mapping=None, /, **kwargs)[source]¶
Dictionarylike class designed to store and retrieve dependent variable time histories using dependent variable settings objects (instances of VariableSettingsderived classes, check the Tudat API docs for more information about this class).
The goal of this class is to make dependent variable time history retrieval semantic and straightforward:
``` total_acceleration_history = dep_vars_dict[
propagation_setup.dependent_variable.total_acceleration(“DelfiC3”)
]¶
Example usage:¶
See the example below. As you can see, we can use as keys either the
Original dependent variable settings object (dependent_variables_to_save[0]),
Or a newly created dependent variable settings object (propagation_setup.dependent_variable.total_acceleration(“DelfiC3”))
``` # Create simulation object and propagate the dynamics dynamics_simulator = numerical_simulation.create_dynamics_simulator(
bodies, propagator_settings
)
# Create DependentVariableDictionary dep_vars_dict = result2dict(dynamics_simulator)
# Retrieve the time history (in dict[epoch: value] form) of the total acceleration experienced by DelftC3 total_acceleration_history = dep_vars_dict[
# This can be done using either the SingleAccelerationDependentVariableSaveSettings # corresponding to this dependent variable dependent_variables_to_save[0]
] total_acceleration_history = dep_vars_dict[
# Or a newly created one propagation_setup.dependent_variable.total_acceleration(“DelfiC3”)
]¶
How are time histories saved in a DependentVariableDictionary?¶
A DependentVariableDictionary maps which maps dependent variables, identified by either their corresponding dependent variable settings object (an instance of a VariableSettingsderived class) or its string ID, to their time histories.
The time history of each dependent variable is a Python dict which maps epochs (float) to NumPy arrays (np.ndarray) of shape (A, B):
dict[epoch: np.ndarray[A, B]]
Important: in (A, B), we remove singleton/trivial dimensions (dimensions, A or B, of size 1). In the case of scalar dependent variables, the value associated to each epoch is a np.ndarray of shape (1,). In the case of vectorial dependent variables, it is a row vector of size (A,). This is done by using np.squeeze to remove any dimensions of size 1. Practical examples:
Dimensions of dependent variable values associated to each epoch based on their type:
 asarray(key: VariableSettings) ndarray [source]¶
Return the time history of a given dependent variable as a NumPy array.
 Parameters:
key ()
Output

time_history ()