C++ Module: stateData

Object that is to be used by an integrator. It’s basically an interface with only one method: the \(F\) function describing a dynamic model \(\dot X = F(X,t)\).

class StateData

#include <stateData.h>

Represents a physical state, which has a name, a value, and a derivative.

Public Functions

StateData(std::string inName, const Eigen::MatrixXd &newState)

Creates a new state with the given name and set’s the initial state.

The state derivative will be resized to the same size as the state and zero’d.

virtual std::unique_ptr<StateData> clone() const: Clone constructor for polymorphic class

virtual ~StateData() = default: Destructor

void setNumNoiseSources(size_t numSources)

Sets the number of noise sources for this state.

This is used for stochastic dynamics, where the evolutions of the state are driven by a set of independent noise sources:

\[ dx = f(t,x)\,dt + g_0(t,x)\,dW_0 + g_1(t,x)\,dW_1 + \cdots + g_{n-1}(t,x)\,dW_{n-1} \]

where \(dW_i\) are independent Wiener processes. The number of noise sources is equal to the number of diffusion matrices that are used to drive the stochastic dynamics (n above).

Parameters:: numSources – The number of noise sources

size_t getNumNoiseSources() const

Get how many independent sources of noise drive the dynamics of this state.

Any number greater than zero indicates that this state is driven by a stochastic differential equation.

void setState(const Eigen::MatrixXd &newState): Updates the value of the state

virtual void setDerivative(const Eigen::MatrixXd &newDeriv): Updates the derivative of the value of the state

void setDiffusion(const Eigen::MatrixXd &newDiffusion, size_t index)

Updates the diffusion of the value of the state.

This is used for stochastic dynamics, where the evolutions of the state are driven by a set of independent noise sources:

\[ dx = f(t,x)\,dt + g_0(t,x)\,dW_0 + g_1(t,x)\,dW_1 + \cdots + g_{n-1}(t,x)\,dW_{n-1} \]

where \(dW_i\) are independent Wiener processes. The diffusion matrices are used to drive the stochastic dynamics ( \(g_i\) above).

Parameters:

newDiffusion – The new diffusion matrix
index – The index of the diffusion matrix to update. This must be less than the number of noise sources.

inline Eigen::MatrixXd getState() const: Retrieves a copy of the current state

inline Eigen::MatrixXd getStateDeriv() const: Retrieves a copy of the current state derivative

inline Eigen::MatrixXd getStateDiffusion(size_t index) const

Retrieves a copy of the current state diffusion

Parameters:: index – The index of the diffusion matrix to retrieve. This must be less than the number of noise sources.

inline std::string getName() const: Returns the name of the state

inline uint32_t getRowSize() const: Returns the row-size of the state

inline uint32_t getColumnSize() const: Returns the column-size of the state

inline uint32_t getDerivativeRowSize() const: Returns the row-size of the derivative of the state

inline uint32_t getDerivativeColumnSize() const: Returns the column-size of the derivative of the state

void scaleState(double scaleFactor): Multiples the state by a scalar

void addState(const StateData &other): Adds the values of the other state to this state

virtual void propagateState(double h, std::vector<double> pseudoStep = {})

Propagates the state over a time step.

This method integrates the position state using the state derivative over the given time step::

\[ x \mathrel{+}= f(t,x)\,h + g_0(t,x)\,\mathrm{pseudoStep}[0] + g_1(t,x)\,\mathrm{pseudoStep}[1] + \cdots \]

Parameters:

h – The time step for propagation.
pseudoStep – For states driven by stochastic dynamics, this represents the random pseudotimestep. The length of this input must match the number of noise sources of this state (getNumNoiseSources())

Public Members

Eigen::MatrixXd state: [-] State value storage

Eigen::MatrixXd stateDeriv: [-] State derivative value storage

std::vector<Eigen::MatrixXd> stateDiffusion: [-] State diffusion value storage

const std::string stateName: [-] Name of the state

BSKLogger bskLogger: — BSK Logging

bool perComponentErrorControl = false

[-] Whether an adaptive integrator should measure this state’s relative truncation error per scalar component instead of over the whole vector.

The default (false) compares the L2 norm of the state’s error against a tolerance built from the L2 norm of the whole state, which is the right choice when every component of the state is the same physical quantity (e.g. a position in metres). When a single state instead bundles quantities of very different scales (e.g. the MuJoCo bulk position state, which mixes orbital translation in metres with order-unity attitude quaternion components), the whole-vector norm lets the large component swamp the small one and loosen its effective tolerance. Setting this flag makes the integrator scale each component by its own magnitude instead.