C++ Module: stateVecStochasticIntegrator

StateVecStochasticIntegrator supplies the flat storage and candidate operations shared by native stochastic methods. Models continue to register local noise counts and write diffusion tangents through StateData; they do not manage packed buffers.

During binding, shared local endpoints are assigned to global noise slots. Each slot has a contiguous range of StochasticNoiseBinding records and packed tangent values. Mappings back to state-local order preserve the order of special-policy increments. The class also owns step-entry rollback, accepted intermediate state, candidate scratch, and a drift baseline for sparse per-source trials.

Candidate phases describe which scratch operations are valid. A complete candidate can become an intermediate base; sparse candidates reuse a common drift baseline; all-Euclidean final candidates may accumulate terms before one scatter. Live states are restored from the sparse baseline if callbacks changed them, including states outside the previous noise slot.

StochasticRKIntegratorBase adds generator ownership and output buffers. FlatStochasticWorkspace provides reusable method stages. See Dynamics state and integrator architecture for the three noise orderings and rollback limits.

Shared noise topology and stochastic candidate construction.

Typedefs

using StochasticObjectDescriptor = FlatObjectDescriptor : Stochastic methods reuse the same live-buffer metadata as deterministic RK.

using StochasticStateDescriptor = FlatStateDescriptor : Stochastic methods reuse state shapes and offsets from the common binding.

struct StochasticNoiseBinding

#include <stateVecStochasticIntegrator.h>

One state-local diffusion tangent assigned to a global noise slot.

Public Members

size_t boundStateIndex = 0: State descriptor affected by this endpoint.

size_t packedOffset = 0: First tangent scalar in packed global-slot storage.

size_t scalarCount = 0: Number of tangent scalars for this endpoint.

const double *liveData = nullptr: Borrowed tangent pointer in the finalized registry.

struct StochasticNoiseSlot

#include <stateVecStochasticIntegrator.h>

A finalized global noise source and its packed diffusion range.

Public Members

size_t bindingBegin = 0: First endpoint in the noise-binding vector.

size_t bindingCount = 0: Endpoints sharing this global process.

size_t packedBegin = 0: First scalar of this slot in a packed diffusion buffer.

size_t packedCount = 0: Sum of tangent sizes for all endpoints in this slot.

class StateVecStochasticIntegrator : public StateVecIntegrator 

#include <stateVecStochasticIntegrator.h>

Flat topology and candidate operations shared by stochastic numerical methods.

State layout follows registration order. Global noise slots are assigned by the binding’s canonical traversal and group shared endpoints. Packed diffusion buffers follow global-slot order, but updates to each state follow its local source order; special policies may have noncommuting increments.

This base owns reusable candidate/rollback storage and mappings between those orders. StochasticRKIntegratorBase adds generator output; concrete methods supply recurrences and stage storage. The protected API serves those methods. Dynamics modules only register states and supply drift/diffusion callbacks. Rollback restores state values, not RNG position or external callback effects.

Subclassed by StochasticRKIntegratorBase

Public Functions

explicit StateVecIntegrator(DynamicObject *dynIn): Construct an integrator for its future owning dynamics object.

Protected Functions

void bindStochasticTopology(): Lazily builds immutable flat stochastic topology and scratch.

void resetStochasticTopologyBinding() noexcept: Discards an incomplete topology binding after method-scratch failure.

void validateStochasticTopology() const: Validates that dynamic-object and manager topology remains bound.

inline size_t globalNoiseCount() const noexcept: Returns the number of global noise sources in the bound topology.

inline const std::vector<StochasticStateDescriptor> &stochasticStateDescriptors() const noexcept: Borrow state metadata in flat registration order.

inline const std::vector<StochasticObjectDescriptor> &stochasticObjectDescriptors() const noexcept: Borrow live object buffer descriptors.

inline const std::vector<StochasticNoiseBinding> &stochasticNoiseBindings() const noexcept: Borrow state-local endpoints grouped by global source.

inline const std::vector<StochasticNoiseSlot> &stochasticNoiseSlots() const noexcept: Borrow independent global sources and their packed ranges.

inline const std::vector<size_t> &stochasticLocalNoiseSlots() const noexcept: Borrow local endpoint to global source mappings.

inline const std::vector<size_t> &stochasticLocalNoisePackedOffsets() const noexcept: Borrow local endpoint to packed tangent mappings.

inline void gatherStochasticStates(): Captures the accepted state for rollback.

inline void gatherStochasticStates(Eigen::VectorXd &output) const: Copies live object buffer segments into caller-owned flat storage.

inline void scatterStochasticStates(const Eigen::VectorXd &input) const: Copies caller-owned flat storage into live object buffer segments.

void restoreStochasticStates() const: Restores the accepted state after a failed attempted step.

void buildStochasticCandidateInPlace(const Eigen::VectorXd &base, const Eigen::VectorXd &drift, double timeStep, const Eigen::VectorXd &diffusions, const Eigen::VectorXd &globalPseudoSteps): Builds and scatters a candidate in descriptor-local noise order.

void buildStochasticCandidateInPlace(const Eigen::VectorXd &base, const Eigen::VectorXd &drift, double timeStep, const Eigen::VectorXd &diffusions, const Eigen::VectorXd &globalPseudoSteps, size_t slotBegin, size_t slotEnd): Builds and scatters a candidate using only a global noise-slot range.

void applyStochasticDiffusionUpdateInPlace(const Eigen::VectorXd &diffusions, const Eigen::VectorXd &globalPseudoSteps): Applies packed diffusion increments in descriptor-local noise order.

void applyStochasticNoiseSlotInPlace(const Eigen::VectorXd &diffusions, size_t slotIndex, double pseudoStep): Applies one packed global noise slot to the live state.

inline void gatherStochasticDerivatives(): Captures the current drift values in flat buffer order.

inline void gatherStochasticDerivatives(Eigen::VectorXd &output) const: Copies live derivative buffer segments into caller-owned flat storage.

inline void gatherStochasticDerivatives(double *output, Eigen::Index outputSize) const: Copies live drift values into caller-owned contiguous storage.

inline void gatherStochasticDiffusions(): Captures all diffusion tangents in packed global-slot storage.

inline void gatherStochasticDiffusions(Eigen::VectorXd &output) const: Copies live diffusion tangents into caller-owned packed storage.

void buildEulerMaruyamaCandidate(double timeStep, const Eigen::VectorXd &globalPseudoSteps): Applies one flat Euler-Maruyama candidate in local state-noise order.

void advanceEuclideanEulerMaruyama(double timeStep, const Eigen::VectorXd &globalPseudoSteps): Updates Euclidean states from captured drift and live diffusion, without packing diffusion or scattering.

Note

Only valid when every state uses ordinary vector addition. The captured drift remains independent of writes made by the diffusion callback.

void buildStochasticCandidate(const Eigen::VectorXd &base, const Eigen::VectorXd &drift, double timeStep, const Eigen::VectorXd &diffusions, const Eigen::VectorXd &globalPseudoSteps, size_t slotBegin, size_t slotEnd): Builds and scatters a candidate directly from packed work buffers.

inline void buildStochasticCandidate(const Eigen::VectorXd &base, const Eigen::VectorXd &drift, double timeStep, const Eigen::VectorXd &diffusions, const Eigen::VectorXd &globalPseudoSteps): Builds a candidate using every global noise slot.

void beginStochasticSparseCandidates(const Eigen::VectorXd &base, const Eigen::VectorXd &drift, double timeStep): Builds and scatters the drift baseline for sparse per-slot candidates.

void buildStochasticNoiseSlotCandidate(const Eigen::VectorXd &diffusions, double pseudoStep, size_t slotIndex): Restores the sparse baseline and scatters one noise-slot candidate.

void acceptStochasticCandidate(): Makes the last packed candidate the base for a subsequent update.

inline bool stochasticUpdatesAreAllEuclidean() const noexcept: Whether every bound state uses ordinary vector addition.

void beginAllEuclideanFinalCandidate(const Eigen::VectorXd &base, const Eigen::VectorXd &drift, double timeStep, const Eigen::VectorXd &diffusions, const Eigen::VectorXd &globalPseudoSteps): Starts an unscattered final candidate for an all-Euclidean topology.

void appendAllEuclideanFinalCandidate(const Eigen::VectorXd &drift, double timeStep, const Eigen::VectorXd &diffusions, const Eigen::VectorXd &globalPseudoSteps): Appends one ordered term to an all-Euclidean final candidate.

void commitAllEuclideanFinalCandidate(): Scatters the completed all-Euclidean final candidate once.

inline const Eigen::VectorXd &stochasticAcceptedState() const noexcept: Borrow the method’s current base; step-entry rollback remains separate.

inline const Eigen::VectorXd &stochasticPackedDerivatives() const noexcept: Borrow the most recently captured flat drift.

inline const Eigen::VectorXd &stochasticPackedDiffusions() const noexcept: Borrow the most recently captured packed tangents.

void buildStochasticDriftCandidate(const StochasticStateDescriptor &descriptor, ConstMatrixView base, ConstMatrixView drift, double timeStep, MutableMatrixView output): Builds one policy-aware drift candidate.

void applyStochasticNoiseIncrement(const StochasticStateDescriptor &descriptor, MutableMatrixView state, ConstMatrixView diffusion, double pseudoStep): Applies one policy-aware diffusion increment.

void applyStochasticNoiseInLocalOrder(const StochasticStateDescriptor &descriptor, MutableMatrixView state, const Eigen::VectorXd &diffusions, const Eigen::VectorXd &globalPseudoSteps, size_t slotBegin, size_t slotEnd): Applies selected global sources in the descriptor’s local noise order.

Protected Static Functions

static inline void validateStochasticTimeStep(double timeStep): Reject invalid stochastic step sizes before state or RNG mutation.

Private Types

enum class CandidateAssemblyPhase

Which candidate operations are valid for the reusable scratch.

Values:

enumerator Idle: No complete candidate is available for acceptance.

enumerator Ready: A full candidate can become the next working base.

enumerator Sparse: Per-slot trials share sparseBaselineState.

enumerator EuclideanFinal: Ordered terms are accumulating before one final scatter.

Private Functions

void writeStochasticCandidate(const Eigen::VectorXd &base, const Eigen::VectorXd &drift, double timeStep, const Eigen::VectorXd &diffusions, const Eigen::VectorXd &globalPseudoSteps, size_t slotBegin, size_t slotEnd): Fill candidateState without scattering, preserving each state’s local noise order.

bool diffusionInputsMatchTopology(const Eigen::VectorXd &diffusions, const Eigen::VectorXd &globalPseudoSteps) const: Check packed tangent and pseudo-step sizes against the binding.

Private Members

FlatStateBinding flatBinding: Owns descriptors and borrows finalized buffers/policies.

std::vector<StochasticNoiseBinding> noiseBindings: Endpoints grouped by global source.

std::vector<StochasticNoiseSlot> noiseSlots: One packed range per independent global process.

std::vector<size_t> localNoiseToGlobalSlot: Local endpoint -> shared/global process index.

std::vector<size_t> localNoiseToPackedOffset: Local endpoint -> packed tangent offset.

std::vector<const double*> localNoiseLiveData: Local endpoint -> live tangent for direct updates.

Eigen::VectorXd rollbackState: State at attempted-step entry, preserved until the step completes.

Eigen::VectorXd workingState: Accepted intermediate candidate when a method advances its own base.

Eigen::VectorXd candidateState: Reusable destination for complete, sparse, or final assembly.

Eigen::VectorXd sparseBaselineState: Drift-only baseline reused by per-source trials.

Eigen::VectorXd packedDerivatives: Captured drift in flat registration order.

Eigen::VectorXd packedDiffusions: Captured tangents in global-slot order.

bool workingStateIsRollback = true: Selects rollbackState until an intermediate candidate is accepted.

size_t activeSparseSlot = static_cast<size_t>(-1): Previous perturbed scratch slot; size_t(-1) means none.

CandidateAssemblyPhase candidatePhase = CandidateAssemblyPhase::Idle : Validity of candidateState.