`simulator`¶

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.

Functions¶

`create_dynamics_simulator`(bodies, ...[, ...])	Function to create object that propagates the dynamics.
`create_variational_equations_solver`(bodies, ...)	Function to create object that propagates the dynamics and variational equations.

create_dynamics_simulator(bodies: tudatpy.kernel.dynamics.environment.SystemOfBodies, propagator_settings: tudatpy.kernel.dynamics.propagation_setup.propagator.PropagatorSettings, simulate_dynamics_on_creation: bool = True) → tudatpy.kernel.dynamics.simulator.DynamicsSimulator¶

Function to create object that propagates the dynamics.

Function to create object that propagates the dynamics, as specified by propagator settings, and the physical environment. Depending on the specific input type (e.g. which function from the propagator module was used), a single-, multi- or hybrid-arc simulator is created. The environment is typically created by the create_system_of_bodies() function.

Note

When using default settings, calling this function will automatically propagate the dynamics.

Parameters:

bodies (SystemOfBodies) – Object defining the physical environment, with all properties of artificial and natural bodies.
propagator_settings (PropagatorSettings) – Settings to be used for the numerical propagation (dynamics type, termination conditions, integrator, etc.)
simulate_dynamics_on_creation (bool, default=True) – Boolean defining whether to propagate the dynamics upon creation of the Simulator. If false, the dynamics c can be propagated at a later time by calling the integrate_equations_of_motion() function

Returns:

Object that propagates the dynamics, and processes the results. Depending on the propagator_settings, this object can be a single-, multi- or hybrid-arc simulator.

Return type:

DynamicsSimulator

create_variational_equations_solver(bodies: tudatpy.kernel.dynamics.environment.SystemOfBodies, propagator_settings: tudatpy.kernel.dynamics.propagation_setup.propagator.PropagatorSettings, parameters_to_estimate: tudat::estimatable_parameters::EstimatableParameterSet<double>, simulate_dynamics_on_creation: bool = True) → tudatpy.kernel.dynamics.simulator.VariationalSimulator¶

Function to create object that propagates the dynamics and variational equations.

Function to create object that propagates the dynamics and variational equations, as specified by propagator settings, the physical environment, and a set of parameters for which to compute the partials. Depending on the specific input type (e.g. which function from the propagator module was used to define the propagator settings), a single-, multi- or hybrid-arc variational solver is created. The environment is typically created by the create_system_of_bodies() function. When using default settings, calling this function will automatically propagate the dynamics.

Parameters:

bodies (SystemOfBodies) – Object defining the physical environment, with all properties of artificial and natural bodies.
propagator_settings (PropagatorSettings) – Settings to be used for the numerical propagation (dynamics type, termination conditions, integrator, etc.)
parameters_to_estimate (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.
simulate_dynamics_on_creation (bool, default=True) – Boolean defining whether to propagate the dynamics upon creation of the Simulator. If false, the dynamics can be propagated at a later time by calling the integrate_equations_of_motion() function

Returns:

Object that propagates the dynamics, and processes the results.

Return type:

VariationalSimulator

Classes¶

`DynamicsSimulator`	Base class for propagation of dynamics (with derived classes implementing single-, multi- or hybrid-arc.
`SingleArcSimulator`	Class for propagation of single arc dynamics.
`MultiArcSimulator`	Class for propagation of multi-arc dynamics.
`HybridArcSimulator`	Class for propagation of hybrid-arc dynamics.
`VariationalSimulator`	Base class for variational equations propagation.
`SingleArcVariationalSimulator`	Class for single arc variational equations propagation.
`CombinedStateTransitionAndSensitivityMatrixInterface`	Class establishing an interface with the simulation's State Transition and Sensitivity Matrices.

class DynamicsSimulator¶

Bases: pybind11_object

Base class for propagation of dynamics (with derived classes implementing single-, multi- or hybrid-arc.

class SingleArcSimulator¶

Bases: DynamicsSimulator

Class for propagation of single arc dynamics.

Class for propagation of single arc dynamics, from propagation settings and environment models, typically instantiated using create_dynamics_simulator() function. See user guide for more details.

evaluate_dependent_variables_along_arajectory(self: tudatpy.kernel.dynamics.simulator.SingleArcSimulator, predefined_state_history: dict[float | SupportsIndex, numpy.ndarray[numpy.float64[m, 1]]]) → dict[float, numpy.ndarray[numpy.float64[m, 1]]]¶

Function that evaluates the dependent variables defined in this object’s propagator settings along a pre-defined trajectory (provided as input to this function). This is in contrast to the regular calculation of the dependent variables, which is done along a trajectory numerically propagated by this object

Parameters:: predefined_state_history (:dict[ float, numpy.ndarray([m, 1]) ]) – State history (with state entry definition as per the propagator settings of this object) along which the dependent variables are to be computed
Returns:: Dependent variables evaluated along pre-defined trajectory
Return type:: dict[ float, numpy.ndarray([n, 1]) ]

integrate_equations_of_motion(self: tudatpy.kernel.dynamics.simulator.SingleArcSimulator, initial_state: numpy.ndarray[numpy.float64[m, n]]) → None¶

Function to reintegrate the equations of motion with a new initial state.

Parameters:: initial_state (numpy.ndarray) – New initial state from which the dynamics is to be propagated

property bodies¶

read-only

Object storing the set of bodies that comprise the physical environment.

Type:: SystemOfBodies

property cumulative_computation_time_history¶

read-only

Shorthand for propagation_results.cumulative_computation_time_history

Type:: dict[float, float]

property cumulative_number_of_function_evaluations¶

read-only

Shorthand for propagation_results.cumulative_number_of_function_evaluations

Type:: dict[float, int]

property dependent_variable_history¶

read-only

Shorthand for propagation_results.dependent_variable_history

Type:: dict[float, numpy.ndarray]

property dependent_variable_history_time_object¶

read-only

Shorthand for propagation_results.dependent_variable_history_time_object

Type:: dict[astro.time_representation.Time, numpy.ndarray]

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, but can be useful in specific situations.

Type:: EnvironmentUpdater

property integration_completed_successfully¶

read-only

Shorthand for propagation_results.integration_completed_successfully

Type:: bool

property propagation_results¶

read-only

Object containing all the results of the numerical propagation, stored in a single wrapper object.

Type:: SingleArcSimulationResults

property propagation_termination_details¶

read-only

Shorthand for propagation_results.termination_details

Type:: PropagationTerminationDetails

property propagator_settings¶

read-only

Settings for the propagation used to initialize the simulator

Type:: SingleArcPropagatorProcessingSettings

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[[astro.time_representation.Time, numpy.ndarray], numpy.ndarray]

property state_history¶

read-only

Shorthand for propagation_results.state_history

Type:: dict[float, numpy.ndarray]

property state_history_time_object¶

read-only

Shorthand for propagation_results.state_history_time_object

Type:: dict[astro.time_representation.Time, numpy.ndarray]

property unprocessed_state_history¶

read-only

Shorthand for propagation_results.unprocessed_state_history

Type:: dict[float, numpy.ndarray]

property unprocessed_state_history_time_object¶

read-only

Shorthand for propagation_results.unprocessed_state_history_time_object

Type:: dict[astro.time_representation.Time, numpy.ndarray]

class MultiArcSimulator¶

Bases: DynamicsSimulator

Class for propagation of multi-arc dynamics.

Class for propagation of multi-arc dynamics, from propagation settings and environment models, typically instantiated using create_dynamics_simulator() function. See user guide for more details.

integrate_equations_of_motion(self: tudatpy.kernel.dynamics.simulator.MultiArcSimulator, initial_state: numpy.ndarray[numpy.float64[m, n]]) → None¶

Function to reintegrate the equations of motion with a new initial state.

Parameters:: initial_state (numpy.ndarray) – New initial state from which the dynamics is to be propagated, consisting of concatenated initial states of each arc

property propagation_results¶

read-only

Object containing all the results of the numerical propagation, stored in a single wrapper object

Type:: MultiArcSimulationResults

property single_arc_simulators¶

read-only

List of single-arc simulators, that were used to propagate the dynamics on the constituent single arcs

Type:: list[SingleArcSimulator]

class HybridArcSimulator¶

Bases: DynamicsSimulator

Class for propagation of hybrid-arc dynamics.

Class for propagation of hybrid-arc dynamics, from propagation settings and environment models, typically instantiated using create_dynamics_simulator() function. See user guide for more details.

integrate_equations_of_motion(self: tudatpy.kernel.dynamics.simulator.HybridArcSimulator, initial_state: numpy.ndarray[numpy.float64[m, n]]) → None¶

Function to reintegrate the equations of motion with a new initial state.

Parameters:: initial_state (numpy.ndarray) – New initial state from which the dynamics is to be propagated, consisting of concatenated initial state single-arc portion of dynamics, followed by concatenated initial states of the constituent arcs of the multi-arc portion

property multi_arc_simulator¶

read-only

Object used to propagate the multi-arc portion of the hybrid-arc dynamics

Type:: MultiArcSimulator

property propagation_results¶

read-only

Object containing all the results of the numerical propagation, stored in a single wrapper object

Type:: HybridArcSimulationResults

property single_arc_simulator¶

read-only

Object used to propagate the single-arc portion of the hybrid-arc dynamics

Type:: SingleArcSimulator

class VariationalSimulator¶

Bases: pybind11_object

Base class for variational equations propagation.

Base class for variational equations propagation. Derived classes SingleArcVariationalSimulator, MultiArcVariationalSimulator and HybridArcVariationalSimulator implement single-, multi- and hybrid-arc functionality, respectively.

property state_transition_interface¶

read-only

State transition interface that includes the state transition and sensitivity matrices, which can be used for instance to propagate a covariance, see propagate_covariance().

Type:: CombinedStateTransitionAndSensitivityMatrixInterface

class SingleArcVariationalSimulator¶

Bases: VariationalSimulator

Class for single arc variational equations propagation.

__init__(self: tudatpy.kernel.dynamics.simulator.SingleArcVariationalSimulator, bodies: tudatpy.kernel.dynamics.environment.SystemOfBodies, integrator_settings: tudatpy.kernel.dynamics.propagation_setup.integrator.IntegratorSettings, propagator_settings: tudatpy.kernel.dynamics.propagation_setup.propagator.PropagatorSettings, estimated_parameters: tudat::estimatable_parameters::EstimatableParameterSet<double>, integrate_equations_concurrently: bool = True, variational_only_integrator_settings: tudat::numerical_integrators::IntegratorSettings<double> = None, clear_numerical_solutions: bool = False, integrate_on_creation: bool = True, set_integrated_result: bool = False, print_dependent_variable_data: 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, 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.dynamics.simulator.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 SingleArcVariationalSimulator object.
Return type:: None

integrate_full_equations(self: tudatpy.kernel.dynamics.simulator.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¶

read-only

Object containing the set of (estimatable) parameters w.r.t. the variational dynamics in this object are estimated

Type:: EstimatableParameterSet

property sensitivity_matrix_history¶

read-only

Sensitivity matrix history, given as epoch with propagation epochs as keys.

Warning

This function is deprecated and will be removed in a future version of Tudat. Use sensitivity_matrix_history attribute of variational_propagation_results instead.

Type:: dict[float, numpy.ndarray]

property state_history¶

read-only

State history, given as epoch with propagation epochs as keys.

Warning

This function is deprecated and will be removed in a future version of Tudat. Use dynamics_results.state_history attribute of variational_propagation_results instead.

Type:: dict[float, numpy.ndarray]

property state_transition_matrix_history¶

read-only

State transition matrix history, given as epoch with propagation epochs as keys.

Warning

This function is deprecated and will be removed in a future version of Tudat. Use state_transition_matrix_history attribute of variational_propagation_results instead.

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).

Warning

This function is deprecated and will be removed in a future version of Tudat. Use state_transition_matrix_history and sensitivity_matrix_history attributes of variational_propagation_results instead.

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

property variational_propagation_results¶

read-only

Object containing all the results of the numerical propagation of both the dynamics and the variational equations, stored in a single wrapper object.

Examples

Assuming you have an object of type SingleArcVariationalSimulator named variational_simulator, the numerical solution of the state transition matrix and sensitivity matrix can be retrieved as:

# Retrieve object containing all propagation results
results_container = variational_simulator.variational_propagation_results

# Retrieve dictionaries with numerically integrated time histories of state transition and sensitivity matrices
state_transition_matrix_history = results_container.state_transition_matrix_history
sensitivity_matrix_history = results_container.sensitivity_matrix_history

# Retrieve object containing propagation results of the dynamics (not including variational equations)
dynamics_results_container = results_container.dynamics_results

# Retrieve dictionaries with numerically integrated time history of states and associated dependent variables
state_history = dynamics_results_container.state_history
dependent_variable_history = dynamics_results_container.dependent_variable_history

Type:: SingleArcVariationalSimulationResults

class CombinedStateTransitionAndSensitivityMatrixInterface¶

Bases: pybind11_object

Class establishing an interface with the simulation’s State Transition and Sensitivity Matrices.

Class establishing an interface to the State Transition and Sensitivity Matrices. Instances of this class are instantiated automatically upon creation of Estimator objects, using the simulation information in the observation, propagation and integration settings that the Estimator instance is linked to.

full_state_transition_sensitivity_at_epoch(self: tudatpy.kernel.dynamics.simulator.CombinedStateTransitionAndSensitivityMatrixInterface, time: float | SupportsIndex, add_central_body_dependency: bool = True, arc_defining_bodies: list[str] = []) → numpy.ndarray[numpy.float64[m, n]]¶

Parameters:: time (astro.time_representation.Time) – Time at which full concatenated state transition and sensitivity matrix are to be retrieved.
Returns:: Full concatenated state transition and sensitivity matrix at a given time.
Return type:: numpy.ndarray[numpy.float64[m, n]]

state_transition_sensitivity_at_epoch(self: tudatpy.kernel.dynamics.simulator.CombinedStateTransitionAndSensitivityMatrixInterface, time: float | SupportsIndex, add_central_body_dependency: bool = True, arc_defining_bodies: list[str] = []) → numpy.ndarray[numpy.float64[m, n]]¶

Function to get the concatenated state transition and sensitivity matrix at a given time.

Function to get the concatenated state transition and sensitivity matrix at a given time. Entries corresponding to parameters which are not active at the current arc are omitted.

Parameters:: time (astro.time_representation.Time) – Time at which concatenated state transition and sensitivity matrix are to be retrieved.
Returns:: Concatenated state transition and sensitivity matrix at a given time.
Return type:: numpy.ndarray[numpy.float64[m, n]]

property full_parameter_size¶

read-only

Full amount of parameters w.r.t. which partials have been set up via State Transition and Sensitivity Matrices.

Type:: int

property sensitivity_size¶

read-only

Number of columns in the sensitivity matrix.

Type:: int

property state_transition_size¶

read-only

Size of the (square) state transition matrix.

Type:: int