Module: svIntegratorAdaptiveRungeKutta

template<size_t numberStages>
struct RKAdaptiveCoefficients : public RKCoefficients<numberStages>

#include <svIntegratorAdaptiveRungeKutta.h>

Extends RKCoefficients with “b” coefficients used for the lower order method.

The extended Butcher table looks like:

Public Members

RKCoefficients<numberStages>::StageSizedArray bStarArray = {}

“b*” Coefficients of the Adaptive RK method (“b” coefficients of the higher order method)

template<size_t numberStages>
class svIntegratorAdaptiveRungeKutta : public svIntegratorRungeKutta<numberStages>

#include <svIntegratorAdaptiveRungeKutta.h>

The svIntegratorRungeKutta class implements a state integrator based on the family of explicit Runge-Kutta numerical integrators with variable time step.

When ‘svIntegratorAdaptiveRungeKutta::integrate’ is called, this integrator will try to integrate with the given time step. It will then evaluate the error commited and, if it’s too large, internally use smaller time steps until the error tolerances are met.

Public Functions

svIntegratorAdaptiveRungeKutta(DynamicObject *dynIn, const RKAdaptiveCoefficients<numberStages> &coefficients, const double methodLargestOrder)

Constructs the integrator for the given dynamic object and specified Adaptive RK coefficients.

methodLargestOrder is the higher order of the two orders used in adaptive RK methods. For the RKF45 method, for example, methodLargestOrder should be 5.

virtual void integrate(double currentTime, double timeStep) override

Performs the integration of the associated dynamic objects up to time currentTime+timeStep

void setRelativeTolerance(double relTol)

Sets the relative tolerance for every DynamicObject and every state.

This is akin to changing svIntegratorAdaptiveRungeKutta::relTol directly

double getRelativeTolerance()

Returns the relative tolerance for every DynamicObject and every state.

This is akin to reading svIntegratorAdaptiveRungeKutta::relTol directly

void setAbsoluteTolerance(double absTol)

Sets the absolute tolerance for every DynamicObject and every state.

This is akin to changing svIntegratorAdaptiveRungeKutta::absTol directly

double getAbsoluteTolerance()

Returns the absolute tolerance for every DynamicObject and every state.

This is akin to reading svIntegratorAdaptiveRungeKutta::absTol directly

void setRelativeTolerance(std::string stateName, double relTol)

Sets the relative tolerance for every DynamicObject and the state identified by the given name.

std::optional<double> getRelativeTolerance(std::string stateName)

Returns the relative tolerance for every DynamicObject and the state identified by the given name.

If the relative tolerance for this state was not set, then returns an empty optional.

void setAbsoluteTolerance(std::string stateName, double absTol)

Sets the absolute tolerance for every DynamicObject and the state identified by the given name.

std::optional<double> getAbsoluteTolerance(std::string stateName)

Returns the absolute tolerance for every DynamicObject and the state identified by the given name.

If the absolute tolerance for this state was not set, then returns an empty optional.

void setRelativeTolerance(const DynamicObject &dynamicObject, std::string stateName, double relTol)

Sets the relative tolerance for the given DynamicObject and the state identified by the given name.

inline std::optional<double> getRelativeTolerance(const DynamicObject &dynamicObject, std::string stateName)

Returns the relative tolerance for the given DynamicObject and the state identified by the given name.

If the relative tolerance for this state and DynamicObject was not set, then returns an empty optional.

void setAbsoluteTolerance(const DynamicObject &dynamicObject, std::string stateName, double absTol)

Sets the absolute tolerance for the given DynamicObject and the state identified by the given name.

inline std::optional<double> getAbsoluteTolerance(const DynamicObject &dynamicObject, std::string stateName)

Returns the absolute tolerance for he given DynamicObject and the state identified by the given name.

If the absolute tolerance for this state and DynamicObject was not set, then returns an empty optional.

Public Members

double relTol = 1e-4

Maximum relative truncation error allowed.

The relative truncation error is the absolute error of the state divided by the magnitude of the state.

double absTol = 1e-8

Maximum absolute truncation error allowed.

double safetyFactorForNextStepSize = 0.9

When a new step size is computed, it is multiplied by this factor.

New step sizes are initially computed so that the error made using the new step matches exactly the tolerance limits. By providing a safetyFactor < 0.9, we obtain a step size the produces a lower error than the tolerance, thus almost guaranteen that we don’t repeat a step twice.

double maximumFactorIncreaseForNextStepSize = 4.0

When a new step size is computed, it can only be maximumFactorIncreaseForNextStepSize times the old step size.

double minimumFactorDecreaseForNextStepSize = 0.1

When a new step size is computed, it must be above minimumFactorDecreaseForNextStepSize times the old step size.

Protected Functions

double computeMaxRelativeError(double timeStep, const ExtendedStateVector &candidateNextState, const typename svIntegratorRungeKutta<numberStages>::KCoefficientsValues &kVectors) const

Computes the absolute error of every state using the lower and higher order RK methods.

Then, the norm of each state error is compared to the error tolerance for that state. Greatest relation between error and tolerance is returned, which is the relation that defines the minimum acceptable time step.

size_t findDynamicObjectIndex(const DynamicObject &dynamicObject) const

Finds index of dynamicObject in dynPtrs (vector of pointers to DynamicObject)

double getTolerance(size_t dynamicObjectIndex, const std::string &stateName, double stateNorm) const

Combines the relative and absolute tolerances into a single tolerance

This checks for the general, state-specific, and dynamicObject-state-specific tolerances; only the most specific tolerance is used.

Protected Attributes

const double methodLargestOrder

The higher order of the two orders used in adaptive RK methods.

For the RKF45 method, for example, methodLargestOrder should be 5.

std::unordered_map<std::string, double> stateSpecificRelTol

Holds the maximum relative truncation error allowed for specific states

std::unordered_map<std::string, double> stateSpecificAbsTol

Holds the maximum absolute truncation error allowed for specific states

std::unordered_map<ExtendedStateId, double, ExtendedStateIdHash> dynObjectStateSpecificRelTol

Holds the maximum relative truncation error allowed for specific states of specific dynamic objects

std::unordered_map<ExtendedStateId, double, ExtendedStateIdHash> dynObjectStateSpecificAbsTol

Holds the maximum absolute truncation error allowed for specific states of specific dynamic objects