C++ Module: igbmNoiseStateEffector

Executive Summary

The IgbmNoiseStateEffector module is a spacecraft StateEffector that propagates a single scalar correction \(\delta\) whose multiplicative factor \((1+\delta)\) follows an inhomogeneous geometric Brownian motion (IGBM).

It is the multiplicative-noise counterpart to C++ Module: meanRevertingNoiseStateEffector: the correction has the same \((1+\delta)\) form consumed by e.g. C++ Module: dragDynamicEffector (densityCorrectionStateName). The exact factor \(1+\delta\) is positive, but the module integrates the SDE as written, so an explicit integrator can occasionally make it non-positive for a large step/increment; a consumer that needs a non-negative quantity clamps it downstream (DragDynamicEffector clamps the corrected density to be non-negative).

Module Description

The multiplicative factor \(X = 1 + \delta\) follows the Itô SDE

\[\text{d}X = \frac{1}{\tau}(\mu - X)\,\text{d}t + \sigma X\,\text{d}W\]

so the registered correction state evolves as

\[\text{d}\delta = \frac{\mu - 1 - \delta}{\tau}\,\text{d}t + \sigma (1+\delta)\,\text{d}W\]

Like the other IGBM/OU noise classes, the process is configured in stationary form: the mean level \(\mu\) of the factor (setMean, defaults to 1 for a mean-preserving correction), the time constant \(\tau\) (setTimeConstant), and the stationary standard deviation \(\sigma_{st}\) (setStationaryStd). The SDE volatility is derived internally as

\[\sigma^2 = \frac{2}{\tau}\,\frac{\sigma_{st}^2}{\mu^2 + \sigma_{st}^2}\]

so the factor’s stationary mean and standard deviation are exactly \(\mu\) and \(\sigma_{st}\), and the IGBM stationarity condition \(2/\tau > \sigma^2\) holds by construction.

No module-specific input or output messages are used. Other modules can consume the state by reading it from the dynamics state manager by name.

The registered state name can be set or queried using setStateName("...") and getStateName().

Detailed Behavior

At each integrator sub-step, the module:

  1. Reads the internal correction \(\delta\) and forms the factor \(X = 1+\delta\).

  2. Sets deterministic drift \(\dot{\delta} = (\mu - X)/\tau\).

  3. Sets one diffusion term with state-dependent amplitude \(\sigma X\).

At state registration the correction defaults to \(\mu - 1\) (the factor at its mean level), since a zero factor is degenerate for the multiplicative diffusion; override with setStateValue if desired.

Module Assumptions and Limitations

  • Because the registered state has a stochastic diffusion source, a stochastic integrator must be used for the parent spacecraft dynamics.

  • The diffusion is multiplicative (state-dependent), so a strong stochastic integrator (e.g. Euler-Maruyama or an SRI method) must be used; weak integrators do not reproduce the correct sample-path statistics.

  • The module integrates the SDE as written. The exact factor \(1+\delta\) is positive, but an explicit integrator can occasionally produce a non-positive factor for a large step or Wiener increment; a consumer requiring positivity (e.g. a density) must clamp the derived quantity downstream.

  • setMean(m) requires \(\mu > 0\); setTimeConstant(t) requires \(\tau > 0\); setStationaryStd(s) requires \(\sigma_{st} \ge 0\); setStateValue requires an initial factor \(1+\delta > 0\).

Configuration Validation

Numeric setters reject NaN and positive or negative infinity before modifying either the configured value or an already registered state. setTimeConstant() requires a finite, strictly positive time constant, and setStationaryStd() requires a finite, non-negative standard deviation. setStateValue() requires a finite value.

setMean() additionally requires a strictly positive finite mean, and setStateValue() requires a correction greater than -1. These bounds apply to configured values; the integrated correction is not clamped by this module.

Valid defaults and private configuration members make attachment safe without task scheduling. The inherited Reset() leaves the configured parameters and integrated state unchanged.

The drift and diffusion calculations avoid intermediate overflow when taking square roots or forming stationary-parameter ratios. If the resulting drift or diffusion is non-finite, the module raises BasiliskError before storing either result.

class IgbmNoiseStateEffector : public StateEffector, public SysModel
#include <igbmNoiseStateEffector.h>

State effector that propagates a scalar correction \(\delta\) whose factor \((1+\delta)\) follows an inhomogeneous geometric Brownian motion (IGBM).

The multiplicative factor \(X = 1 + \delta\) follows the Ito SDE

\[ dX = \frac{1}{\tau}(\mu - X)\,dt + \sigma X\,dW, \]
so the registered correction state evolves as
\[ d\delta = \frac{\mu - 1 - \delta}{\tau}\,dt + \sigma (1+\delta)\,dW. \]
The correction form matches consumers that apply a \((1+\delta)\) correction (e.g. DragDynamicEffector::densityCorrectionStateName). The exact factor \(X\) is positive, but the module integrates the SDE as written (pure math), so an explicit integrator can occasionally produce \(X = 1+\delta \le 0\) for a large step or Wiener increment. A consumer that needs a non-negative quantity should clamp it downstream: DragDynamicEffector clamps the corrected density to be non-negative.

Like the other IGBM/OU noise classes, the process is configured in stationary form: the mean level \(\mu\) of the factor, the time constant \(\tau\), and the stationary standard deviation \(\sigma_{\mathrm{st}}\). The SDE volatility is derived as \(\sigma^2 = (2/\tau)\,\sigma_{\mathrm{st}}^2/(\mu^2 + \sigma_{\mathrm{st}}^2)\) so the factor’s stationary mean and std are exactly \(\mu\) and \(\sigma_{\mathrm{st}}\), and stationarity holds by construction.

Public Functions

IgbmNoiseStateEffector()

Constructor.

~IgbmNoiseStateEffector() override = default

Destructor.

void registerStates(DynParamManager &states) override

Register this effector’s internal stochastic state with the dynamics manager.

Parameters:

states – Dynamics parameter manager used to create the correction state.

void linkInStates(DynParamManager &states) override

Link any required external states and properties.

This effector has no required external state links.

Parameters:

states – Dynamics parameter manager.

void computeDerivatives(double integTime, Eigen::Vector3d rDDot_BN_N, Eigen::Vector3d omegaDot_BN_B, Eigen::MRPd sigma_BN) override

Compute deterministic and stochastic dynamics for the correction state.

Parameters:

  • integTime – Integration time in seconds.

  • rDDot_BN_N – Hub translational acceleration [m/s^2] (unused).

  • omegaDot_BN_B – Hub angular acceleration [rad/s^2] (unused).

  • sigma_BN – Hub attitude MRP (unused).

void setMean(double mean)

Set the mean level \(\mu\) of the multiplicative factor \((1+\delta)\).

Non-finite values and values less than or equal to zero are rejected without changing the previous setting.

Parameters:

mean – Mean level \(\mu\) [-].

inline double getMean() const

Get the mean level \(\mu\) of the multiplicative factor [-].

void setStationaryStd(double sigmaStationary)

Set the stationary standard deviation of the factor.

Non-finite values and values smaller than zero are rejected without changing the previous setting.

Parameters:

sigmaStationary – Stationary standard deviation, \(\sigma_{\mathrm{st}}\) [-].

inline double getStationaryStd() const

Get the stationary standard deviation \(\sigma_{\mathrm{st}}\) [-].

void setTimeConstant(double timeConstant)

Set the IGBM time constant.

Non-finite values and values less than or equal to zero are rejected without changing the previous setting.

Parameters:

timeConstant – Time constant \(\tau\) [s].

inline double getTimeConstant() const

Get the IGBM time constant \(\tau\) [s].

double getStateValue() const

Get the current state value.

If called before state registration, this returns the configured initial value (which defaults to \(\mu - 1\), i.e. the factor at its mean level).

Returns:

Current scalar correction \(\delta\) [-].

void setStateValue(double val)

Set the state value.

Non-finite values are rejected before changing either the initial or registered state. This updates the configured initial value and also updates the registered state immediately if registration has already occurred.

Parameters:

val – New scalar correction \(\delta\) [-]. Must be greater than \(-1\) so the initial multiplicative factor \(1 + \delta\) is positive (the process is only well-posed from a positive factor). This constrains the initial condition; it does not guarantee the numerically-integrated factor stays positive at every later step.

inline std::string getStateName() const

Get the registered state manager name.

inline void setStateName(std::string name)

Set the state manager name.

Parameters:

name – State name.

Private Members

std::string nameOfState

state manager key for scalar correction \(\delta\)

StateData *state = nullptr

pointer to scalar state container

double mean = 1.0

mean level \(\mu\) of the factor \((1+\delta)\) [-]

double sigmaStationary = 0.0

stationary standard deviation \(\sigma_{\mathrm{st}}\) [-]

double timeConstant = 1.0

IGBM time constant \(\tau\) [s].

double stateInit = 0.0

initial value for \(\delta\) used at state registration

bool stateInitSet = false

whether the user set an explicit initial value

Private Static Attributes

static uint64_t effectorID = 1

unique ID counter used to generate a distinct state name