Added minor missing comments to BS/ABAM integrators

Tudat/Astrodynamics/Propagators/dynamicsStateDerivativeModel.h

@@ -449,12 +449,23 @@ class DynamicsStateDerivativeModel
         return stateTypeStartIndex_;
     }
 
-
+    //! Function to retrieve number of calls to the computeStateDerivative function
+    /*!
+     * Function to retrieve number of calls to the computeStateDerivative function since object creation/last call to
+     * resetFunctionEvaluationCounter function
+     * \return Number of calls to the computeStateDerivative function since object creation/last call to
+     * resetFunctionEvaluationCounter function
+     */
     int getNumberOfFunctionEvaluations( )
     {
         return functionEvaluationCounter_;
     }
 
+    //! Function to resetr the number of calls to the computeStateDerivative function to zero.
+    /*!
+     * Function to resetr the number of calls to the computeStateDerivative function to zero.  Typically called before any
+     * start of numerical integration of dynamics (automatically by DynamicsSimulator)
+     */
     void resetFunctionEvaluationCounter( )
     {
         functionEvaluationCounter_ = 0;
@@ -504,19 +515,13 @@ class DynamicsStateDerivativeModel
                 // Get state block indices of current state derivative model
                 currentIndices = stateIndices_.at( stateDerivativeModelsIterator_->first ).at( i );
 
-                //                std::cout << "Pre-converted state: " << state.block( currentIndices.first, startColumn, currentIndices.second, 1 ).transpose( ) << std::endl;
-
                 // Set current block in split state (in global form)
                 stateDerivativeModelsIterator_->second.at( i )->convertCurrentStateToGlobalRepresentation(
                             state.block( currentIndices.first, startColumn, currentIndices.second, 1 ), time,
                             currentStatesPerTypeInConventionalRepresentation_.at(
                                 stateDerivativeModelsIterator_->first ).block(
                                 currentStateTypeSize, 0, currentIndices.second, 1 ) );
 
-                //                std::cout << "Converted state: " << currentStatesPerTypeInConventionalRepresentation_.at(
-                //                               stateDerivativeModelsIterator_->first ).block(
-                //                               currentStateTypeSize, 0, currentIndices.second, 1 ).transpose( ) << std::endl;
-
                 currentStateTypeSize += currentIndices.second;
             }
         }
@@ -573,6 +578,7 @@ class DynamicsStateDerivativeModel
     std::unordered_map< IntegratedStateType, Eigen::Matrix< StateScalarType, Eigen::Dynamic, 1 > >
     currentStatesPerTypeInConventionalRepresentation_;
 
+    //! Variable to keep track of the number of calls to the computeStateDerivative function
     int functionEvaluationCounter_ = 0;
 };
 

Tudat/Mathematics/NumericalIntegrators/adamsBashforthMoultonIntegrator.h

@@ -546,8 +546,8 @@ class AdamsBashforthMoultonIntegrator
     //! Set the minimum and maximum step size.
     /*!
      * Change the bounds of the stepsize.
-     * \param minimum stepsize
-     * \param maximum stepsize
+     * \param minimumStepSize minimum stepsize
+     * \param maximumStepSize maximum stepsize
      */
     void setStepSizeBounds( IndependentVariableType minimumStepSize, IndependentVariableType maximumStepSize ) {
         minimumStepSize_ = minimumStepSize;
@@ -572,8 +572,18 @@ class AdamsBashforthMoultonIntegrator
      */
     void setStepSize( IndependentVariableType stepSize ) { stepSize_ = stepSize; }
 
+    //! Function to reset the minimum order of the integrator
+    /*!
+     * Function to reset the minimum order of the integrator
+     * \param minimumOrder New minimum order of the integrator
+     */
     void setMinimumOrder( unsigned int minimumOrder ){ minimumOrder_ = minimumOrder; }
 
+    //! Function to reset the maximum order of the integrator
+    /*!
+     * Function to reset the maximum order of the integrator
+     * \param maximumOrder New maximum order of the integrator
+     */
     void setMaximumOrder( unsigned int maximumOrder ){ maximumOrder_ = maximumOrder; }
 
     IndependentVariableType getPreviousIndependentVariable( )
@@ -793,8 +803,8 @@ class AdamsBashforthMoultonIntegrator
     //! Perform predictor step.
     /*!
      * Using the order find predicted estimate using the Adams-Bashforth predictor
-     * \param order of the integration.
-     * \param boolean if stepsize should be considered double, true for estimating doubling error.
+     * \param order Order of the integration.
+     * \param doubleStep Boolean if stepsize should be considered double, true for estimating doubling error.
      * \return state after predictor step
      */
     StateType performPredictorStep( unsigned int order, bool doubleStep )
@@ -865,8 +875,8 @@ class AdamsBashforthMoultonIntegrator
      * true if first one is better than second (smaller is better).
      * \param absoluteError1 absolute error one.
      * \param relativeError1 relative error one.
-     * \param absoluteError1 absolute error two.
-     * \param relativeError1 relative error two.
+     * \param absoluteError2 absolute error two.
+     * \param relativeError2 relative error two.
      * \return true if one is better than two, false otherwise.
      */
     bool errorCompare( StateType absoluteError1, StateType relativeError1,
@@ -912,8 +922,8 @@ class AdamsBashforthMoultonIntegrator
     /*!
      * Checks error (absolute and relative form) and return true if
      * the exceed tolerance limits.
-     * \param a absolute error.
-     * \param r relative error.
+     * \param absoluteError absolute error.
+     * \param relativeError relative error.
      * \return true if one error is too small, false if within limits
      */
     bool errorTooSmall( StateType absoluteError, StateType relativeError )

Tudat/Mathematics/NumericalIntegrators/bulirschStoerVariableStepsizeIntegrator.cpp

@@ -26,7 +26,7 @@ namespace tudat
 namespace numerical_integrators
 {
 
-
+//! Function to retrieve the sequence of number of steps to used for Bulirsch-Stoer integration
 std::vector< unsigned int > getBulirschStoerStepSequence(
         const ExtrapolationMethodStepSequences& extrapolationMethodStepSequenceType,
         const unsigned int lengthOfSequence )

Tudat/Mathematics/NumericalIntegrators/bulirschStoerVariableStepsizeIntegrator.h

@@ -37,13 +37,20 @@ namespace tudat
 namespace numerical_integrators
 {
 
+//! Types of sequences available for extrapolation integration methods
 enum ExtrapolationMethodStepSequences
 {
     bulirsch_stoer_sequence,
     deufelhard_sequence
 };
 
-
+//! Function to retrieve the sequence of number of steps to used for Bulirsch-Stoer integration
+/*!
+ * Function to retrieve the sequence of number of steps to used for Bulirsch-Stoer integration
+ * \param extrapolationMethodStepSequenceType Type of sequence that is to be retrieved
+ * \param lengthOfSequence Length of the sequence that is to be retrieved (default 12)
+ * \return Function to retrieve the sequence of number of steps to used for Bulirsch-Stoer integration
+ */
 std::vector< unsigned int > getBulirschStoerStepSequence(
         const ExtrapolationMethodStepSequences& extrapolationMethodStepSequenceType = bulirsch_stoer_sequence,
         const unsigned int lengthOfSequence = 12 );
@@ -88,8 +95,14 @@ class BulirschStoerVariableStepSizeIntegrator :
      * \param initialState The initial state.
      * \param minimumStepSize The minimum step size to take. If this constraint is violated, a
      *          flag will be set that can be retrieved with isMinimumStepSizeViolated( ).
+     * \param maximumStepSize The maximum step size to take.
      * \param relativeErrorTolerance The relative error tolerance, for each individual state
      *          vector element.
+     * \param absoluteErrorTolerance The absolute error tolerance, for each individual state
+     *          vector element.
+     * \param safetyFactorForNextStepSize Safety factor used to scale prediction of next step size.
+     * \param maximumFactorIncreaseForNextStepSize Maximum factor increase for next step size.
+     * \param minimumFactorDecreaseForNextStepSize Maximum factor decrease for next step size.
      * \sa NumericalIntegrator::NumericalIntegrator.
      */
     BulirschStoerVariableStepSizeIntegrator(
@@ -127,14 +140,20 @@ class BulirschStoerVariableStepSizeIntegrator :
     /*!
      * Default constructor, taking coefficients, a state derivative function, initial conditions,
      * minimum step size and relative error tolerance for all items in the state vector as argument.
-     * \param coefficients Coefficients to use with this integrator.
+     * \param sequence Rational function sequence used by algorithm.
      * \param stateDerivativeFunction State derivative function.
      * \param intervalStart The start of the integration interval.
      * \param initialState The initial state.
      * \param minimumStepSize The minimum step size to take. If this constraint is violated, a
      *          flag will be set that can be retrieved with isMinimumStepSizeViolated( ).
+     * \param maximumStepSize The maximum step size to take.
      * \param relativeErrorTolerance The relative error tolerance, equal for all individual state
      *          vector elements.
+     * \param absoluteErrorTolerance The absolute error tolerance, for each individual state
+     *          vector element.
+     * \param safetyFactorForNextStepSize Safety factor used to scale prediction of next step size.
+     * \param maximumFactorIncreaseForNextStepSize Maximum factor increase for next step size.
+     * \param minimumFactorDecreaseForNextStepSize Maximum factor decrease for next step size.
      * \sa NumericalIntegrator::NumericalIntegrator.
      */
     BulirschStoerVariableStepSizeIntegrator(
@@ -401,6 +420,10 @@ class BulirschStoerVariableStepSizeIntegrator :
      */
     TimeStepType minimumStepSize_;
 
+    //! Minimum step size.
+    /*!
+     * Maximum step size.
+     */
     TimeStepType maximumStepSize_;
 
     //! Relative error tolerance.
@@ -415,13 +438,27 @@ class BulirschStoerVariableStepSizeIntegrator :
      */
     StateType absoluteErrorTolerance_;
 
-
+    //! Safety factor for next step size.
+    /*!
+     * Safety factor used to scale prediction of next step size. This is usually picked between
+     * 0.8 and 0.9 (Burden and Faires, 2001).
+     */
     TimeStepType safetyFactorForNextStepSize_;
 
-
+    //! Maximum factor increase for next step size.
+    /*!
+     * The maximum factor by which the next step size can increase compared to the current value.
+     * The need for this maximum stems from a need to ensure that the step size changes do not
+     * alias with the dynamics of the model being integrated.
+     */
     TimeStepType maximumFactorIncreaseForNextStepSize_;
 
-
+    //! Minimum factor decrease for next step size.
+    /*!
+     * The minimum factor by which the next step size can decrease compared to the current value.
+     * The need for this minimum stems from a need to ensure that the step size changes do not
+     * alias with the dynamics of the model being integrated.
+     */
     TimeStepType minimumFactorDecreaseForNextStepSize_;
 
     //! Flag to indicate whether the minimum step size constraint has been violated.
@@ -437,7 +474,7 @@ class BulirschStoerVariableStepSizeIntegrator :
      * \param stateAtCenterPoint State at center point.
      * \param independentVariableAtFirstPoint Independent variable at first point.
      * \param subStepSize Sub step size between successive states used by mid-point method.
-     * \param stateAtLastPoint State at last point.
+     * \return Result of midpoint method
      */
     StateType executeMidPointMethod( StateType stateAtFirstPoint, StateType stateAtCenterPoint,
                                      const IndependentVariableType independentVariableAtFirstPoint,

Tudat/Mathematics/NumericalIntegrators/createNumericalIntegrator.h

@@ -211,11 +211,12 @@ class BulirschStoerIntegratorSettings: public IntegratorSettings< TimeType >
     //! Constructor
     /*!
      *  Constructor for variable step RK integrator settings.
-     *  \param integratorType Type of numerical integrator (must be an RK variable step type)
      *  \param initialTime Start time (independent variable) of numerical integration.
      *  \param initialTimeStep Initial time (independent variable) step used in numerical integration.
      *  Adapted during integration
-     *  \param coefficientSet Coefficient set (butcher tableau) to use in integration.
+     *  \param extrapolationSequence Type of sequence that is to be used for Bulirsch-Stoer integrator
+     *  \param maximumNumberOfSteps Number of entries in teh sequence, e.g. number of integrations used for a single
+     *  extrapolation.
      *  \param minimumStepSize Minimum step size for integration. Integration stops (exception thrown) if time step
      *  comes below this value.
      *  \param maximumStepSize Maximum step size for integration.
@@ -258,8 +259,10 @@ class BulirschStoerIntegratorSettings: public IntegratorSettings< TimeType >
      */
     ~BulirschStoerIntegratorSettings( ){ }
 
+    //! Type of sequence that is to be used for Bulirsch-Stoer integrator
     ExtrapolationMethodStepSequences extrapolationSequence_;
 
+    //! Number of entries in teh sequence, e.g. number of integrations used for a single extrapolation.
     unsigned int maximumNumberOfSteps_;
 
     //! Minimum step size for integration.
@@ -302,16 +305,16 @@ class AdamsBashforthMoultonSettings: public IntegratorSettings< TimeType >
     //! Constructor
     /*!
      *  Constructor for variable step RK integrator settings.
-     *  \param integratorType Type of numerical integrator (must be an RK variable step type)
      *  \param initialTime Start time (independent variable) of numerical integration.
      *  \param initialTimeStep Initial time (independent variable) step used in numerical integration.
      *  Adapted during integration
-     *  \param coefficientSet Coefficient set (butcher tableau) to use in integration.
      *  \param minimumStepSize Minimum step size for integration. Integration stops (exception thrown) if time step
      *  comes below this value.
      *  \param maximumStepSize Maximum step size for integration.
      *  \param relativeErrorTolerance Relative error tolerance for step size control
      *  \param absoluteErrorTolerance Absolute error tolerance for step size control
+     *  \param minimumOrder Minimum order of integrator (default 6)
+     *  \param maximumOrder Maximum order of integrator (default 11)
      *  \param saveFrequency Frequency at which to save the numerical integrated states (in units of i.e. per n integration
      *  time steps, with n = saveFrequency).
      *  \param assessPropagationTerminationConditionDuringIntegrationSubsteps Whether the propagation termination
@@ -358,8 +361,10 @@ class AdamsBashforthMoultonSettings: public IntegratorSettings< TimeType >
     //! Absolute error tolerance for step size control
     TimeType absoluteErrorTolerance_;
 
+    //! Minimum order of integrator
     const int minimumOrder_;
 
+    //! Maximum order of integrator
     const int maximumOrder_;
 
     //! Safety factor for step size control