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. :literal`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.

  • 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 literal:dependentVariablesToSave may be left unspecified, in which case no dependent variables are saved, so:

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

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

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.

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:

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.