`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¶

`get_state_of_bodies`(bodies_to_propagate, ...)	Function to get the translational states of a set of bodies, with respect to some set of central bodies, at the requested time.
`get_damped_proper_mode_initial_rotational_state`(...)	Function to compute an initial rotational state for which the proper mode of rotation is damped.
`combine_initial_states`(...)	Function to retrieve the initial state for a list of propagator settings.
`dependent_variable_dictionary.create_dependent_variable_dictionary`(...)	Construct a dictionary-like 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: tudatpy.kernel.numerical_simulation.Time) → 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 in central_bodies.

Return type:

numpy.ndarray

get_damped_proper_mode_initial_rotational_state(bodies: tudatpy.kernel.numerical_simulation.environment.SystemOfBodies, propagator_settings: tudatpy.kernel.numerical_simulation.propagation_setup.propagator.SingleArcPropagatorSettings, 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 progress 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 body-fixed frame), \(\tau_{d}\) the damping time of the current propagation, and \(\omega_{x}, \omega_{y}, \omega_{z}\) the body’s current rotation about its body-fixed, x-, y- and z-axes, respectively. The damping torque is implemented to damp out all rotations along the body-fixed x- and y-axes, and any deviations from constant rotation with frequency :omega_{p}: about the body-fixed z-axis.

Note

The mean rotation rate of the body \(\omega_{p}\) is a user-defined 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 multi-type rotational dynamics that contains rotational dynamics for a single body (e.g. translational-rotational dynamics for a single body)
body_mean_rotational_rate (float) – Mean rotational rate \(\omega_{p}\) to which the damping algorithm will force the body-fixed rotation about its z-axis.
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[tudatpy.kernel.numerical_simulation.propagation_setup.propagator.StateType, list[tudatpy.kernel.numerical_simulation.propagation_setup.propagator.SingleArcPropagatorSettings]]) → 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:: numpy.ndarray

create_dependent_variable_dictionary(dynamics_simulator: SingleArcSimulator) → DependentVariableDictionary[source]¶

Construct a dictionary-like 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 of propagation
Return type:: DependentVariableDictionary

Enumerations¶

PropagationTerminationReason

Enumeration of types of termination of propagation.

class PropagationTerminationReason¶

Enumeration of types of termination of propagation.

Members:

propagation_never_run

unknown_reason

termination_condition_reached

runtime_error_caught_in_propagation

nan_or_inf_detected_in_state

property name¶

Classes¶

`SimulationResults`	Base class for objects that store all results of a numerical propagation.
`SingleArcSimulationResults`	Class that stores all the results (including logging data) of a single-arc propagation of states
`SingleArcVariationalSimulationResults`	Class that stores all the results (including logging data) of a single-arc propagation of states and variational equations
`MultiArcSimulationResults`	Class that stores all the results (including logging data) of a multi-arc propagation of states.
`MultiArcVariationalSimulationResults`	Class that stores all the results (including logging data) of a multi-arc propagation of states and variational equations
`HybridArcSimulationResults`	Class that stores all the results (including logging data) of a hybrid-arc propagation of states.
`HybridArcVariationalSimulationResults`	Class that stores all the results (including logging data) of a hybrid-arc propagation of states and variational equations.
`PropagationTerminationDetails`	Class that provides information on the reason for the termination of the propagation.
`PropagationTerminationDetailsFromHybridCondition`	Class that provides information on the reason for the termination of the propagation, for hybrid termination conditions
`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
`dependent_variable_dictionary.DependentVariableDictionary`([...])	Dictionary-like class designed to store and retrieve dependent variable time histories using dependent variable settings objects (instances of VariableSettings-derived 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 hybrid-arc propagation of both dynamics and variational equations

property dependent_variable_interface¶

read-only

Attrribute that allows for automatic interpolation and retrieval of dependent variables

Type:: DependentVariablesInterface

class SingleArcSimulationResults¶

Class that stores all the results (including logging data) of a single-arc propagation of states

clear_data(self: tudatpy.kernel.numerical_simulation.propagation.SingleArcSimulationResults) → None¶

Function to delete the contents of this object.

Function to delete the contents of this object. This function is typically called when wanting to manually reduce the memory usage in large analyses by clearing data. It does not need to be used manually before repropagating.

property cumulative_computation_time_history¶

read-only

History of cumulative computation time in seconds needed during the propagation as key-value pairs. At each epoch (key, as a float) 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 (single-arc) propagation.

Type:: dict[float, float]

property cumulative_number_of_function_evaluations_history¶

read-only

History of cumulative number of function evaluations (e.g. number of times the state derivative model is evaluated) as key-value pairs. At each epoch (key, as a float) the cumulative number of function evaluations (value) including the current one is included.

Note

At present, this dictionary is updated during each function evaluation, including the minor stages of (for instance) a multi-stage integrator. This is unlike the rest of the data in this object, which is provided only after each full time step. For variable-time step integration, this also means that the values need not be monotonically increasing with propagation time (if a step size is rejected and recomputed with smaller step size).

Type:: dict[float, float]

property dependent_variable_history¶

read-only

Dependent variables computed during the propagation as key-value pairs. The key denotes the epoch as a float. If the output with the higher-resolution Time() object is required, use the dependent_variable_history_time_object() function.

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:: dict[float, numpy.ndarray]

property dependent_variable_history_time_object¶

read-only

Same as dependent_variable_history(), but using the high-resolution Time() type used as independent variable in the propagation as key

Type:: dict[Time, numpy.ndarray]

property dependent_variable_ids¶

read-only

Key-value container with the starting entry of the dependent variables saved (key), along with associated ID (value).

Type:: dict[[int,int], str]

property initial_and_final_times¶

read-only

Initial and final time of the propagation

Type:: tuple[float,float]

property integration_completed_successfully¶

read-only

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:: bool

property processed_state_ids¶

read-only

Key-value container with the starting entry of the states (key), along with associated ID (value).

Type:: dict[[int,int] str]

property propagated_state_ids¶

read-only

Key-value container with the starting entry of the states (key), along with associated ID (value).

Type:: dict[[int,int] str]

property propagated_state_vector_length¶

read-only

Length of the propagated state vector

Type:: int

property propagation_is_performed¶

read-only

Boolean indicating whether the propagation for which this object stores the results has been performed or not

Type:: int

property state_history¶

read-only

Numerical solution of the equations of motion as key-value pairs. The key denotes the epoch as a float. If the output with the higher-resolution Time() object is required, use the state_history_time_object() function.

The values of this dictionary contains the numerically calculated state at this epoch. For this function, the states are always converted to so-called ‘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 class

Note

For propagation of translational dynamics using cowell propagator, the conventional and propagated coordinates are identical.

Type:: dict[float, numpy.ndarray]

property state_history_float_split¶

read-only

Same as state_history, but with a return type of two lists (one with times and one with states)

Type:: tuple[ list[float], list[numpy.ndarray] ]

property state_history_time_object¶

read-only

Same as state_history(), but using the high-resolution Time() type used as independent variable in the propagation as key

Type:: dict[Time, numpy.ndarray]

property termination_details¶

read-only

Object describing the details of the event that triggered the termination of the last propagation.

Type:: PropagationTerminationDetails

property total_computation_time¶

read-only

Total computation time (in seconds) that was required for the propagation.

Type:: float

property total_number_of_function_evaluations¶

read-only

Total number of function evaluations that were computed for the propagation

Type:: float

property unprocessed_state_history¶

read-only

Numerical solution of the equations of motion as key-value pairs, without any processing applied. The key denotes the epoch as a float. If the output with the higher-resolution Time() object is required, use the unprocessed_state_history_time_object() function.

The values contain 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 Gauss-Kepler propagation scheme, this attribute will contain the numerically propagated Keplerian elements at each time epoch

Type:: dict[float, numpy.ndarray]

property unprocessed_state_history_time_object¶

read-only

Same as unprocessed_state_history(), but using the high-resolution Time() type used as independent variable in the propagation as key

Type:: dict[Time, numpy.ndarray]

class SingleArcVariationalSimulationResults¶

Class that stores all the results (including logging data) of a single-arc propagation of states and variational equations

Class that stores all the results (including logging data) of a single-arc propagation of states and variational equations. The propagation results of the states are accessed through the dynamics_results attribute.

property dynamics_results¶

read-only

Object with all results of the propagation results of the states, as well as details on propagation termination reason, runtime, function evaluations, etc.

Type:: SingleArcSimulationResults

property sensitivity_matrix_history¶

read-only

Numerical solution of the sensitivity matrix \(\partial \mathbf{x}/\partial\mathbf{p}\) from the variational equations as key-value pairs. The key denotes the epoch. The value contains the numerically calculated sensitivity matrix at this epoch. The state \(\mathbf{x}\) in the definition is always in the so-called ‘processed’ formulations (e.g. Cartesian states for translational dynamics), see here for details. See state_history for the definition of the order of the elements of the states.

Type:: dict[float, numpy.ndarray]

property state_transition_matrix_history¶

read-only

Numerical solution of the state transition matrix \(\partial \mathbf{x}/\partial\mathbf{x}_{0}\) from the variational equations as key-value pairs. The key denotes the epoch. The value contains the numerically calculated state transition matrix at this epoch. The states \(\mathbf{x}\) and \(\mathbf{x}_{0}\) in the definition are always in the so-called ‘processed’ formulations (e.g. Cartesian states for translational dynamics), see here for details. See state_history for the definition of the order of the elements of the states.

Type:: dict[float, numpy.ndarray]

class MultiArcSimulationResults¶

Class that stores all the results (including logging data) of a multi-arc propagation of states.

Class that stores all the results (including logging data) of a multi-arc propagation of states. The results of the constituent arcs are accessed through the single_arc_results attribute.

property arc_end_times¶

read-only

List of epochs at which each of the arcs end (e.g. latest epoch in state history per arc)

Type:: list[float]

property arc_start_times¶

read-only

List of epochs at which each of the arcs start (e.g. earliest epoch in state history per arc)

Type:: list[float]

property propagation_is_performed¶

read-only

Boolean indicating whether the propagation for which this object stores the results has been performed or not

Type:: int

property single_arc_results¶

read-only

List of results from the single-arc propagations. The list of single-arc results objects store all numerical and logging results from the constituent arc propagations. These single-arc result objects are where the state history, etc. can be retrieved

Type:: list[SingleArcSimulationResults]

class MultiArcVariationalSimulationResults¶

Class that stores all the results (including logging data) of a multi-arc propagation of states and variational equations

Class that stores all the results (including logging data) of a multi-arc propagation of states and variational equations. The results of the constituent arcs are accessed through the single_arc_results attribute.

property propagation_is_performed¶

read-only

Boolean indicating whether the propagation for which this object stores the results has been performed or not

Type:: int

property single_arc_results¶

R”doc( read-only

Type:: list[SingleArcVariationalSimulationResults]

class HybridArcSimulationResults¶

Class that stores all the results (including logging data) of a hybrid-arc propagation of states.

Class that stores all the results (including logging data) of a hybrid-arc propagation of states. The results of the constituent arcs are accessed through the single_arc_results and multi_arc_results attribute1.

property multi_arc_results¶

read-only

Object with results from the multi-arc propagation component of the hybrid-arc propagation. This object stores all numerical and logging results from the multi-arc component.

Type:: MultiArcSimulationResults

property single_arc_results¶

read-only

Object with results from the single-arc propagation component of the hybrid-arc propagation. This object stores all numerical and logging results from the single-arc component.

Type:: SingleArcSimulationResults

class HybridArcVariationalSimulationResults¶

Class that stores all the results (including logging data) of a hybrid-arc propagation of states and variational equations.

Class that stores all the results (including logging data) of a hybrid-arc propagation of states and variational equations. The results of the constituent arcs are accessed through the single_arc_results and multi_arc_results attribute1.

property multi_arc_results¶

read-only

Object with results from the multi-arc propagation component of the hybrid-arc propagation. This object stores all numerical and logging results from the multi-arc component.

Type:: MultiArcVariationalSimulationResults

property single_arc_results¶

read-only

Object with results from the single-arc propagation component of the hybrid-arc propagation. This object stores all numerical and logging results from the single-arc component.

Type:: SingleArcVariationalSimulationResults

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 value termination_condition_reached

Type:: bool

property termination_reason¶

Enum defining the reason the propagation was terminated

Type:: PropagationTerminationReason

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 the hybrid_termination()) function

property was_condition_met_when_stopping¶

List of booleans defining, per entry in termination_settings when calling hybrid_termination(), whether the corresponding entry of the hybrid termination settings was met or not.

Type:: list[bool]

Examples

Assuming the hybrid termination settings were defined similar to the example in the hybrid_termination():

# Store termination setting objects in a list
termination_settings_list = [
    time_termination_settings,
    altitude_termination_settings,
    cpu_termination_settings,
]
# Define string representations for output
termination_conditions_repr = [
    "Time Termination",
    "Altitude Termination",
    "CPU Time Termination",
]

# Create hybrid termination settings
termination_settings = propagation_setup.propagator.hybrid_termination(
    termination_settings_list, fulfill_single_condition=True
)

The was_condition_met_when_stopping attribute contains a list of booleans, with the same length as the termination_settings_list. The following code can be used to print if the termination condition was met for each of the termination settings:

# perform propagation
...

# post-process propagation results
termination_details = dynamics_simulator.propagation_results.termination_details
condition_met_flags = termination_details.was_condition_met_when_stopping

condition_fulfilled = [
    f"{condition:<35}: {met}"
    for condition, met in zip(termination_conditions_repr, condition_met_flags)
]

print("Termination Conditions fulfilled:")
print("\n".join(condition_fulfilled))

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¶

Initial 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 orbital-rotational dynamics of a single body, etc.)

Type:: numpy.ndarray

property forward_backward_dependent_variables¶

As forward_backward_states, but for the dependent variables.

Type:: list[tuple[dict[float,numpy.ndarray],dict[float,numpy.ndarray]]]

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 forward-backward 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

Type:: list[tuple[dict[float,numpy.ndarray],dict[float,numpy.ndarray]]]

class DependentVariableDictionary(mapping=None, /, **kwargs)[source]¶

Dictionary-like class designed to store and retrieve dependent variable time histories using dependent variable settings objects (instances of VariableSettings-derived 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 straight-forward:

total_acceleration_history = dep_vars_dict[
    propagation_setup.dependent_variable.total_acceleration("Delfi-C3")
]

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(“Delfi-C3”))

# 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 Delft-C3
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("Delfi-C3")
]

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 VariableSettings-derived 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:

Data Type	Shape
Scalar	(1,)
Vectorial	(3,)
Matrix	(A, B)
Tensor	(A, B, C)

asarray(key: VariableSettings) → ndarray[source]¶

Return the time history of a given dependent variable as a NumPy array.

Parameters:: key (VariableSettings) – dependent variable settings object or string ID of the dependent variable
Returns:: time_history – time history of the dependent variable, returned as a NumPy array
Return type:: np.ndarray

propagation¶

Functions¶

Enumerations¶

Classes¶

Example usage:¶

How are time histories saved in a DependentVariableDictionary?¶

`propagation`¶