C++ Module: stateData

StateData is a stable, registry-owned handle for one named continuous state. It provides shaped access to the state value, its time derivative, and one diffusion tangent per local noise source. It neither owns an independent matrix nor evaluates the equations of motion. See Dynamics state and integrator architecture for the surrounding system.

Using a handle

Keep the handle returned by DynParamManager::registerState(). During a dynamics callback, acquire views and write the derivative in place:

// A dimensionless scalar x obeys dx/dt = -decayRate * x.
const double decayRate = 0.5; // [1/s]
const auto x = this->xState->stateView();
this->xState->derivativeView() = -decayRate * x;

stateView(), derivativeView(), and diffusionView(index) are borrowed Eigen maps with column-major storage. They must not outlive the owning manager and must be reacquired after first finalization. Handles and finalized buffer addresses survive later resets; their values update in place. The copying getters getState(), getStateDeriv(), and getStateDiffusion() return owning snapshots. Setters require exact shape matches.

Shapes and special updates

StateSpec declares state, derivative, and diffusion-tangent shapes separately. They match for ordinary Euclidean states. A StateUpdatePolicy defines propagation when the representation needs a special update, such as a quaternion driven by angular velocity. Policies are immutable and owned by the registry, not by individual integrators. Adaptive error control can measure the whole state or each scalar component.

Declare noise counts in StateSpec. The deprecated setNumNoiseSources() remains available for initial registration; it cannot change established topology.

State declarations, update-policy contract, and borrowed matrix access.

Typedefs

using MutableMatrixView = Eigen::Map<Eigen::MatrixXd, Eigen::Unaligned>

Writable column-major matrix alias; does not own or extend storage lifetime.

using ConstMatrixView = Eigen::Map<const Eigen::MatrixXd, Eigen::Unaligned>

Read-only column-major matrix alias; does not own or extend storage lifetime.

Enums

enum class ErrorControlMode

Adaptive-integrator error scaling associated with a state.

Values:

enumerator WholeState

Compare the norm of the state error against one state-level threshold.

enumerator PerComponent

Compare each scalar error against its own scaled threshold.

enum class StateUpdateKind

Kind of update applied when a state is propagated.

Values:

enumerator Euclidean

State, drift, and diffusion share a shape and use ordinary addition.

enumerator Special

An immutable StateUpdatePolicy defines drift and noise updates.

struct MatrixShape
#include <stateData.h>

Shape of a matrix stored by the dynamics state registry.

Public Functions

inline bool operator==(const MatrixShape &other) const noexcept

Compare two matrix shapes.

inline bool operator!=(const MatrixShape &other) const noexcept

Compare two matrix shapes.

Public Members

uint32_t rows = 0

Number of matrix rows.

uint32_t cols = 0

Number of matrix columns.

struct StateSpec
#include <stateData.h>

Immutable topology supplied when a state is registered.

Public Functions

inline bool operator==(const StateSpec &other) const noexcept

Compare two state specifications.

inline bool operator!=(const StateSpec &other) const noexcept

Compare two state specifications.

Public Members

MatrixShape state

Shape of the stored physical state.

MatrixShape derivative

Shape of drift returned by the equations of motion.

MatrixShape diffusionTangent

Shape of one local noise tangent, even when no noise is registered.

size_t noiseCount = 0

Number of local sources; shared declarations may map them to global sources.

ErrorControlMode errorControl = ErrorControlMode::WholeState

Adaptive error-scaling convention.

StateUpdateKind updateKind = StateUpdateKind::Euclidean

Selects ordinary addition or policy dispatch.

class StateUpdatePolicy
#include <stateData.h>

Defines propagation when a state’s representation requires more than vector addition.

The registry owns the policy; handles and integrators borrow it. Configuration is immutable after registration, and topologyEquals() compares configuration by value when a repeated Reset presents a replacement policy. A policy has no stage storage: the integrator combines derivatives before calling it.

Implementations must fully write drift output and apply noise increments in place. Noise calls arrive in state-local source order, which matters for noncommuting updates. Use the supplied views without resizing, retaining them, or changing registration.

Public Functions

virtual ~StateUpdatePolicy() = default
virtual bool topologyEquals(const StateUpdatePolicy &other) const = 0

Compare immutable policy topology by value.

virtual void validate(const StateSpec &spec) const = 0

Validate that a state specification is supported by this policy.

virtual void buildDriftCandidate(ConstMatrixView base, ConstMatrixView combinedDrift, double timeStep, MutableMatrixView output) const = 0

Construct one drift candidate from a base state and combined drift.

Parameters:

  • base – State at the start of this candidate update.

  • combinedDrift – Weighted drift in the declared derivative shape.

  • timeStep – Drift multiplier in seconds.

  • output – Destination in the declared state shape; must be fully written.

virtual void applyNoiseIncrement(MutableMatrixView state, ConstMatrixView diffusionTangent, double pseudoStep) const = 0

Apply one diffusion-tangent increment to a candidate state.

Parameters:

  • state – Candidate to update in place.

  • diffusionTangent – One combined tangent in the declared diffusion shape.

  • pseudoStep – Method-provided multiplier for this tangent, often a Wiener increment.

class StateData
#include <stateData.h>

Stable borrowed handle to one registry-owned state and its drift and diffusion.

Obtain handles from DynParamManager during registration and retain them for model callbacks. Values begin in temporary matrices; the first finalization redirects handles into contiguous buffers. Reacquire views after that allocation. Later resets update live values in place and preserve both handle and buffer addresses.

The manager must outlive native handles and views. Python wrappers retain the owning manager. Copying getters return independent snapshots of current values.

Public Functions

StateData(const StateData&) = delete
StateData &operator=(const StateData&) = delete
StateData(StateData&&) = delete
StateData &operator=(StateData&&) = delete
size_t getNumNoiseSources() const

Return the number of local noise sources, before shared-source grouping.

void setNumNoiseSources(size_t numSources)

Set the registration-time number of independent noise sources.

This deprecated compatibility API may establish the count during the initial registration. Once topology is established, only the already-established value is accepted.

void setState(Eigen::Ref<const Eigen::MatrixXd> newState)

Set the state value, requiring an exact shape match.

void setDerivative(Eigen::Ref<const Eigen::MatrixXd> newDeriv)

Set the derivative value, requiring an exact shape match.

inline MutableMatrixView stateView()

Return a mutable borrowed view of the active state storage.

The view aliases the manager buffer active when it is acquired. Do not retain it across the first finalizeStates(); reacquire it after storage allocation. Later resets preserve its address.

inline ConstMatrixView stateView() const

Return a constant borrowed view of the active state storage.

The view follows the same storage-lifetime restrictions as the mutable stateView().

inline ConstMatrixView getStateReference() const

Compatibility alias for stateView() on a constant state handle.

Deprecated:

Will be removed after September 30, 2027. Use stateView().

Deprecated:

Will be removed after 2027-09-30; use stateView().

inline MutableMatrixView derivativeView()

Return a mutable borrowed view of active derivative storage.

The view aliases the manager buffer active when it is acquired and must be reacquired after the first finalization.

inline ConstMatrixView derivativeView() const

Return a constant borrowed view of active derivative storage.

The view follows the same storage-lifetime restrictions as the mutable derivativeView().

inline ConstMatrixView getStateDerivReference() const

Compatibility alias for derivativeView() on a constant state handle.

Deprecated:

Will be removed after September 30, 2027. Use derivativeView().

Deprecated:

Will be removed after 2027-09-30; use derivativeView().

MutableMatrixView diffusionView(size_t localNoiseIndex)

Return a mutable borrowed view of one diffusion tangent.

The view aliases the manager buffer active when it is acquired and must be reacquired after the first finalization.

ConstMatrixView diffusionView(size_t localNoiseIndex) const

Return a constant borrowed view of one diffusion tangent.

The view follows the same storage-lifetime restrictions as the mutable diffusionView().

double *stateData()

Return the live state-buffer pointer.

Raw access is valid only while the owning manager is finalized.

double *derivativeData()

Return the live derivative-buffer pointer.

double *diffusionData(size_t localNoiseIndex)

Return one live diffusion-buffer pointer.

void setDiffusion(Eigen::Ref<const Eigen::MatrixXd> newDiffusion, size_t index)

Set one diffusion tangent, requiring an exact shape match.

Parameters:

  • newDiffusion – New diffusion tangent.

  • index – Local noise-source index.

Eigen::MatrixXd getState() const

Return a copy of the active state value.

Eigen::MatrixXd getStateDeriv() const

Return a copy of the active derivative value.

Eigen::MatrixXd getStateDiffusion(size_t index) const

Return a copy of one active diffusion tangent.

std::string getName() const

Return the state name.

bool usesPerComponentErrorControl() const

Return whether adaptive error is measured per scalar component.

MatrixShape stateShape() const

Return the state shape.

MatrixShape derivativeShape() const

Return the derivative shape.

MatrixShape diffusionShape() const

Return the diffusion tangent shape.

inline uint32_t getRowSize() const

Return the state row count.

inline uint32_t getColumnSize() const

Return the state column count.

inline uint32_t getDerivativeRowSize() const

Return the derivative row count.

inline uint32_t getDerivativeColumnSize() const

Return the derivative column count.

inline uint32_t getDiffusionRowSize() const

Return the diffusion tangent row count.

inline uint32_t getDiffusionColumnSize() const

Return the diffusion tangent column count.

Private Functions

StateData(StateRegistry *owner, size_t slot, const StateSpec &spec)

Create a stable handle for a registry slot and cache its immutable view shapes.

~StateData() = default
inline void bindStateViews(double *state, double *derivative) noexcept

Rebind borrowed views when the manager changes the active buffer.

Private Members

StateRegistry *owner = nullptr

Registry owning this handle’s metadata and storage.

size_t slot = 0

Stable registration slot.

double *activeState = nullptr

Active seed or buffer state storage.

double *activeDerivative = nullptr

Active seed or buffer derivative storage.

const MatrixShape viewStateShape

Immutable shape cached for inline state maps.

const MatrixShape viewDerivativeShape

Immutable shape cached for inline derivative maps.

Friends

friend class StateRegistry
friend struct std::default_delete< StateData >