C++ Module: flatStateBinding

FlatStateBinding is the native bridge from named registered states to integrator arithmetic. It owns descriptors and update runs while borrowing finalized registry buffers and update policies. Numerical stage buffers belong to the consuming integrator.

Binding and reuse

bind() validates state shapes and policies, assigns combined-buffer offsets, and coalesces adjacent Euclidean states into contiguous update runs. It also builds the state traversal used to assign stochastic noise sources. validate() checks object identity and finalized storage before an existing binding is reused. reset() discards metadata after failed preparation.

FlatObjectDescriptor addresses one object’s live buffers. FlatStateDescriptor addresses one state in the integrator’s combined buffers. FlatUpdateRun describes either adjacent states using ordinary vector addition or one special-policy state. All offsets count doubles, and matrix views are column-major. These offsets must not be confused with registry-local StateLayout offsets.

Gather and scatter operate on already sized buffers and copy complete object buffers. Candidate construction combines flat drift and dispatches special updates through the registered policy. External policy calls use the supplied callback guard before further borrowed-storage access. See Dynamics state and integrator architecture for ownership and call ordering.

Native descriptors that connect finalized registries to numerical buffers.

struct FlatObjectDescriptor

#include <flatStateBinding.h>

One finalized object’s buffers within the integrator’s concatenated buffers. Counts and offsets are in doubles. Live pointers borrow the registry’s committed buffers; binding validation must succeed before any pointer is used.

Public Members

DynamicObject *object = nullptr: Borrowed dynamics callback target.

StateRegistry *registry = nullptr: Borrowed registry owning this object’s buffers.

size_t firstStateIndex = 0: First entry in the binding’s state-descriptor vector.

size_t stateOffset = 0: First scalar in a combined state buffer.

size_t stateCount = 0: Scalars in this object’s live state buffer.

size_t derivativeOffset = 0: First scalar in a combined derivative buffer.

size_t derivativeCount = 0: Scalars in this object’s derivative buffer.

double *stateData = nullptr: Borrowed start of this object’s live state buffer.

double *derivativeData = nullptr: Borrowed start of this object’s derivative buffer.

struct FlatStateDescriptor

#include <flatStateBinding.h>

One state with shapes and integrator-global offsets resolved at binding time. State, derivative, and diffusion counts may differ for special policies. Noise offsets address the state-local mapping; packed global-slot offsets live in the stochastic binding. No state-name lookup is needed during numerical updates.

Public Functions

inline bool usesEuclideanUpdate() const noexcept: Select ordinary vector arithmetic without virtual policy dispatch.

inline bool usesPerComponentErrorControl() const noexcept: Select scalar adaptive thresholds instead of one matrix-norm threshold.

inline ConstMatrixView stateView(const Eigen::VectorXd &buffer) const: Maps this state’s values in an already validated flat buffer.

inline MutableMatrixView stateView(Eigen::VectorXd &buffer) const: Maps this state’s writable values in an already validated flat buffer.

inline ConstMatrixView derivativeView(const Eigen::VectorXd &buffer) const: Maps this state’s drift in an already validated flat buffer.

inline ConstMatrixView diffusionView(const Eigen::VectorXd &buffer, size_t packedOffset) const: Maps a diffusion tangent at its validated packed offset.

Public Members

StateData *state = nullptr: Borrowed stable handle.

std::string stateName: Registration name, used for diagnostics and tolerance resolution.

size_t dynamicObjectIndex = 0: Owning entry in the object-descriptor vector.

size_t stateOffset = 0: First scalar in a combined state buffer.

size_t stateCount = 0: Stored state scalars.

Eigen::Index stateRows = 0: Rows in the stored state.

Eigen::Index stateColumns = 0: Columns in the stored state.

size_t derivativeOffset = 0: First scalar in a combined drift buffer.

size_t derivativeCount = 0: Drift scalars.

Eigen::Index derivativeRows = 0: Rows in drift views.

Eigen::Index derivativeColumns = 0: Columns in drift views.

size_t diffusionCount = 0: Scalars per local diffusion tangent.

Eigen::Index diffusionRows = 0: Rows in tangent views.

Eigen::Index diffusionColumns = 0: Columns in tangent views.

size_t noiseCount = 0: Local noise endpoints for this state.

size_t localNoiseOffset = 0: First entry in concatenated local-noise mappings.

StateUpdateKind updateKind = StateUpdateKind::Euclidean : Cached arithmetic dispatch choice.

ErrorControlMode errorControl = ErrorControlMode::WholeState : Cached adaptive scaling convention.

const StateUpdatePolicy *specialUpdate = nullptr: Borrowed immutable policy; null for Euclidean states.

struct FlatUpdateRun

#include <flatStateBinding.h>

One contiguous Euclidean update span or one special-policy state.

Public Members

size_t firstDescriptorIndex = 0: First state in this run; the only state for a special update.

size_t stateOffset = 0: First scalar in a combined state buffer.

size_t stateCount = 0: State scalars covered by the run.

size_t derivativeOffset = 0: First scalar in a combined derivative buffer.

size_t derivativeCount = 0: Drift scalars covered by the run.

StateUpdateKind updateKind = StateUpdateKind::Euclidean : A vector-addition run or one policy-dispatched state.

class FlatStateBinding

#include <flatStateBinding.h>

Native bridge between named state registration and flat integrator arithmetic.

bind() walks finalized registries once, validates shapes and policies, and builds object/state descriptors plus contiguous Euclidean update runs. Descriptors borrow buffers and policies; this class owns only topology metadata, not numerical stages. validate() checks object identity and fixed layout before reuse.

Gather/scatter operations copy complete object buffers. Candidate construction uses vector addition for Euclidean runs and policy dispatch for special states. These operations require correctly sized caller-owned buffers and do not resize them.

Public Types

enum class Mode

Select validation and diagnostics for the consuming numerical family.

Values:

enumerator DeterministicRungeKutta: Drift-only RK candidate construction.

enumerator Stochastic: Drift and diffusion candidate construction.

Public Functions

FlatStateBinding() = default

FlatStateBinding(const FlatStateBinding&) = delete

FlatStateBinding &operator=(const FlatStateBinding&) = delete

FlatStateBinding(FlatStateBinding&&) noexcept = default: Transfer prepared descriptors when a binding transaction commits.

FlatStateBinding &operator=(FlatStateBinding&&) noexcept = default: Replace descriptors with a successfully prepared binding.

void bind(const std::vector<DynamicObject*> &dynamics, Mode mode): Builds a binding from finalized managers.

void reset() noexcept: Discards a binding assembled as part of an aborted transaction.

void validate(const std::vector<DynamicObject*> &dynamics) const: Validates object/registry identity, finalized status, and fixed layout.

inline bool isBound() const noexcept: Report whether descriptor construction committed.

inline size_t stateScalarCount() const noexcept: Return combined state-buffer size in doubles.

inline size_t derivativeScalarCount() const noexcept: Return combined drift-buffer size in doubles.

inline size_t localNoiseCount() const noexcept: Return total state-local noise endpoints before shared-source grouping.

inline bool updatesAreAllEuclidean() const noexcept: Report whether every state supports ordinary vector addition.

inline const std::vector<FlatObjectDescriptor> &objects() const noexcept: Borrow object descriptors in synchronized integration order.

inline const std::vector<FlatStateDescriptor> &states() const noexcept: Borrow state descriptors in object and registration order.

inline const std::vector<FlatUpdateRun> &updateRuns() const noexcept: Borrow coalesced Euclidean spans and individual special-state runs.

inline const std::vector<size_t> &noiseTraversalOrder() const noexcept: Borrow state indices in object order, then lexical state-name order.

inline void gatherStates(Eigen::VectorXd &output) const: Copies live state buffers into flat storage.

inline void scatterStates(const Eigen::VectorXd &input) const: Copies flat state storage into live buffers.

inline void gatherDerivatives(Eigen::VectorXd &output) const: Copies live derivative buffers into flat storage.

inline void gatherDerivatives(double *output, Eigen::Index outputSize) const: Copies live derivative buffers into caller-owned contiguous storage.

void writeDriftCandidate(const Eigen::VectorXd &base, const Eigen::VectorXd &drift, double timeStep, Eigen::Ref<Eigen::VectorXd> output) const: Builds one drift-only candidate in descriptor order.

Private Members

bool bound = false: True after complete descriptor construction.

Mode bindingMode = Mode::DeterministicRungeKutta : Consumer family used for validation diagnostics.

size_t stateCount = 0: Total stored state scalars.

size_t derivativeCount = 0: Total drift scalars.

size_t noiseCount = 0: Total local noise endpoints.

bool allEuclideanUpdates = true: Enables whole-buffer arithmetic when no policy dispatch is needed.

std::vector<FlatObjectDescriptor> objectDescriptors: Borrowed buffer metadata in integration order.

std::vector<FlatStateDescriptor> stateDescriptors: Per-state metadata in registration order.

std::vector<FlatUpdateRun> stateUpdateRuns: Adjacent compatible Euclidean states coalesced for vector arithmetic.

std::vector<size_t> canonicalNoiseTraversalOrder: State indices sorted by object and name for stable noise assignment.