C++ Module: stateVecIntegrator

StateVecIntegrator provides shared workspace preparation and dynamics callbacks for deterministic and stochastic integrators. A DynamicObject owns it and invokes integration after model initialization.

Implementing an integrator

Derive from an existing numerical family when possible. A new family implements:

  • prepareIntegrationBinding() to resolve finalized state topology and allocate workspaces before the first step or after a synchronized secondary is destroyed;

  • validateIntegrationBinding() to check that cached descriptors remain valid;

  • integrateImpl(currentTime, timeStep) to advance one requested interval.

The private integrate() entry point prepares storage when needed and reuses it while the dynamics group remains unchanged. Model code calls DynamicObject::integrateState(). Numerical methods call evaluateDerivatives() and evaluateDiffusions() to evaluate the dynamics objects in synchronization order.

Ownership

The dynamics list is borrowed. Configure it before workspace preparation. Keep its objects alive while using the integrator. The base does not track object destruction during callbacks. Replacing an integrator destroys it and invalidates its borrowed pointers.

See Dynamics state and integrator architecture for the complete call path.

Shared dynamics callbacks and integrator workspace preparation.

class StateVecIntegrator
#include <stateVecIntegrator.h>

Base for numerical methods that advance a fixed group of dynamics objects.

DynamicObject owns its integrator. The first step prepares state descriptors and numerical buffers; subsequent steps reuse them. If a synchronized secondary is destroyed outside a callback, the next step prepares storage for the surviving group. Borrowed state storage must remain alive while a step uses it.

Subclassed by svIntegratorRungeKutta< 4 >, StateVecStochasticIntegrator, svIntegratorRungeKutta< numberStages >

Public Functions

explicit StateVecIntegrator(DynamicObject *dynIn)

Construct an integrator for its future owning dynamics object.

virtual ~StateVecIntegrator() = default

Release numerical storage without taking ownership of dynamics objects.

inline std::size_t getDynamicsCount() const noexcept

Return the number of objects advanced together.

inline const std::vector<DynamicObject*> &getDynamics() const noexcept

Borrow the dynamics list in integration order, with the primary first.

Protected Functions

virtual void prepareIntegrationBinding() = 0

Resolve the current group’s state layouts and allocate numerical workspace.

virtual void validateIntegrationBinding() const = 0

Check that cached descriptors still refer to finalized dynamics.

virtual void integrateImpl(double currentTime, double timeStep) = 0

Advance from currentTime by timeStep, both in seconds.

void ensureIntegrationBinding()

Prepare storage on first use and validate it on later calls.

void evaluateDerivatives(double time, double timeStep)

Evaluate each object’s drift at the supplied time and step in seconds.

void evaluateDiffusions(double time, double timeStep)

Evaluate each object’s diffusion at the supplied time and step in seconds.

inline const std::vector<DynamicObject*> &dynamics() const noexcept

Borrow dynamics objects in callback order.

Private Functions

void integrate(double currentTime, double timeStep)

Prepare workspace and execute the numerical method.

Private Members

std::vector<DynamicObject*> dynPtrs

Borrowed callback targets, with the primary first.

bool bindingPrepared = false

True when workspace preparation has succeeded for the current group.

Friends

friend class DynamicObject
friend class integrator_step_test::StateVecIntegratorTestAccess