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

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.
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 Acceleration Set-Up.

  • 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 being used. Currently, cowell, encke, gaus_keplerian and gaus_modified_equinoctial are available. By default, the cowell propagator is used.

  • dependentVariablesToSave

    boost::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.

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 }
User-defined termination settings
TranslationalStatePropagatorSettings<StateScalarType>( centralBodies,
                                      accelerationsMap,
                                      bodiesToIntegrate,
                                      initialBodyStates,
                                      terminationSettings,
                                      propagator,
                                      dependentVariablesToSave )

where:

  • terminationSettings

    boost::shared_ptr< PropagationTerminationSettings > that defines the termination settings of the propagation. This is the fifth argument and replaces the endTime in the default constructor.

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,
          dependentVariablesToSave )

where:

  • torqueModelMap

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

class MassPropagatorSettings

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
MassPropagatorSettings<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, boost::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
MassPropagatorSettings<StateScalarType>(
        bodiesWithMassToPropagate,
        massRateModels,
        initialBodyMasses,
        terminationSettings,
        dependentVariablesToSave )

where:

  • massRateModels

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

class CustomPropagatorSettings

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

    boost::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

    boost::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. The constructor of this class is overloaded depending on how the list of propagator settings is passed:

Using an std::vector
MultiTypePropagatorSettings<StateScalarType>(
    propagatorSettingsMap,
    terminationSettings,
    dependentVariablesToSave )

where:

  • propagatorSettingsMap

    std::vector< boost::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< boost::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.

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< boost::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 allows only a single initial state to be defined: that for the first arc. When this variable is true, the initial state for arc 2 is taken from interpolating arc 1 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).

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.