Semantic dependent variable retrieval: SimulationVariableDict and result2dict

[alopezrivera]

TL;DR

This pull requests implements semantic dependent variable retrieval using dependent variable settings objects, that is, to obtain time histories (epoch: value maps) of dependent variables with ease, where the value of the dependent variable at each epoch will be either numeric, vectorial, a matrix, etc.:

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

Subject to approval and review

• API: parent module and name of result2dict function

Table of contents

1. Usage
2. In-depth explanation

---

Usage

This pull request implements the pure Python SimulationVariableDict dictionary-like class and result2dict function, which takes a numerical_simulation.SingleArcSimulator and returns a SimulationVariableDict.

Both live in the tudatpy.utils module. Importing result2dict is done as follows:

from tudatpy.utils import result2dict

The goal of result2dict and the SimulationVariableDict 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")
] 

See the complete 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"))

# General imports
# ...

# Tudat imports
# ...
from tudatpy.utils import result2dict

# Propagation setup
# ...

# Create simulation object and propagate the dynamics
dynamics_simulator = numerical_simulation.create_dynamics_simulator(
    bodies, propagator_settings
)

# Create SimulationVariableDict
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")
]

In-depth explanation

result2dict

result2dict is a function that takes a numerical_simulation.SingleArcSimulator object, obtains from it the

1. Dependent variable time histories of the current propagation
2. Dependent variable settings objects of the current propagation
3. Obtains the correct shapes of all dependent variables from their settings objects
4. For each dependent variable, and for each epoch, it retrieves the value of the dependent variable, reshapes it to the correct shape (as Tudat time histories return tabular data, ie the value of a 3x3 matrix at any given epoch is returned as a 1x9 array)
5. Creates a SimulationVariableDict which associates the dependent variable's ID string to its correct-shape time history

SimulationVariableDict

SimulationVariableDict is a 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).

How are time histories saved in a SimulationVariableDict?

A SimulationVariableDict 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]]

Practical examples:

• [1, 1] (a number, most likely a float) for a scalar dependent variable
• [3, 1] for a vectorial dependent variable
• [3, 3] for a matrix dependent variable, etc.

[alopezrivera]

Can be disregarded and closed when #120 is merged