3.2. Propagator Settings: Basics¶

This page presents an overview of the available options within PropagatorSettings. As the name suggests, these settings define how the orbit is propagated within the DynamicsSimulator.

Similarly to the IntegratorSettings discussed in Integrator Settings, various derived classes are used to implement different settings:

class PropagatorSettings¶: Base class from which the other settings classes described below are derived.

3.2.1. Single-arc Propagation¶

class SingleArcPropagatorSettings¶: Derived class of PropagatorSettings. Base class from which the other single-arc settings classes described below are derived. Settings object for a specific type (e.g. translational, rotational, etc.) are always derived from this class. This class (or in essence one of its derived classes) is used as input to the SingleArcDynamicsSimulator. A list of single-arc settings can be passed to a MultiArcPropagatorSettings to perform multi-arc propagation (see below).

class TranslationalStatePropagatorSettings¶

This class implements the framework required to propagate the translation state of a body. The constructor of this derived class is overloaded allowing two types of termination conditions:

Termination when the simulation time reaches a predefined endTime (Default).
Termination when a predefined dependent variables meets a certain criterion.

Using default termination settings

TranslationalStatePropagatorSettings<StateScalarType>( centralBodies,
                                                       accelerationsMap,
                                                       bodiesToIntegrate,
                                                       initialBodyStates,
                                                       endTime,
                                                       propagator,
                                                       dependentVariablesToSave )

where:

StateScalarType

Template argument used to set the precision of the state, in general double is used. For some application where a high precision is required this can be changed to e.g. long double.
centralBodies

std::vector< std::string > that contains the names of the central bodies and must match with those in the BodyMap.
accelerationsMap

AccelerationMap that contains the accelerations for each body as discussed in Setting up State Derivative Models.
bodiesToIntegrate

std::vector< std::string > that contains the names of the bodies to integrate which must match with those in the BodyMap.

initialBodyStates

Eigen::Matrix< StateScalarType, Eigen::Dynamic, 1 > that stores the states of the bodies to propagate with respect to their central bodies.
Note

The state variables contained in initialBodyStates are ordered with respect to the elements of centralBodies and bodiesToIntegrate. Please take a look at the following pseudocode:
centralBodies = { Sun , Earth , Moon }
bodiesToIntegrate = { Earth , Moon }
initialBodyStates = { xEarthWrtSun , yEarthWrtSun , zEarthWrtSun , uEarthWrtSun , vEarthWrtSun , wEarthWrtSun ,
                  xMoonWrtEarth , yMoonWrtEarth , zMoonWrtEarth , uMoonWrtEarth , vMoonWrtEarth , wMoonWrtEarth }

endTime

double that defines the end-time of the simulation.
propagator
TranslationalPropagatorType which defines the type of propagator to be used. Currently, the following propagators are supported:
cowell

encke

gauss_keplerian

gauss_modified_equinoctial

unified_state_model_quaternions

unified_state_model_modified_rodrigues_parameters

unified_state_model_exponential_map
By default, the cowell propagator is used. Moreover, you should keep in mind that this option only changes the coordinates for propagation, but the acceleration model is still computed with Cartesian coordinates, i.e., the conventional coordinates.

Tip

You can find more information about the difference between conventional and propagated coordinates in Propagator Settings: Conventional vs. Propagated Coordinates.
dependentVariablesToSave

std::shared_ptr< DependentVariableSaveSettings > that presents a list of the dependent variables to save during propagation. How this is exactly done is explained below. By default, an empty list is used and no dependent variable is saved. See the tutorial on DependentVariableSaveSettings for more details on this class. Note that the dependentVariablesToSave may be left unspecified, in which case no dependent variables are saved, so:

TranslationalStatePropagatorSettings<StateScalarType>( centralBodies,
                                                       accelerationsMap,
                                                       bodiesToIntegrate,
                                                       initialBodyStates,
                                                       endTime,
                                                       propagator )

With user-defined termination settings

TranslationalStatePropagatorSettings<StateScalarType>( centralBodies,
                                                       accelerationsMap,
                                                       bodiesToIntegrate,
                                                       initialBodyStates,
                                                       terminationSettings,
                                                       propagator,
                                                       dependentVariablesToSave )

where:

terminationSettings

std::shared_ptr< PropagationTerminationSettings > that defines the termination settings of the propagation. This is the fifth argument and replaces the endTime in the default constructor. See the tutorial on PropagationTerminationSettings for more details on this class.

class RotationalStatePropagatorSettings¶

This class implements the framework required to propagate the rotational dynamics of a body. The settings are constructed as follows:

RotationalStatePropagatorSettings< StateScalarType >( torqueModelMap,
                                                      bodiesToIntegrate,
                                                      initialBodyStates,
                                                      terminationSettings,
                                                      propagator,
                                                      dependentVariablesToSave )

where:

torqueModelMap

TorqueModelMap List of torque models that are to be used in propagation.
bodiesToIntegrate

std::vector< std::string > that contains the names of the bodies to integrate which must match with those in the BodyMap.
initialBodyStates

Eigen::Matrix< StateScalarType, Eigen::Dynamic, 1 > that stores the states of the bodies to propagate with respect to their central bodies.
terminationSettings

std::shared_ptr< PropagationTerminationSettings > that defines the termination settings of the propagation. See the tutorial on PropagationTerminationSettings for more details on this class.
propagator
RotationalPropagatorType which defines the type of propagator to be used. Currently, the following propagators are supported:
quaternions

modified_rodrigues_parameters

exponential_map
By default, the quaternions propagator is used. Moreover, you should keep in mind that this option only changes the coordinates for propagation, but the acceleration model is still computed with quaternions, i.e., the conventional coordinates.

Tip

You can find more information about the difference between conventional and propagated coordinates in Propagator Settings: Conventional vs. Propagated Coordinates.
dependentVariablesToSave

std::shared_ptr< DependentVariableSaveSettings > that presents a list of the dependent variables to save during propagation. How this is exactly done is explained below. By default, an empty list is used and no dependent variable is saved. See the tutorial on DependentVariableSaveSettings for more details on this class.

class MassPropagationSettings¶

This class implements the framework required to propagate the mass of a body. The constructor of this derived class is overloaded allowing either a single mass-rate per body or multiple mass-rates per body:

Single mass-rate model per body

MassPropagationSettings< StateScalarType >( bodiesWithMassToPropagate,
                                            massRateModels,
                                            initialBodyMasses,
                                            terminationSettings,
                                            dependentVariablesToSave )

where:

bodiesWithMassToPropagate

std::vector< std::string > that provides the names of the bodies with mass that must be propagated. These names must match with those in the BodyMap.
massRateModels

std::map< std::string, std::shared_ptr< MassRateModel > > that associates a MassRateModel to every body with mass that needs to be propagated.
initialBodyMasses

Eigen::Matrix< StateScalarType, Eigen::Dynamic, 1 > passed by reference that associates an initial body mass to each body with mass to be propagated.
terminationSettings

std::shared_ptr< PropagationTerminationSettings > that defines the termination settings of the propagation. See the tutorial on PropagationTerminationSettings for more details on this class.
dependentVariablesToSave

std::shared_ptr< DependentVariableSaveSettings > that presents a list of the dependent variables to save during propagation. How this is exactly done is explained below. By default, an empty list is used and no dependent variable is saved. See the tutorial on DependentVariableSaveSettings for more details on this class.

Various mass-rate models per body

MassPropagationSettings< StateScalarType >( bodiesWithMassToPropagate,
                                            massRateModels,
                                            initialBodyMasses,
                                            terminationSettings,
                                            dependentVariablesToSave )

where:

massRateModels

std::map< std::string, std::vector< std::shared_ptr< MassRateModel > > > that associates a std::vector of MassRateModel to each body with mass to be propagated.

class CustomStatePropagatorSettings¶

This class allows the user to define and propagate its own state derivative function. The constructor of this derived class is overloaded allowing the user to either use a scalar state or vector state:

Using a scalar state

CustomStatePropagatorSettings< StateScalarType, TimeType >( stateDerivativeFunction,
                                                            initialState,
                                                            terminationSettings,
                                                            dependentVariablesToSave )

where:

TimeType

Template argument used to set the precision of the time, in general double is used. For some application where a high precision is required this can be changed to e.g. :literal`long double`.
stateDerivativeFunction

std::function< StateScalarType( const TimeType , const StateScalarType ) > that must comply with the requirements discussed in Integrators.
initialState

StateScalarType that stores the initial state.

Using a vector state

CustomStatePropagatorSettings< StateScalarType, TimeType >( stateDerivativeFunction,
                                                            initialState,
                                                            terminationSettings,
                                                            dependentVariablesToSave )

where:

stateDerivativeFunction

std::function< Eigen::VectorXd( const double , const Eigen::VectorXd ) > that must comply with the requirements discussed in Integrators.
initialState

Eigen::VectorXd that stores the initial state.

class MultiTypePropagatorSettings¶

This class is used to propagate multiple types of PropagatorSettings concurrently, for instance a translational-rotational dynamics, translational and mass dynamics (spacecraft under thrust) etc. Note that the types of dynamics need not apply to the same body, you may for instance propagate the translational state and mass of a spacecraft concurrently with the rotational state of the Earth. The constructor of this class is overloaded depending on how the list of propagator settings is passed (with the former being typical) :
Using an std::vector
MultiTypePropagatorSettings< StateScalarType >( propagatorSettingsMap,
                                               terminationSettings,
                                               dependentVariablesToSave )
where:

propagatorSettingsMap

std::vector< std::shared_ptr< PropagatorSettings< StateScalarType > > > where each element contains a pointer to a PropagatorSettings class. This class is the simplest to use, since it allows to pass a set of unsorted PropagatorSettings derived classes by means of the push_back method of std::vector.
Using an std::map
MultiTypePropagatorSettings< StateScalarType >( propagatorSettingsMap,
                                                terminationSettings,
                                                dependentVariablesToSave )
where:

propagatorSettingsMap

std::map< IntegratedStateType, std::vector< std::shared_ptr< PropagatorSettings< StateScalarType > > > > where each element contains a pointer to a PropagatorSettings class. This class requires a sorted list PropagatorSettings derived classes.

Warning

When using the MultiTypePropagatorSettings derived class note that the dependentVariablesToSave need to be passed in this constructor and not inside the propagatorSettingsMap since these will be ignored. The same applies to the termination settings. They have to be defined in this constructor, as those provided inside the propagatorSettingsMap are disregarded as well.

3.2.2. Multi- and Hybrid-arc Propagation¶

class MultiArcPropagatorSettings¶

This class is meant to be used together with a MultiArcDynamicsSimulator. This allows the numerical propagation to be performed in an arc-wise manner. Dynamical model settings may be defined differently per arc.

MultiArcPropagatorSettings< StateScalarType >( singleArcSettings,
                                               transferInitialStateInformationPerArc)

where:

singleArcSettings

std::vector< std::shared_ptr< SingleArcPropagatorSettings< StateScalarType > > > defines the settings for the constituent arcs. The switch times for the arcs are defined by the initial times for each of the arcs.
transferInitialStateInformationPerArc

bool If set to true (default is false), only a single initial state is used: that for the first arc. When this variable is true, the initial state for arc 2 is taken by interpolating the arc 1 state results at the arc 2 start time. This allows a continuous state to be set, while still using the multi-arc interface (for instance for a first estimate when doing multi-arc propagation). If set to false, the initial states from each entry of the singleArcSettings vector will be used.

class HybridArcPropagatorSettings¶

This class is meant to be used together with a HybridArcDynamicsSimulator (see this class description for more details on model implementation). This allows the numerical propagation to be performed, with any number of states propagated in a single arc, and any other states propagated in a multi-arc state. The results of the single-arc propagation are automatically used for the subsequent multi-arc propagation. A typical application is the propagation of a planetary orbiter (multi-arc) and the planet it is orbiting (single-arc).

HybridArcPropagatorSettings< StateScalarType >( singleArcPropagatorSettings, multiArcPropagatorSettings )

where:

singleArcPropagatorSettings

SingleArcPropagatorSettings Settings to be used for the single-arc propagation.
multiArcPropagatorSettings

MultiArcPropagatorSettings Settings to be used for the multi-arc propagation.

Tip

Please beware that all the classes belonging to Tudat libraries are declared above without their namespace. To get the code working please make use of the appropriate #include and using statements.