C Module: svIntegratorRungeKutta
svIntegratorRungeKutta<numberStages> implements fixed-step explicit
Runge–Kutta integration from a Butcher tableau. Concrete RK methods supply the
stage count and coefficients. The constructor rejects nonfinite coefficients
and matrices that are not strictly lower triangular.
The class uses FlatStateBinding for topology and owns a flat base state,
candidate scratch, combined drift, and one contiguous derivative column per stage.
Each stage makes its candidate visible before evaluating the dynamics. Euclidean
states use vector arithmetic; special states dispatch through their registered
StateUpdatePolicy. A single all-Euclidean object’s live buffer can serve directly
as the candidate destination.
On failure, step-entry state is restored if the participating dynamics objects are still alive. Derivative buffers and external callback effects are not checkpointed. See Dynamics state and integrator architecture for equations and lifecycle rules.
Explicit Runge-Kutta stages over finalized flat state storage.
-
template<size_t numberStages>
struct RKCoefficients - #include <svIntegratorRungeKutta.h>
Stores the coefficients necessary to use the Runge-Kutta methods.
The Butcher table looks like:
c | A
b
Subclassed by RKAdaptiveCoefficients< numberStages >
Public Types
-
using StageSizedArray = std::array<double, numberStages>
Array with size = numberStages
-
using StageSizedMatrix = std::array<StageSizedArray, numberStages>
Square matrix with size = numberStages
Public Members
-
StageSizedMatrix aMatrix = {}
“a” coefficient matrix of the RK method
-
StageSizedArray bArray = {}
“b” coefficient array of the RK method
-
StageSizedArray cArray = {}
“c” coefficient array of the RK method
-
using StageSizedArray = std::array<double, numberStages>
-
template<size_t numberStages>
class svIntegratorRungeKutta : public StateVecIntegrator - #include <svIntegratorRungeKutta.h>
The svIntegratorRungeKutta class implements a state integrator based on the family of explicit Runge-Kutta numerical integrators.
A Runge-Kutta method is defined by its stage number and its coefficients. The stage number drives the computational cost of the method: an RK method of stage 4 requires 4 dynamics evaluations (FSAL optimizations are not done).
The integrator binds finalized registries through FlatStateBinding and owns one contiguous derivative column per stage. Adjacent Euclidean states share vector arithmetic; special states use their immutable StateUpdatePolicy. A single all-Euclidean object can expose its live buffer as the candidate buffer.
baseState preserves step-entry values for candidate construction and exception rollback. Derived adaptive methods reuse the stage machinery but manage accepted internal steps separately.
Subclassed by svIntegratorAdaptiveRungeKutta< numberStages >
Public Functions
-
svIntegratorRungeKutta(DynamicObject *dynIn, const RKCoefficients<numberStages> &coefficients)
Creates an explicit RK integrator for the given DynamicObject using the passed coefficients.
Protected Functions
-
virtual void integrateImpl(double currentTime, double timeStep) override
Performs the integration of the associated dynamic objects up to time currentTime+timeStep
-
inline virtual void prepareIntegrationBinding() override
Validate topology and allocate stage storage before first use.
-
inline virtual void validateIntegrationBinding() const override
Check that descriptors still address the same finalized buffers.
-
void bindFlatStorage()
Build descriptors and buffers transactionally, or validate an existing binding.
-
void resetFlatStorage() noexcept
Discard descriptors and workspace after failed preparation.
-
void validateFlatBinding() const
Validate object identity and fixed layout through FlatStateBinding.
-
void gatherStates(Eigen::VectorXd &output) const
Copy live state buffers into an already sized combined buffer.
-
void scatterStates(const Eigen::VectorXd &input) const
Make an already sized combined candidate visible to dynamics callbacks.
-
void gatherDerivatives(size_t stageIndex)
Capture live derivative buffers in the selected stage column.
-
void buildFlatCandidate(double timeStep, const std::array<double, numberStages> &stageCoefficients, size_t maxStage, Eigen::Ref<Eigen::VectorXd> output)
Build a policy-aware candidate from baseState and captured stages.
- Parameters:
timeStep – Drift multiplier in seconds.
stageCoefficients – Weights for the captured derivative columns.
maxStage – Number of initialized columns available to this combination.
output – Already sized destination; may alias a live Euclidean buffer.
-
inline const std::vector<FlatStateDescriptor> &flatStateDescriptors() const noexcept
Borrow state shapes and offsets, also used by adaptive tolerance resolution.
-
inline const std::vector<FlatUpdateRun> &flatStateUpdateRuns() const noexcept
Borrow contiguous Euclidean spans and individual special-state runs.
Protected Attributes
-
const RKCoefficients<numberStages> coefficients
Coefficients to be used in the method
-
FlatStateBinding flatBinding
Owns descriptors and borrows finalized registry storage.
-
svIntegratorRungeKutta(DynamicObject *dynIn, const RKCoefficients<numberStages> &coefficients)