C++ Module: stateEffector

Executive Summary

StateEffector is the abstract base class for effectors with integrated states, including reaction wheels, flexible bodies, prescribed motion, and fuel slosh. A dynamic object calls each effector during every integrator stage to assemble instantaneous mass properties, back-substitution terms, state derivatives, and energy and momentum contributions.

Retained Mass-Property Derivatives and Equation-of-Motion Overrides

The original EffectorMassProps fields describe derivatives of the retained effector mass properties:

\[\mathtt{mEffDot},\quad \mathtt{rEffPrime\_CB\_B},\quad \mathtt{IEffPrimePntB\_B}.\]

They are used for the reported total-mass, center-of-mass, and inertia derivatives. The reported center-of-mass derivative follows the complete retained first-moment quotient rule.

A variable-mass approximation can intentionally omit generic rate-dependent terms from the equations of motion without corrupting the reported derivatives. Such an effector sets hasMassPropertyRateDynamics and fills mEffDotDynamics, rEffPrime_CB_BDynamics, and IEffPrimePntB_BDynamics. C++ Module: spacecraft uses these overrides only in its equations of motion. The existing rEffPrime_CB_B remains the body-frame derivative of the retained effector center of mass. Effectors that do not set the flag retain the established behavior in which the corresponding retained-property rates are also used as the dynamics rates.

Dynamics-rate overrides are currently supported only for effectors attached directly to C++ Module: spacecraft. PrescribedMotionStateEffector rejects variable-mass nested effectors rather than silently applying incomplete variable-mass bookkeeping. The legacy SpacecraftSystem does not consume this override contract and provides no runtime guard for it; use C++ Module: spacecraft for effectors that provide dynamics-rate overrides.

The dynamics-only center-of-mass-rate quantity follows the quotient rule on the retained mass properties,

\[\mathbf c'_{\mathrm{dyn}} = \frac{\sum_i m_i\mathbf r'_{i,\mathrm{dyn}}}{M} - \frac{\dot M_{\mathrm{dyn}}}{M}\mathbf c.\]

This differs from the derivative reported through centerOfMassPrimeSC, which additionally carries the source first moments described below.

A complete open-system mass-flow model also requires the position and velocity at which mass crosses the selected control-volume boundary. Those quantities cannot be reconstructed from retained mass, center-of-mass, and inertia rates. The coupled-depletion FuelTank.setUpdateOnly(False) model therefore continues to omit the source first moments \(\dot m_i\mathbf r_i\), and a model that needs them must supply its own momentum-flux loads.

Implementation Requirements

An effector using explicit equation-of-motion rate overrides must:

assign mEffDotDynamics, rEffPrime_CB_BDynamics, and IEffPrimePntB_BDynamics on every call;
reset quantities that are zero rather than relying on values from a prior integrator stage;
evaluate all values from the current stage state and integTime;
document which legacy rate terms are retained or omitted.

struct BackSubMatrices

#include <stateEffector.h>

back substitution matrix structure

Public Members

Eigen::Matrix3d matrixA: Back-Substitution matrix A.

Eigen::Matrix3d matrixB: Back-Substitution matrix B.

Eigen::Matrix3d matrixC: Back-Substitution matrix C.

Eigen::Matrix3d matrixD: Back-Substitution matrix D.

Eigen::Vector3d vecTrans: Back-Substitution translation vector.

Eigen::Vector3d vecRot: Back-Substitution rotation vector.

struct EffectorMassProps

#include <stateEffector.h>

Abstract class that is used to implement an effector attached to the dynamicObject that has a state that needs to be integrated. For example: reaction wheels, flexing solar panels, fuel slosh etc.

Public Members

double mEff: [kg] Mass of the effector

double mEffDot: [kg/s] Time derivative of retained effector mass

Eigen::Matrix3d IEffPntB_B: [kg m^2] Inertia of effector relative to point B in B frame components

Eigen::Vector3d rEff_CB_B: [m] Center of mass of effector with respect to point B in B frame comp

Eigen::Vector3d rEffPrime_CB_B: [m/s] Body-frame derivative of the retained effector CoM

Eigen::Matrix3d IEffPrimePntB_B: [kg m^2/s] Body-frame derivative of retained effector inertia

bool hasMassPropertyRateDynamics: — True when the equations of motion use explicit rate overrides

double mEffDotDynamics: [kg/s] Mass rate substituted into generic rate-dependent terms

Eigen::Vector3d rEffPrime_CB_BDynamics: [m/s] CoM derivative used by generic rate terms

Eigen::Matrix3d IEffPrimePntB_BDynamics: [kg m^2/s] Inertia rate substituted into generic rate-dependent terms

class StateEffector

#include <stateEffector.h>

state effector class

Subclassed by HubEffector

Public Functions

void setStateNameOfPosition(std::string value): setter for stateNameOfPosition property

inline const std::string getStateNameOfPosition() const: getter for stateNameOfPosition property

void setStateNameOfVelocity(std::string value): setter for stateNameOfVelocity property

inline const std::string getStateNameOfVelocity() const: getter for stateNameOfVelocity property

void setStateNameOfSigma(std::string value): setter for stateNameOfSigma property

inline const std::string getStateNameOfSigma() const: getter for stateNameOfSigma property

void setStateNameOfOmega(std::string value): setter for stateNameOfOmega property

inline const std::string getStateNameOfOmega() const: getter for stateNameOfOmega property

void setPropName_m_SC(std::string value): setter for propName_m_SC property

inline const std::string getPropName_m_SC() const: getter for propName_m_SC property

void setPropName_mDot_SC(std::string value): setter for propName_mDot_SC property

inline const std::string getPropName_mDot_SC() const: getter for propName_mDot_SC property

void setPropName_centerOfMassSC(std::string value): setter for propName_centerOfMassSC property

inline const std::string getPropName_centerOfMassSC() const: getter for propName_centerOfMassSC property

void setPropName_inertiaSC(std::string value): setter for propName_inertiaSC property

inline const std::string getPropName_inertiaSC() const: getter for propName_inertiaSC property

void setPropName_inertiaPrimeSC(std::string value): setter for propName_inertiaPrimeSC property

inline const std::string getPropName_inertiaPrimeSC() const: getter for propName_inertiaPrimeSC property

void setPropName_centerOfMassPrimeSC(std::string value): setter for propName_centerOfMassPrimeSC property

inline const std::string getPropName_centerOfMassPrimeSC() const: getter for propName_centerOfMassPrimeSC property

void setPropName_centerOfMassDotSC(std::string value): setter for propName_centerOfMassDotSC property

inline const std::string getPropName_centerOfMassDotSC() const: getter for propName_centerOfMassDotSC property

void setPropName_inertialPosition(std::string value): setter for propName_inertialPosition property

inline const std::string getPropName_inertialPosition() const: getter for propName_inertialPosition property

void setPropName_inertialVelocity(std::string value): setter for propName_inertialVelocity property

inline const std::string getPropName_inertialVelocity() const: getter for propName_inertialVelocity property

void setPropName_vehicleGravity(std::string value): setter for propName_vehicleGravity property

inline const std::string getPropName_vehicleGravity() const: getter for propName_vehicleGravity property

void setPropName_prescribedPosition(std::string value): setter for propName_prescribedPosition property

inline const std::string getPropName_prescribedPosition() const: getter for propName_prescribedPosition property

void setPropName_prescribedVelocity(std::string value): setter for propName_prescribedVelocity property

inline const std::string getPropName_prescribedVelocity() const: getter for propName_prescribedVelocity property

void setPropName_prescribedAcceleration(std::string value): setter for propName_prescribedAcceleration property

inline const std::string getPropName_prescribedAcceleration() const: getter for propName_prescribedAcceleration property

void setPropName_prescribedAttitude(std::string value): setter for propName_prescribedAttitude property

inline const std::string getPropName_prescribedAttitude() const: getter for propName_prescribedAttitude property

void setPropName_prescribedAngVelocity(std::string value): setter for propName_prescribedAngVelocity property

inline const std::string getPropName_prescribedAngVelocity() const: getter for propName_prescribedAngVelocity property

void setPropName_prescribedAngAcceleration(std::string value): setter for propName_prescribedAngAcceleration property

inline const std::string getPropName_prescribedAngAcceleration() const: getter for propName_prescribedAngAcceleration property

StateEffector()

Contructor.

This is the constructor, just setting the variables to zero

virtual ~StateEffector()

Destructor.

This is the destructor, nothing to report here

virtual void updateEffectorMassProps(double integTime)

Method for stateEffector to give mass contributions.

This method is for the state effector to provide its contributions of mass and mass rates to the dynamicObject. This allows for the dynamicObject to have access to the total mass, and inerita, mass and inertia rates

virtual void updateContributions(double integTime, BackSubMatrices &backSubContr, Eigen::MRPd sigma_BN, Eigen::Vector3d omega_BN_B, Eigen::Vector3d g_N)

Back-sub contributions.

This method is strictly for the back-substituion method for computing the dynamics of the spacecraft. The back-sub method first computes rDDot_BN_N and omegaDot_BN_B for the spacecraft using these contributions from the state effectors. Then computeDerivatives is called to compute the stateEffectors derivatives using rDDot_BN_N omegaDot_BN_B

virtual void addPrescribedMotionCouplingContributions(BackSubMatrices &backSubContr)

Method for adding coupling contributions for state effector branching on prescribed motion.

This method must be implemented to attach a state effector to a prescribed motion state effector. The additional coupling terms required to attach the state effector to the prescribed component are computed in this method. Similar to how the spacecraft module calls updateContributions for all its attached effectors, the prescribed motion module calls this method for all its attached state effectors.

virtual void updateEnergyMomContributions(double integTime, Eigen::Vector3d &rotAngMomPntCContr_B, double &rotEnergyContr, Eigen::Vector3d omega_BN_B)

Energy and momentum calculations.

This method allows for an individual stateEffector to add its energy and momentum calculations to the dynamicObject. The analytical devlopement of these contributions can be seen in Basilisk/simulation/dynamics/_Documentation/Basilisk-EnergyAndMomentum-20161219.pdf

virtual void modifyStates(double integTime)

Modify state values after integration.

This method allows for an individual stateEffector to modify their states after integration

virtual void calcForceTorqueOnBody(double integTime, Eigen::Vector3d omega_BN_B)

Force and torque on s/c due to stateEffector.

This method allows for an individual stateEffector to find the force and torque that the stateEffector is placing on to the body

virtual void writeOutputStateMessages(uint64_t integTimeNanos)

Write State Messages after integration.

This method ensures that all dynamics states have their messages written after integation

virtual void registerStates(DynParamManager &states) = 0: Method for stateEffectors to register states.

virtual void registerProperties(DynParamManager &states)

Method for stateEffectors to register properties.

This method allows the effector to register its properties

virtual void addDynamicEffector(DynamicEffector *newDynamicEffector, int segment)

Method to attach a dynamic effector.

This method can only be called for a state effector with override definition set up to support attached dynamic effectors

virtual void linkInStates(DynParamManager &states) = 0: Method for stateEffectors to get other states.

virtual void linkInPrescribedMotionProperties(DynParamManager &properties)

Method for stateEffectors to access prescribed motion properties.

This method allows the state effector to link in prescribed motion properties

virtual void computeDerivatives(double integTime, Eigen::Vector3d rDDot_BN_N, Eigen::Vector3d omegaDot_BN_B, Eigen::MRPd sigma_BN) = 0: Method for each stateEffector to calculate derivatives.

virtual void prependSpacecraftNameToStates(): This method ensures that stateEffectors can be implemented using the multi-spacecraft archticture

virtual void receiveMotherSpacecraftData(Eigen::Vector3d rSC_BP_P, Eigen::Matrix3d dcmSC_BP): class method

Public Members

std::string nameOfSpacecraftAttachedTo = "": class variable

std::string parentSpacecraftName = "": name of the spacecraft the state effector is attached to

EffectorMassProps effProps: stateEffectors instantiation of effector mass props

Eigen::VectorXd stateDerivContribution: stateEffector contribution to another stateEffector to prevent double-counting

Eigen::Vector3d forceOnBody_B: [N] Force that the state effector applies to the s/c

Eigen::Vector3d torqueOnBodyPntB_B: [N] Torque that the state effector applies to the body about point B

Eigen::Vector3d torqueOnBodyPntC_B: [N] Torque that the state effector applies to the body about point B

Eigen::Vector3d r_BP_P: position vector of the spacecraft mody frame origin B relative to the primary spacecraft body frame P. This is used in the SpacecraftSystem module where multiple spacecraft hubs can be a single spacecraft

Eigen::Matrix3d dcm_BP: DCM of the spacecraft body frame B relative to primary spacecraft body frame P.

BSKLogger bskLogger: BSK Logging.

Protected Attributes

std::string stateNameOfPosition = "": state engine name of the parent rigid body inertial position vector

std::string stateNameOfVelocity = "": state engine name of the parent rigid body inertial velocity vector

std::string stateNameOfSigma = "": state engine name of the parent rigid body inertial attitude

std::string stateNameOfOmega = "": state engine name of the parent rigid body inertial angular velocity vector

std::string propName_m_SC = "": property name of m_SC

std::string propName_mDot_SC = "": property name of mDot_SC

std::string propName_centerOfMassSC = "": property name of centerOfMassSC

std::string propName_inertiaSC = "": property name of inertiaSC

std::string propName_inertiaPrimeSC = "": property name of inertiaPrimeSC

std::string propName_centerOfMassPrimeSC = "": property name of centerOfMassPrimeSC

std::string propName_centerOfMassDotSC = "": property name of centerOfMassDotSC

std::string propName_inertialPosition = "": property name of inertialPosition

std::string propName_inertialVelocity = "": property name of inertialVelocity

std::string propName_vehicleGravity = "": property name of vehicleGravity

std::string propName_prescribedPosition = "": property name of prescribedPosition

std::string propName_prescribedVelocity = "": property name of prescribedVelocity

std::string propName_prescribedAcceleration = "": property name of prescribedAcceleration

std::string propName_prescribedAttitude = "": property name of prescribedAttitude

std::string propName_prescribedAngVelocity = "": property name of prescribedAngVelocity

std::string propName_prescribedAngAcceleration = "": property name of prescribedAngAcceleration

Eigen::MatrixXd *prescribedPositionProperty = nullptr: [m] r_PB_B prescribed position relative to hub

Eigen::MatrixXd *prescribedVelocityProperty = nullptr: [m/s] rPrime_PB_B prescribed velocity relative to hub

Eigen::MatrixXd *prescribedAccelerationProperty = nullptr: [m/s^2] rPrimePrime_PB_B prescribed acceleration relative to hub

Eigen::MatrixXd *prescribedAttitudeProperty = nullptr: sigma_PB prescribed MRP attitude relative to hub

Eigen::MatrixXd *prescribedAngVelocityProperty = nullptr: [rad/s] omega_PB_P prescribed angular velocity relative to hub

Eigen::MatrixXd *prescribedAngAccelerationProperty = nullptr: [rad/s^2] omegaPrime_PB_P prescribed angular acceleration relative to hub