`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.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: 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 in central_bodies.

Return type:

numpy.ndarray

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 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[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:: 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) – DependentVariableDictionary of propagation

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
`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.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 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 single-arc propagation

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) 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¶: No documentation found.

property dependent_variable_history¶

read-only

Dependent variables computed during the propagation as key-value 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:: dict[float, 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¶: No documentation found.

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 ordered_dependent_variable_settings¶: No documentation found.

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¶: No documentation found.

property propagation_is_performed¶: No documentation found.

property solution_is_cleared¶: No documentation found.

property state_history¶

read-only

Numerical solution of the equations of motion as key-value 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 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 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¶: No documentation found.

property total_number_of_function_evaluations¶: No documentation found.

property unordered_dependent_variable_settings¶: No documentation found.

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

Type:: dict[float, numpy.ndarray]

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]

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

Type:: np.ndarray

property forward_backward_dependent_variables¶

As forward_backward_states, but for the dependent variables.

Type:: list[tuple[dict[float,np.ndarray],dict[float,np.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,np.ndarray],dict[float,np.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:

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

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

Parameters:

key (-)
Output
------
time_history (-)

propagation¶

Functions¶

Enumerations¶

Classes¶

]¶

Example usage:¶

]¶

How are time histories saved in a DependentVariableDictionary?¶

`propagation`¶