stochasticNoiseGenerator

struct GaussianNoiseSample

#include <stochasticNoiseGenerator.h>

One draw of the Gaussian random variables needed to advance a stochastic integrator by a single time step.

Both members have length m (the number of independent noise sources). dW is the Wiener increment for each noise source; dZ is a second, independent Wiener increment required by the higher-order Roessler methods (SRI/SRA) to build the mixed iterated integrals.

With time step h, each entry of dW and dZ is distributed as \(N(0, h)\).

Public Members

Eigen::VectorXd dW: Wiener increment per noise source, ~ N(0, h).

Eigen::VectorXd dZ: Second independent Wiener increment per noise source, ~ N(0, h).

class GaussianNoiseGenerator

#include <stochasticNoiseGenerator.h>

Interface for the random-variable source used by the native stochastic integrators.

Separating the noise generation from the integrator lets a test install a generator that replays a known sequence of increments (see PrescribedGaussianNoiseGenerator), which is how the Basilisk integrators are checked for numerical equivalence against a reference implementation.

Warning

Stochastic integration is in beta.

Subclassed by PrescribedGaussianNoiseGenerator, RandomGaussianNoiseGenerator

Public Functions

virtual ~GaussianNoiseGenerator() = default

virtual void setSeed(size_t seed) = 0: Sets the seed for the underlying RNG (if any).

virtual GaussianNoiseSample generate(size_t m, double h) = 0: Returns the Gaussian increments for one step with m noise sources and time step h. Both returned vectors have length m.

inline Eigen::VectorXd generateWiener(size_t m, double h)

Returns only the Wiener increments for one step.

This allocation-bearing convenience method is intended for bindings and non-hot-path callers. Native integrators use generateWienerInto.

inline virtual void generateInto(Eigen::VectorXd &dW, Eigen::VectorXd &dZ, size_t m, double h)

Writes one Gaussian sample into caller-owned, pre-sized storage.

The compatibility implementation calls generate() and may allocate. Generators used on allocation-sensitive paths should override this method to write directly into the supplied buffers.

Parameters:

dW – Pre-sized Wiener-increment output.
dZ – Pre-sized second-increment output.
m – Number of independent noise sources.
h – Integration time step.

inline virtual void generateWithAuxiliaryInto(Eigen::VectorXd &dW, Eigen::VectorXd &dZ, size_t m, size_t auxiliaryCount, double h)

Writes Wiener increments and a requested prefix of auxiliary increments.

The compatibility implementation forwards to generateInto and may generate more auxiliary values than requested. Built-in generators override this method so methods that need fewer than m auxiliary values do not pay for unused random draws.

inline virtual void generateWienerInto(Eigen::VectorXd &dW, size_t m, double h)

Writes only Wiener increments into caller-owned, pre-sized storage.

The default preserves source compatibility with custom generators by forwarding through generateInto. Built-in generators override this method to avoid generating an unused auxiliary increment.

inline virtual void generateWienerInto(Eigen::VectorXd &dW, Eigen::VectorXd &unusedDZ, size_t m, double h)

Wiener-only generation with caller-owned compatibility scratch.

Existing custom generators inherit this adapter. Built-in generators override it and leave unusedDZ untouched.

Protected Static Functions

static inline void requireOutputSize(const Eigen::VectorXd &dW, const Eigen::VectorXd &dZ, size_t m): Validates caller-owned generator output dimensions.

static inline void requireWienerOutputSize(const Eigen::VectorXd &dW, size_t m): Validates caller-owned Wiener-only output dimensions.

static inline void requireAuxiliaryOutputSize(const Eigen::VectorXd &dW, const Eigen::VectorXd &dZ, size_t m, size_t auxiliaryCount): Validates a Wiener output and an auxiliary prefix.

class RandomGaussianNoiseGenerator : public GaussianNoiseGenerator 

#include <stochasticNoiseGenerator.h>

Draws the Gaussian increments from a Mersenne-Twister RNG.

This is the default generator used in production. Each entry of dW and dZ is drawn as \(\sqrt{h}\,N(0,1)\). The dW entries are drawn first (indices 0..m-1), then the dZ entries.

Public Functions

inline virtual void setSeed(size_t seed) override: Sets the seed for the underlying RNG (if any).

inline virtual GaussianNoiseSample generate(size_t m, double h) override: Returns the Gaussian increments for one step with m noise sources and time step h. Both returned vectors have length m.

inline virtual void generateInto(Eigen::VectorXd &dW, Eigen::VectorXd &dZ, size_t m, double h) override

Writes one Gaussian sample into caller-owned, pre-sized storage.

The compatibility implementation calls generate() and may allocate. Generators used on allocation-sensitive paths should override this method to write directly into the supplied buffers.

Parameters:

dW – Pre-sized Wiener-increment output.
dZ – Pre-sized second-increment output.
m – Number of independent noise sources.
h – Integration time step.

inline virtual void generateWithAuxiliaryInto(Eigen::VectorXd &dW, Eigen::VectorXd &dZ, size_t m, size_t auxiliaryCount, double h) override

Writes Wiener increments and a requested prefix of auxiliary increments.

The compatibility implementation forwards to generateInto and may generate more auxiliary values than requested. Built-in generators override this method so methods that need fewer than m auxiliary values do not pay for unused random draws.

inline virtual void generateWienerInto(Eigen::VectorXd &dW, size_t m, double h) override

Writes only Wiener increments into caller-owned, pre-sized storage.

The default preserves source compatibility with custom generators by forwarding through generateInto. Built-in generators override this method to avoid generating an unused auxiliary increment.

inline virtual void generateWienerInto(Eigen::VectorXd &dW, Eigen::VectorXd &unusedDZ, size_t m, double h) override

Wiener-only generation with caller-owned compatibility scratch.

Existing custom generators inherit this adapter. Built-in generators override it and leave unusedDZ untouched.

Protected Attributes

std::mt19937 rng = {std::random_device{}()}: Random Number Generator

std::normal_distribution<double> normal_rv = {0., 1.}: Standard normally distributed random variable

class PrescribedGaussianNoiseGenerator : public GaussianNoiseGenerator 

#include <stochasticNoiseGenerator.h>

Replays a pre-computed sequence of Gaussian increments.

Each call to generate advances to the next queued sample. This is used by the unit tests to feed a native integrator exactly the same Wiener increments that a reference implementation used, so that the two can be compared to within floating-point tolerance.

The queued dW/dZ values are the actual increments (already scaled to the step, i.e. distributed as \(N(0,h)\)); they are returned verbatim and the h argument to generate is ignored for the values themselves. If a generate call is made after the queue is exhausted, a std::runtime_error is thrown.

Public Functions

inline virtual void setSeed(size_t) override: Seeding has no effect on a prescribed generator.

inline void pushStep(const std::vector<double> &dW, const std::vector<double> &dZ = {})

Appends one step’s worth of increments to the replay queue.

Parameters:

dW – Wiener increments for each noise source for this step.
dZ – Second Wiener increments for each noise source for this step. May be empty for methods that do not use it, in which case a zero vector of matching length is returned.

inline void clear(): Removes all queued samples.

inline void discardConsumed(): Discards consumed samples while preserving pending FIFO order.

inline size_t remaining() const: Number of steps still queued.

inline virtual GaussianNoiseSample generate(size_t m, double) override: Returns the Gaussian increments for one step with m noise sources and time step h. Both returned vectors have length m.

inline virtual void generateInto(Eigen::VectorXd &dW, Eigen::VectorXd &dZ, size_t m, double) override

Writes one Gaussian sample into caller-owned, pre-sized storage.

The compatibility implementation calls generate() and may allocate. Generators used on allocation-sensitive paths should override this method to write directly into the supplied buffers.

Parameters:

dW – Pre-sized Wiener-increment output.
dZ – Pre-sized second-increment output.
m – Number of independent noise sources.
h – Integration time step.

inline virtual void generateWithAuxiliaryInto(Eigen::VectorXd &dW, Eigen::VectorXd &dZ, size_t m, size_t auxiliaryCount, double) override

Writes Wiener increments and a requested prefix of auxiliary increments.

The compatibility implementation forwards to generateInto and may generate more auxiliary values than requested. Built-in generators override this method so methods that need fewer than m auxiliary values do not pay for unused random draws.

inline virtual void generateWienerInto(Eigen::VectorXd &dW, size_t m, double) override

Writes only Wiener increments into caller-owned, pre-sized storage.

The default preserves source compatibility with custom generators by forwarding through generateInto. Built-in generators override this method to avoid generating an unused auxiliary increment.

inline virtual void generateWienerInto(Eigen::VectorXd &dW, Eigen::VectorXd &unusedDZ, size_t m, double h) override

Wiener-only generation with caller-owned compatibility scratch.

Existing custom generators inherit this adapter. Built-in generators override it and leave unusedDZ untouched.

Protected Functions

inline const GaussianNoiseSample &nextAndValidate(size_t m, size_t auxiliaryCount): Advances to and validates the next queued sample.

Protected Attributes

std::vector<GaussianNoiseSample> samples: Prescribed increments retained for the lifetime of the replay sequence.

size_t cursor = 0: Index of the next prescribed sample to consume.