C++ Module: dynParamManager

DynParamManager gives a dynamic object and its effectors access to named states and shared properties. Integrators advance states; properties hold matrices that modules read or update directly.

Using the manager

Declare states in your module’s registration callback and retain the returned StateData handles. Use getStateObject() to link another module’s state. Create shared matrices with createProperty() and link them with getPropertyReference(). The manager owns these objects and must outlive borrowed handles and property pointers.

The owning DynamicObject calls finalizeStates() during Reset() after initial state registration. An individual effector only declares its own states. A standalone manager follows the same pattern:

DynParamManager manager;
StateData* position = manager.registerState(3, 1, "position");
position->stateView().setZero();
manager.finalizeStates();

Finalization and reset

First finalization computes the fixed layout and allocates contiguous buffers. Reacquire Eigen views after this allocation. Later resets reuse states by name; they write directly into the live buffers without moving their addresses. Repeated finalization has no effect. Shapes, update policies, and noise connections cannot change, and new states cannot be added to a finalized manager.

Setup errors propagate to the caller. The manager does not checkpoint values or provide a registration rollback operation.

Native storage access

Include stateRegistry.h and call getStateRegistry() to inspect finalized layouts, read shared-noise topology, or resolve contiguous buffer segments from C++. The returned registry is owned by this manager and has no Python proxy.

See Creating DynamicObject Basilisk Modules for a Reset example and Dynamics state and integrator architecture for the relationship between modules, storage, and numerical workspaces.

Module-facing state declarations, lookup, and shared properties. Registration and contiguous storage are implemented by StateRegistry.

class DynParamManager

#include <dynParamManager.h>

Named integration states and shared property matrices for dynamics modules.

Register states in your module’s registration callback and retain the returned StateData handles. Use getStateObject() to link another module’s state and getPropertyReference() to link a shared property. Properties are not integrated.

The owning DynamicObject calls finalizeStates() after initial registration to allocate contiguous storage. Later resets reuse existing states by name and update their values in place. Shapes, update policies, and noise connections cannot change after finalization. Repeated finalization has no effect.

This manager owns all handles and properties and must outlive borrowed pointers. Reacquire Eigen views after the first finalization; subsequent resets preserve storage addresses. Setup errors propagate to the caller without value rollback.

getStateRegistry() provides native access to layouts and contiguous segments.

Public Functions

DynParamManager(): Construct an empty manager with no states or properties.

~DynParamManager(): Release all states, properties, and registry storage.

DynParamManager(const DynParamManager&) = delete

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

DynParamManager(DynParamManager&&) = delete

DynParamManager &operator=(DynParamManager&&) = delete

void finalizeStates()

Allocate contiguous state storage and fix the layout after registration.

Note

Call before integration. Repeated calls have no effect.

Throws:: std::exception – If dimensions or shared-noise declarations are invalid.

StateData *registerState(std::string stateName, const StateSpec &spec)

Declare a state with explicit dimensions, noise count, and error scaling.

Parameters:

stateName – Nonempty name, unique within this manager.
spec – Fixed state topology; Euclidean states require equal state, derivative, and diffusion-tangent shapes.

Throws:

std::exception – If the declaration is invalid or would change finalized topology.

Returns:

Manager-owned handle, reused when matching a repeated declaration.

StateData *registerState(std::string stateName, const StateSpec &spec, std::unique_ptr<StateUpdatePolicy> policy)

Declare a state whose update requires a non-Euclidean policy.

Parameters:

stateName – Nonempty state name, reused by name on reset.
spec – State topology with StateUpdateKind::Special.
policy – Immutable update policy; ownership transfers to this call. Repeated declarations must provide an equivalent policy.

Throws:

std::exception – If the declaration or policy is invalid.

Returns:

Manager-owned handle for the declaration.

StateData *registerState(uint32_t nRow, uint32_t nCol, std::string stateName)

Compatibility overload for an equal-shape Euclidean matrix state.

Note

A matching repeated declaration retains its established noise count and error-control settings. Use StateSpec for explicit new declarations.

Parameters:

nRow – Nonzero number of rows.
nCol – Nonzero number of columns.
stateName – Nonempty state name.

Returns:

Manager-owned state handle.

StateData *getStateObject(std::string stateName)

Find a state declared in this manager.

Parameters:: stateName – Name supplied to registerState().
Returns:: Borrowed handle, or nullptr with a warning if the name is absent.

void registerSharedNoiseSource(std::vector<std::pair<const StateData&, size_t>> sharedNoises)

Declare that several states use the same stochastic process.

Note

Group ordering is immaterial; repeat the same connections on reset.

Parameters:: sharedNoises – Pairs of state handles and zero-based local noise indices. All states must belong to this manager. A local source may appear in only one group, and a group may contain at most one source from each state.
Throws:: std::exception – If the group is invalid or would change finalized noise connections.

bool statesAreFinalized() const noexcept: Report whether fixed state storage has been allocated.

Eigen::MatrixXd *createProperty(std::string propName, const Eigen::MatrixXd &propValue)

Create or replace a named property without integrating it.

Parameters:

propName – Property name used by modules to link this matrix.
propValue – Initial matrix; replacing a property may change its shape.

Returns:

Borrowed pointer to the matrix object, stable across later updates.

Eigen::MatrixXd *getPropertyReference(std::string propName)

Look up a shared property matrix.

Parameters:: propName – Previously created property name.
Throws:: BasiliskError – If the property does not exist.
Returns:: Borrowed pointer, valid until the manager is destroyed.

void setPropertyValue(std::string propName, const Eigen::MatrixXd &propValue)

Update an existing property without changing its shape.

Parameters:

propName – Previously created property name.
propValue – Replacement values with the existing dimensions.

Throws:

BasiliskError – If the property does not exist.
std::invalid_argument – If its dimensions differ.

inline StateRegistry &getStateRegistry() noexcept

Access state layouts, contiguous buffer segments, and shared-noise topology.

Note

This interface is not exposed to Python.

Returns:: Borrowed registry owned by this manager. Include stateRegistry.h to inspect layouts, resolve buffer segments, or bind shared-noise topology.

inline const StateRegistry &getStateRegistry() const noexcept

Inspect the native registry through a constant manager.