C++ Module: stochasticRKIntegratorBase

StochasticRKIntegratorBase connects the shared stochastic topology to a GaussianNoiseGenerator and the concrete method’s workspace. The public setRNGSeed() and setNoiseGenerator() configuration methods remain independent of the stage recurrence.

The binding hook allocates topology-sized Wiener and auxiliary output, then invokes bindStochasticMethodStorage(). Incomplete preparation is discarded on failure. Retirement calls the method’s release hook and frees shared numerical storage while retaining generator configuration.

Concrete methods implement integrateImpl() and request only the noise output they need. Wiener-only methods avoid unused auxiliary draws; other methods can request an auxiliary prefix. Built-in generators fill preallocated buffers. Compatibility adapters permit older custom generators, which may still allocate or produce unused auxiliary values.

A local shared pointer keeps a custom generator alive during its callback, including if that callback replaces the configured generator. The exact built-in generator can use a cached direct pointer. State rollback does not rewind either generator. See Dynamics state and integrator architecture for the complete stochastic call path.

Noise-generator ownership and stochastic method workspace binding.

class StochasticRKIntegratorBase : public StateVecStochasticIntegrator 

#include <stochasticRKIntegratorBase.h>

Shared base for the native stochastic Runge-Kutta integrators (Euler-Maruyama, the SRI/SRA strong methods, the weak W2Ito/DRI1/RI/RS/SIESME families, RDI1WM and Euler-Heun/RKMil).

It factors out the machinery every one of these integrators needs, so each concrete method implements its own integrateImpl() recurrence and, when needed, bindStochasticMethodStorage() hook:

a pluggable GaussianNoiseGenerator (defaulting to a random Mersenne-Twister source, replaceable by a prescribed-replay generator for tests), plus the setRNGSeed / setNoiseGenerator accessors;
one canonical flat state/noise binding shared by all concrete methods.

Every native stochastic integrator derives from this base. Methods that need only the Wiener increment use the base buffers through the generator’s Wiener-only interface; dZ remains available as compatibility scratch for legacy generators. Generator output and method storage are prepared in the same binding transaction. A method failure restores state through the stochastic base but does not rewind RNG position. The built-in generator uses a cached exact-type pointer; custom generators are held by a local shared owner while their callbacks run.

Warning

Stochastic integration is in beta.

Subclassed by svIntegratorStrongStochasticRungeKuttaSRA< numberStages >, svIntegratorStrongStochasticRungeKuttaSRI< numberStages >, svIntegratorWeakSIESME

Public Functions

void setRNGSeed(size_t seed)

Sets the seed for the (default) Random Number Generator used by this integrator.

As a stochastic integrator, random numbers are drawn during each time step. By default a randomly generated seed is used. Setting the seed makes the integrator draw the same sequence each run. Has no effect if a custom noise generator that does not honour the seed was installed via setNoiseGenerator.

void setNoiseGenerator(std::shared_ptr<GaussianNoiseGenerator> generator): Replaces the noise generator used by this integrator. This is primarily useful for testing, where a PrescribedGaussianNoiseGenerator can be installed so the integrator replays a known sequence of Wiener increments.

Protected Functions

virtual void prepareIntegrationBinding() override: Prepare shared noise output and method scratch before binding commits.

inline virtual void validateIntegrationBinding() const override: Verify the borrowed topology before reusing numerical storage.

inline virtual void bindStochasticMethodStorage(): Allocates method-specific scratch in the topology-binding transaction.

template<typename MethodBinder> inline void bindFlatStochasticStorage(MethodBinder &&bindMethodStorage): Binds topology, generator output, and method scratch as one transaction.

void bindFlatStochasticStorage(): Binds methods that need no additional scratch beyond the flat base.

void generateNoise(double timeStep): Draws one sample into preallocated dW and dZ buffers.

void generateNoise(double timeStep, size_t auxiliaryCount): Draws Wiener increments and only the requested auxiliary prefix.

void generateWienerNoise(double timeStep): Draws only Wiener increments, reusing dZ as compatibility scratch.

inline const Eigen::VectorXd &flatDW() const noexcept: Preallocated Wiener increments for flat stochastic methods.

inline const Eigen::VectorXd &flatDZ() const noexcept: Preallocated auxiliary Gaussian increments for flat stochastic methods.

Private Functions

inline std::shared_ptr<GaussianNoiseGenerator> noiseGenerator() const: Hold the configured generator alive across a potentially replacing callback.

void bindFlatStochasticCore(): Bind topology and size Wiener/auxiliary buffers once.

void resetFlatStochasticStorage() noexcept: Discard incomplete topology and noise output after binding failure.

Private Members

bool flatNoiseOutputBound = false: True after topology-sized output allocation commits.

Eigen::VectorXd dW: Wiener increments indexed by independent global source.

Eigen::VectorXd dZ: Auxiliary Gaussian output; only the requested prefix is meaningful.

std::shared_ptr<GaussianNoiseGenerator> rvGenerator = std::make_shared<RandomGaussianNoiseGenerator>(): Random Number Generator for the integrator (supplies dW and dZ per noise source).

RandomGaussianNoiseGenerator *nativeGenerator = static_cast<RandomGaussianNoiseGenerator*>(this->rvGenerator.get()): Cached exact built-in type, or null for custom generators. Exact built-in generators cannot replace themselves from a callback.