numerical_simulation#

Setup and execution of numerical simulations.

This module contains everything related to the setup of a numerical simulation, including submodules to define environment, propagation, and integration settings. It also contains objects that perform the simulation using such settings.

Modules

Classes#

SingleArcSimulator

Class for consolidating single arc dynamics simulation functionality.

SingleArcVariationalSimulator

Class for consolidating single arc variational dynamics functionality.

Estimator

Class for consolidating all estimation functionality.
class SingleArcSimulator#

Class for consolidating single arc dynamics simulation functionality.

Class for consolidating all functionality required to perform single arc dynamics simulations.

__init__(self: tudatpy.kernel.numerical_simulation.SingleArcSimulator, bodies: tudatpy.kernel.numerical_simulation.environment.SystemOfBodies, integrator_settings: tudatpy.kernel.numerical_simulation.propagation_setup.integrator.IntegratorSettings, propagator_settings: tudatpy.kernel.numerical_simulation.propagation_setup.propagator.PropagatorSettings, are_equations_of_motion_to_be_integrated: bool = True, clear_numerical_solutions: bool = False, set_integrated_result: bool = False, print_number_of_function_evaluations: bool = False, print_dependent_variable_data: bool = True, print_state_data: bool = True) → None#

Class constructor.

Defines environment, propagation and integrations models, as well as a number of settings related to simulation output and processing.

Note

When using default settings, creating an object of this type automatically triggers the propagation

Parameters

  • bodies (SystemOfBodies) – Object defining the physical environment, with all properties of artificial and natural bodies.

  • integrator_settings (IntegratorSettings) – Settings to create the numerical integrator that is to be used for the integration of the equations of motion

  • propagator_settings (PropagatorSettings) – Settings to create the propagator that is to be used for the propagation of dynamics

  • are_equations_of_motion_to_be_integrated (Bool, default = True) – Boolean defining whether the propagation should be performed immediately (default), or at a later time when calling the integrate_equations_of_motion function.

  • clear_numerical_solutions (Bool, default = False) – Boolean defining whether the propagation results should be deleted after the propagation is terminated. If this is done, the state_history, unprocessed_state_history and dependent_variable_history will not be accessible. Putting this setting to True (deleting the results) is only sensible when the set_integrated_result is set to True. In that case, the propagated states are not accessible directly from this objects, but the results are used to update the environment, e.g. update the ephemeris of the propagated body with the numerical results.

  • set_integrated_result (Bool, default = False) –

    Boolean defining whether the propagation results are to be used to update the environment. If this variable is set to False, the numerical propagation results can be retrieved from this object (provided the clear_numerical_solutions is set to False), but the (for instance) Ephemeris of the propagated body is not updated with the propagation results. If this variable is set to True, the properties of the propagated Body object will be updated as per the numerical results. Depending on the state type, this will result in:

    • Translational: The ephemeris of the propagated body will be updated.

      Note

      This requires the propagated body to be endowed with a tabulated ephemeris.

    • Rotational: The rotational ephemeris of the propagated body will be updated.

      Note

      This requires the propagated body to be endowed with a tabulated rotational ephemeris.

    • Mass: The mass function of the propagated body will be updated.

  • print_number_of_function_evaluations (bool, default = False) – Boolean defining whether the number of function evaluations that were performed is to be printed to the console after propagation.

  • print_dependent_variable_data (bool, default = True) –

    Boolean defining whether the meaning and indices of the entries of the dependent variable data are to be printed to the console.

    Note

    The same information can be retrieved from the dependent_variable_ids property.

  • print_state_data (bool, default = True) – Boolean defining whether the meaning and indices of the entries of the state vector are to be printed to the console.

integrate_equations_of_motion(self: tudatpy.kernel.numerical_simulation.SingleArcSimulator, initial_states: numpy.ndarray[numpy.float64[m, n]]) → None#

This function numerically (re-)integrates the equations of motion.

This function numerically (re-)integrates the equations of motion, using the settings set through the constructor and a new initial state vector provided here.

Parameters

initial_states (numpy.ndarray) –

Initial state vector that is to be used for numerical integration. Note that this state should be in the correct frame (i.e. relative to central_bodies in propagator_settings), and in Cartesian elements (even when using a different propagation scheme than Cowell).

Note

When using default settings for the class constructor, this function is called during object creation.

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.

Type

dict[float, float]

property cumulative_number_of_function_evaluations#

read-only

This function returns the history of cumulative number of function evaluations taken during the propagation as key-value pairs. At each epoch (key), the number of computed function evaluations (value) are given up to and including that time step.

Type

dict[float, int]

property dependent_variable_history#

read-only

Dependent variables computed during the propagation as key-value pairs. They are returned in the order with the same order of the DependentVariableSaveSettings object as values, as value, with the epoch as key.

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, str]

property environment_updater#

read-only

# Object used in the propagation to update the environment, it uses the current time and numerically calculated state to update the translational state, rotational state, flight conditions, etc. of all bodies in the simulation to be consistent with this time and state. Typically, this class is NOT used directly by users.

Type

EnvironmentUpdater

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 integrator_settings#

Settings to create the numerical integrator that is to be used for the integration of the equations of motion

Type

IntegratorSettings

property propagation_termination_details#

No documentation found.

property state_derivative_function#

read-only

Function that performs a single state derivative function evaluation. This function takes the numerically propagated state, and current independent variable (time) as input, and returns the derivative of the state that is then used by the numerical integration routine. Typically, this function is NOT used directly by users.

Type

Callable[[float, numpy.ndarray], numpy.ndarray]

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 ‘conventional’ formulations (e.g. Cartesian states for translational dynamics), see here for detailed. 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 ( C ), 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 ]

Note

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

Type

dict[float, numpy.ndarray]

property unprocessed_state_history#

read-only

Raw 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. 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 SingleArcVariationalSimulator#

Class for consolidating single arc variational dynamics functionality.

Class for consolidating all functionality required to perform single arc variational dynamics simulations.

__init__(self: tudatpy.kernel.numerical_simulation.SingleArcVariationalSimulator, bodies: tudatpy.kernel.numerical_simulation.environment.SystemOfBodies, integrator_settings: tudatpy.kernel.numerical_simulation.propagation_setup.integrator.IntegratorSettings, propagator_settings: tudatpy.kernel.numerical_simulation.propagation_setup.propagator.PropagatorSettings, estimated_parameters: tudatpy.kernel.numerical_simulation.estimation.EstimatableParameterSet, integrate_equations_concurrently: bool = True, variational_only_integrator_settings: tudatpy.kernel.numerical_simulation.propagation_setup.integrator.IntegratorSettings = None, clear_numerical_solutions: bool = False, integrate_on_creation: bool = True, set_integrated_result: bool = False) → None#

Class constructor.

Constructor through which the user can create instances of this class. Defines environment, propagation and integrations models, as well as a number of settings related to the (estimatable) parameters, w.r.t. which the variational equations are defined.

Note

When using default settings, creating an object of this type automatically triggers the propagation

Parameters

  • bodies (SystemOfBodies) – Object defining the physical environment, with all properties of artificial and natural bodies.

  • integrator_settings (IntegratorSettings) – Settings to create the numerical integrator that is to be used for the integration of the equations of motion.

  • propagator_settings (PropagatorSettings) – Settings to create the propagator that is to be used for the propagation of the dynamics.

  • estimated_parameters (EstimatableParameterSet) – Object defining a consolidated set of (estimatable) parameters (w.r.t. variational equations are defined), linked to the environment and acceleration settings of the simulation.

  • integrate_equations_concurrently (Bool, default = True) – Boolean defining whether equations of motion and variational equations are to be propagated concurrently (if true) or sequentially (of false).

  • variational_only_integrator_settings (IntegratorSettings, default = []) – Settings to create the numerical integrator that is to be used for integration the variational equations. If none is given (default), the numerical integration settings are taken to be the same as the ones applied in the integration of the equations of motions (specified by the integrator_settings parameter).

  • clear_numerical_solutions (Bool, default = False) – Boolean to determine whether to clear the raw numerical solution member variables and to reset the state transition interface after propagation.

  • integrate_on_creation (Bool, default = True) – Boolean defining whether the propagation should be performed immediately (default), or at a later time (when calling the integrate_full_equations() or integrate_equations_of_motion_only() member function).

  • set_integrated_result (Bool, default = True) – Boolean to determine whether to automatically use the integrated results to set ephemerides for the propagated bodies.

integrate_equations_of_motion_only(self: tudatpy.kernel.numerical_simulation.SingleArcVariationalSimulator, initial_states: numpy.ndarray[numpy.float64[m, 1]]) → None#

Function to trigger the integration of the (regular) equations of motion.

Function to trigger the integration only of the (regular) equations of motion, resulting in a state_history. This step does not yet use variational dynamics. In order to also solve the variational equations, use the integrate_full_equations() member function.

Returns

Creates / modifies the state_history property of the SingleArcVariationalSolver object.

Return type

None

integrate_full_equations(self: tudatpy.kernel.numerical_simulation.SingleArcVariationalSimulator, initial_states: numpy.ndarray[numpy.float64[m, 1]], integrate_equations_concurrently: bool = True) → None#

Function to trigger the integration of variational and dynamical equations (equations of motion).

Function to trigger the integration of the (regular) equations of motion as well as the variational equations, solving for state_history and variational_equations_history (in its two components state_transition_matrix_history & sensitivity_matrix_history).

Parameters

  • initial_states (numpy.ndarray([m, 1])) – Initial state to be used for the parameters in the equations of motion.

  • integrate_equations_concurrently (Bool, default = True) – Boolean defining whether equations of motion and variational equations are to be propagated concurrently (if true) or sequentially (of false).

Returns

Creates / modifies the properties of the VariationalSolver object.

Return type

None

property dynamics_simulator#

read-only

Simulator object containing all functionality for solving of the (regular) equations of motion.

Type

SingleArcSimulator

property parameter_vector#

Consolidated set of (estimatable) parameters w.r.t. the variational dynamics in the Variational Simulator are defined.

Type

EstimatableParameterSet

property sensitivity_matrix_history#

read-only

Sensitivity matrix history, given as epoch with propagation epochs as keys. This is (alongside the state_transition_matrix_history) the solution of the variational equations.

Type

dict[float, numpy.ndarray]

property state_history#

read-only

State history, given as epoch with propagation epochs as keys. This is the solution of the (propagated) equations of motion, describing the states along which the variational dynamics are solved.

Type

dict[float, numpy.ndarray]

property state_transition_matrix_history#

read-only

State transition matrix history, given as epoch with propagation epochs as keys. This is (alongside the sensitivity_matrix_history) the solution of the variational equations.

Type

dict[float, numpy.ndarray]

property variational_equations_history#

read-only

List containing the solution of the variational equations, i.e. the state transition matrix history (first entry) and sensitivity matrix history (second vector entry).

Type

list[ dict[float, numpy.ndarray] ]

class Estimator#

Class for consolidating all estimation functionality.

Class for consolidating all functionality required to perform an estimation.

__init__(self: tudatpy.kernel.numerical_simulation.Estimator, bodies: tudatpy.kernel.numerical_simulation.environment.SystemOfBodies, estimated_parameters: tudatpy.kernel.numerical_simulation.estimation.EstimatableParameterSet, observation_settings: List[tudatpy.kernel.numerical_simulation.estimation_setup.observation.ObservationSettings], integrator_settings: tudatpy.kernel.numerical_simulation.propagation_setup.integrator.IntegratorSettings, propagator_settings: tudatpy.kernel.numerical_simulation.propagation_setup.propagator.PropagatorSettings, integrate_on_creation: bool = True) → None#

Class constructor.

Constructor through which the user can create instances of this class. Defines environment, propagation and integrations models, as well as a number of settings related to the estimatable parameters and observation settings.

Note

When using default settings, creating an object of this type automatically triggers the propagation

Parameters

  • bodies (SystemOfBodies) – Object defining the physical environment, with all properties of artificial and natural bodies.

  • estimated_parameters (EstimatableParameterSet) – Object defining a consolidated set of estimatable parameters, linked to the environment and acceleration settings of the simulation.

  • observation_settings (ObservationSettings) – List of settings objects, each object defining the observation model settings for one combination of observable and link geometry that is to be simulated.

  • integrator_settings (IntegratorSettings) – Settings to create the numerical integrator that is to be used for the integration of the equations of motion

  • propagator_settings (PropagatorSettings) – Settings to create the propagator that is to be used for the propagation of dynamics

  • integrate_on_creation (Bool, default = True) – Boolean defining whether the propagation should be performed immediately (default), or at a later time (when calling the perform_estimation() member function.

perform_estimation(self: tudatpy.kernel.numerical_simulation.Estimator, estimation_input: tudatpy.kernel.numerical_simulation.estimation.PodInput, convergence_checker: tudatpy.kernel.numerical_simulation.estimation.EstimationConvergenceChecker = <tudatpy.kernel.numerical_simulation.estimation.EstimationConvergenceChecker object at 0x7f895044cd30>) → tudatpy.kernel.numerical_simulation.estimation.PodOutput#

Function to trigger the parameter estimation.

Function to trigger parameter estimation, including orbit determination, i.e. body initial states, from (simulated) observations and a priori constraints. All observable types and link ends per observable types that are included in the estimation input must have been provided to the constructor of the Estimator object by the observation_settings parameter.

Parameters

  • estimation_input (PodInput) – Object consolidating all inputs required to conduct an estimation. This includes foremost the simulated observations, as well as a priori information about the estimatable parameters.

  • EstimationConvergenceChecker (EstimationConvergenceChecker) – Object defining the convergence criteria for the estimation.

Returns

Object containing all outputs from the estimation (Pod) process.

Return type

PodOutput

property observation_managers#

read-only

Observation managers contained in the Estimator object. A single observation manager can simulate observations and calculate observation partials for all link ends involved in the given observable type.

Type

dict[ ObservableType, ObservationManager ]

property observation_simulators#

read-only

Observation simulators contained in the Estimator object. A single observation simulator hosts the functionality for simulating a given observable over the defined link geometry.

Type

list[ ObservationSimulator ]

property state_transition_interface#

read-only

State transition and sensitivity matrix interface, setting the variational equations/dynamics in the Estimator object.

Type

CombinedStateTransitionAndSensitivityMatrixInterface

property variational_solver#

read-only

Variational equations solver, which is used to manage and execute the numerical integration of equations of motion and variational equations/dynamics in the Estimator object.

Type

SingleArcVariationalSolver